enuno/mempalace

MemPalace Skill

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.

When to Use This Skill

• Setting up persistent memory for Claude Code or another LLM agent
• Mining project files (mempalace mine) or Claude Code transcripts (--mode convos)
• Retrieving forgotten context from past sessions (mempalace search, wake-up)
• Wiring auto-save hooks so sessions survive context compression
• Installing and configuring the MCP server (29 palace tools)
• Managing the knowledge graph (entities, predicates, temporal relationships)
• Backfilling existing ~/.claude/projects/ JSONL transcripts
• Repairing, deduplicating, or migrating a corrupted or upgraded palace
• Writing custom storage backends or switching embedding models
• Reproducing or extending memory benchmarks

Core Architecture

Palace 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)

4-Layer Memory Stack (token budget)

| 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.

Install

# 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

Key CLI Commands

Initialize a palace for a project

mempalace init ~/projects/myapp

Mine content into the palace

# 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

Sweep — store one drawer per message (per-message granularity)

# Idempotent and resume-safe; run periodically for fine-grained recall
mempalace sweep ~/.claude/projects/myapp/

Search past sessions

mempalace search "why did we switch to GraphQL"
mempalace search "auth bug fix" --wing myapp

Load memory context for a new session

mempalace wake-up

Knowledge graph

# Query graph (entities, relationships, timelines)
mempalace status          # palace overview

Hooks

mempalace hook install    # wire stop + precompact hooks
mempalace hook status     # verify hooks are active

Repair and maintenance

mempalace repair          # consistency checks
mempalace repair --status # dry-run report
mempalace migrate         # ChromaDB version migration

Claude Code Hooks

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"

MCP Server

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:

• Palace read/write (drawers, rooms, wings)
• Knowledge graph (entity add/query/invalidate, timeline)
• Agent diaries (per-agent wings, diary entries)
• Cross-wing navigation and tunnels
• mempalace_list_agents — discover agent wings at runtime (no system-prompt bloat)

Design Principles (non-negotiable)

• Verbatim always — never summarizes, paraphrases, or lossy-compresses user data
• Incremental only — append-only after initial build; crashes leave existing palace untouched
• Entity-first — keyed by real names with DOB/ID disambiguation
• Local-first — zero external API by default; BYOK (Anthropic, OpenAI, Google) is explicit and never silent
• Performance budgets — hooks <500ms, startup injection <100ms
• Privacy by architecture — data physically cannot leave the machine for core operations

Benchmarks

| 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.

Storage Backends

Default: ChromaDB. To add a custom backend:

1. Subclass mempalace/backends/base.py
2. Register in backends/__init__.py

Key Source Files

| 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 |

Examples

Example 1: Claude Code retention setup (fastest path)

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

Example 2: Per-message granularity (sweep after mining)

# After mining, sweep for one drawer per message
mempalace sweep ~/.claude/projects/myapp/
# Subsequent sweeps are idempotent — safe to run repeatedly

Example 3: Multi-agent palace

# Each agent gets its own wing and diary
# Discover agents at runtime (no system-prompt bloat):
mempalace_list_agents   # via MCP tool

Example 4: Backfill existing JSONL transcripts

# Mine all existing Claude Code sessions retroactively
mempalace mine ~/.claude/projects/ --mode convos
# Then sweep for message-level granularity
mempalace sweep ~/.claude/projects/

Resources

• Docs: https://mempalaceofficial.com/guide/getting-started
• CLI reference: https://mempalaceofficial.com/reference/cli
• Python API: https://mempalaceofficial.com/reference/python-api
• MCP tools: https://mempalaceofficial.com/reference/mcp-tools
• Knowledge graph: https://mempalaceofficial.com/concepts/knowledge-graph
• Hooks guide: https://mempalaceofficial.com/guide/hooks
• Retention checklist: https://mempalaceofficial.com/guide/claude-code-retention
• GitHub: https://github.com/MemPalace/mempalace