mempalace — Summary

mempalace (MemPalace/mempalace) is a local-first AI memory system built on verbatim storage and semantic retrieval. It achieves 96.6% R@5 on LongMemEval without any LLM or API key — raw semantic search only. The palace is a spatial hierarchy: wings (people/projects) → rooms (topics) → drawers (verbatim content). A pluggable backend ABC defaults to ChromaDB; SQLite backs the temporal knowledge graph. The Python CLI (mempalace) installs via uv tool install mempalace. Claude Code integration ships 5 slash-commands, 1 skill, and 2 hooks (Stop + PreCompact). The MCP server exposes 30 tools covering palace reads/writes, knowledge graph operations, cross-wing navigation, tunnel management (cross-wing shortcuts), drawer CRUD, and agent diaries. Multi-agent support: each specialist agent gets its own wing and diary, discoverable via mempalace_list_agents. 52,851 stars, MIT license, 30 contributors, actively developed (pushed 2026-05-26).

Differs from seeds: closest to agentmemory (persistent memory, hybrid search, MCP-anchored, knowledge graph) but mempalace stores content verbatim (never summarizes), ships a 4-layer memory stack with explicit token budgets, uses ChromaDB as the default backend (pluggable via ABC), and achieves 96.6% R@5 without any LLM at any stage. It competes with Zep's temporal knowledge graph using local SQLite instead of Neo4j. Its security posture is unusually explicit: the README prominently warns about impostor sites distributing malware.

mempalace — Origin and Philosophy

Origin

Author: milla-jovovich (MemPalace org). 52,851 stars, 6,966 forks. MIT license. Python. Version 3.3.6. Develop branch is the active branch. 30 contributors. Website: mempalaceofficial.com.

The project description: "Local-first AI memory. Verbatim storage, pluggable backend, 96.6% R@5 raw on LongMemEval — zero API calls."

Philosophy

The central design choice is verbatim storage: MemPalace does not summarize, extract, or paraphrase. Every drawer stores the original text. This is a deliberate contrast with systems like agentmemory (LLM compression) and mem0 (extraction-based).

"MemPalace stores your conversation history as verbatim text and retrieves it with semantic search. It does not summarize, extract, or paraphrase."

The indexing is structured, not flat: rather than a single corpus, content is organized into wings (people, projects), rooms (topics), and drawers (verbatim units). Searches can be scoped to a wing or room rather than run against everything.

The retrieval layer is local and free: the 96.6% R@5 requires no API key, no cloud, and no LLM at any stage. The hybrid pipeline adds keyword boosting and temporal-proximity boosting to push to 98.4%. LLM rerank can push above 99%, but "we do not headline a '100%' number because the last 0.6% was reached by inspecting specific wrong answers."

The 4-Layer Memory Stack

layers.py defines explicit token budgets:

• Layer 0 — Identity (~100 tokens): Always loaded. Reads from ~/.mempalace/identity.txt.
• Layer 1 — Essential Story (~500–800 tokens): Always loaded. Top moments from the palace.
• Layer 2 — On-Demand (~200–500 tokens each): Loaded when a topic/wing comes up.
• Layer 3 — Deep Search (unlimited): Full ChromaDB semantic search.

"Wake-up cost: ~600–900 tokens (L0+L1). Leaves 95%+ of context free."

Temporal Knowledge Graph

The knowledge graph (knowledge_graph.py) positions itself against Zep:

"This is what competes with Zep's temporal knowledge graph. Zep uses Neo4j in the cloud ($25/mo+). We use SQLite locally (free)."

Default path: ~/.mempalace/knowledge_graph.sqlite3.

Security Posture

The README prominently warns:

"Beware of impostor sites. MemPalace has no other official websites. The only official sources are this GitHub repository, the PyPI package, and mempalaceofficial.com. Any other domain (including .tech, .net, or other .com variants) is an impostor and may distribute malware."

This is unusual in the AI tools space and suggests the project has been targeted by typosquatters.

Claude Code Retention Warning

"Claude Code sessions expire in 30 days without auto-save hooks wired."

The Stop and PreCompact hooks are presented as essential safety infrastructure, not optional enhancements.

mempalace — Architecture

Distribution

Python package on PyPI. Recommended install:

uv tool install mempalace   # isolated environment, mempalace CLI on PATH
mempalace init ~/projects/myapp

Also: pipx install mempalace or pip install mempalace (inside venv only — PEP 668 errors on system Pythons).

Version 3.3.6 as of analysis.

Required Runtime

• Python 3.9+
• ChromaDB (default backend, installed as dependency)
• ~300 MB disk for embedding model (embeddinggemma-300m recommended, multilingual 100+ languages; or all-MiniLM-L6-v2 English-only ~30 MB)
• No API key required for core path

Server Architecture

mempalace CLI
      ↓
mempalace/cli.py — 15 subcommands (init, mine, sweep, sync, search, wakeup,
                   split, migrate, status, repair-status, repair, hook,
                   instructions, mcp, compress)
      ↓
mempalace/palace.py — palace operations via backend layer
      ├── mempalace/backends/chroma.py — ChromaDB backend (default)
      ├── mempalace/backends/base.py — BaseBackend ABC (pluggable)
      └── mempalace/backends/registry.py — backend registry

State:
  ChromaDB collections (default): mempalace_drawers, mempalace_closets
  SQLite: ~/.mempalace/knowledge_graph.sqlite3
  Identity: ~/.mempalace/identity.txt

MCP: mempalace/mcp_server.py — 30 tools (stdio via mempalace-mcp binary)

Repository Structure

MemPalace/mempalace/ (develop branch)
├── mempalace/
│   ├── __init__.py
│   ├── cli.py              # 15 CLI subcommands
│   ├── mcp_server.py       # 30 MCP tools (stdio)
│   ├── palace.py           # Core palace operations
│   ├── backends/
│   │   ├── base.py         # BaseBackend ABC, BaseCollection ABC
│   │   ├── chroma.py       # ChromaDB backend
│   │   └── registry.py     # Backend registry
│   ├── knowledge_graph.py  # Temporal entity-relationship graph (SQLite)
│   ├── layers.py           # 4-layer memory stack (L0–L3)
│   ├── miner.py            # File mining pipeline
│   ├── convo_miner.py      # Conversation (JSONL) mining
│   ├── convo_scanner.py    # Claude Code JSONL scanner
│   ├── embedding.py        # Local embedding model
│   ├── hooks_cli.py        # Hook implementation (called by shell scripts)
│   ├── onboarding.py       # Interactive onboarding
│   └── ...                 # 30+ additional modules
├── .claude-plugin/
│   ├── plugin.json         # v3.3.6
│   ├── .mcp.json           # MCP server wiring
│   ├── commands/           # 5 slash commands
│   ├── hooks/              # 2 hook scripts (Stop + PreCompact)
│   └── skills/             # 1 skill (mempalace/)
├── benchmarks/             # LongMemEval, LoCoMo, ConvoMem, MemBench
└── docs/
    └── HISTORY.md          # Public corrections and security notices

Backend Abstraction (RFC 001)

BaseBackend ABC defines get_collection(palace_path, collection_name, create). Any implementation that satisfies the interface can replace ChromaDB. The registry (backends/registry.py) allows drop-in backend substitution.

Error hierarchy: BackendError → PalaceNotFoundError → CollectionNotInitializedError | BackendClosedError | UnsupportedFilterError. Silent dropping of unknown filter operators is explicitly forbidden by spec.

Normalization Versioning

NORMALIZE_VERSION = 2 (as of 2026-04). When the normalization pipeline changes, the version bumps and existing drawers are rebuilt on the next mine pass. file_already_mined treats drawers with missing/stale normalize_version as "not mined." No user action required.

mempalace — Components

5 Slash-Commands (Claude Code)

All in .claude-plugin/commands/:

Command pattern (from init.md): commands delegate to the generic mempalace skill via Skill tool with the <command> command, then follow its instructions. The skill calls mempalace instructions <command> to fetch live instructions from the CLI.

1 Skill

mempalace skill (SKILL.md):

MemPalace provides dynamic instructions via the CLI. To get instructions for any operation:
  mempalace instructions <command>
Where <command> is one of: help, init, mine, search, status.
Run the appropriate instructions command, then follow the returned instructions step by step.

Allowed tools: Bash, Read, Write, Edit, Glob, Grep.

2 Hooks

Both hooks are thin bash wrappers calling mempalace hook run --hook <event> --harness claude-code. All logic lives in mempalace/hooks_cli.py for cross-harness extensibility.

Hook fallback chain: tries mempalace CLI → python3 -m mempalace → python -m mempalace → error message to stderr.

30 MCP Tools (stdio, via mempalace-mcp binary)

Palace navigation:

• mempalace_status — server health and palace status
• mempalace_list_wings — list all wings (people/project namespaces)
• mempalace_list_rooms — list rooms within a wing
• mempalace_get_taxonomy — full wing/room/drawer taxonomy
• mempalace_get_aaak_spec — get palace specification

Knowledge graph:

• mempalace_kg_query — query entities/relations (point-in-time)
• mempalace_kg_add — add entity/relation triple with validity window
• mempalace_kg_invalidate — mark a fact as no longer valid
• mempalace_kg_timeline — get entity timeline
• mempalace_kg_stats — knowledge graph statistics

Graph/tunnel navigation:

• mempalace_traverse — traverse the palace graph from a node
• mempalace_find_tunnels — find tunnels (cross-wing shortcuts)
• mempalace_graph_stats — overall graph statistics
• mempalace_create_tunnel — create a cross-wing shortcut
• mempalace_list_tunnels — list all tunnels
• mempalace_delete_tunnel — remove a tunnel
• mempalace_follow_tunnels — navigate via tunnels

Search and drawer ops:

• mempalace_search — semantic search across palace
• mempalace_check_duplicate — dedup check before adding
• mempalace_add_drawer — add verbatim content
• mempalace_delete_drawer — remove a drawer
• mempalace_sync — sync the palace
• mempalace_get_drawer — get specific drawer by ID
• mempalace_list_drawers — list drawers in a room
• mempalace_update_drawer — update drawer content

Agent diaries:

• mempalace_diary_write — write to agent's diary
• mempalace_diary_read — read agent's diary entries

System:

• mempalace_hook_settings — get/set hook configuration
• mempalace_memories_filed_away — get session filing summary
• mempalace_reconnect — reconnect to backend

Note: README says "29 MCP tools" but mcp_server.py defines 30 named tools.

CLI Commands (15 subcommands)

mempalace init <palace_path>            # initialize palace
mempalace mine <path> [--mode]         # mine files (default) or convos
mempalace sweep <transcript_dir>       # per-message sweep (idempotent)
mempalace sync                          # sync palace
mempalace search "<query>"             # semantic search
mempalace wake-up / wakeup             # load L0+L1 context for session
mempalace split                         # split large drawers
mempalace migrate                       # migrate palace schema
mempalace status                        # palace health
mempalace repair-status                # detailed repair diagnostics
mempalace repair                        # repair corrupted palace
mempalace hook run --hook <event>      # internal hook runner
mempalace instructions <command>       # dynamic CLI instructions (used by skill)
mempalace mcp                          # run MCP server
mempalace compress                     # compress palace

mempalace — Uniqueness and Positioning

Differs from Seeds

Closest to agentmemory (persistent memory, hybrid search, MCP-anchored, knowledge graph, Claude Code plugin + hooks) but with fundamental design differences:

1. Verbatim storage: agentmemory compresses observations via LLM. mempalace stores everything verbatim — "it does not summarize, extract, or paraphrase." This is a principled stance: verbatim recall is higher fidelity even if noisier.

2. 96.6% R@5 without any LLM: agentmemory achieves 95.2% R@5 but requires local embeddings (all-MiniLM-L6-v2) plus optional LLM compression. mempalace achieves 96.6% with zero LLM at any stage, 98.4% with purely algorithmic boosting (keyword + temporal proximity), 99%+ with LLM rerank. The gap matters: no API key, no API cost, no API dependency.

3. Spatial hierarchy vs flat observations: agentmemory stores observations in a flat per-session KV. mempalace has a 3-tier spatial hierarchy (wings → rooms → drawers). Searches can be scoped to a wing/room rather than always running against the full corpus.

4. 4-layer token budget: mempalace defines explicit token budgets (L0: 100, L1: 500–800, L2: 200–500, L3: unlimited). "Wake-up cost: 600–900 tokens. Leaves 95%+ of context free." agentmemory has no equivalent layered context loading model.

5. Dynamic instructions pattern: The skill calls mempalace instructions <command> to fetch live instructions from the CLI at runtime. Prompt updates ship with pip upgrades, not plugin reinstalls. agentmemory's skills contain static instruction text.

6. Pluggable backend ABC: RFC 001 defines a formal BaseBackend interface. ChromaDB is the default, but any conforming implementation can drop in. agentmemory is tightly coupled to iii-engine's SQLite StateModule.

7. Temporal knowledge graph in local SQLite: Both systems have knowledge graphs; mempalace's runs in ~/.mempalace/knowledge_graph.sqlite3 with explicit point-in-time queries. No Neo4j, no cloud ($25/mo+).

Security Stance

Unusually explicit: README warns about impostor sites distributing malware. docs/HISTORY.md maintains a public correction and incident log. This is the only framework in the Phase B corpus with a formal public security notice.

Benchmark Honesty

Does not make comparative claims against competitors because "those projects publish different metrics on different splits, and placing retrieval recall next to end-to-end QA accuracy is not an honest comparison." Does not headline 100% because "the last 0.6% was reached by inspecting specific wrong answers." Publishes full per-question result files in benchmarks/results_*.

Observable Failure Modes

1. ChromaDB version sensitivity: ChromaDB has a history of breaking schema changes between minor versions. palace.py's NORMALIZE_VERSION versioning partially mitigates this, but upstream ChromaDB changes can still break the backend silently.

2. 30 vs 19 vs 29 MCP tool count skew: plugin.json says "19 MCP tools", README says "29 MCP tools", mcp_server.py defines 30. Three different counts for the same thing — the plugin description is significantly stale.

3. Wake-up is manual: Unlike agentmemory's SessionStart context injection, mempalace's L0+L1 loading requires the user or agent to call mempalace wake-up. Agents that don't invoke the skill at session start get no prior context automatically.

4. PreCompact 90s timeout: Mining the current session before compaction takes up to 90 seconds. Long sessions with many files can exceed this, leaving the compacted context without fresh memories.

5. Single palace per mining run: Each mempalace mine <path> targets a single palace. Multi-project setups require multiple mine calls and manual wing management.