// MemPalace local-first AI memory system. Use when setting up persistent memory for Claude Code sessions, mining project files or conversation transcripts, querying past context, configuring MCP tools, managing the knowledge graph, or troubleshooting palace operations.
| name | mempalace |
| description | MemPalace local-first AI memory system. Use when setting up persistent memory for Claude Code sessions, mining project files or conversation transcripts, querying past context, configuring MCP tools, managing the knowledge graph, or troubleshooting palace operations. |
| triggers | ["When setting up persistent memory for Claude Code or another AI agent","When mining project files, repos, or conversation transcripts into a palace","When searching past sessions or retrieving forgotten context","When wiring auto-save hooks (stop hook, precompact hook)","When configuring the MCP server (29 tools) for palace reads/writes","When working with the knowledge graph (entities, relationships, timelines)","When backfilling existing JSONL transcripts into memory","When troubleshooting palace repair, deduplication, or migration","When adding a new storage backend or customizing the embedding model","When running LongMemEval or other memory benchmarks"] |
MemPalace (v3.3.6) is a local-first AI memory system. It stores conversation history and project content verbatim — no summarization, no paraphrasing, no external API calls by default. Retrieval uses hybrid BM25 + semantic search, achieving 96.6% R@5 on LongMemEval with zero LLM involvement.
mempalace mine) or Claude Code transcripts (--mode convos)mempalace search, wake-up)~/.claude/projects/ JSONL transcriptsPalace structure:
WING — broad category (person, project, topic)
└── ROOM — time-based grouping (day, session)
└── DRAWER — verbatim text chunk (exact words)
Index layer (AAAK dialect):
Compressed pointers → DRAWER locations
LLM scans AAAK index to know which drawer to open — no full content read needed
Knowledge Graph (SQLite):
ENTITY → PREDICATE → ENTITY (with valid_from / valid_to dates)
| Layer | Tokens | Loaded | Purpose |
|---|---|---|---|
| L0 | ~100 | Always | Identity — ~/.mempalace/identity.txt |
| L1 | ~500–800 | Always | Essential story — top moments from the palace |
| L2 | ~200–500 each | On demand | Wing/topic content when referenced |
| L3 | Unlimited | On demand | Full ChromaDB semantic search |
mempalace wake-up loads L0+L1 (~600–900 tokens total), leaving 95%+ of context free.
# Recommended — isolates deps, puts CLI on PATH
uv tool install mempalace
# Or with pipx
pipx install mempalace
# Inside an activated venv only
pip install mempalace
Python 3.9+ required. ChromaDB is the default backend (~300 MB for the embedding model).
First-run setup (choose embedding model, configure palace path):
python -m mempalace.onboarding
mempalace init ~/projects/myapp
# Project source files
mempalace mine ~/projects/myapp
# Claude Code conversation transcripts
mempalace mine ~/.claude/projects/ --mode convos
# Scope to a specific wing (person/project)
mempalace mine ~/.claude/projects/myapp --wing myapp
# Idempotent and resume-safe; run periodically for fine-grained recall
mempalace sweep ~/.claude/projects/myapp/
mempalace search "why did we switch to GraphQL"
mempalace search "auth bug fix" --wing myapp
mempalace wake-up
# Query graph (entities, relationships, timelines)
mempalace status # palace overview
mempalace hook install # wire stop + precompact hooks
mempalace hook status # verify hooks are active
mempalace repair # consistency checks
mempalace repair --status # dry-run report
mempalace migrate # ChromaDB version migration
Two hooks ship with MemPalace for automatic session persistence:
| Hook | Trigger | Purpose |
|---|---|---|
mempal_save_hook.sh | Stop | Saves session diary to palace before Claude exits |
mempal_precompact_hook.sh | PreCompact | Saves state before context compression |
Wire the hooks (required for automatic persistence):
mempalace hook install
The hooks must find the mempalace CLI. If installed via uv tool, ensure ~/.local/bin is on PATH inside the hook:
export PATH="$HOME/.local/bin:$PATH"
29 MCP tools cover palace reads/writes, knowledge-graph operations, cross-wing navigation, drawer management, and agent diaries.
# Start MCP server
mempalace mcp
Key tool categories:
mempalace_list_agents — discover agent wings at runtime (no system-prompt bloat)| Benchmark | Mode | Score |
|---|---|---|
| LongMemEval R@5 (500q) | Raw semantic, no LLM | 96.6% |
| LongMemEval R@5 (500q) | Hybrid v4, held-out 450q | 98.4% |
| LongMemEval R@5 (500q) | Hybrid v4 + LLM rerank | ≥99% |
| LoCoMo R@10 (1,986q) | Hybrid v5 | 88.9% |
| ConvoMem avg recall (250) | All categories | 92.9% |
| MemBench R@5 (8,500) | All categories | 80.3% |
Raw 96.6% requires no API key and no LLM at any stage.
Default: ChromaDB. To add a custom backend:
mempalace/backends/base.pybackends/__init__.py| Task | File |
|---|---|
| Add an MCP tool | mempalace/mcp_server.py — add handler + TOOLS dict entry |
| Change search | mempalace/searcher.py |
| Modify mining | mempalace/miner.py (files) or convo_miner.py (transcripts) |
| Add storage backend | Subclass mempalace/backends/base.py |
| Input validation | mempalace/config.py — sanitize_name() / sanitize_content() |
| AAAK compression | mempalace/dialect.py |
| 4-layer stack | mempalace/layers.py |
uv tool install mempalace
python -m mempalace.onboarding # choose embedding model
mempalace init ~/projects/myapp
mempalace mine ~/.claude/projects/ --mode convos --wing myapp
mempalace hook install # wire stop + precompact
mempalace wake-up # load L0+L1 into context
# After mining, sweep for one drawer per message
mempalace sweep ~/.claude/projects/myapp/
# Subsequent sweeps are idempotent — safe to run repeatedly
# Each agent gets its own wing and diary
# Discover agents at runtime (no system-prompt bloat):
mempalace_list_agents # via MCP tool
# Mine all existing Claude Code sessions retroactively
mempalace mine ~/.claude/projects/ --mode convos
# Then sweep for message-level granularity
mempalace sweep ~/.claude/projects/
GitBook documentation platform. Use when creating, publishing, or managing docs sites — content structure, blocks, Git Sync, customization, AI search, collaboration, and the GitBook API.
LangChain AWS integration — ChatBedrockConverse (Claude/Nova/Llama/Mistral on Bedrock), BedrockEmbeddings, AmazonKnowledgeBasesRetriever, BedrockAgentsRunnable, BedrockRerank, BedrockPromptCachingMiddleware, CodeInterpreterToolkit, BrowserToolkit (computer use), Neptune graph chains, and SageMaker endpoint.
LangChain Deep Agents (Python) — build, deploy, and customize stateful long-running agents with virtual filesystems, subagents, human-in-the-loop, and LangSmith observability. Also covers LangGraph, LangChain OSS chains/retrievers, and Agent Server API.
LangChain Exa integration — semantic web search with ExaSearchRetriever (RAG), ExaSearchResults (agent tool), and ExaFindSimilarResults (find similar URLs). Unique features: use_autoprompt (LLM query rewriting), highlights (excerpts), summary (per-result LLM summaries), livecrawl (real-time), and date filtering.
LangChain MCP Adapters — connect LangChain agents to MCP (Model Context Protocol) servers. Load MCP tools, prompts, and resources as LangChain-compatible objects. Supports stdio, SSE, StreamableHTTP, and WebSocket transports. Includes interceptors, callbacks, and multi-server management.
LangChain Neo4j integration — Neo4jGraph for Cypher queries and schema inspection, GraphCypherQAChain for natural-language-to-Cypher Q&A, Neo4jVector for vector/hybrid RAG, Neo4jSaver LangGraph checkpointer, Neo4jChatMessageHistory, and GraphDocument/Node/Relationship for knowledge graph construction.