# MemPalace

An AI memory system that stores conversation history verbatim in ChromaDB and organizes it using a memory palace metaphor — architectural hierarchy instead of flat search. Fully local, zero API calls, MCP integration for Claude/ChatGPT/Cursor/Gemini. Claims 96.6% R@5 on LongMemEval (500 questions, raw verbatim mode).

## Architecture

The palace hierarchy is inspired by the ancient Greek method of loci:

- **Wings** — people or projects (unlimited)
- **Rooms** — topic-specific areas within wings (auth, billing, deploy)
- **Halls** — memory type corridors (facts, events, discoveries, preferences, advice)
- **Tunnels** — cross-references linking the same room across different wings
- **Closets** — summaries pointing to original content
- **Drawers** — verbatim original files, never summarized

The structure serves as metadata for ChromaDB filtering. Unfiltered search hit 60.9% R@10 on 22K real memories; wing+room filtering reached 94.8% — a 34-point improvement from what's essentially standard metadata filtering dressed up in the palace metaphor.

## Design philosophy: verbatim over summarization

MemPalace stores raw conversation text without extraction or summarization. This is the opposite of [[hippo-memory]]'s approach (decay, consolidation, semantic compression). The bet: verbatim storage with good retrieval beats lossy summarization. The trade-off is storage — you keep everything — but ChromaDB handles large collections and the four-layer memory stack controls what actually gets loaded into context.

### Four-layer stack

- **L0** (~50 tokens) — identity info
- **L1** (~120 tokens) — critical facts about team, projects, preferences
- **L2** (on-demand) — recent sessions and current project context
- **L3** (on-demand) — deep semantic search across all closets

Wake-up context (L0 + L1) is ~170 tokens. Cost comparison: pasting everything = 19.5M tokens (impossible), LLM summaries = ~650K tokens (~$507/yr), MemPalace wake-up = ~$0.70/yr.

## Temporal knowledge graph

SQLite-based entity-relationship triples with `valid_from` and `ended` timestamps. Facts have validity windows, enabling historical queries ("what was true in January?") alongside current state. This is a different approach to [[memory-conflict-detection]] — instead of flagging contradictions, it tracks fact validity over time so both old and new states coexist as temporal records.

## AAAK compression (experimental)

A lossy abbreviation dialect using entity codes and structural markers for compressing context. Currently scores 84.2% R@5 vs 96.6% for raw mode — the headline benchmark is raw, not compressed. The README's "Honest Status" section acknowledges this and other overclaims (token counts used heuristics not tokenizers, palace filtering is standard ChromaDB metadata filtering, contradiction detection wasn't wired up).

## Usage

```bash
pip install mempalace
mempalace init ~/projects/myapp
mempalace mine ~/chats/ --mode convos    # ingest conversations
mempalace search "why did we switch to GraphQL"
mempalace wake-up                         # ~170 token context block
```

MCP integration:
```bash
claude mcp add mempalace -- python -m mempalace.mcp_server
```

Exposes 19 tools including search, wake-up, knowledge graph operations, diary management, and agent discovery.

## Mining modes

- **Projects** — code, documentation, notes
- **Convos** — Claude, ChatGPT, Slack exports
- **General** — auto-classifies into decisions, milestones, problems, preferences, emotional context

## Comparison with Hippo Memory and Stash

[[hippo-memory]], [[toolbox/stash|Stash]], and MemPalace all solve agent memory across sessions with different philosophies:

| | MemPalace | Hippo Memory | Stash |
|---|---|---|---|
| Storage | Verbatim, keep everything | Decay by default, consolidate | Episodes → facts → patterns (pipeline) |
| Retrieval | Structural filtering + semantic search | [[hybrid-search]] (BM25 + embeddings) | Namespace-scoped queries + KG traversal |
| Staleness | Temporal validity timestamps | Half-life decay | Confidence decay on contradiction |
| Conflicts | Temporal fact tracking | Explicit conflict detection | Contradiction stage in consolidation |
| Higher-order reasoning | None (verbatim only) | Semantic patterns | Causal links, goals, failures, hypotheses |
| Backend | ChromaDB + SQLite | SQLite, optional embeddings | Postgres + pgvector |
| Language | Python | TypeScript | Go |

No approach is strictly better — MemPalace optimizes for completeness, Hippo for relevance, Stash for pipeline-driven synthesis. The [[agent-memory-decay]] concept page covers the trade-offs.

## Specialist agents

Create focused agents with individual wings, diaries, and expertise domains. Each agent maintains separate memory. Agents write findings in AAAK and read domain-specific history. Runtime discovery finds available agents automatically.

15.3K stars, MIT license. Repo: https://github.com/milla-jovovich/mempalace