MemPalace is a free, open-source, local-first AI memory system that stores conversation history, project files, and agent context as searchable verbatim memory. It organizes that memory into a palace structure and exposes it through a Python CLI, Python API, and MCP server.
The default setup uses ChromaDB and local embeddings on your machine. Shared HTTP serving and Milvus, Qdrant, or pgvector backends extend the same memory to teams and multi-machine agent setups. MemPalace reports 96.6% raw R@5 on LongMemEval for its local retrieval path.
For long-running coding and research work, the main value is continuity. Architecture decisions, debugging history, preferences, and project context stay available when a new session starts. The same memory can follow work across days, projects, and multiple agents.
Official Download
Install the Python package with uv:
uv tool install mempalaceHow MemPalace Works
MemPalace uses a memory-palace hierarchy to keep large memory collections navigable. People and projects become wings, topics become rooms, and original content lives in drawers. Search can span the full palace or use wing and room filters to narrow retrieval to one project or topic.
Raw drawers hold the original text. Closets hold compact notes that point back to those drawers, and AAAK supplies an experimental shorthand format for token-dense memory notes. Use the verbatim drawer text for exact quotes and detailed reasoning.
| Palace element | Role |
|---|---|
| Wing | A person, project, or other top-level memory area |
| Hall | A memory category such as facts, events, discoveries, preferences, or advice |
| Room | A topic inside a wing, such as authentication, database work, or planning |
| Closet | A compact note layer that points back to original content |
| Drawer | The original verbatim memory content and metadata |
| Hallway | A connection between related rooms inside one wing |
| Tunnel | A connection between related locations across wings |
Background and Inspiration
MemPalace was created by Milla Jovovich and Ben Sigman after Jovovich spent months manually organizing AI conversations and found that file organization alone did not make old reasoning easy for an LLM to retrieve.
The organizational model adapts the classical method of loci, where information is associated with locations in an imagined building. MemPalace applies that idea to AI history by mapping projects, people, topics, and original conversations to searchable palace locations.
Keeping the original conversation text preserves wording, code, trade-offs, and the reasoning behind decisions for later retrieval.
Features
- Stores AI conversations and project files as searchable verbatim memory.
- Organizes memory into wings, halls, rooms, closets, drawers, and tunnels.
- Exposes 44 MCP tools for memory, graph, diary, and coordination tasks.
- Tracks time-aware entity facts in a local SQLite knowledge graph.
- Auto-saves Claude Code, Codex CLI, and Cursor sessions through hooks.
- Runs a shared HTTP palace for team and multi-machine deployments.
- Coordinates agents through logstream events, acknowledgements, patches, and exact artifacts.
- Uses ChromaDB, SQLite Exact, Milvus, Qdrant, or pgvector storage.
- Mines project files, conversation exports, and optional office documents.
- Uses local embeddings or an OpenAI-compatible embedding endpoint.
- Ships Docker support for CLI and MCP server deployments.
- Generates compact wake-up context for identity and active project memory.
Use Cases
- Recover the reasoning behind architecture, database, authentication, deployment, and product decisions.
- Keep Claude Code, Codex, Cursor, Gemini, and other MCP clients on shared project memory.
- Search several projects with wing or room filters.
- Backfill Claude, ChatGPT, Slack, Markdown, and plain-text conversation exports.
- Share long-term memory across a team or a fleet of coding agents.
- Feed local models compact wake-up context or retrieved memory results.
How to Use MemPalace
1. Install MemPalace
MemPalace requires Python 3.9 or newer. Use uv or pipx for an isolated install. Use pip inside an activated virtual environment when Python code needs to import the package.
# Recommended
uv tool install mempalace
# Alternative isolated install
pipx install mempalace
# Virtual environment
python -m venv .venv
source .venv/bin/activate
pip install mempalace2. Initialize a Project
Initialize a project directory and create its palace configuration:
mempalace init ~/projects/myapp
# Use the current directory
mempalace init .3. Mine Project Files and Conversations
Mine code, documentation, notes, or conversation exports. --dry-run previews a mining pass before it writes memory.
# Project files
mempalace mine ~/projects/myapp
# Preview before filing memory
mempalace mine ~/projects/myapp --dry-run
# Conversation exports
mempalace mine ~/chats/ --mode convos
# Classify conversation content into memory types
mempalace mine ~/chats/ --mode convos --extract general
# Keep one project's history in a named wing
mempalace mine ~/chats/orion/ --mode convos --wing orionSplit multi-session transcript files before mining:
mempalace split ~/chats/ --dry-run
mempalace split ~/chats/
mempalace split ~/chats/ --min-sessions 3Install the extraction extra for office documents:
pip install "mempalace[extract]"
mempalace mine ~/documents/ --mode extract4. Search the Palace
Search the full palace or filter by wing and room:
mempalace search "why did we switch to GraphQL"
mempalace search "database decision" --wing orion
mempalace search "auth decisions" --wing orion --room auth
mempalace search "release blockers" --results 105. Connect an MCP Client
Run the MCP helper to print client setup syntax and resolve the active palace path:
mempalace mcp
mempalace mcp --palace ~/.custom-palace6. Load Context for a Local Model
Load compact wake-up context or retrieve only the memory needed for the current prompt:
mempalace wake-up > context.txt
mempalace search "auth decisions" > results.txt7. Use the Python API
The Python API supports the same wing and room filters:
from mempalace.searcher import search_memories
results = search_memories(
query="why did we switch to GraphQL",
wing="myapp",
room="architecture",
n_results=5,
)For team or multi-machine use, run the HTTP server behind bearer-token authentication and TLS or a trusted private network:
mempalace serve --host 127.0.0.1 --port 8765Core CLI Commands
| Command | Purpose |
|---|---|
mempalace init <dir> | Scan a project and initialize palace configuration |
mempalace mine <dir> | File project data or conversation exports into memory |
mempalace search "query" | Run semantic search with optional wing and room filters |
mempalace split <dir> | Split transcript mega-files into individual sessions |
mempalace wake-up | Print compact L0 and L1 session context |
mempalace compress | Create AAAK compact memory notes |
mempalace status | Show drawer, wing, and room status |
mempalace repair | Repair or rebuild palace indexes |
mempalace mcp | Print MCP client setup syntax |
mempalace hook run | Run Claude Code or Codex hook logic |
mempalace instructions | Print bundled skill instructions |
mempalace logstream | Append, list, wait for, watch, acknowledge, and sync coordination events |
mempalace artifact | Store and retrieve exact patch, file, log, JSON, or note artifacts |
mempalace serve | Run an HTTP MCP server for a shared palace |
Available MCP Tools
Palace Read Tools
| Tool | Description |
|---|---|
mempalace_status | Show drawer counts, wings, rooms, memory protocol, AAAK spec, and loaded library versions |
mempalace_list_wings | List wings with drawer counts |
mempalace_list_rooms | List rooms globally or inside one wing |
mempalace_get_taxonomy | Return the wing-to-room-to-drawer-count tree |
mempalace_search | Search verbatim drawers with optional wing and room filters |
mempalace_check_duplicate | Check content similarity before filing a new drawer |
mempalace_get_aaak_spec | Return the AAAK dialect specification |
Palace Filing and Management Tools
| Tool | Description |
|---|---|
mempalace_add_drawer | File verbatim content into a wing and room |
mempalace_checkpoint | Save several session items and an optional diary entry in one call |
mempalace_delete_drawer | Delete one drawer by ID |
mempalace_mine | Mine project files, conversations, or extracted documents |
mempalace_delete_by_source | Preview or delete every drawer filed from one source file |
mempalace_sync | Find and optionally prune drawers whose source files were removed or ignored |
mempalace_get_drawer | Read one drawer with its content and metadata |
mempalace_list_drawers | List drawers with pagination and wing or room filters |
mempalace_update_drawer | Update drawer content, wing, or room metadata |
Knowledge Graph Tools
| Tool | Description |
|---|---|
mempalace_kg_query | Query entity relationships with optional point-in-time filtering |
mempalace_kg_add | Store a time-aware entity relationship |
mempalace_kg_invalidate | Mark an existing fact as ended |
mempalace_kg_supersede | Replace a single-valued fact at one shared time boundary |
mempalace_kg_timeline | Return a chronological fact timeline |
mempalace_kg_stats | Show entity, triple, fact, and relationship counts |
Navigation Tools
| Tool | Description |
|---|---|
mempalace_traverse | Walk connected rooms from a starting room |
mempalace_find_tunnels | Find rooms that connect two wings |
mempalace_graph_stats | Show room, tunnel, edge, and connectivity statistics |
mempalace_create_tunnel | Create an explicit connection between locations in different wings |
mempalace_list_tunnels | List explicit cross-wing tunnels |
mempalace_delete_tunnel | Delete an explicit tunnel by ID |
mempalace_list_hallways | List within-wing entity co-occurrence connections |
mempalace_delete_hallway | Delete a hallway record by ID |
mempalace_follow_tunnels | Follow cross-wing tunnels and return connected room previews |
Agent Diary Tools
| Tool | Description |
|---|---|
mempalace_diary_write | Write a diary entry for one specialist agent |
mempalace_diary_read | Read recent diary entries for one agent |
System Tools
| Tool | Description |
|---|---|
mempalace_hook_settings | Read or update auto-save hook settings |
mempalace_memories_filed_away | Check the most recent palace checkpoint status |
mempalace_reconnect | Reconnect a long-running MCP session to palace storage |
Agent Coordination Tools
| Tool | Description |
|---|---|
mempalace_event_append | Append an immutable coordination event |
mempalace_event_list | List coordination events with routing and cursor filters |
mempalace_event_wait | Wait for matching coordination events with a timeout |
mempalace_event_ack | Acknowledge an event with a new reply event |
mempalace_artifact_put | Store exact patch, file, log, JSON, or note content |
mempalace_artifact_get | Retrieve an exact artifact with its SHA-256 metadata |
mempalace_patch_submit | Store a patch artifact and emit its patch-ready event |
mempalace_mesh_peers | Inspect peer reachability, replica state, version vectors, and node profiles |
Memory Stack Layers
A typical wake-up loads L0 + L1 in roughly 600 to 900 tokens. L2 and L3 retrieve more detail when a topic or explicit query needs it.
| Layer | Content | Typical Size | Load Trigger |
|---|---|---|---|
| L0 | AI identity | ~50–100 tokens | Always loaded |
| L1 | Essential story and top moments | ~500–800 tokens | Always loaded |
| L2 | Wing- or room-scoped recall | ~200–500 tokens per recall | Topic match |
| L3 | Full semantic search | Variable | Explicit query |
Configuration Files
~/.mempalace/config.json stores the palace path, collection name, entity mappings, backup retention, and backend selection.
{
"palace_path": "/custom/path/to/palace",
"collection_name": "mempalace_drawers",
"people_map": {"Kai": "KAI", "Priya": "PRI"},
"max_backups": 10
}Project Configuration
mempalace init creates mempalace.yaml with the project wing, room names, and palace path:
wing: myproject
rooms:
- backend
- frontend
- decisions
palace_path: ~/.mempalace/palaceEntity Mappings
entities.json stores detected people and their AAAK codes:
{
"Kai": "KAI",
"Priya": "PRI"
}Identity File
~/.mempalace/identity.txt stores the Layer 0 identity context:
I am Atlas, a personal AI assistant for Alice.
Traits: warm, direct, remembers everything.
People: Alice (creator), Bob (Alice's partner).
Project: A journaling app that helps people process emotions.Storage Backends and Privacy
ChromaDB and SQLite Exact keep palace data local. Milvus, Qdrant, and pgvector can point to local or network services. Their connection settings define where verbatim memory is stored.
| Backend | Mode | Install | Data location |
|---|---|---|---|
chroma | Local embedded default | Bundled | Local palace directory |
sqlite_exact | Local exact-vector backend | Bundled | Local SQLite database |
milvus | Milvus Lite or server | mempalace[milvus] | Local Lite database or configured Milvus service |
qdrant | REST server | Bundled client path | Configured Qdrant service |
pgvector | Postgres server | mempalace[pgvector] | Configured Postgres database |
96.6% LongMemEval Recall Explained
MemPalace reports 96.6% raw R@5 retrieval recall on 500 LongMemEval questions. The run checks whether the labeled relevant session appears in the top five results and uses no LLM, cloud API, or reranking step.
R@5 measures retrieval recall. End-to-end question answering uses different metrics. Compare memory benchmarks only when they evaluate the same task and metric.
| Mode | R@5 | LLM required | Interpretation |
|---|---|---|---|
| Raw semantic retrieval | 96.6% | No | Main reproducible retrieval headline |
| Hybrid v4 held-out 450-question set | 98.4% | No | Held-out hybrid retrieval result |
| Hybrid v4 with LLM reranking | 99%+ | Yes | Candidate retrieval followed by model reranking |
Auto-Save Hooks and Session Retention
MemPalace provides auto-save hooks for Claude Code, Codex CLI, and Cursor IDE. Claude Code session files expire after 30 days. Use the hooks or backfill transcripts to keep that history in MemPalace.
Claude Code and Codex hook logic can be invoked from the CLI:
mempalace hook run --hook stop --harness claude-code
mempalace hook run --hook precompact --harness claude-code
mempalace hook run --hook session-start --harness codexPer-Message Recall With Sweep
sweep files one verbatim drawer per user or assistant message and can be rerun safely over the same transcript directory:
mempalace sweep ~/.claude/projects/Agent Coordination and Artifact Handoffs
Teams running several coding agents can use the palace as a coordination channel alongside long-term memory. Agents can append task events to the logstream, wait for matching replies, acknowledge outcomes, exchange exact file or patch artifacts, and inspect peer state across shared deployments.
A background watcher can wait for several event types and persist its cursor across restarts. These commands target multi-agent coding and operations setups. Single-user memory setups can ignore them.
mempalace logstream watch \
--agent mac \
--type task.request \
--type patch.ready \
--state-file ~/.mempalace/watch/mac.json \
--jsonPros
- Free and open-source
- Local-first memory storage
- Verbatim conversation retention
- 44 MCP tools
- Team and multi-agent support
- Reproducible retrieval benchmarks
Cons
- Command-line setup
- Experimental AAAK compression
- Extra storage for large memory collections
- Some transcript exports need preprocessing
Alternatives & Related Resources
Alternatives
- Personal AI Memory: A Chrome extension that stores and recalls conversations from ChatGPT, Claude, Gemini, Perplexity, and Grok in browser IndexedDB.
- OpenMemory MCP: A local-first MCP memory server for storing context with topics, emotions, timestamps, and search.
- Memory Service MCP: A persistent MCP memory server with semantic retrieval, consolidation, and multi-client access.
Related Resources
- MemPalace GitHub Repository: Code, releases, issues, benchmark files, and project history.
- MemPalace on PyPI: Verified Python package and release files.
- Getting Started: Installation, project initialization, mining, and search setup.
- CLI Commands: Current command syntax and options.
- MCP Tools: Parameters and return values for the current MCP tool set.
- Codebase Memory MCP: A local repository knowledge graph for coding agents that need structural code memory.
FAQs
Q: Is MemPalace fully local?
A: The default ChromaDB and local-embedding workflow runs on your machine. Remote team servers, networked storage backends, and OpenAI-compatible embedding endpoints extend the data path to the services you configure.
Q: What does 96.6% R@5 mean?
A: The relevant LongMemEval session appeared among the top five retrieved results for 96.6% of the 500 benchmark questions in the raw retrieval run. This is a retrieval-recall metric.
Q: How do I keep Claude Code sessions in long-term memory?
A: Configure the MemPalace auto-save hooks and backfill existing Claude Code transcripts with mempalace mine ~/.claude/projects/ --mode convos. Claude Code session files expire after 30 days.
Q: Can a team share one MemPalace?
A: Yes. mempalace serve can run a central MCP server, and networked backends can hold the shared palace. Use bearer-token authentication plus TLS or a trusted private network for remote access.
Q: Where should I install MemPalace from?
A: Use the MemPalace package on PyPI or the MemPalace GitHub repository. Documentation is hosted at mempalaceofficial.com. Look-alike MemPalace domains are unaffiliated.
Changelog
August 23, 2026
- Updated the article for MemPalace v3.8.0 and the current 44-tool MCP set.
- Updated local-first storage, team server, configuration, memory-stack, and agent-coordination details.
- Clarified the 96.6% LongMemEval R@5 retrieval metric.
- Added the current installation security warning and verified distribution locations.
