mempalace-code 1.5.0

Developer memory tool — mine codebases and conversations into a LanceDB-backed searchable palace. No API key required.

mempalace-code

Your AI's long-term memory. Local. Instant. Private.

One command indexes your codebase. Your AI remembers everything — architecture decisions, debugging sessions, API patterns — across sessions and projects. Forever.

No cloud. No API keys. No subscription. Nothing leaves your machine.

Get Started in 30 seconds · How It Works · All Features · Benchmarks

Tree-sitter AST Parsing Chunks at function boundaries not arbitrary line counts	27 MCP Tools Native Claude Code integration search, store, traverse	Temporal Knowledge Graph Facts that change over time with validity windows
595x Token Savings measured peak · median 80x scales with project size	Cross-Project Tunnels Search auth in one project find it everywhere	1008 Tests · $0 Cost Every feature acceptance-gated fully offline after install

---

Quick Start

uv tool install mempalace-code        # recommended (fast, Rust-based)
# or
pipx install mempalace-code           # alternative
# or
pip install mempalace-code            # into current environment
# or
uvx --from mempalace-code mempalace --help  # try without installing

Then ask your AI to read docs/AGENT_INSTALL.md — it will handle setup, MCP wiring, prompt injection, and verification automatically.

Or do it manually

mempalace init ~/projects/myapp       # detect rooms, download embedding model (~80 MB)
mempalace mine ~/projects/myapp       # index your codebase
claude mcp add mempalace -- python -m mempalace.mcp_server  # connect to Claude Code

Optional: auto-sync on commit (requires [watch] extra — see Auto-Watch):

mempalace watch ~/projects/           # re-mines on every commit, zero noise

This makes the 27 tools available to your AI. For proactive search and storage (without you asking), you'll also need to add usage rules to your CLAUDE.md (or equivalent agent-instruction file) — copy from docs/LLM_USAGE_RULES.md, or let docs/AGENT_INSTALL.md Section 7 inject them for you.

Do you need it? Ask your LLM:

Read https://github.com/rergards/mempalace-code/blob/main/docs/AGENT_INSTALL.md

1. How much context do I re-explain to you each session? Estimate tokens wasted.
2. Would auto-indexing this codebase as it grows save tokens over time? By how much?
3. Is my language/stack supported? If not, what's missing?
4. Decision: install now, wait for [feature], or skip — with reasoning.
5. If waiting: ask me if I want to draft a feature request for GitHub.

Supported MCP Clients

mempalace works with any MCP-compatible client:

• Claude Code (CLI, desktop, web) — claude mcp add mempalace -- python -m mempalace.mcp_server
• Claude Desktop — add to claude_desktop_config.json
• Cursor — add as MCP server in settings
• Windsurf — add as MCP server in settings
• Any MCP client — point it at python -m mempalace.mcp_server (stdio transport)

For local models without MCP support (Llama, Mistral, etc.), use mempalace wake-up to pipe context into the system prompt — see Memory Layers.

---

How It Actually Works

You write code. You make decisions. You debug things. Between sessions, all that context vanishes.

mempalace-code indexes it once into a local vector store, then your AI finds it in milliseconds — using 595x fewer tokens than grep + read at measured peak (median 80x on a 19k-chunk project, and it keeps scaling). Think of it as git log for everything that isn't in the code: the why, the discussions, the dead ends, the decisions.

What gets indexed:

• Code files — functions, classes, modules (Python, TypeScript/JS, Go, Rust, C/C++, C#, F#, VB.NET, XAML, Java, Kotlin, Scala, Swift, Dart, PHP, Markdown) plus Kubernetes manifests
• .NET solutions — .sln/.csproj project graphs, cross-project symbol relationships, interface implementations
• Conversation exports — Claude, ChatGPT, Slack
• Architecture notes, decisions, anything you store manually

How you use it: After setup, your AI calls mempalace tools automatically. You don't type search commands.

---

Features

Language-Aware Code Mining

mempalace mine walks your source tree and chunks at structural boundaries — functions, classes, methods — not arbitrary line counts. Leading comments and docstrings stay attached to their declarations.

Language	Strategy	AST Support
Python	Functions, classes, methods, decorators	Tree-sitter
TypeScript / JavaScript / TSX / JSX	Functions, classes, exports, imports	Tree-sitter
Go	Functions, types, methods, interfaces	Tree-sitter
Rust	Functions, structs, enums, traits, impls	Tree-sitter
Java	Classes, interfaces, methods, annotations	Regex
Kotlin	Classes, objects, functions, extensions	Regex
Scala	Classes, case classes, objects, traits, enums, functions, implicits, type aliases, generics	Regex
Swift	Classes, structs, enums, protocols, functions, properties, extensions, actors, async/await	Regex
Dart	Classes, mixins, extensions, enums, functions, named/factory constructors, async/await	Regex
PHP	Classes, interfaces, traits, enums (8.1+), functions, methods, namespaces (Laravel/WP/Symfony aware)	Regex
C#	Classes, interfaces, records, methods, properties	Regex
F# / VB.NET	Modules, types, functions	Regex
XAML	Controls, resources, code-behind linking	Regex
C / C++	Functions, structs, enums, classes	Regex
Kubernetes manifests	Deployments, Services, ConfigMaps, Secrets, Ingresses, CRDs (indexed by kind/namespace/labels)	YAML-aware
Markdown / plain text	Heading sections, paragraphs	—
YAML / JSON / TOML	Adaptive line-count	—

Tree-sitter is optional (pip install "mempalace-code[treesitter]"). Without it, all languages fall back to regex boundary detection — still structural, just less precise.

mempalace mine ~/projects/myapp                  # all supported file types
mempalace mine ~/projects/myapp --wing myapp     # tag with a specific wing
mempalace mine ~/chats/ --mode convos            # mine conversation exports
mempalace mine-all ~/projects/                   # batch mine all projects in a directory

Mining is incremental by default — content-hash based, only changed files are re-chunked. Use --full to force a rebuild.

Auto-Watch

Keep your palace in sync automatically. By default, watches .git/refs/heads/ and re-mines only on commit — no noise from work-in-progress saves. Handles multiple branches and worktrees.

Requires the watch extra:

uv tool install "mempalace-code[watch]"   # or: pipx install "mempalace-code[watch]"

Already installed without it? Add watchfiles:

uv tool inject mempalace-code watchfiles  # or: pipx inject mempalace-code watchfiles

mempalace watch ~/projects/                      # watch all projects (on commit, default)
mempalace watch ~/projects/ --on-save            # watch all file saves instead (noisier)
mempalace watch ~/projects/ schedule             # print launchd/cron snippet for daemon

Install as persistent daemon (macOS):

mempalace watch ~/projects/ schedule > ~/Library/LaunchAgents/com.mempalace.watch.plist
launchctl load ~/Library/LaunchAgents/com.mempalace.watch.plist

Starts at login, restarts if crashed. Logs to /tmp/mempalace-watch.log.

---

The Palace

mempalace-code organizes memories into a navigable structure — the same mental model ancient Greek orators used to memorize speeches.

  ┌─────────────────────────────────────────────────────────────┐
  │  WING: myapp                                               │
  │    ┌──────────┐  ──hall──  ┌──────────┐                    │
  │    │  backend │            │  frontend│                    │
  │    └────┬─────┘            └──────────┘                    │
  │         ▼                                                  │
  │    ┌──────────┐      ┌──────────┐                          │
  │    │  Closet  │ ───▶ │  Drawer  │  (verbatim content)     │
  │    └──────────┘      └──────────┘                          │
  └─────────┼──────────────────────────────────────────────────┘
            │ tunnel (auto-created when room names match)
  ┌─────────┼──────────────────────────────────────────────────┐
  │  WING: otherapp                                            │
  │    ┌────┴─────┐  ──hall──  ┌──────────┐                    │
  │    │  backend │            │  infra   │                    │
  │    └──────────┘            └──────────┘                    │
  └─────────────────────────────────────────────────────────────┘

Concept	What it is
Wing	A project, person, or domain. As many as you need.
Room	A topic within a wing: backend, auth, deploy, decisions.
Drawer	Verbatim content. Never summarized, never rewritten.
Hall	Connection between rooms in the same wing.
Tunnel	Auto-connection between wings when the same room name appears.

---

MCP Server — 27 Tools

claude mcp add mempalace -- python -m mempalace.mcp_server

Palace — Read

Tool	What
mempalace_status	Palace overview — total drawers, wings, rooms
mempalace_list_wings	All wings with drawer counts
mempalace_list_rooms	Rooms within a wing
mempalace_get_taxonomy	Full wing → room → count tree
mempalace_search	Semantic search with optional wing/room filters
mempalace_code_search	Filter by language, symbol name/type, file glob
mempalace_file_context	All indexed chunks for a source file, ordered by chunk_index
mempalace_check_duplicate	Similarity check before filing (0.9 threshold)

Palace — Write

Tool	What
mempalace_add_drawer	File verbatim content into a wing/room
mempalace_delete_drawer	Remove a drawer by ID
mempalace_delete_wing	Delete all drawers in a wing
mempalace_mine	Trigger re-mining of a project directory (incremental or full)

Knowledge Graph

Tool	What
mempalace_kg_query	Entity relationships with time filtering
mempalace_kg_add	Add a fact with optional validity window
mempalace_kg_invalidate	Mark a fact as no longer true
mempalace_kg_timeline	Chronological story of an entity
mempalace_kg_stats	Graph overview

Architecture Retrieval

Tool	What
mempalace_find_implementations	Find all types implementing a given interface
mempalace_find_references	Find all usages of a type (implementors, subclasses, deps)
mempalace_show_project_graph	Project-level dependency graph, optionally filtered by solution
mempalace_show_type_dependencies	Inheritance/implementation chain (ancestors + descendants)
mempalace_explain_subsystem	Explain how a subsystem works: semantic search + KG expansion
mempalace_extract_reusable	Classify deps as core/platform/glue; identify extraction boundary

Navigation & Diary

Tool	What
mempalace_traverse	Walk the graph from a room across wings
mempalace_find_tunnels	Find rooms bridging two wings
mempalace_graph_stats	Graph connectivity overview
mempalace_diary_write	Write a session journal entry
mempalace_diary_read	Read recent diary entries

MCP tools are discoverable by any MCP-capable client automatically. To teach the AI when and how to use them, paste the usage rules from docs/LLM_USAGE_RULES.md into your agent's instructions (CLAUDE.md, AGENTS.md, .cursorrules, etc.) — otherwise the tools are available but the assistant will not know the protocol.

---

Knowledge Graph

Temporal entity-relationship triples — local SQLite, no Neo4j, no cloud.

kg = KnowledgeGraph()
kg.add_triple("myapp", "uses", "Postgres", valid_from="2025-11-03")
kg.add_triple("myapp", "uses", "Redis",    valid_from="2026-01-15")

kg.query_entity("myapp")                    # → Postgres (current), Redis (current)
kg.query_entity("myapp", as_of="2025-12-01")  # → Postgres only

kg.invalidate("myapp", "uses", "Postgres", ended="2026-03-01")  # fact expired

Good candidates: version numbers, team assignments, tech stack choices, deployment states, deadlines.

---

Memory Layers

Layer	What	When
L0	Identity — project, persona	Always loaded (~50 tokens)
L1	Critical facts — team, decisions	Always loaded (~120 tokens)
L2	Room recall — current topic	On demand
L3	Deep search — full semantic query	On demand

mempalace wake-up --wing myapp    # emit L0 + L1 context (~170 tokens)

For local models (Llama, Mistral) that don't speak MCP, pipe wake-up into the system prompt.

---

Backup & Restore

mempalace backup create                           # create backup archive (default: <palace_parent>/backups/)
mempalace backup create --out ~/safe/my.tar.gz   # custom path
mempalace backup                                  # back-compat: same as 'backup create'
mempalace backup --out ~/safe/my.tar.gz           # back-compat: same as 'backup create --out ...'
mempalace backup list                             # list existing backups
mempalace backup list --dir ~/old_backups/        # include extra directory in discovery
mempalace restore palace_backup_2026-04-14.tar.gz # restore
mempalace restore backup.tar.gz --force           # overwrite existing

Backups are written to <palace_parent>/backups/ by default. For a palace at ~/.mempalace/palace, that is ~/.mempalace/backups/.

Scheduled backups:

# Print a scheduler snippet (does NOT install — owner action required)
mempalace backup schedule --freq daily    # daily at 03:00
mempalace backup schedule --freq weekly   # weekly on Sunday at 03:00
mempalace backup schedule --freq hourly   # every hour

# macOS: save and load the launchd plist
mempalace backup schedule --freq daily > ~/Library/LaunchAgents/com.mempalace.backup.plist
launchctl load ~/Library/LaunchAgents/com.mempalace.backup.plist

# Linux: paste the printed cron line into crontab -e
mempalace backup schedule --freq daily
# → 0 3 * * * /usr/local/bin/mempalace backup create --out /path/to/backups/scheduled_$(date +%Y%m%d_%H%M%S).tar.gz

Auto-backup before optimize (on by default):

backup_before_optimize is true by default. A backup is created under <palace_parent>/backups/pre_optimize_*.tar.gz before every optimize() call (runs after mining).

To opt out, add to ~/.mempalace/config.json:

{
  "auto_backup_before_optimize": false
}

Or set env var: MEMPALACE_AUTO_BACKUP_BEFORE_OPTIMIZE=0 (preferred) or MEMPALACE_BACKUP_BEFORE_OPTIMIZE=0.

Disable auto-optimize (paranoid mode):

{
  "optimize_after_mine": false
}

Skips compaction entirely. Storage will grow with more fragments but avoids any compaction-related corruption risk.

Why backup matters: Manual drawer additions (via mempalace_add_drawer) are not recoverable from source code. If LanceDB storage gets corrupted, only backups preserve this data. Code-mined drawers can be restored by re-running mempalace mine.

Also available: mempalace export --only-manual for JSONL export of manually-stored drawers.

---

Health & Repair

mempalace health              # probe palace for fragment corruption
mempalace health --json       # machine-readable report

mempalace repair --dry-run    # show what would be recovered
mempalace repair --rollback   # roll back to last working version

What health checks:

1. Manifest read (count_rows)
2. Data fragment read (head)
3. Metadata scan (count_by_pair) - catches the silent-failure surface

What repair --rollback does:

1. Walks LanceDB version history from newest to oldest
2. Finds the most recent version where all probes pass
3. Restores to that version (loses data added after corruption)

Use --dry-run first to see how many rows would be lost.

---

This Fork vs Upstream

This is a code-first fork of milla-jovovich/mempalace. We inherited the good parts — the palace metaphor, the MCP integration, the LongMemEval harness — and rebuilt what was broken. Every claim here is backed by code, tests, and documented benchmarks.

Upstream	This fork
ChromaDB — silently deletes data on version bump	LanceDB — crash-safe Arrow storage, no version-cliff
"No internet after install" — false	mempalace init downloads model explicitly; fully offline after
"100% R@5" — unverifiable	Number removed. Methodology caveats documented
~30% test coverage	1008 tests, every feature acceptance-gated
No backup, no recovery	backup / restore / export / import
No incremental mining	Content-hash incremental: only changed files re-chunked
No code-search	code_search — filter by language, symbol, glob
Line-count chunking	Tree-sitter AST + regex structural chunking

Full audit: docs/UPSTREAM_HARDENING.md.

---

Benchmarks

Token savings vs grep + read (full methodology)

Project size	Median	Mean	P95	Peak
Small (555 chunks)	13x	19x	42x	59x
Large (19k chunks)	80x	129x	279x	595x

Token savings scale with project size — grep noise grows linearly (more files contain the keyword), while mempalace search stays constant (top-5 semantically relevant chunks regardless of corpus size). These numbers are from a 19k-chunk project; larger codebases would push the ratios higher.

Retrieval quality

Benchmark	Score
Code retrieval R@5 (MiniLM, 469 chunks)	95.0%
Code retrieval R@10	100%

Upstream LongMemEval result (96.6% R@5 on conversations) retained with methodology caveats.

---

Installation Details

pip install mempalace-code
# or
uv pip install mempalace-code

Bootstrap script (recommended for servers/CI):

curl -fsSL https://raw.githubusercontent.com/rergards/mempalace-code/main/scripts/bootstrap.sh | bash

Optional extras:

pip install "mempalace-code[treesitter]"  # AST parsing
pip install "mempalace-code[chroma]"      # ChromaDB legacy backend (deprecated)
pip install "mempalace-code[spellcheck]"  # autocorrect for room/wing names
pip install "mempalace-code[dev]"         # pytest + ruff

Requirements: Python 3.11+. ~80 MB embedding model downloaded once during mempalace init.

All CLI Commands

# Setup
mempalace init <dir>                              # initialize + mine

# Mining
mempalace mine <dir>                              # mine code project
mempalace mine <dir> --wing myapp                 # tag with wing
mempalace mine <dir> --mode convos                # mine conversations
mempalace mine <dir> --full                       # force full rebuild
mempalace mine <dir> --watch                      # auto-incremental on file changes
mempalace mine-all <parent-dir>                   # batch mine all projects in a directory

# Watch (multi-project auto-sync)
mempalace watch <parent-dir>                      # watch all initialized projects
mempalace watch <parent-dir> schedule             # print launchd/cron daemon snippet

# Search
mempalace search "query"                          # search everything
mempalace search "query" --wing myapp             # scoped to wing
mempalace search "query" --room auth              # scoped to room

# Backup & Recovery
mempalace backup create                           # create backup (default: <palace_parent>/backups/)
mempalace backup list                             # list existing backups
mempalace backup schedule --freq daily            # print daily scheduler snippet
mempalace restore <archive>                       # restore from backup
mempalace export --only-manual                    # JSONL export
mempalace import <file>                           # JSONL import
mempalace health                                  # probe for fragment corruption
mempalace repair --rollback                       # roll back to last working version

# Context
mempalace wake-up                                 # L0 + L1 context
mempalace wake-up --wing myapp                    # project-scoped
mempalace status                                  # palace overview

# Model
mempalace fetch-model                             # pre-download for offline use

Saving Conversation Context

Code mining is automatic via mempalace watch-all. For conversation context (decisions, discussions, debugging notes), the AI uses MCP tools directly — works with any agent (Claude Code, Codex, Cursor, etc.):

1. Wire the MCP server (see install docs)
2. Add usage rules to your agent's instructions (CLAUDE.md, system prompt, etc.)
3. The agent calls mempalace_add_drawer and mempalace_diary_write during sessions

Legacy: Claude Code also supports optional auto-save hooks that remind the AI to save at fixed intervals. These are redundant if MCP + usage rules are set up.

Project Structure

mempalace/
├── mempalace/
│   ├── cli.py              ← CLI entry point
│   ├── mcp_server.py       ← MCP server (27 tools)
│   ├── storage.py          ← LanceDB vector storage
│   ├── miner.py            ← language-aware code chunking
│   ├── convo_miner.py      ← conversation ingest
│   ├── searcher.py         ← semantic search
│   ├── knowledge_graph.py  ← temporal entity graph (SQLite)
│   ├── palace_graph.py     ← room navigation graph
│   └── layers.py           ← 4-layer memory stack
├── benchmarks/             ← reproducible benchmark runners
├── hooks/                  ← Claude Code auto-save hooks (legacy, optional)
├── examples/               ← usage examples
└── tests/                  ← 1008 tests

---

Contributing

PRs welcome. See CONTRIBUTING.md.

python -m pytest tests/ -x -q    # full suite, all local, no network

License

Apache 2.0 — see LICENSE and NOTICE.