Files

T

Igor Lins e Silva c35686c9e1 docs(install): recommend uv as the package manager

End-user installs now lead with `uv tool install mempalace`, with
`pip install mempalace` kept as a fallback. Dev/contributor docs lead
with `uv sync --extra dev` and `uv run` for tests/benchmarks/lint, with
the equivalent pip recipe kept inline. The shipped `/mempalace:init`
skill instructions (mempalace/instructions/init.md) try `uv tool install`
first when uv is on PATH, then fall back through the pip variants.

Adds a .python-version pin at 3.12 because the lockfile's
onnxruntime==1.24.3 only ships wheels for Python >=3.11; without the
pin, `uv sync` on a host where uv prefers 3.10 fails with no source
distribution available, which would make the documented command a
footgun. pyproject's `requires-python = ">=3.9"` is unchanged — pip
users on 3.9/3.10 are unaffected.

Files updated: README.md, CONTRIBUTING.md, CLAUDE.md, the gemini-cli
guide and example, the .claude-plugin / .codex-plugin READMEs, the
mempalace SKILL, the openclaw SKILL, tools/save.md, the three
benchmarks docs, and the corresponding website mirrors.

2026-05-08 01:38:00 -03:00

3.1 KiB

Raw Blame History

Contributing

PRs welcome. MemPalace is open source and we welcome contributions of all sizes — from typo fixes to new features.

Getting Started

git clone https://github.com/MemPalace/mempalace.git
cd mempalace

# Recommended: uv (https://docs.astral.sh/uv/) manages the venv for you
uv sync --extra dev

# Or with pip in your own venv:
# pip install -e ".[dev]"

Running Tests

uv run 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)
uv run python benchmarks/longmemeval_bench.py /path/to/longmemeval_s_cleaned.json --limit 20

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

See Benchmarks for data download instructions.

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 uv run pytest tests/ -v — everything must pass
Commit with clear 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 main

Code Style

Formatting: Ruff with 100-char line limit
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:

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. 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 make scoping predictable when a palace holds many unrelated projects; they are not a novel retrieval mechanism.

Community

Discord
GitHub Issues — bug reports and feature requests
GitHub Discussions — questions and ideas

License

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

3.1 KiB Raw Blame History