mempalace Documentation

[!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 .com variants) 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 Copy Chapter

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 Copy Chapter

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

Android / Termux Copy Section

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. See the
Termux installation guide for the tested setup and
an argv-preserving launcher.

Docker Copy Section

A container image is also available for running the MCP server or the CLI
without a local Python toolchain. Multi-arch (amd64 + arm64), so it runs
natively on Apple Silicon:

docker pull ghcr.io/mempalace/mempalace:latest

Everything persists under /data — palace, config, and the cached embedding
model — so mount a volume there and reuse it across runs:

# MCP server over stdio — note the `-i` flag (JSON-RPC needs stdin)
docker run -i --rm -v mempalace-data:/data ghcr.io/mempalace/mempalace

# Run any CLI command instead. The container only sees what you mount, so
# mount the directory you want to mine — read-only is enough, mining never
# writes to the source.
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"

The first command that needs embeddings downloads the model into /data
(~80 MB for the default minilm, ~300 MB for embeddinggemma). It is a
one-off as long as the volume persists, but it does mean the first call is
slow and needs network — worth knowing before assuming a hung container.

Wire it into an MCP client (e.g. Claude Code) as a stdio server. Mount
anything you want the server to be able to mine — 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 there — ~ and $HOME are not expanded by every
MCP client. Paths are container paths from then on: mine /transcripts, not
~/.claude/projects.

Mount permissions on Linux. The image runs as uid 1000 and bind mounts
keep their host ownership, so a mounted directory 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 about
Docker. Docker Desktop maps uids on macOS and Windows, so this only bites on
Linux. Do not work around it with --user: /data is owned by uid 1000
inside the image, so another uid cannot write the palace at all.

docker compose run --rm mcp works too (see docker-compose.yml), and
deploy/docker-compose.server.yml stands up the team server. To build the
image yourself instead of pulling — required for the GPU variant, which is not
published:

docker build -t mempalace .                                  # CPU
docker build --build-arg EXTRAS="extract,spellcheck" -t mempalace .
docker build -f Dockerfile.gpu -t mempalace:gpu .            # CUDA; run with --gpus all

The GPU image is x86_64-only: onnxruntime-gpu publishes no aarch64 Linux
wheels, so that last build fails on an ARM host (including Apple Silicon) with
a dependency-resolution error rather than an obvious one.

Note that a build from a clone uses whatever branch you checked out; develop
is the default branch, so pull the published image if you want the released
version.

Storage backends Copy Chapter

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.

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 Copy Chapter

# 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 Copy Chapter

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):

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):

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 Copy Chapter

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 Copy Chapter

44 MCP tools cover palace reads/writes, knowledge-graph operations,
cross-wing navigation, drawer management, agent diaries, and agent
coordination (logstream events + artifact handoffs). Installation
and the full tool list:
mempalaceofficial.com/reference/mcp-tools.

Agents Copy Chapter

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 Copy Chapter

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 periodically — it stores one
verbatim drawer per user/assistant message, idempotent and resume-safe.

Requirements Copy Chapter

• Python 3.9+
• A vector-store backend (ChromaDB by default)
• ~300 MB disk for the embedding model. Onboarding (python -m mempalace.onboarding) offers embeddinggemma-300m (multilingual, 100+ languages, recommended) or all-MiniLM-L6-v2 (English-only, ~30 MB). See the docstring at mempalace/embedding.py for details and migration notes.
• Optional — compute embeddings on a server instead of locally. Set embedding_model: "openai-compat" in ~/.mempalace/config.json together with embedding_api_url / embedding_api_model (and embedding_api_key if the server needs auth) to use any OpenAI-compatible /v1/embeddings endpoint — LM Studio, llama.cpp, vLLM, Ollama's OpenAI shim, or a self-hosted server (e.g. a larger multilingual or GPU-served embedder). Each key is overridable via the matching MEMPALACE_EMBEDDING_API_* env var. When the endpoint is on your machine or LAN, no content leaves your network. Switching to it requires mempalace repair rebuild-index (different vector space).

No API key is required for the core benchmark path.

Docs Copy Chapter

• 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 Copy Chapter

PRs welcome. See CONTRIBUTING.md.

License Copy Chapter

MIT — see LICENSE.