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. For the pluggable-backend preview, MemPalace also ships sqlite_exact for local exact-vector correctness checks, and two opt-in external service backends — qdrant (REST) and pgvector (Postgres). The two external backends exercise the storage contract on different substrates (a REST/dict store and a SQL/JSONB store), so it is not accidentally shaped around one vendor.

# local no-service backend
mempalace mine ~/projects/myapp --backend sqlite_exact

# Qdrant backend, defaulting to http://localhost:6333
MEMPALACE_QDRANT_URL=http://localhost:6333 \
  mempalace mine ~/projects/myapp --backend qdrant

# Postgres + pgvector backend, defaulting to postgresql://localhost:5432/mempalace
#   needs the optional driver: pip install mempalace[pgvector]
#   and the `vector` extension available on the server
MEMPALACE_PGVECTOR_DSN=postgresql://localhost:5432/mempalace \
  mempalace mine ~/projects/myapp --backend pgvector