🧠 pi-mempalace

Your AI forgot everything again. How delightful.

Every conversation you've ever had with an AI — every architectural decision, every late-night debugging eureka, every "let's use Postgres because..." — poof. Gone the moment you close the tab. Your AI has the long-term memory of a goldfish at a rave.

pi-mempalace fixes that. It gives pi agents persistent, cross-session memory. Store everything. Search it later. Never re-explain your life choices to a machine again.

🏰 Standing on the Shoulders of a Memory Palace

This project is directly inspired by the wonderful MemPalace — built by Milla Jovovich (yes, that Milla Jovovich — Leeloo from The Fifth Element, Alice from Resident Evil) and developer Ben Sigman.

Milla's origin story is painfully relatable: after thousands of conversations with AI, she realized every new session was a clean slate. All her decisions, reasoning, creative ideas — thrown into the void. Existing memory tools like Mem0 and Zep tried to help, but they had a fatal flaw: they used AI to decide what was worth remembering. The nuance, the "why," the reasoning behind decisions — exactly the stuff that matters — was the first to go.

So Milla and Ben spent months building MemPalace with Claude Code, and landed on a beautifully simple idea:

Don't let AI decide what to forget — store everything, then make it findable.

Their MemPalace scored 96.6% on LongMemEval (the standard benchmark for AI memory) in raw mode — the highest published result requiring zero API calls. The full system hit 100% with hybrid reranking, sparking a glorious internet debate about benchmarks and bragging rights. 7,000+ GitHub stars in 48 hours. Not bad for an actress and a developer with an idea.

pi-mempalace takes that core philosophy — verbatim storage + semantic search — and reimagines it as a native pi extension. No Python. No ChromaDB. No pip install nightmares. Just pure TypeScript running in-process, fast enough to forget that forgetting was ever a problem.

✨ What It Does

• 🔄 Auto-capture — Every conversation exchange is stored automatically after each turn. You don't have to remember to remember.
• 🌅 Wake-up context — Each new session starts with a whisper of who you are and what you've been up to (~600-900 tokens of "previously on your life").
• 🔍 Semantic search — Find past decisions by meaning, not keywords. "Why did we pick that database?" just works.
• 📁 Project-aware — Memories are tagged by project (auto-detected from your directory) and topic. Your work stays organized even if you don't.
• 🏠 Fully local — Embeddings computed in-process via all-MiniLM-L6-v2. No cloud calls. No API keys. No surveillance capitalism. Just you and your memories.
• 📊 Beautiful stats — Sparkline activity charts, bar graphs by project/topic, and a TUI overlay that makes you feel like a hacker in a 90s movie.

🚀 Install

# Install from npm
pi install npm:pi-mempalace

# Or from GitHub
pi install https://github.com/Jabbslad/pi-mempalace

# Or from a local checkout
pi install /path/to/pi-mempalace

That's it. pi install runs npm install automatically, which pulls in all three runtime dependencies:

| Dependency | What It Does | Native? | |-----------|-------------|--------| | @huggingface/transformers | Local embeddings (all-MiniLM-L6-v2, 384 dims) | No — pure JS, downloads model on first use (~80MB) | | better-sqlite3 | SQLite database access | Yes — compiles native addon via node-gyp | | sqlite-vec | Vector similarity search for SQLite | Yes — ships prebuilt binary per platform |

No Python. No conda. No Docker. No ChromaDB server. No API keys. No sacrificial offerings to the dependency gods.

Prerequisites

• Node.js (required by pi)
• C++ toolchain for better-sqlite3's native build:
  • macOS: xcode-select --install
  • Linux: sudo apt install build-essential (or equivalent)
  • Windows: Visual Studio Build Tools

Most dev machines already have this. If pi install fails with gyp errors, that's the fix.

🎮 Quick Start

# Set up your identity and verify everything works
/skill:memory-setup

# Explicitly save something important
memory_save("We chose PostgreSQL for concurrent write support", project: "myapp", topic: "database")

# Search later, when you've inevitably forgotten
memory_search("why did we pick the database?")

# Browse a project's collected wisdom
memory_recall(project: "myapp")

# Check on your growing brain
memory_status()

🧰 Tools

Memory Tools

| Tool | What It Does | |------|-------------| | memory_search | Semantic search across all stored memories — find things by meaning | | memory_save | Explicitly save important info — for those "remember this" moments | | memory_recall | Browse memories by project/topic — like flipping through a journal | | memory_status | Memory store overview — how big is your brain now? |

Palace Graph Tools

| Tool | What It Does | |------|-------------| | memory_graph | Visualize the palace — projects as wings, shared topics as tunnel connections | | memory_tunnel | Traverse a tunnel between two projects via a shared topic |

Knowledge Graph Tools

| Tool | What It Does | |------|-------------| | knowledge_add | Add structured facts — "myapp uses PostgreSQL since 2025-01" | | knowledge_query | Query facts about an entity, with temporal filtering — "what did we use in 2024?" | | knowledge_status | Knowledge graph stats — entities, facts, predicates |

⌨️ Commands

| Command | What It Does | |---------|-------------| | /memory status | Quick status overview | | /memory stats | Full stats overlay with sparklines and bar charts | | /memory project <name> | Set current project context | | /memory search <query> | Quick search shortcut | | /memory graph | Show palace graph with cross-project connections | | /memory knowledge <entity> | Query knowledge graph for an entity | | /memory on / off | Enable/disable memory (for those private moments) |

🏗️ Architecture

Following the MemPalace 4-layer memory stack:

┌─────────────────────────────────────────────────────────┐
│  L0: IDENTITY (~100 tokens)                             │
│  Always loaded. ~/.pi/agent/memory/identity.txt         │
├─────────────────────────────────────────────────────────┤
│  L1: ESSENTIAL STORY (~500-800 tokens)                  │
│  Top 15 memories by importance + recency.               │
│  Grouped by project. Injected at session start.         │
├─────────────────────────────────────────────────────────┤
│  L2: ON-DEMAND PROJECT CONTEXT                          │
│  Filtered by project/topic via SQL indexes.             │
│  Loaded only when you ask about a specific area.        │
├─────────────────────────────────────────────────────────┤
│  L3: DEEP SEMANTIC SEARCH                               │
│  Full vector similarity via sqlite-vec ANN index.       │
│  Searches 100K+ memories in milliseconds.               │
└─────────────────────────────────────────────────────────┘

pi (TypeScript — everything in-process)
┌──────────────────────────────────────────────────┐
│  extensions/pi-mempalace/                        │
│                                                  │
│  index.ts                memory_store.ts         │
│  ┌──────────────────┐    ┌────────────────────┐  │
│  │ turn_end →        │    │ MemoryStore        │  │
│  │   auto-capture    │───│                    │  │
│  │ before_agent →    │    │ SQLite + sqlite-vec│  │
│  │   L0+L1 inject    │←──│ ANN vector search  │  │
│  │ Tools + Commands  │    │ Metadata indexes   │  │
│  │ Stats TUI overlay │    │ WAL mode           │  │
│  └──────────────────┘    │                    │  │
│                           │ ~/.pi/agent/       │  │
│                           │   memory/          │  │
│                           │     memories.db    │  │
│                           └────────────────────┘  │
│                                                  │
│  @huggingface/transformers                       │
│    all-MiniLM-L6-v2 (384 dimensions)             │
│                                                  │
│  better-sqlite3 + sqlite-vec                     │
│    Indexed storage + vector similarity search    │
└──────────────────────────────────────────────────┘

⚡ Performance

Benchmarked on Apple Silicon (M-series). Your mileage may vary, but it'll be fast.

| Operation | Time | Vibes | |-----------|------|-------| | Model load (first store) | ~200ms | ☕ One-time cost per session | | Store 1 memory (warm) | ~1ms | ⚡ Blink and you'll miss it | | Search 100 memories | ~1ms | 🚀 Faster than you can forget | | Wakeup L0+L1 | <1ms | 🌅 Instant dawn | | Recall L2 (filtered) | <1ms | 🎯 SQL indexes go brrr | | Knowledge graph query | <1ms | 🧩 Basically free | | Palace graph | <1ms | 🏰 All the tunnels, no waiting |

💾 Storage

Memories live in a SQLite database at ~/.pi/agent/memory/memories.db, powered by sqlite-vec for vector similarity search. Metadata is indexed (project, topic, timestamp) for fast pre-filtering before vector search kicks in. Deduplication via SHA-256 hash means you can't accidentally remember the same thing twice — unlike that embarrassing story you keep retelling at parties.

Migrating from v0.1? If you have an existing memories.jsonl file, it's automatically migrated to SQLite on first load. Your old file is renamed to .bak. No data lost, no action needed.

🏰 The Full MemPalace Architecture

The original MemPalace uses a gorgeous metaphorical architecture — Wings (top-level containers), Rooms (topics), Halls (corridors by memory type), Closets (compressed summaries), and Drawers (verbatim source files). It runs on Python with ChromaDB and includes AAAK, a custom 30x compression dialect that any LLM can read natively.

pi-mempalace faithfully implements the core MemPalace architecture in TypeScript:

| MemPalace Concept | pi-mempalace Implementation | |---|---| | Wings (projects/people) | project field — auto-detected from git repo | | Rooms (topics within wings) | topic field — set per memory | | Drawers (verbatim chunks) | 800-char chunks with 100-char overlap, each with its own embedding | | Tunnels (cross-wing connections) | memory_graph discovers shared topics across projects | | 4-Layer Stack | L0 Identity → L1 Essential Story → L2 On-Demand → L3 Deep Search | | Knowledge Graph | Temporal triples with valid_from/valid_to — "what was true when?" | | ChromaDB | SQLite + sqlite-vec — same HNSW indexing, no Python |

The one thing we deliberately skip is AAAK compression — MemPalace's own benchmarks show it drops accuracy from 96.6% to 84.2%. We'll take the storage cost over the precision loss.

The soul is the same: your AI should remember you.

If you want the full palace experience with all its wings and halls and drawers, go check out mempalace.tech. Milla and Ben built something special.

📊 Benchmark Validation

We reproduce LongMemEval — the standard benchmark for AI memory systems — to validate that our implementation matches MemPalace's retrieval quality. The benchmark stores 500 questions, each with ~50 timestamped conversation sessions, and measures whether the correct session appears in the top-K search results.

Results (Raw Mode — Zero API, Fully Local)

| Metric | pi-mempalace | MemPalace (reference) | Delta | |--------|-------------|----------------------|-------| | Recall@5 | 95.8% (479/500) | 96.6% (483/500) | -0.8pp | | Recall@10 | 98.2% (491/500) | 98.2% (491/500) | identical | | NDCG@10 | 0.884 | 0.889 | -0.005 |

Per Question Type

| Question Type | R@5 | R@10 | Questions | |--------------|-----|------|-----------| | knowledge-update | 🟢 100% | 100% | 78 | | multi-session | 🟢 97.7% | 98.5% | 133 | | temporal-reasoning | 🟡 94.7% | 99.2% | 133 | | single-session-assistant | 🟡 94.6% | 96.4% | 56 | | single-session-user | 🟡 92.9% | 95.7% | 70 | | single-session-preference | 🟡 90.0% | 96.7% | 30 |

The 0.8pp R@5 gap comes from our 800-char chunking (MemPalace stores whole sessions in benchmark mode) and minor differences between sqlite-vec and ChromaDB's HNSW implementations. The weakest categories (temporal, preference) are exactly what MemPalace's hybrid modes address with keyword re-ranking and temporal boosting — features we haven't implemented.

Run It Yourself

# Download the LongMemEval dataset (~277MB)
curl -fsSL -o benchmarks/data/longmemeval_s_cleaned.json \
  https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned/resolve/main/longmemeval_s_cleaned.json

# Run full benchmark (500 questions, ~4 minutes)
npx tsx benchmarks/longmemeval_bench.mjs

# Quick smoke test (10 questions, ~5 seconds)
npx tsx benchmarks/longmemeval_bench.mjs --limit 10

# Save per-question results
npx tsx benchmarks/longmemeval_bench.mjs --out benchmarks/results/raw_500.jsonl

🤔 Why Not Just Use MemPalace Directly?

You absolutely could! MemPalace is great. But if you're already living in the pi ecosystem:

• No Python required — pi-mempalace is pure TypeScript, runs in-process
• Full MemPalace architecture — 4-layer stack, chunking, palace graph, knowledge graph
• SQLite instead of ChromaDB — one file, no server, native Node.js via better-sqlite3
• Palace graph with tunnels — discover cross-project connections via shared topics
• Temporal knowledge graph — structured facts with time validity ("what was true when?")
• Auto-chunking — long content split into 800-char chunks with overlap, just like MemPalace
• Native pi integration — hooks into pi's extension system, session lifecycle, and TUI
• Auto-capture built in — no manual memory management needed
• Wake-up context — L0 identity + L1 essential story, injected before you even ask
• Zero config — install it and go. It just works.

📜 License

MIT — because memories should be free.