MemPalace: palace architecture, AAAK compression, knowledge graph

The memory system:
- Palace structure: Wings (people/projects) → Rooms (topics) → Closets (AAAK compressed) → Drawers (verbatim transcripts)
- Halls connect related rooms within a wing
- Tunnels cross-reference rooms across wings
- AAAK: 30x lossless compression dialect for AI agents
- Knowledge graph: temporal entity-relationship triples (SQLite)
- Palace graph: room-based navigation with tunnel detection
- MCP server: 19 tools — search, graph traversal, agent diary, AAAK auto-teach
- Onboarding: guided setup generates wing config + AAAK entity registry
- Contradiction detection: catches wrong pronouns, names, ages
- Auto-save hooks for Claude Code

96.6% Recall@5 on LongMemEval — highest zero-API score published.
100% with optional Haiku rerank (500/500).
Local. Free. No API key required.

examples/basic_mining.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+"""Example: mine a project folder into the palace."""
+
+import sys
+
+project_dir = sys.argv[1] if len(sys.argv) > 1 else "~/projects/my_app"
+print("Step 1: Initialize rooms from folder structure")
+print(f"  mempalace init {project_dir}")
+print("\nStep 2: Mine everything")
+print(f"  mempalace mine {project_dir}")
+print("\nStep 3: Search")
+print("  mempalace search 'why did we choose this approach'")

examples/convo_import.py

@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+"""Example: import Claude Code / ChatGPT conversations."""
+
+print("Import Claude Code sessions:")
+print("  mempalace mine ~/claude-sessions/ --mode convos --wing my_project")
+print()
+print("Import ChatGPT exports:")
+print("  mempalace mine ~/chatgpt-exports/ --mode convos")
+print()
+print("Use general extractor for richer extraction:")
+print("  mempalace mine ~/chats/ --mode convos --extract general")

examples/mcp_setup.md

@@ -0,0 +1,25 @@
+# MCP Integration — Claude Code
+
+## Setup
+
+Run the MCP server:
+
+```bash
+python mcp_server.py
+```
+
+Or add to Claude Code:
+
+```bash
+claude mcp add mempal -- python /path/to/mempalace/mcp_server.py
+```
+
+## Available Tools
+
+- **mempal_status** — palace stats (wings, rooms, drawer counts)
+- **mempal_search** — semantic search across all memories
+- **mempal_list_wings** — list all projects in the palace
+
+## Usage in Claude Code
+
+Once configured, Claude Code can search your memories directly during conversations.