How to use Mempalace

01 Install

Mempalace requires Python 3.10 or higher. Install via pip:

pip install mempalace

Verify the install:

mempalace --version

Mempalace installs ChromaDB for vector storage and SQLite for the knowledge graph. No external services are started. Everything stays local.

02 Initialize your world

The init command walks you through setting up your world - the people you work with and the projects you work on. This context shapes how Mempalace organizes everything it mines.

mempalace init ~/projects/myapp

During init, Mempalace asks:

• Who do you work with? (Creates person wings)
• What are your main projects? (Creates project wings)
• What are your key goals? (Anchors the L0 identity layer)

The result is a ~/.mempalace/config.json file and the palace directory structure. You can edit this file manually at any time.

# View your palace config
cat ~/.mempalace/config.json

03 Mine your data

Mining ingests your data into the palace. Three modes handle different data types:

Projects mode

Code, docs, notes - any directory of text files.

mempalace mine ~/projects/myapp

Conversations mode

Chat exports from Claude, ChatGPT, Slack, or plain text transcripts.

mempalace mine ~/chats/ --mode convos

Supported formats:

• Claude Code JSONL exports
• Claude.ai JSON exports
• ChatGPT JSON exports (from data export)
• Slack JSON workspace exports
• Plain text transcripts

General mode

Auto-classifies content into five memory types: decisions, preferences, milestones, problems, and emotional context.

mempalace mine ~/chats/ --mode convos --extract general

Check status

mempalace status

04 Search your palace

Search uses semantic vector search via ChromaDB plus palace structure filtering. Results are ranked by relevance and palace location.

# Basic search
mempalace search "why did we switch to GraphQL"

# Search within a specific wing
mempalace search "auth decision" --wing projects

# Search with room filter
mempalace search "naming convention" --room architecture

# Return top 10 results
mempalace search "postgres config" --top 10

Results include verbatim context, not summaries. What you stored is what you get back.

05 MCP integration with Claude

Model Context Protocol lets Claude call Mempalace tools automatically. Once connected, you never need to run mempalace search manually - Claude does it for you when it needs context.

Connect Mempalace to Claude

claude mcp add mempalace -- python -m mempalace.mcp_server

Or configure manually in Claude's MCP config

{
  "mcpServers": {
    "mempalace": {
      "command": "python",
      "args": ["-m", "mempalace.mcp_server"]
    }
  }
}

Available MCP tools (19 total)

• mempalace_search - Semantic search across all wings
• mempalace_kg_query - Entity relationship queries
• mempalace_wake_up - Load full palace context
• mempalace_diary - Write to agent journal
• mempalace_compress - Compress context to AAAK
• ...and 14 more. See the MCP server source for the full list.

06 Local models (Llama, Mistral, etc.)

Local models don't typically support MCP yet. Two approaches work well:

Wake-up context (recommended)

Generate a compressed context file and paste it into your model's system prompt:

mempalace wake-up > context.txt
# Paste context.txt into your local model's system prompt

Bash injection

For scripted pipelines, inject search results directly:

CONTEXT=$(mempalace search "your question here")
echo "Context: $CONTEXT\n\nQuestion: your question" | ollama run llama3

07 Git hooks for automatic mining

Set up git hooks to automatically mine your project on commit or push. Two hooks are included:

Pre-compact hook (save before Claude compacts)

cp hooks/mempal_precompact_hook.sh ~/.claude/hooks/pre_compact
chmod +x ~/.claude/hooks/pre_compact

Post-save hook (mine after session save)

cp hooks/mempal_save_hook.sh ~/.claude/hooks/post_tool_use
chmod +x ~/.claude/hooks/post_tool_use

With these in place, your palace stays up to date automatically as you work. No manual mining required after setup.

08 AAAK compression

AAAK is a lossless shorthand dialect designed for AI context windows. It achieves 30x compression while preserving all semantic content.

Teach your AI to read AAAK

The MCP server does this automatically. For manual use:

# Compress a large context file
mempalace compress context.txt --output compressed.aaak

# Decompress back to plain text
mempalace decompress compressed.aaak

How AAAK works

• Entity codes: People and projects get 2-4 character codes (e.g., JD for John Doe)
• Emotion markers: Sentiment encoded in single characters
• Relationship shorthand: Structured grammar for entity relationships
• Universal decoder: Any text model can read it after a 120-token bootstrap

FAQ

mempalace export --output palace_backup.zip