Igor Lins e Silva
bf3b9c5979
Remaining in-repo surfaces carrying the same retracted or broken claims as the public pages fixed in the previous two commits. CONTRIBUTING.md - "Palace structure matters ... 34% retrieval improvement" → reframed as scoping (same rewording applied to the website equivalents). benchmarks/BENCHMARKS.md - Add a prominent "Important caveat" block at the top of the "Comparison vs Published Systems" table explaining that R@5 (retrieval recall) and QA accuracy are different metrics, with citations to Mastra, Mem0, and Supermemory's own published methodology pages. Annotate the specific competitor rows whose numbers are QA accuracy, not retrieval recall. - Annotate the `hybrid v4 + rerank 100%` row to note that the 99.4 → 100 step was tuned on 3 specific wrong answers (already disclosed further down in the doc under "Benchmark Integrity"); the honest hybrid figure is held-out 98.4%. - Fix the broken clone URL — `aya-thekeeper/mempal` no longer points at anything; now `MemPalace/mempalace`. benchmarks/README.md + benchmarks/HYBRID_MODE.md - Same clone-URL fix applied. CHANGELOG.md - Add a ### Documentation entry under [Unreleased] v3.3.0 that names #875 and summarises the scope of the rewrite.
96 lines
3.6 KiB
Markdown
96 lines
3.6 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 is scoping, not magic**: Wings, halls, and rooms act as metadata filters in the underlying vector store. They keep retrieval predictable when a palace holds many unrelated projects or people. Respect the hierarchy — but don't present it as a novel retrieval mechanism.
|
|
|
|
## 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.
|