Use the MemPalace CLI to persist, search, and manage AI memory across sessions. Triggers whenever the user asks to remember, recall, save, store, or retrieve information that should persist across conversations — including past decisions, preferences, facts about people or projects, conversation history, and any verbatim content the user wants preserved. Also triggers when the user mentions "palace", "wings", "rooms", "drawers", "knowledge graph", "AAAK", or when they want to search through historical context, traverse connections between topics, or check what their AI knows. Mirrors the MemPalace MCP server tools: each CLI command maps to an MCP tool with an equivalent trigger condition.
Use MemPalace CLI commands to store and retrieve persistent memory. Each command below mirrors an MCP server tool with the same trigger condition.
pip install mempalace
MemPalace organizes memory as a navigable building:
hall_facts, hall_events, hall_discoveries, hall_preferences, hall_adviceUnderlying storage: ChromaDB (semantic search) + SQLite (knowledge graph). Everything local, no API key.
Each command has a trigger condition that mirrors its MCP server counterpart.
mempalace init <dir>Mirrors: First-time setup (no direct MCP tool — prerequisite for all tools)
Trigger: User wants to set up MemPalace for the first time, or says "initialize my palace", "set up memory", "start mempalace".
mempalace init ~/projects/myapp
mempalace init ~/projects/myapp --yes # auto-accept detected entities
Detects people and projects from file content, then detects rooms from folder structure. Creates wing config and entity registry. Must run before mining.
mempalace statusMirrors: mempalace_status — Palace overview, total drawers, wing and room counts, AAAK spec, memory protocol
Trigger: User asks "what's in my palace?", "show me my memory status", "how many memories do we have?", "what do you know?". Also call at the start of a session to understand the user's world.
mempalace status
Shows total drawers filed, wing breakdown, room counts. Use this to get oriented before any memory operation.
mempalace search "query"Mirrors: mempalace_search — Semantic search with wing/room filters. Returns verbatim drawer content with similarity scores.
Trigger: User asks any question about past information: "what did we decide about X?", "why did we choose Y?", "find our discussion about Z", "what was the reasoning for...", "search my memory for...", "what do you know about...". Any time the user references a past decision, conversation, or fact that should exist in stored memory.
mempalace search "why did we switch to GraphQL"
mempalace search "auth decision" --wing myapp
mempalace search "pricing discussion" --wing myapp --room costs
mempalace search "Kai sprint" --results 10
Returns verbatim text with similarity scores, wing/room location, and source files. Filter by --wing and --room for targeted retrieval.
mempalace wake-upMirrors: mempalace_status + mempalace_diary_read — Load L0 (identity) and L1 (essential story) into context
Trigger: User starts a new session and wants the AI to "remember" them, or says "wake up", "load your memory", "what do you know about me?", "recall our context". Also use when injecting palace context into a local model's system prompt.
mempalace wake-up
mempalace wake-up --wing driftwood
Generates ~600-900 tokens of context: identity from ~/.mempalace/identity.txt plus essential story auto-generated from top palace drawers. Redirect to a file for local model injection:
mempalace wake-up > context.txt
mempalace mine <dir>Mirrors: mempalace_add_drawer — File verbatim content into the palace (batch operation)
Trigger: User wants to ingest project files or conversation exports into the palace: "import my chats", "mine this project", "ingest these conversations", "load my Claude/ChatGPT history", "add my project files to memory". Also when user says "remember everything in this folder" or "store all these conversations".
# Mine project files (code, docs, notes)
mempalace mine ~/projects/myapp
# Mine conversation exports (Claude, ChatGPT, Slack)
mempalace mine ~/chats/ --mode convos
# Tag with a specific wing name
mempalace mine ~/chats/ --mode convos --wing myapp
# Auto-classify into decisions, preferences, milestones, problems
mempalace mine ~/chats/ --mode convos --extract general
# Preview what would be filed without filing
mempalace mine ~/projects/myapp --dry-run
# Limit number of files
mempalace mine ~/projects/myapp --limit 50
mempalace split <dir>Mirrors: No direct MCP tool — preprocessing step for mempalace mine --mode convos
Trigger: User has concatenated transcript mega-files that need splitting before mining: "split my chat exports", "these transcripts are all in one file", "separate my conversation sessions". Run before mempalace mine --mode convos when exports contain multiple sessions per file.
mempalace split ~/chats/
mempalace split ~/chats/ --dry-run
mempalace split ~/chats/ --min-sessions 3
mempalace split ~/chats/ --output-dir ~/chats/split/
mempalace compressMirrors: mempalace_get_aaak_spec — AAAK compression of palace content
Trigger: User wants to compress stored memories for token-efficient context loading: "compress my memories", "reduce token usage", "AAAK encode my palace", "make my memory smaller for context".
mempalace compress --wing myapp
mempalace compress --wing myapp --dry-run
mempalace compress # all wings
Compresses drawers using AAAK dialect and stores in a separate mempalace_compressed collection.
mempalace repairMirrors: No direct MCP tool — recovery operation
Trigger: Palace is corrupted, returns errors, or ChromaDB segfaults (known on macOS ARM64): "my palace is broken", "repair my memory", "mempalace crashed", "ChromaDB error", "palace won't load".
mempalace repair
Rebuilds palace vector index from stored data. Creates a backup before rebuilding.
Mirrors: mempalace_kg_query, mempalace_kg_add, mempalace_kg_invalidate, mempalace_kg_timeline, mempalace_kg_stats
Trigger: User asks about entity relationships, wants to store structured facts, or needs temporal queries: "what do you know about Kai?", "who works on Orion?", "add that Kai works on Orion", "Kai moved to Nova project", "show me the timeline for project X", "what was true about Y in January?"
The knowledge graph is accessible via Python API (no CLI command yet):
from mempalace.knowledge_graph import KnowledgeGraph
kg = KnowledgeGraph()
# Add a fact (mirrors mempalace_kg_add)
kg.add_triple("Kai", "works_on", "Orion", valid_from="2025-06-01")
# Query entity relationships (mirrors mempalace_kg_query)
kg.query_entity("Kai")
# → [Kai → works_on → Orion (current), Kai → recommended → Clerk (2026-01)]
# Temporal query — what was true on a specific date
kg.query_entity("Maya", as_of="2026-01-20")
# → [Maya → assigned_to → auth-migration (active)]
# Invalidate a changed fact (mirrors mempalace_kg_invalidate)
kg.invalidate("Kai", "works_on", "Orion", ended="2026-03-01")
# Chronological timeline (mirrors mempalace_kg_timeline)
kg.timeline("Orion")
# → chronological story of the project
# Graph overview (mirrors mempalace_kg_stats)
kg.stats()
# → entities, triples, current vs expired facts, relationship types
Run inline with uv run or python -c:
python -c "from mempalace.knowledge_graph import KnowledgeGraph; kg = KnowledgeGraph(); print(kg.query_entity('Kai'))"
Mirrors: mempalace_search — programmatic access to search results
Trigger: Same as mempalace search CLI, but when you need structured data instead of printed output.
from mempalace.searcher import search_memories
results = search_memories("auth decisions", palace_path="~/.mempalace/palace")
# Returns dict with query, filters, and results list
Mirrors: mempalace_traverse, mempalace_find_tunnels, mempalace_graph_stats
Trigger: User wants to explore connections between topics across projects: "what's connected to auth-migration?", "how do these projects relate?", "find cross-project connections", "show me tunnels between wings", "what topics bridge my personal and work wings?"
from mempalace.palace_graph import traverse, find_tunnels, graph_stats
import chromadb
client = chromadb.PersistentClient(path="~/.mempalace/palace")
col = client.get_collection("mempalace_drawers")
# Walk from a room across wings (mirrors mempalace_traverse)
traverse("auth-migration", col=col, max_hops=2)
# Find rooms bridging two wings (mirrors mempalace_find_tunnels)
find_tunnels("wing_code", "wing_team", col=col)
# Graph connectivity overview (mirrors mempalace_graph_stats)
graph_stats(col=col)
Mirrors: 4-layer memory protocol from mempalace_status — L0 identity, L1 essential story, L2 on-demand, L3 deep search
Trigger: User wants layered memory loading: "load my identity", "get my essential context", "retrieve on-demand memories for project X", "deep search for..."
from mempalace.layers import MemoryStack
stack = MemoryStack()
# L0 + L1 wake-up (~600-900 tokens) — same as `mempalace wake-up`
stack.wake_up()
# L2 on-demand retrieval by wing/room
stack.recall(wing="driftwood", room="auth-migration")
# L3 deep semantic search
stack.search("pricing change")
AAAK is a lossy abbreviation system for token-efficient memory storage. Used by mempalace compress and agent diaries.
*action markers* (*warm*=joy, *fierce*=determined, *raw*=vulnerable, *bloom*=tenderness)FAM: family | PROJ: projects | ⚠: warningsNx = N mentions. Importance: ★ to ★★★★★SESSION:2026-04-08|fixed.auth.bug.in.OAuth|KAI→reviewed|ALC→approved.deploy|★★★★
mempalace init <dir> # set up palace from project
mempalace mine <dir> # mine project files
mempalace mine <dir> --mode convos # mine conversation exports
mempalace mine <dir> --mode convos --wing myapp # tag with wing name
mempalace mine <dir> --mode convos --extract general # auto-classify
mempalace split <dir> # split concatenated transcripts
mempalace search "query" # semantic search
mempalace search "query" --wing myapp # search within a wing
mempalace search "query" --room auth-migration # search within a room
mempalace wake-up # load identity + essential story
mempalace wake-up --wing driftwood # project-specific wake-up
mempalace compress --wing myapp # AAAK compress
mempalace repair # rebuild corrupted index
mempalace status # palace overview
All commands accept --palace <path> to override the default palace location.
mempalace search before stating facts about people or projects. Wrong is worse than slowkg.invalidate() + kg.add_triple() when facts changemempalace wake-up at session start to load context--wing and --room on search for targeted retrieval