mempalace

[!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

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