d1d904f44b
A long-lived MCP server imports mempalace and chromadb once and serves from those in-memory modules for the life of the process, so an upgrade on disk mid-session never reaches it and it keeps accepting writes produced by code the user no longer has installed. Refuse mutating tools with JSON-RPC -32005 once a watched distribution's installed version differs from the snapshot taken at import, or once it is gone entirely. Reads stay available, mempalace_status reports library_versions, and MEMPALACE_MCP_ALLOW_STALE_LIBRARY=1 opts out. Both sides of the comparison come from installed metadata rather than a live module.__version__. A distribution whose metadata cannot be read, or whose search root will not open, is reported and left uncompared rather than treated as removed: importlib.metadata suppresses the failure at both of those levels, so either one would otherwise look exactly like an uninstall and refuse every write on a healthy install. The same module also memoizes each search root's listing against that root's mtime, read in seconds where this fingerprint compares nanoseconds. An upgrade whose removal and creation both land inside one timestamp tick would then be answered from the listing taken before it, naming a dist-info that is already gone; its version reads as empty, the distribution is left uncompared, and nothing moves that mtime afterwards, so the gate would stay off for it for the rest of the process. Drop the memo before each reading. Watch chromadb only when chromadb is the backend serving. It is a hard dependency rather than an extra, so it is installed even for a palace kept in Postgres, and watching it there would refuse that user's writes whenever chromadb alone was upgraded, over a library that writes nothing they own. A backend that cannot be resolved keeps it watched. Skip a sys.path entry carrying an embedded NUL. os.stat and os.listdir refuse it during argument conversion, raising ValueError rather than the OSError those callers hold; POSIX never gets there because realpath rejects it first, but Windows resolves it and one such entry would end the whole reading. The gate sits ahead of the diverged-index refusal added since (-32004, which is why this one takes -32005). That gate's remedy is `mempalace repair rebuild-index`, which would run the installed code against a palace this process is still writing with the superseded one, so the restart instruction has to be the one that reaches the client; the index probe re-runs per call and surfaces immediately after a restart. Ordering it this way also skips that gate's segment probe on a call already refused. Both directions of the precedence are pinned by tests. Co-Authored-By: messelink <274674234+messelink@users.noreply.github.com> |
||
|---|---|---|
| .agents/plugins | ||
| .antigravity-plugin | ||
| .claude-plugin | ||
| .codex-plugin | ||
| .cursor-plugin | ||
| .devcontainer | ||
| .github | ||
| assets | ||
| benchmarks | ||
| commands | ||
| deploy | ||
| docs | ||
| examples | ||
| hooks | ||
| integrations | ||
| landing | ||
| mempalace | ||
| rules | ||
| scripts | ||
| skills | ||
| tests | ||
| tools | ||
| website | ||
| .dockerignore | ||
| .gitignore | ||
| .pre-commit-config.yaml | ||
| .python-version | ||
| AGENTS.md | ||
| CHANGELOG.md | ||
| CLAUDE.md | ||
| CONTRIBUTING.md | ||
| Dockerfile | ||
| Dockerfile.gpu | ||
| LICENSE | ||
| MISSION.md | ||
| README.md | ||
| ROADMAP.md | ||
| SECURITY.md | ||
| docker-compose.yml | ||
| docker-entrypoint.sh | ||
| mcp.json | ||
| openarena-claim.txt | ||
| pyproject.toml | ||
| uv.lock | ||
README.md
MemPalace
Local-first AI memory. Verbatim storage, pluggable backend, 96.6% R@5 raw on LongMemEval — zero API calls.
[!CAUTION] Beware of impostor sites. MemPalace has no other official websites. The only official sources are this GitHub repository, the PyPI package, and the docs at mempalaceofficial.com. Any other domain (including
.tech,.net, or other.comvariants) is an impostor and may distribute malware. Details and timeline: docs/HISTORY.md.
[!IMPORTANT] Claude Code sessions expire in 30 days without auto-save hooks wired. Read this →
Need the shortest recovery/setup path? Use the Claude Code retention setup checklist.
What it is
MemPalace stores your conversation history as verbatim text and retrieves it with semantic search. It does not summarize, extract, or paraphrase. The index is structured — people and projects become wings, topics become rooms, and original content lives in drawers — so searches can be scoped rather than run against a flat corpus.
The retrieval layer is pluggable. The current default is ChromaDB; the
interface is defined in mempalace/backends/base.py
and alternative backends can be dropped in without touching the rest of
the system.
Nothing leaves your machine unless you opt in.
Architecture, concepts, and mining flows: mempalaceofficial.com/concepts/the-palace.
Install
MemPalace ships a CLI, so install it in an isolated environment to avoid
PEP 668 errors on Debian/Ubuntu/Homebrew Pythons and to keep mempalace's
deps (chromadb, numpy, grpcio, …) from conflicting with anything
else in your global site-packages.
We recommend uv — uv tool install puts
the mempalace CLI in an isolated environment on your PATH:
uv tool install mempalace
mempalace init ~/projects/myapp
pipx works the same way if you prefer it:
pipx install mempalace.
Prefer plain pip only inside an activated virtualenv where you
explicitly want import mempalace available:
python -m venv .venv && source .venv/bin/activate
pip install mempalace
Docker
A container image is also available for running the MCP server or the CLI
without a local Python toolchain. Everything persists under /data (palace,
config, and the cached embedding model), so mount a volume there.
# Build the image (CPU; bundles the `extract` + `spellcheck` extras)
docker build -t mempalace .
# MCP server over stdio — note the `-i` flag (JSON-RPC needs stdin)
docker run -i --rm -v mempalace-data:/data mempalace
# Run any CLI command instead (mount the host directory you want to mine)
docker run --rm -v mempalace-data:/data -v /path/to/project:/work mempalace mine /work
docker run --rm -v mempalace-data:/data mempalace search "why GraphQL"
Wire it into an MCP client (e.g. Claude Code) as a stdio server:
{
"mcpServers": {
"mempalace": {
"command": "docker",
"args": ["run", "-i", "--rm", "-v", "mempalace-data:/data", "mempalace"]
}
}
}
docker compose run --rm mcp works too (see docker-compose.yml). For
CUDA-accelerated embeddings, build the GPU variant with
docker build -f Dockerfile.gpu -t mempalace:gpu . and run it with
--gpus all. Customise the bundled extras at build time, e.g.
docker build --build-arg EXTRAS="extract,spellcheck" -t mempalace ..
Storage backends
ChromaDB is the default and needs no configuration. MemPalace also ships a pluggable backend contract, exercised across deliberately different substrates so the contract is never accidentally shaped around one vendor. Every non-default backend is opt-in.
| Backend | Mode | Install | Namespaces | Lexical | Configure with |
|---|---|---|---|---|---|
chroma (default) |
Local (embedded) | bundled | – | ✓ | – |
sqlite_exact |
Local (exact) | bundled | – | ✓ | – |
milvus |
Local (Lite) · Server opt-in | mempalace[milvus] |
✓ | ✓ | MEMPALACE_MILVUS_URI |
qdrant |
Server (REST) | bundled | ✓ | ✓ | MEMPALACE_QDRANT_URL |
pgvector |
Server (Postgres) | mempalace[pgvector] |
✓ | ✓ | MEMPALACE_PGVECTOR_DSN |
Select with --backend <name>, MEMPALACE_BACKEND=<name>, or
"backend": "<name>" in config.json. See
Storage backends for connection
variables, namespace behavior, and deployment notes.
Quickstart
# Mine content into the palace
mempalace mine ~/projects/myapp # project files
mempalace mine ~/.claude/projects/ --mode convos # Claude Code sessions (scope with --wing per project)
# Search
mempalace search "why did we switch to GraphQL"
# Load context for a new session
mempalace wake-up
For Claude Code, Gemini CLI, Antigravity, MCP-compatible tools, and local models, see mempalaceofficial.com/guide/getting-started.
Benchmarks
All numbers below are reproducible from this repository with the commands
in benchmarks/BENCHMARKS.md. Full
per-question result files are committed under benchmarks/results_*.
LongMemEval — retrieval recall (R@5, 500 questions):
| Mode | R@5 | LLM required |
|---|---|---|
| Raw (semantic search, no heuristics, no LLM) | 96.6% | None |
| Hybrid v4, held-out 450q (tuned on 50 dev, not seen during training) | 98.4% | None |
| Hybrid v4 + LLM rerank (full 500) | ≥99% | Any capable model |
The raw 96.6% requires no API key, no cloud, and no LLM at any stage. The hybrid pipeline adds keyword boosting, temporal-proximity boosting, and preference-pattern extraction; the held-out 98.4% is the honest generalisable figure.
The rerank pipeline promotes the best candidate out of the top-20
retrieved sessions using an LLM reader. It works with any reasonably
capable model — we have reproduced it with Claude Haiku, Claude Sonnet,
and minimax-m2.7 via Ollama Cloud (no Anthropic dependency). The gap
between raw and reranked is model-agnostic; we do not headline a "100%"
number because the last 0.6% was reached by inspecting specific wrong
answers, which benchmarks/BENCHMARKS.md flags as teaching to the test.
Other benchmarks (full results in benchmarks/BENCHMARKS.md):
| Benchmark | Metric | Score | Notes |
|---|---|---|---|
| LoCoMo (session, top-10, no rerank) | R@10 | 60.3% | 1,986 questions |
| LoCoMo (hybrid v5, top-10, no rerank) | R@10 | 88.9% | Same set |
| ConvoMem (all categories, 250 items) | Avg recall | 92.9% | 50 per category |
| MemBench (ACL 2025, 8,500 items) | R@5 | 80.3% | All categories |
We deliberately do not include a side-by-side comparison against Mem0, Mastra, Hindsight, Supermemory, or Zep. Those projects publish different metrics on different splits, and placing retrieval recall next to end-to-end QA accuracy is not an honest comparison. See each project's own research page for their published numbers.
Reproducing every result:
git clone https://github.com/MemPalace/mempalace.git
cd mempalace
uv sync --extra dev # or: pip install -e ".[dev]"
# see benchmarks/README.md for dataset download commands
uv run python benchmarks/longmemeval_bench.py /path/to/longmemeval_s_cleaned.json
Knowledge graph
MemPalace includes a temporal entity-relationship graph with validity windows — add, query, invalidate, timeline — backed by local SQLite. Usage and tool reference: mempalaceofficial.com/concepts/knowledge-graph.
MCP server
36 MCP tools cover palace reads/writes, knowledge-graph operations, cross-wing navigation, drawer management, and agent diaries. Installation and the full tool list: mempalaceofficial.com/reference/mcp-tools.
Agents
Each specialist agent gets its own wing and diary in the palace.
Discoverable at runtime via mempalace_list_agents — no bloat in your
system prompt:
mempalaceofficial.com/concepts/agents.
Auto-save hooks
Auto-save hooks for Claude Code, Codex CLI, and Cursor IDE save periodically and before context compression:
- Claude Code + Codex → mempalaceofficial.com/guide/hooks
- Cursor IDE (adds session-start recall and a transcript snapshot before compaction) → mempalaceofficial.com/guide/cursor-hooks
If you are installing under time pressure, start with the
Claude Code retention setup checklist:
wire the hooks, back up existing JSONL transcripts, and backfill them with
mempalace mine ~/.claude/projects/ --mode convos.
For per-message recall on top of the file-level chunks the hooks produce,
run mempalace sweep <transcript-dir> periodically — it stores one
verbatim drawer per user/assistant message, idempotent and resume-safe.
Requirements
- Python 3.9+
- A vector-store backend (ChromaDB by default)
- ~300 MB disk for the embedding model. Onboarding (
python -m mempalace.onboarding) offersembeddinggemma-300m(multilingual, 100+ languages, recommended) orall-MiniLM-L6-v2(English-only, ~30 MB). See the docstring atmempalace/embedding.pyfor details and migration notes.
No API key is required for the core benchmark path.
Docs
- Getting started → mempalaceofficial.com/guide/getting-started
- CLI reference → mempalaceofficial.com/reference/cli
- Python API → mempalaceofficial.com/reference/python-api
- Full benchmark methodology → benchmarks/BENCHMARKS.md
- Release notes → CHANGELOG.md
- Corrections and public notices → docs/HISTORY.md
Contributing
PRs welcome. See CONTRIBUTING.md.
License
MIT — see LICENSE.