From install to first memory search. Covers pip, Claude Code plugin, MCP server, local models, auto-save hooks, and knowledge graph.
Requires Python 3.9+, chromadb≥0.4.0, pyyaml≥6.0. Works on macOS, Linux, Windows.
pip install mempalace
mempalace --version should output 3.0.0.
The guided init command auto-detects the people and projects in your directory,
creates your wing structure, generates the AAAK bootstrap, and writes ~/.mempalace/config.json,
wing_config.json, and identity.txt (your Layer 0 context).
mempalace init ~/projects/myapp # Creates ~/.mempalace/ with: # config.json — global settings + palace path # wing_config.json — your people & projects mapped to wings # identity.txt — Layer 0, always loaded on wake-up
Three mining modes: projects (code & docs), convos (conversation exports), general (auto-classifies into decisions, preferences, milestones, problems, emotional context). If your exports are concatenated into huge files, split them first.
# Split large concatenated exports into per-session files first mempalace split ~/chats/ --dry-run # preview mempalace split ~/chats/ # Mine conversation exports (Claude, ChatGPT, Slack) mempalace mine ~/chats/ --mode convos # Mine with auto-classification (decisions, milestones, problems) mempalace mine ~/chats/ --mode convos --extract general # Mine project files (code, docs, notes) mempalace mine ~/projects/myapp # Tag conversations with a specific wing name mempalace mine ~/chats/work/ --mode convos --wing driftwood
claude plugin marketplace add milla-jovovich/mempalace claude plugin install --scope user mempalace # Restart Claude Code → type /skills → verify "mempalace" appears
claude mcp add mempalace -- python -m mempalace.mcp_server # Your AI now has 19 MemPalace tools. It learns the AAAK dialect # automatically from the mempalace_status response.
# Wake-up command — loads L0+L1 context (~170 tokens) mempalace wake-up > context.txt # Paste context.txt into your local model's system prompt # Or use the Python API directly from mempalace.searcher import search_memories results = search_memories("auth decisions", palace_path="~/.mempalace/palace")
# Search everything mempalace search "why did we switch to GraphQL" # Narrow by wing (person/project) mempalace search "auth decisions" --wing driftwood # Narrow by room (topic) mempalace search "Clerk vs Auth0" --room auth-migration # Load L0+L1 wake-up context (170 tokens = critical facts) mempalace wake-up # Project-specific wake-up mempalace wake-up --wing driftwood # Check palace stats mempalace status
Two shell hooks keep your palace updated automatically during Claude Code sessions: the Save Hook fires every 15 messages and saves topics, decisions, quotes, and code changes. The PreCompact Hook fires before context compression — an emergency save before the window shrinks.
{
"hooks": {
"Stop": [{
"matcher": "",
"hooks": [{
"type": "command",
"command": "/path/to/mempalace/hooks/mempal_save_hook.sh"
}]
}],
"PreCompact": [{
"matcher": "",
"hooks": [{
"type": "command",
"command": "/path/to/mempalace/hooks/mempal_precompact_hook.sh"
}]
}]
}
}
MEMPAL_DIR environment variable to a directory path and the hooks will automatically run mempalace mine on that directory during each save trigger.
MemPalace includes a free, local alternative to Zep's Graphiti — temporal entity-relationship triples stored in SQLite. Track who decided what, when, and why. Facts have validity windows; when something stops being true, invalidate it.
from mempalace.knowledge_graph import KnowledgeGraph kg = KnowledgeGraph() kg.add_triple("Kai", "works_on", "Orion", valid_from="2025-06-01") kg.add_triple("Maya", "assigned_to", "auth-migration", valid_from="2026-01-15") # Query current state kg.query_entity("Kai") → [Kai → works_on → Orion (current)] # Query historical state kg.query_entity("Maya", as_of="2026-01-20") → [Maya → assigned_to → auth-migration (active)] # Invalidate when something changes kg.invalidate("Kai", "works_on", "Orion", ended="2026-03-01")
Create agents that focus on specific areas — code reviewer, architect, ops engineer. Each agent gets its own wing and AAAK-compressed diary in the palace. Add 50 agents, your CLAUDE.md stays one line.
{
"name": "reviewer",
"focus": "code quality, patterns, security bugs",
"wing": "wing_reviewer"
}
# Your CLAUDE.md just needs:
# "You have MemPalace agents. Run mempalace_list_agents to see them."
Known issue, tracked in Issue #74.
Pin ChromaDB: pip install "chromadb==0.5.x" (check issue for latest tested version).
Tracked in Issue #47.
Set environment variable: PYTHONIOENCODING=utf-8
Tracked in Issue #100. The team is pinning a tested ChromaDB range. Check the issue for the current recommended version.
Tracked in Issue #110. A fix is in progress. For now, avoid using untrusted input in hook-triggered paths.