Igor Lins e Silva
8b26bf2ac3
* 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>
96 lines
3.4 KiB
Markdown
96 lines
3.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
pytest tests/ -v
|
|
```
|
|
|
|
All tests must pass before submitting a PR. Tests should run without API keys or network access.
|
|
|
|
## Running Benchmarks
|
|
|
|
```bash
|
|
# 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](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
|
|
|
|
1. Fork the repo and create a feature branch: `git checkout -b feat/my-thing`
|
|
2. Write your code
|
|
3. Add or update tests if applicable
|
|
4. Run `pytest tests/ -v` — everything must pass
|
|
5. Commit with a clear message following [conventional commits](https://www.conventionalcommits.org/):
|
|
- `feat: add Notion export format`
|
|
- `fix: handle empty transcript files`
|
|
- `docs: update MCP tool descriptions`
|
|
- `bench: add LoCoMo turn-level metrics`
|
|
6. Push to your fork and open a PR against `develop`
|
|
|
|
## Code Style
|
|
|
|
- **Formatting**: [Ruff](https://docs.astral.sh/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](https://github.com/MemPalace/mempalace/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](https://discord.com/invite/ycTQQCu6kn)
|
|
- **Issues**: Bug reports and feature requests welcome
|
|
- **Discussions**: For questions and ideas
|
|
|
|
## License
|
|
|
|
MIT — your contributions will be released under the same license.
|