MemPalace: Local-First AI Memory System

1. Project Overview

MemPalace is a local-first, open-source AI memory system that stores an AI agent's conversation history verbatim and retrieves it with semantic search, solving the problem of coding agents and chatbots "forgetting" everything once a session ends or the context window compacts.

2. Background & Positioning

MemPalace was created to fix a very specific pain point: long-running agent sessions (in tools like Claude Code) lose earlier context after compaction, forcing the agent to ask "what are we doing today?" even after hours of prior work. Its core mission is to combine two things most memory tools trade off against each other — storing everything with full fidelity, and finding the right piece of it instantly, including from a vague, half-remembered query.

Architecturally, it borrows from the Zettelkasten method (small, cross-referenced index cards), organizing memory into a hierarchy of wings (people/projects), rooms (topics), closets (compressed, AI-readable index entries), and drawers (the original verbatim content). This differs from most memory frameworks in two ways: it never summarizes or paraphrases what it stores (retrieval always returns the original text), and its retrieval backend is pluggable rather than tied to one vector database, so teams can start local-only and move to a server-backed store without changing how the rest of the system works.

3. Feature Categories

🗂️ Palace Storage — verbatim, structured storage across wings/rooms/closets/drawers; core operations include mine, search, wake-up, and per-message sweep; purpose: preserve full conversation fidelity while keeping it navigable.
🔌 Pluggable Backends — 5 supported stores: chroma (default, embedded), sqlite_exact, milvus, qdrant, pgvector; purpose: let users start local and scale to a shared server without re-architecting.
🕸️ Knowledge Graph — a temporal entity-relationship graph with validity windows, backed by local SQLite; supports add/query/invalidate/timeline operations; purpose: track how facts and relationships change over time, not just static snapshots.
🔧 MCP Server & Tools — 45 MCP tools covering palace reads/writes, knowledge-graph operations, cross-wing navigation, drawer management, agent diaries, and multi-agent coordination; purpose: expose memory as a first-class capability to any MCP-compatible agent.
🪝 Auto-Save Hooks — hooks for Claude Code, Codex CLI, and Cursor IDE that save periodically and before context compression; purpose: capture sessions automatically, with no manual "please remember this" step.
🤖 Multi-Agent Support — each specialist agent gets its own wing and diary, discoverable at runtime via mempalace_list_agents; purpose: let multiple agents share a memory system without polluting each other's context or the system prompt.

4. Key Highlights

Verbatim retrieval, not summarization — search results return the original text, so nothing is lost to lossy compression along the way.
Local-first and offline-capable — the core benchmark path (96.6% R@5 on LongMemEval) requires no API key, no cloud, and no LLM call at any stage.
Benchmarked, reproducible results — every published number (LongMemEval, LoCoMo, ConvoMem, MemBench) ships with the exact commands to reproduce it from the repository.
Optional hybrid + LLM rerank pipeline — keyword boosting, temporal-proximity boosting, and preference-pattern extraction push recall to 98.4% held-out, with an LLM-rerank option reaching ≥99%, and it is model-agnostic (tested with Claude, and with open models via Ollama Cloud).
Silent background operation — as of the current design, diary writes and palace filing run in background hooks/subagents rather than in the visible chat, cutting token overhead from re-transmitted status updates.
Multi-arch Docker support — a published container image runs natively on both amd64 and arm64 (including Apple Silicon), with a separate CUDA build for GPU workloads.

5. Use Cases by Role

General developers — keep an AI coding assistant's project context across sessions instead of re-explaining decisions after every compaction or restart.
Data / research scientists — mine and search large volumes of past conversations or notes semantically, and reproduce the project's own retrieval benchmarks as a reference implementation.
Project managers / teams — mine shared Claude Code transcripts into a common palace (a "shared-brain hub") so team knowledge and decisions stay searchable in one place rather than scattered across individual chat histories.

6. Getting Started

Find what you need — browse the docs site for guides and reference material:

https://mempalaceofficial.com/guide/getting-started.html

Install / integrate — recommended isolated install via uv, then initialize a palace:

uv tool install mempalace
mempalace init ~/projects/myapp
mempalace mine ~/projects/myapp
mempalace search "why did we switch to GraphQL"

Agent-guided setup is also available by installing the project's skills:

npx skills add MemPalace/mempalace

Contribute — read the contribution guide before opening a PR:

https://github.com/MemPalace/mempalace/blob/main/CONTRIBUTING.md

7. Project Structure

mempalace/
├── backends/          # pluggable storage backend implementations (chroma, qdrant, pgvector, ...)
├── data/              # bundled data assets
├── i18n/              # internationalization resources
├── instructions/      # agent-facing instruction sets
├── integrations/      # third-party tool integrations
├── sources/           # ingestion sources for mining
├── cli.py             # `mempalace` command-line entry points
├── mcp_server.py       # MCP server implementation (tool exposure)
├── knowledge_graph.py  # temporal entity-relationship graph
├── palace.py           # core palace read/write logic
├── miner.py / convo_miner.py  # content and conversation mining pipelines
├── searcher.py         # semantic search / retrieval logic
└── onboarding.py        # first-run setup and embedding-model selection

Other top-level directories worth knowing: benchmarks/ (reproducible benchmark scripts and results), hooks/ (auto-save hook implementations for supported editors/agents), skills/ (installable agent skills), and website/ (source for the documentation site).

8. Related Ecosystem

Upstream dependencies: ChromaDB (default vector store), with optional support for Milvus, Qdrant, and pgvector; ONNX Runtime and embedding models (all-MiniLM-L6-v2, embeddinggemma-300m) for local embeddings.
Agent/editor integrations: Claude Code, Codex CLI, Cursor IDE, Gemini CLI, and Antigravity, connected via the Model Context Protocol (MCP).
Complementary tooling: any OpenAI-compatible /v1/embeddings endpoint (LM Studio, llama.cpp, vLLM, Ollama) can be used for remote or GPU-accelerated embedding instead of local computation.

9. License

✅ Commercial use, modification, distribution, and private use are permitted under the MIT License.
❌ The license provides no warranty and no liability coverage for the authors.
ℹ️ The original copyright and license notice must be retained in copies or substantial portions of the software.

10. FAQ

Q: Does MemPalace require an API key or cloud service to work?
A: No. The core benchmark path, including the 96.6% R@5 raw retrieval score on LongMemEval, runs entirely locally with the default chroma backend and no LLM calls.

Q: Which vector database does MemPalace use?
A: ChromaDB by default, with pluggable support for sqlite_exact, milvus, qdrant, and pgvector, selectable via --backend <name> or MEMPALACE_BACKEND.

Q: Can MemPalace run without a local Python environment?
A: Yes, via the published multi-arch Docker image:

docker pull ghcr.io/mempalace/mempalace:latest

Q: How do I keep a Claude Code session's context after compaction?
A: Wire up the auto-save hooks described in the Claude Code retention setup checklist, then backfill existing transcripts with:

mempalace mine ~/.claude/projects/ --mode convos

Q: Are there official websites besides the GitHub repository?
A: The only official sources are the GitHub repository, the PyPI package (mempalace), and the documentation at mempalaceofficial.com; other similarly named domains are not affiliated with the project.

11. Quick Links

Repository: https://github.com/MemPalace/mempalace
Official docs: https://mempalaceofficial.com
Contributing guide: https://github.com/MemPalace/mempalace/blob/main/CONTRIBUTING.md
Community: https://discord.com/invite/ycTQQCu6kn

12. Summary

MemPalace fills a practical gap for anyone building or using long-running AI agents: it keeps full, verbatim conversation history that stays fast and precise to search, instead of forcing a choice between storing everything and finding anything. Developers integrating coding agents like Claude Code, Codex, or Cursor get persistent, reproducible-benchmarked memory with no mandatory cloud dependency, while teams can scale the same system from a private local palace to a shared backend as their needs grow.