MemPalace/mempalace

What it is

MemPalace is a local-first memory layer for AI assistants (Claude Code, Codex CLI, Cursor, Gemini CLI, any MCP-compatible client). It stores conversation transcripts verbatim — no summarization, no paraphrasing — and retrieves them by semantic search when a new session needs context. It markets itself on privacy: nothing leaves your machine unless you explicitly opt in (e.g., connecting to a server embedding endpoint).

Problem it solves

AI agents have a memory problem: each new session starts cold, and long-running sessions get context-compressed into oblivion. Claude Code sessions, for instance, expire after ~30 days without careful hook wiring. MemPalace gives agents a durable, searchable archive of past work — so a fresh session can answer "why did we switch to GraphQL?" by retrieving the actual conversation where that decision was made, not a summary of it.

How it works

1. Mine — a CLI command (mempalace mine) ingests files, git history, or Claude Code transcripts and stores them as verbatim text chunks.
2. Index — chunks are embedded with a local model (MiniLM ~30MB, or EmbeddingGemma ~300MB, multilingual) and stored in a vector database. ChromaDB is the default backend; SQLite-exact, Rust-native, Milvus, Qdrant, and pgvector are optional drop-ins.
3. Structure — the index uses a palace metaphor: people/projects become wings, topics become rooms, content sits in drawers. Searches can be scoped to a wing rather than run against a flat corpus.
4. Retrieve — a search or a wake-up command pulls relevant past sessions into the agent's context.
5. Serve — an MCP server (47 tools) lets any MCP-compatible agent query the palace at runtime: reads/writes, knowledge-graph ops, cross-wing navigation, agent coordination via logstream events.

Key components

• CLI (mempalace): mine, search, wake-up, audit, sweep — installable via uv tool, pipx, virtualenv, or Docker (multi-arch amd64/arm64, GPU variant via Dockerfile.gpu).
• MCP server: stdio JSON-RPC server exposing 47 tools; wired into Claude Code as a subprocess.
• Pluggable backends: six storage backends behind a common contract (backends/base.py); non-default ones are all opt-in.
• Knowledge graph: temporal entity-relationship graph with validity windows — add, query, invalidate, timeline — backed by local SQLite.
• Agent wings & diaries: each specialist agent gets its own namespace, discoverable at runtime rather than bloating system prompts.
• Auto-save hooks: for Claude Code, Codex CLI, and Cursor — periodic saves and pre-compaction snapshots; sweep adds per-message verbatim drawers.
• Native Rust engine: rust_exact backend and standalone mempalace-native CLI scan the same SQLite db with a Rust vector engine, with Python fallback for complex cases.
• Setup skills: npx skills add MemPalace/mempalace installs agent skills that detect your system, install the package, configure MCP, and verify the live connection.

Notable details / claims

• Benchmarks (all reproducible from the repo): LongMemEval retrieval recall R@5 of 96.6% raw (semantic search only, no LLM, no API key), 98.4% with hybrid v4 (tuned on a held-out dev set of 50, reported on 450 unseen), and ≥99% with an optional LLM rerank that works with any capable model (Haiku, Sonnet, minimax via Ollama Cloud). Also listed: LoCoMo R@10 88.9% (hybrid v5), ConvoMem 92.9% avg recall, MemBench (ACL 2025) 80.3% R@5.
• Honest benchmarking: the README explicitly refuses to compare side-by-side against Mem0, Mastra, Hindsight, Supermemory, or Zep, calling mixed-metric comparisons dishonest. It also flags the last 0.6% of rerank gains as "teaching to the test" and deliberately does not headline a 100% number.
• Security posture: an entire CAUTION section warns about impostor domains (mempalace.tech/.net and other .com variants) that distribute malware — only GitHub, PyPI, and mempalaceofficial.com are official.
• Docker gotchas documented: uid 1000 permissions on Linux bind mounts, first-run model download (~80MB/300MB, needs network), GPU image is x86-only (no aarch64 onnxruntime-gpu wheels), develop is the default branch (pull the published image for releases).

Limitations / things to watch

• Setup friction: the README itself warns that Claude Code sessions expire in 30 days without auto-save hooks wired — so the value proposition depends on following the setup checklists carefully.
• No Android/Termux native support: ChromaDB and ONNX Runtime lack Android wheels; Termux users must run Debian PRoot.
• First-use latency: first command that needs embeddings downloads power model (~80–300 MB) and may look hung.
• Embedding model changes require index rebuild (mempalace repair rebuild-index) if you switch models or move to a server-side OpenAI-compatible embedding endpoint.
• Native Rust extension is optional: rust_exact falls back to Python for complex filters and when the native ext isn't installed; no published benchmarks for the native path.

Verdict

A genuine, substantial project in the AI-memory space: real code (Python + Rust crates), reproducible benchmarks, a pluggable architecture, Docker packaging, MCP integration, and a security-conscious README. The "palace" metaphor is applied consistently and the benchmark discipline (held-out splits, honest caveats) is unusually good for this category. The core ideas — verbatim storage, structured scoping, local-only privacy — are simple but well-executed, and the agent-hook ecosystem (Claude Code, Codex, Cursor) makes it immediately actionable. Worth a look if you're building agent memory or evaluating the Mem0/Zep ecosystem.