MemPalace: A Local-First Verbatim Memory Store for Coding Agents

What MemPalace actually stores, and who it is for

Most memory layers for language models compress. They summarize a session, extract facts, and throw the transcript away. MemPalace does the opposite. According to the README, it stores conversation history as verbatim text and retrieves it with semantic search, and it "does not summarize, extract, or paraphrase." That single design decision explains most of the rest of the project.

The index is structured rather than flat. People and projects become wings, topics become rooms, and the original content sits in drawers. The practical consequence is scoped search: instead of running a query against every conversation you have ever had, you can restrict it to one wing or one room. That matters when two projects use the same vocabulary and a global search keeps returning the wrong one.

The intended user is a developer running a coding agent locally, most obviously Claude Code. The README warns that Claude Code sessions expire in 30 days without auto-save hooks wired, and points to a retention setup checklist. So the target reader is someone who already has transcripts piling up on disk and wants them retrievable later, not someone looking for a general-purpose vector database.

Wings, rooms, drawers and the pluggable embedding layer

The retrieval layer is the part most likely to change under you. The README states the current default backend is ChromaDB, and that the interface lives in mempalace/backends/base.py, with alternative backends droppable in without touching the rest of the system. That is a real architectural commitment, not a marketing line: the storage and the embedding are separable.

Embeddings are pluggable too. The pyproject.toml declares huggingface_hub, tokenizers and numpy as required core dependencies rather than optional extras, with a comment explaining that onboarding now offers the embeddinggemma-300m ONNX model as the default for new installs. The 300 MB ONNX model is lazy-downloaded on first use, not at install time. Users who pick minilm during onboarding still get those packages installed but unused, which the comment frames as a small wheel-size cost traded for one fewer pip command in the multilingual path.

That trade-off is defensible but worth naming: a monorepo user who only wants English embeddings still carries the multilingual dependency tree. The alternative, making them extras, would push a second install step onto the multilingual user. The project chose the multilingual user.

There is also a Rust workspace in the repository, with crates/mempalace-core, crates/mempalace-py and crates/mempalace-cli listed as members in Cargo.toml, and the release profile sets lto, codegen-units = 1 and panic = "abort". The README does not document what each crate does, so treat the Rust layer as an internal implementation detail until the docs say otherwise.

Installing MemPalace with uv, pipx or Docker

The README gives two setup paths: agent-guided and direct CLI. For the guided path, you install the skills first and then ask your coding agent to run the setup, which detects the system, installs the Python package, configures MCP, and asks whether you want a private local palace, a shared-brain hub, or a client connected to an existing hub.

npx skills add MemPalace/mempalace

The repository exposes three skills: mempalace for guided installation and operations, mempalace-recall for search-before-answer recall, and mempalace-task for logstream delegation. Note the README's own caveat: installing a skill does not by itself install the MemPalace CLI or MCP server. The setup skill guides the agent through those system changes and verifies the live connection. If you stop after the npx command, you have installed instructions, not software.

For the direct path, the README recommends uv and explains why: it avoids PEP 668 errors on Debian, Ubuntu and Homebrew Pythons, and keeps chromadb, numpy and grpcio out of your global site-packages.

uv tool install mempalace
mempalace init ~/projects/myapp

The first command puts the mempalace CLI in an isolated environment on your PATH; the second initializes a palace rooted at that project directory. pipx install mempalace works the same way. Plain pip is only recommended inside an activated virtualenv where you explicitly want import mempalace available.

Docker is the third route, and the README documents the container's shape clearly. Everything persists under /data, so mount a volume there and reuse it. The MCP server speaks JSON-RPC over stdio, which is why the run command needs -i.

docker run -i --rm -v mempalace-data:/data ghcr.io/mempalace/mempalace
docker run --rm -v mempalace-data:/data -v /path/to/project:/work:ro \
  ghcr.io/mempalace/mempalace mine /work
docker run --rm -v mempalace-data:/data ghcr.io/mempalace/mempalace search "why GraphQL"

Mining never writes to the source, so read-only is enough for the project mount. The first command that needs embeddings downloads the model into /data, roughly 80 MB for the default minilm or about 300 MB for embeddinggemma. It is a one-off as long as the volume persists, but it means the first call is slow and needs network. The README flags this directly, because otherwise it looks like a hung container.

Wiring it into an MCP client is a JSON block. Mount anything you want the server to be able to mine, since it cannot reach your transcripts otherwise:

{
  "mcpServers": {
    "mempalace": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "mempalace-data:/data",
        "-v", "/absolute/path/to/.claude/projects:/transcripts:ro",
        "ghcr.io/mempalace/mempalace"
      ]
    }
  }
}

Use a real absolute path. The README warns that ~ and $HOME are not expanded by every MCP client, and that paths are container paths from then on, so you mine /transcripts rather than ~/.claude/projects.

Where the Docker path and the platform support break down

The container runs as uid 1000, and bind mounts keep their host ownership. A mounted directory therefore has to be readable by that uid. An ordinary 0755 checkout is fine; a 0700 directory is not, and the failure surfaces as PermissionError: [Errno 13] rather than anything mentioning Docker. Docker Desktop maps uids on macOS and Windows, so this only bites on Linux. The README explicitly says not to work around it with --user, because /data is owned by uid 1000 inside the image and another uid cannot write the palace at all. That is a genuine constraint, not a documentation gap, and it is the kind of thing that costs an afternoon if you discover it by experiment.

The GPU image is x86_64 only. onnxruntime-gpu publishes no aarch64 Linux wheels, so the Dockerfile.gpu build fails on an ARM host, including Apple Silicon, with a dependency-resolution error rather than an obvious one. Building from a clone also uses whatever branch you checked out, and develop is the default branch, so the README advises pulling the published image if you want the released code.

Android is the clearest gap. The README states native Termux installation is not currently supported because compiled dependencies such as ChromaDB and ONNX Runtime publish Linux wheels, not Android wheels. Android ARM64 users can run the regular Linux packages in an isolated Debian PRoot container instead, per the Termux installation guide. That is a workaround, and it is described as one.

The README also carries a warning about impostor sites, stating the only official sources are the GitHub repository, the PyPI package and mempalaceofficial.com, and that any other domain, including .tech, .net or other .com variants, may distribute malware. Whatever you think of that framing, it is worth checking the domain before you install anything.

How it compares with mem0 and other memory layers

The obvious comparison is mem0, which appears in the search terms people use around this project. The difference is the storage model. MemPalace keeps the original text and indexes it; the retrieval step returns verbatim material. A summarization-based memory layer stores derived facts and discards the transcript, which produces compact context but loses the ability to recover the exact wording of a decision three months later. If your use case is "what exactly did we agree on, and in what words," verbatim storage is the right shape. If your use case is "give the model a short, dense profile of this user," it is the wrong one, because you are paying to store and embed text you will never read.

The second difference is operational. MemPalace's README emphasizes that nothing leaves your machine unless you opt in, and the benchmark claim is stated as 96.6% R@5 raw on LongMemEval with zero API calls. A hosted memory service trades that local control for managed infrastructure and, usually, a per-call cost. Neither is universally better. A local palace means you own the backup problem, the disk usage, and the model download.

Within the project, the pluggable backend interface is the thing to watch. The README names ChromaDB as the current default and points at mempalace/backends/base.py as the contract. If you have an existing vector store, that interface is where you would check whether an adapter is realistic for your team.

Licence, maintenance and what an upgrade costs

The licence is MIT, declared both in pyproject.toml and in the Cargo workspace manifest, and the repository ships a LICENSE file at the top level. MIT is permissive: you can use it commercially, modify it and redistribute it, provided the copyright notice and permission notice travel with it. That is a statement about the licence text, not legal advice for your situation, and the embedding models the project downloads carry their own terms, which the README does not discuss.

The package classifier in pyproject.toml reads "Development Status :: 4 - Beta", so the project describes itself as beta despite the version number sitting at 3.9.0. Version numbers and maturity labels disagreeing is common, but here you should believe the classifier when planning.

On maintenance: the last push was on 2026-08-23, and releases v3.7.0, v3.7.1 and v3.8.0 all landed in August 2026. The repository is not archived. The CHANGELOG.md and ROADMAP.md files at the top level are the places to check what changed between releases.

Upgrade cost is dominated by the embedding model rather than the code. Because the model is lazy-downloaded on first use and cached under /data in Docker or the home cache otherwise, switching from minilm to embeddinggemma means a fresh download of roughly 300 MB and a re-embed of everything already in the palace. The README does not document a migration command for changing models on an existing palace, so budget for re-mining rather than assuming an in-place switch.

Editorial conclusion

Adopt MemPalace if you already run a coding agent that speaks MCP and you want your transcripts searchable without sending them to a hosted service. Skip it if you need a stable, fully documented API surface, a Windows-native path, or Android/Termux support, since the README states native Termux installation is not currently supported. Before committing, verify two things on your own machine: that your MCP client expands the absolute transcript path you pass to the Docker mount, and that your first embedding call completes, because the default model downloads lazily on first use and a slow container there is a download, not a hang.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes