Files

T

Igor Lins e Silva 8b26bf2ac3 chore: sync main hotfixes into release/3.2.0 (#763 )

* fix: disambiguate hook block reasons to name MemPalace explicitly (#666)

Replace "your memory system" with explicit MemPalace references and
tool names (mempalace_diary_write, mempalace_add_drawer, mempalace_kg_add)
in stop and precompact hook block reasons. This prevents Claude Code from
misinterpreting the hook as a native auto-memory save instruction.

Updated in both Python (hooks_cli.py) and standalone shell scripts.

Also fix CONTRIBUTING.md Getting Started to show the fork-first workflow,
matching the PR Guidelines section.

* fix: remove chromadb <0.7 upper bound — blocks 1.x installs

The current constraint `chromadb>=0.5.0,<0.7` forces pip to install
chromadb 0.6.x, but palaces created with chromadb 1.x (which is what
the mempalace dev environment actually uses — 1.5.7 per uv.lock) have
an incompatible SQLite schema. Specifically, chromadb 0.6.x fails with
`KeyError: '_type'` when opening a collection written by 1.x.

This means a fresh `pip install mempalace` gives users a chromadb
version that cannot read palaces created in the maintainer's own
environment. The fix removes the upper bound so pip can resolve to the
current stable chromadb release.

Reproduction:
  python3 -m venv .venv && source .venv/bin/activate
  pip install mempalace          # installs chromadb 0.6.3
  # Try opening a palace created with chromadb 1.x:
  # -> _get_collection() returns None, tool_status() returns "No palace found"
  pip install chromadb==1.5.7    # force upgrade
  # -> tool_status() returns real data (26k drawers in our case)

---------

Co-authored-by: z3tz3r0 <kittipan.wang@gmail.com>
Co-authored-by: AlyciaBHZ <50111876+AlyciaBHZ@users.noreply.github.com>
Co-authored-by: Ben Sigman <1872138+bensig@users.noreply.github.com>

2026-04-12 23:44:22 -07:00

3.4 KiB

Raw Blame History

Contributing to MemPalace

Thanks for wanting to help. MemPalace is open source and we welcome contributions of all sizes — from typo fixes to new features.

Getting Started

# Fork the repo on GitHub first, then clone your fork
git clone https://github.com/<your-username>/mempalace.git
cd mempalace
git remote add upstream https://github.com/MemPalace/mempalace.git

pip install -e ".[dev]"    # installs with dev dependencies (pytest, build, twine)

Running Tests

pytest tests/ -v

All tests must pass before submitting a PR. Tests should run without API keys or network access.

Running Benchmarks

# Quick test (20 questions, ~30 seconds)
python benchmarks/longmemeval_bench.py /path/to/longmemeval_s_cleaned.json --limit 20

# Full benchmark (500 questions, ~5 minutes)
python benchmarks/longmemeval_bench.py /path/to/longmemeval_s_cleaned.json

See benchmarks/README.md for data download instructions and reproduction guide.

Project Structure

mempalace/          ← core package (see mempalace/README.md for module guide)
benchmarks/         ← reproducible benchmark runners
hooks/              ← Claude Code auto-save hooks
examples/           ← usage examples
tests/              ← test suite
assets/             ← logo + brand

PR Guidelines

Fork the repo and create a feature branch: git checkout -b feat/my-thing
Write your code
Add or update tests if applicable
Run pytest tests/ -v — everything must pass
Commit with a clear message following conventional commits:
- feat: add Notion export format
- fix: handle empty transcript files
- docs: update MCP tool descriptions
- bench: add LoCoMo turn-level metrics
Push to your fork and open a PR against develop

Code Style

Formatting: Ruff with 100-char line limit (configured in pyproject.toml)
Naming: snake_case for functions/variables, PascalCase for classes
Docstrings: on all modules and public functions
Type hints: where they improve readability
Dependencies: minimize. ChromaDB + PyYAML only. Don't add new deps without discussion.

Good First Issues

Check the Issues tab. Great starting points:

New chat formats: Add import support for Cursor, Copilot, or other AI tool exports
Room detection: Improve pattern matching in room_detector_local.py
Tests: Increase coverage — especially for knowledge_graph.py and palace_graph.py
Entity detection: Better name disambiguation in entity_detector.py
Docs: Improve examples, add tutorials

Architecture Decisions

If you're planning a significant change, open an issue first to discuss the approach. Key principles:

Verbatim first: Never summarize user content. Store exact words.
Local first: Everything runs on the user's machine. No cloud dependencies.
Zero API by default: Core features must work without any API key.
Palace structure matters: Wings, halls, and rooms aren't cosmetic — they drive a 34% retrieval improvement. Respect the hierarchy.

Community

Discord: Join us
Issues: Bug reports and feature requests welcome
Discussions: For questions and ideas

License

MIT — your contributions will be released under the same license.

3.4 KiB Raw Blame History