MemPalace: Offline, Local‑First AI Memory System Built on a Memory‑Palace Architecture

Project Overview

MemPalace is a local‑first, fully offline AI memory library that stores raw conversation and project content without summarisation, enabling exact semantic retrieval. The design follows the classical “memory palace” metaphor and maps it to a hierarchical storage model.

Core Architecture

The data model consists of five hierarchical layers:

Wing : top‑level domain (person, project, or topic) that groups related content.

Hall : fixed categories within a wing (facts, events, discoveries, preferences, advice).

Room : specific sub‑topic (e.g., auth‑migration) automatically detected or manually created.

Tunnel : cross‑wing links that connect rooms with the same name across different wings.

Closet : text summary layer that points to original content.

Drawer : raw original text (dialogues, code, documents) stored unchanged.

This hierarchy preserves original content while allowing fast retrieval. Experiments show recall improves from 60.9 % R@10 when searching all closets to 94.8 % R@10 when restricting to “Wing + Room”.

Installation & Quick‑Start

Requirements: Python 3.9+, ChromaDB (default vector store), ~300 MB disk space.

# pip install mempalace
git clone https://github.com/MemPalace/mempalace.git
cd mempalace
pip install -e ".[dev]"

Typical workflow:

Initialize a palace: mempalace init ~/projects/myapp Import content: mempalace mine ~/projects/myapp (project files) mempalace mine ~/.claude/projects/ --mode convos (Claude Code conversations)

Search:

Global semantic search: mempalace search "why did we switch to GraphQL" Wing‑restricted search: mempalace search "database decision" --wing orion Large export files can be split with mempalace split <dir> and previewed via --dry-run.

Benchmark Results

All benchmarks are reproducible from the benchmarks/ folder.

LongMemEval (R@5, 500 questions) :

Original mode (semantic search, no LLM): 96.6 %

Mixed v4 (keyword & temporal enhancements): 98.4 %

Mixed v4 + LLM re‑ranking: ≥ 99 %

LoCoMo (R@10, 1,986 questions) : Original 60.3 % , Mixed v5 88.9 % .

ConvoMem (average recall, 250 projects) : 92.9 % .

MemBench (ACL 2025, 8,500 projects, R@5) : 80.3 % .

The 96.6 % recall of the original mode is the highest publicly reported score for a zero‑API, fully offline setup and can be reproduced on an M2 Ultra in under five minutes.

Modules

Knowledge Graph

SQLite‑based temporal triple store with valid_from / valid_to fields. Example usage:

from mempalace.knowledge_graph import KnowledgeGraph
kg = KnowledgeGraph()
kg.add_triple("Kai", "works_on", "Orion", valid_from="2025-06-01")
kg.add_triple("Maya", "assigned_to", "auth-migration", valid_from="2026-01-15")
kg.invalidate("Kai", "works_on", "Orion", ended="2026-03-01")
kg.query_entity("Maya", as_of="2026-01-20")
kg.timeline("Orion")

MCP Server

Provides 29 tools for palace read/write, graph operations, cross‑wing navigation, and diary handling. Compatible with Claude, ChatGPT, Gemini, etc. Core commands include mempalace status, mempalace search, mempalace list wings, mempalace add drawer, mempalace delete drawer, mempalace kg query, mempalace kg add, mempalace traverse, and diary commands.

Agents

Independent “wings” with private diaries stored in AAAK‑compressed format, enabling domain‑specific AI agents (e.g., a code‑review bot). Example diary commands:

# Write diary entry for code‑review agent
mempalace_diary_write("reviewer", "PR#42|auth.bypass.found|missing.middleware.check|★★★★")
# Read last 10 entries
mempalace_diary_read("reviewer", last_n=10)

Auto‑save Hooks

JSON‑defined hooks that automatically persist Claude Code conversations:

Save Hook : triggers every 15 messages, extracts topics, decisions, references, and code changes.

PreCompact Hook : runs before context compression to avoid data loss.

Hook configuration example:

{
  "hooks": {
    "Save": [{"matcher": "", "hooks": [{"type": "command", "command": "/path/to/mempal_save_hook.sh"}]}],
    "PreCompact": [{"matcher": "", "hooks": [{"type": "command", "command": "/path/to/mempal_precompact_hook.sh"}]}]
  }
}

AAAK Dialect (experimental)

Lossy token compression that replaces repeated entities with short tokens. In LongMemEval the R@5 drops to 84.2 % , indicating a trade‑off between token savings and recall.

Contradiction Checker (experimental)

Standalone script fact_checker.py flags statements that conflict with stored facts. Example output:

Input: Soren finished the auth migration → 🔴 AUTH‑MIGRATION: attribution conflict — Maya was assigned, not Soren

Input: Kai has been here 2 years → 🟡 KAI: wrong_tenure — records show 3 years (started 2023‑04)

Use‑Case Advantages

Privacy‑first: all data stays on‑device, no API keys or cloud uploads.

Cost efficiency: typical search consumes ~600‑900 tokens (~$0.70 /yr) versus hundreds of dollars for LLM‑based summarisation.

Long‑term conversation archiving for Claude, local LLMs, or other AI assistants.

Project management: versioned storage of code, documentation, and decision records.

Persistent AI agent memory: agents can retrieve domain‑specific facts without re‑prompting.

Comparison with Similar Tools

Storage : MemPalace uses local SQLite (free); Zep’s Graphiti uses cloud‑hosted Neo4j (paid).

Cost : MemPalace is free; Zep starts at $25 / mo.

Temporal validity : both support time‑bounded triples.

Self‑hosting : MemPalace always self‑hosted; Zep self‑hosting only in enterprise tier.

Privacy : MemPalace stores all data locally; Zep offers SOC 2/HIPAA compliance but still relies on cloud services.

Cost Comparison (MemPalace vs. alternatives)

Paste all content: 19.5 M tokens – impossible to fit context.

LLM summarisation: ~650 K tokens, ≈ $507 / yr.

MemPalace wake‑up: ~600‑900 tokens, ≈ $0.70 / yr.

MemPalace + 5 searches: ~13.5 K tokens, ≈ $10 / yr.

Repository

https://github.com/MemPalace/mempalace