Guide · Open source

How to use MemPalace: install, set up and connect to AI agents

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

MemPalace is an open-source Python tool that stores your conversation history as exact, unedited text and lets you search it by meaning. It is built to act as memory for AI coding assistants through MCP, and the README says nothing leaves your machine unless you opt in. This guide shows you how to install it, initialize a palace for a project, and connect it to an MCP-capable agent.

MemPalaceMemPalace/mempalace · ★ 60.2k · MIT Install options & downloads

Quick start

1Install the CLI. Run uv tool install mempalace to install MemPalace in an isolated environment. pipx also works, as does pip inside a virtualenv.
2Initialize a palace. Run mempalace init followed by the folder you want to organize, such as ~/projects/myapp.
3Choose a route. Use the CLI directly, or pull the Docker image if you do not want a local Python toolchain.
4Connect an MCP client. Add MemPalace to your MCP client config as a stdio server, using an absolute path for any mounted folders.
5Enable auto-save hooks. Wire auto-save hooks for Claude Code so sessions do not expire after 30 days, following the official retention checklist.

Check what you need before installing

MemPalace is installed as a Python package. The README excerpt does not specify a Python version, so check your own environment. You will need one of uv, pipx, or pip. Docker is optional and only needed if you want the container route.

The README recommends installing the CLI in an isolated environment, which avoids PEP 668 errors on Debian, Ubuntu and Homebrew Pythons and keeps its dependencies such as chromadb and numpy out of your global site-packages.

Python (version not stated in the README excerpt)
uv, pipx, or pip
Docker (optional, for the container route)

Install the MemPalace CLI with uv

The README recommends uv. The uv tool install command puts the mempalace CLI in an isolated environment on your PATH.

If you prefer pipx, the README says it works the same way.

uv tool install mempalace
mempalace init ~/projects/myapp

Initialize a palace for a project folder

A palace is MemPalace's structured store for your material. Its index organizes content into wings (people and projects), rooms (topics), and drawers (original content), so searches can be narrowed instead of run against one flat pile.

The README's example initializes a palace for a project folder with mempalace init followed by the folder path.

Wings: people and projects
Rooms: topics
Drawers: original content, stored verbatim

mempalace init ~/projects/myapp

Use the Docker route instead

The README provides a container image that runs the MCP server or the CLI without a local Python toolchain. The image is multi-arch (amd64 and arm64). Everything persists under /data, so mount a volume there and reuse it across runs.

The first command that needs embeddings downloads the model into /data. The README notes this takes time and needs network access, so a slow first call is expected. The GPU image is x86_64-only and must be built yourself.

Pull the image with docker pull ghcr.io/mempalace/mempalace:latest
Use -i for the MCP server, since JSON-RPC needs stdin
Mount directories you want to mine, read-only is enough
On Linux, mounted directories must be readable by uid 1000; do not use --user

docker pull ghcr.io/mempalace/mempalace:latest
docker run -i --rm -v mempalace-data:/data ghcr.io/mempalace/mempalace

Connect MemPalace to an MCP client such as Claude Code

To give an agent access to your palace, wire MemPalace in as a stdio MCP server. The README example uses Docker as the command. Use a real absolute path for mounted folders, because some MCP clients do not expand ~ or $HOME.

The README warns that Claude Code sessions expire in 30 days without auto-save hooks wired. It links to a retention setup checklist on the official docs site.

Use an absolute path such as /absolute/path/to/.claude/projects
Inside the container, paths are container paths, for example /transcripts

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

Pick a storage backend if the default does not fit

ChromaDB is the default backend and needs no configuration. The README lists other backends you can select with --backend <name>, the MEMPALACE_BACKEND environment variable, or a backend key in config.json. Non-default backends are opt-in.

chroma (default, local, bundled)
sqlite_exact (local, exact NumPy)
rust_exact (local, separate wheel or compiled)
milvus, qdrant and pgvector (server options, each with its own setting)

What people use it for

Letting Claude Code recall decisions from past sessions on the same project
Keeping a local, verbatim record of conversation history instead of a third-party summary
Searching past material by meaning, for example asking for 'why GraphQL' across mined content
Running a shared team server, as described in the README's team server option

Frequently asked questions

Is MemPalace free?

MemPalace is released under the MIT licence, and the project describes itself as free. Check the repository licence file for the full terms.

What do I need to install MemPalace?

You need Python, plus one of uv, pipx or pip. Docker is optional for the container route. The README excerpt does not state a specific Python version.

Does MemPalace send my data to the cloud?

The README says nothing leaves your machine unless you opt in. The default retrieval backend is ChromaDB, which runs locally.

Can I use MemPalace on Android with Termux?

Not natively. The README says Termux installation is not currently supported because some dependencies publish only Linux wheels. It suggests running the Linux packages in a Debian PRoot container on Android ARM64.

Why is my Docker container slow on the first run?

The first command that needs embeddings downloads the model into /data, about 80 MB for the default minilm model. This is a one-off while the volume persists, but it needs network access.

How does MemPalace compare to Mem0 or Letta?

The README does not compare MemPalace with other projects. Comparable projects listed for this tool include Mem0, Letta, Zep and Chroma. Check each project's documentation to compare features.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

MemPalace suits developers who use Claude Code or another MCP-capable agent and are comfortable in a terminal and with Python tools like uv. It is a poor fit if you want a polished point-and-click app, use Termux on Android, or need fully explained benchmark methodology.

Install options & downloads