pi-mempalace

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# 🧠 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](https://github.com/badlogic/pi-mono) agents persistent, cross-session memory. Save important context, search it later, and stop re-explaining your life choices to a machine.

---

## 🏰 Standing on the Shoulders of a Memory Palace

This project is directly inspired by the wonderful [MemPalace](https://github.com/MemPalace/mempalace) — built by **Milla Jovovich** (yes, *that* Milla Jovovich — Leeloo from *The Fifth Element*, Alice from *Resident Evil*) and developer **Ben Sigman**.

> **Official MemPalace sources:** [github.com/MemPalace/mempalace](https://github.com/MemPalace/mempalace), [PyPI](https://pypi.org/project/mempalace/), and [mempalaceofficial.com](https://mempalaceofficial.com). Avoid unofficial MemPalace domains.

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% R@5 on LongMemEval** in raw mode with zero API calls. Current MemPalace also reports stronger hybrid retrieval results, while its maintainers now avoid headline claims that mix retrieval recall with end-to-end QA accuracy.

pi-mempalace takes that core philosophy — **verbatim storage + semantic search** — and reimagines it as a native [pi](https://github.com/badlogic/pi-mono) 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** — Each Pi conversation exchange is stored automatically after each turn. Auto-captured exchanges are capped at 2,000 characters to keep storage cheap; manual saves can store longer content, which is chunked for search.
- **🌅 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. Auto-capture and untitled manual saves use local `flan-t5-small` for a durable topic label, falling back to `general` if inference is unavailable.
- **🏠 Local-first** — Storage, embeddings, search, and topic inference run in-process via HuggingFace models + SQLite. Topic inference never calls Pi's selected LLM and can be disabled with `/memory topics off`.
- **📊 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

```bash
# Install from GitHub
pi install git: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`) and topic labels (`flan-t5-small`) | No — pure JS, downloads models on first use |
| `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. Topic inference is local and does not use Pi model/auth; storage and search need no separate 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

```bash
# 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()
```

### Configuration

Config is stored at `~/.pi/agent/memory/config.json`:

```json
{
  "autoCapture": true,
  "wakeUpEnabled": true,
  "wakeUpMaxTokens": 800,
  "topicInferenceEnabled": true,
  "defaultProject": null
}
```

Local topic inference loads `Xenova/flan-t5-small` on first use when auto-capturing a turn or saving a memory without an explicit topic. It does not call Pi's selected LLM or any paid model API. Toggle it with `/memory topics on` or `/memory topics off`.

---

## 🧰 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

Inspired by the [MemPalace](https://github.com/MemPalace/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       │ ──────▶ │ SQLite + sqlite-vec │  │
│  │ before_agent_start   │ ◀────── │ ANN vector search   │  │
│  │   L0 + L1 inject     │         │ Metadata indexes    │  │
│  │ Tools + Commands     │         │ WAL mode            │  │
│  │ Stats TUI overlay    │         │                     │  │
│  └──────────────────────┘         │ ~/.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, explicit topic) | ~1ms | ⚡ Blink and you'll miss it |
| Infer topic (when enabled) | Local `flan-t5-small` call | 🏷️ Better rooms, no paid LLM call |
| 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](https://github.com/asg017/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.

---

## 🏰 MemPalace Concepts in pi-mempalace

The original [MemPalace](https://github.com/MemPalace/mempalace) uses a richer architecture — **Wings** (top-level containers), **Rooms** (topics), **Halls** (corridors by memory type), **Closets** (searchable pointer layers), and **Drawers** (verbatim source files). It runs on Python with ChromaDB by default and includes AAAK, an experimental lossy compression dialect.

pi-mempalace implements a Pi-native subset of those ideas in TypeScript:

| MemPalace Concept | pi-mempalace Implementation |
|---|---|
| **Wings** (projects/people) | `project` field — auto-detected from git repo |
| **Rooms** (topics within wings) | `topic` field — explicit or inferred locally with `flan-t5-small` |
| **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](https://github.com/asg017/sqlite-vec) — local vector search, no Python |

This plugin deliberately skips several current MemPalace features: AAAK compression, closets, file/conversation mining, source adapters, hook management, repair/migration tools, and hybrid BM25 reranking.

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

If you want the full palace experience with all its wings, halls, closets, drawers, importers, and repair tooling, use the official [MemPalace project](https://github.com/MemPalace/mempalace). Milla and Ben built something special.

---

## 📊 Benchmark Validation

We reproduce [LongMemEval](https://arxiv.org/abs/2410.10813) raw retrieval to validate this plugin's local semantic search. 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 and differences between sqlite-vec and ChromaDB retrieval. The weakest categories (temporal, preference) are exactly what current MemPalace hybrid modes address with keyword re-ranking and temporal boosting — features this plugin has not implemented.

### Run It Yourself

```bash
# 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
- **Pi-native MemPalace-inspired subset** — 4-layer wake-up/search model, 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** — short Pi exchanges are captured automatically; use `memory_save` for explicit durable notes
- **Wake-up context** — L0 identity + L1 essential story, injected before you even ask
- **Zero config** — install it and go. Topic labels use local `flan-t5-small` by default, or `/memory topics off` to keep auto-captures in `general`.

---

## 📜 License

MIT — because memories should be free.

---

<p align="center">
  <i>
    "I wanted my AI to remember the way I remember — not just the conclusions, but the journey."
    <br/>
    — The philosophy behind MemPalace, which inspired this project
  </i>
</p>

<p align="center">
  🏰 Inspired by <a href="https://github.com/MemPalace/mempalace">MemPalace</a> by Milla Jovovich & Ben Sigman
  <br/>
  🧠 Built for <a href="https://github.com/badlogic/pi-mono">pi</a> with ❤️ and a fear of forgetting
</p>

🧠 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. Save important context, search it later, and stop re-explaining your life choices to a machine.

🏰 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.

Official MemPalace sources: github.com/MemPalace/mempalace, PyPI, and mempalaceofficial.com. Avoid unofficial MemPalace domains.

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% R@5 on LongMemEval in raw mode with zero API calls. Current MemPalace also reports stronger hybrid retrieval results, while its maintainers now avoid headline claims that mix retrieval recall with end-to-end QA accuracy.

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 — Each Pi conversation exchange is stored automatically after each turn. Auto-captured exchanges are capped at 2,000 characters to keep storage cheap; manual saves can store longer content, which is chunked for search.
🌅 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. Auto-capture and untitled manual saves use local flan-t5-small for a durable topic label, falling back to general if inference is unavailable.
🏠 Local-first — Storage, embeddings, search, and topic inference run in-process via HuggingFace models + SQLite. Topic inference never calls Pi's selected LLM and can be disabled with /memory topics off.
📊 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 GitHub
pi install git: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`) and topic labels (`flan-t5-small`)	No — pure JS, downloads models on first use
`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. Topic inference is local and does not use Pi model/auth; storage and search need no separate 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()

Configuration

Config is stored at ~/.pi/agent/memory/config.json:

{
  "autoCapture": true,
  "wakeUpEnabled": true,
  "wakeUpMaxTokens": 800,
  "topicInferenceEnabled": true,
  "defaultProject": null
}

Local topic inference loads Xenova/flan-t5-small on first use when auto-capturing a turn or saving a memory without an explicit topic. It does not call Pi's selected LLM or any paid model API. Toggle it with /memory topics on or /memory topics off.

🧰 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

Inspired by 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       │ ──────▶ │ SQLite + sqlite-vec │  │
│  │ before_agent_start   │ ◀────── │ ANN vector search   │  │
│  │   L0 + L1 inject     │         │ Metadata indexes    │  │
│  │ Tools + Commands     │         │ WAL mode            │  │
│  │ Stats TUI overlay    │         │                     │  │
│  └──────────────────────┘         │ ~/.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, explicit topic)	~1ms	⚡ Blink and you'll miss it
Infer topic (when enabled)	Local `flan-t5-small` call	🏷️ Better rooms, no paid LLM call
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.

🏰 MemPalace Concepts in pi-mempalace

The original MemPalace uses a richer architecture — Wings (top-level containers), Rooms (topics), Halls (corridors by memory type), Closets (searchable pointer layers), and Drawers (verbatim source files). It runs on Python with ChromaDB by default and includes AAAK, an experimental lossy compression dialect.

pi-mempalace implements a Pi-native subset of those ideas in TypeScript:

MemPalace Concept	pi-mempalace Implementation
Wings (projects/people)	`project` field — auto-detected from git repo
Rooms (topics within wings)	`topic` field — explicit or inferred locally with `flan-t5-small`
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 — local vector search, no Python

This plugin deliberately skips several current MemPalace features: AAAK compression, closets, file/conversation mining, source adapters, hook management, repair/migration tools, and hybrid BM25 reranking.

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

If you want the full palace experience with all its wings, halls, closets, drawers, importers, and repair tooling, use the official MemPalace project. Milla and Ben built something special.

📊 Benchmark Validation

We reproduce LongMemEval raw retrieval to validate this plugin's local semantic search. 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 and differences between sqlite-vec and ChromaDB retrieval. The weakest categories (temporal, preference) are exactly what current MemPalace hybrid modes address with keyword re-ranking and temporal boosting — features this plugin has not 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
Pi-native MemPalace-inspired subset — 4-layer wake-up/search model, 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 — short Pi exchanges are captured automatically; use memory_save for explicit durable notes
Wake-up context — L0 identity + L1 essential story, injected before you even ask
Zero config — install it and go. Topic labels use local flan-t5-small by default, or /memory topics off to keep auto-captures in general.

📜 License

MIT — because memories should be free.

"I wanted my AI to remember the way I remember — not just the conclusions, but the journey."
— The philosophy behind MemPalace, which inspired this project

🏰 Inspired by MemPalace by Milla Jovovich & Ben Sigman
🧠 Built for pi with ❤️ and a fear of forgetting