Mempalace Code

mempalace-code

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

Index your codebase once. Your AI can recall architecture decisions, debugging sessions, and API patterns across sessions and projects without re-reading the repo.

No cloud service, no API keys, no subscription. After the one-time embedding model download, indexing and search stay on your machine.

[![][version-shield]][release-link] [![][python-shield]][python-link] [![][license-shield]][license-link]

[Get Started in 30 seconds](#quick-start) · [How It Works](#the-palace) · [All Features](#features) · [Benchmarks](#benchmarks)

Language-Aware MiningAST, regex, and adaptive chunkingmatched to each file type 29 MCP ToolsAny MCP-capable agentsearch, store, traverse · static profiles Temporal Knowledge GraphFacts that change over timewith validity windows

595x Token Savingsmeasured peak · median 80xscales with project size Cross-Project TunnelsSearch auth in one projectfind it everywhere 2200+ Tests · $0 CostEvery feature acceptance-gatedoffline after model setup

---

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-code --help  # try without installing

mempalace-code is the default command name so this fork can coexist with upstream/vanilla mempalace on the same machine. If mempalace is unused on your PATH and you want the shorter alias, run mempalace-code install-alias. Packaged installs use the Python import package mempalace_code, so they can coexist with vanilla MemPalace in the same Python environment. Source checkouts keep a small mempalace.mcp_server shim only so older repo-local MCP configs that run with PYTHONPATH=/path/to/mempalace-code continue to start.

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

Or do it manually

mempalace-code init ~/projects/myapp       # detect rooms, cache embedding model (~80 MB)
mempalace-code init ~/projects/myapp --detect-entities  # optional people/project detection for notes/convos
mempalace-code mine ~/projects/myapp       # index your codebase
claude mcp add mempalace-code -- python -m mempalace_code.mcp_server  # connect Claude Code
codex mcp add mempalace-code -- python -m mempalace_code.mcp_server   # connect Codex CLI

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

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

This makes all 29 tools available to your AI. To expose a reduced subset, add a --profile flag (e.g. -- python -m mempalace_code.mcp_server --profile=minimal). 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](docs/LLMUSAGERULES.md), or let [docs/AGENT_INSTALL.md](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/README.md
- https://github.com/rergards/mempalace-code/blob/main/docs/AGENT_INSTALL.md
- https://github.com/rergards/mempalace-code/blob/main/docs/LLM_USAGE_RULES.md

Evaluate mempalace-code for this repo specifically, not generic memory tooling.

1. Current context burn: what do I re-explain, and how many tokens/week are spent re-reading files?
2. Highest-ROI surfaces: rank code, docs/prose, design notes, conversation/log exports, manual decisions, KG facts, architecture relationships.
3. Stack support: list supported languages/file types actually indexed; name unsupported extensions that are skipped by default. Distinguish tree-sitter AST, regex structural, Markdown/prose, Kubernetes YAML, and adaptive chunking.
4. Agent workflow fit: which MCP tools should you use proactively (`mempalace_search`, `mempalace_code_search`, `mempalace_file_context`, KG, tunnels, diary, manual drawers)?
5. Ops fit: recommend global MCP, project-scoped MCP, or no MCP; cover 29-tool prompt surface and profile subsetting options (`--profile`, `--tools`, `--exclude`), `mine` vs `mine-all`, `watch` cadence, backup/repair, and offline/model constraints.
6. Decision: install now, try scoped for a week, wait for a named feature, or skip. Give the first 3 commands you would run.
7. If waiting: ask me whether to draft a GitHub feature request.

For repos that already have a hand-curated memory file, evaluate mempalace-code as a complement, not a replacement. A good trial order is:

1. KG first — move volatile current facts (active branch, phase, owner, deadline,

status) into temporal triples; keep curated prose for reasoning and narrative.

1. Drawers + docs second — mine design docs, specs, long decision notes, and

conversation/log exports where semantic retrieval beats manual grep.

1. Code mining last — start with one high-value subproject, then expand if

agents actually use the results.

Cost caveat: the MCP server defaults to all 29 tools. Use --profile=minimal or --tools=search,add_drawer at startup to reduce the prompt/tool-surface cost. Proactive use also depends on adding the usage-rules block to agent instructions. Prefer project-scoped MCP for trials, and keep it only if searches, KG lookups, or drawer writes show up in real sessions.

Supported MCP Clients

mempalace-code works with any MCP-compatible client:

• Claude Code (CLI, desktop, web) — claude mcp add mempalace-code -- python -m mempalace_code.mcp_server
• Codex CLI — codex mcp add mempalace-code -- python -m mempalace_code.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_code.mcp_server (stdio transport)

For local models without MCP support (Llama, Mistral, etc.), use mempalace-code wake-up to pipe context into the system prompt — see [Memory Layers](#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](docs/BENCHTOKENDELTA.md) 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 or stored:

• Code files — structural chunks for Python, TypeScript/JS/TSX/JSX, Go, Rust, Java, Kotlin, C#, F#, VB.NET, XAML, Swift, PHP, Scala, Dart, Lua, Ruby, Terraform/HCL, Markdown, Kubernetes manifests, Helm charts/templates, and Ansible playbooks/roles/inventory; adaptive chunks for C/C++, shell, SQL, HTML/CSS, JSON/YAML/TOML, CSV, Dockerfile, Make, templates, and config files
• .NET solutions — .sln/.csproj project graphs, cross-project symbol relationships, interface implementations
• Architecture facts — pattern, layer, namespace, and project membership facts for .NET and Python projects
• Conversation/log exports — Claude Code JSONL, OpenAI Codex CLI JSONL, Gemini CLI JSONL, Claude.ai JSON, ChatGPT conversations.json, Slack JSON, plain text transcripts
• MCP-saved context — manual drawers are vector-indexed; diary entries and temporal KG facts are stored in their own retrieval surfaces
• Architecture notes, decisions, anything else you store manually

Generated helper files such as entities.json are skipped during project mining by default, because they are created by init/entity detection and should not become source-code drawers unless explicitly force-included.

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

---

Features

Language-Aware Code Mining

mempalace-code mine walks your source tree and chooses the best chunker for each file type: AST boundaries where optional tree-sitter grammars are available, regex structural boundaries for supported languages, YAML-aware Kubernetes/Helm/Ansible resource splits, Markdown/prose sections, or adaptive line-count chunks for formats without reliable declarations. The shared catalog currently exposes 45 searchable language labels to code_search(language=...). Leading comments and docstrings stay attached to declarations where structural chunking is active; Markdown drawers keep heading path, section type, and Mermaid/code/table flags in search metadata.

| Language | Strategy | AST Support | |----------|----------|:-----------:| | Python | Functions, classes, methods, decorators | Optional tree-sitter | | TypeScript / JavaScript / TSX / JSX | Functions, classes, exports, imports | Optional tree-sitter | | Go | Functions, types, methods, interfaces | Optional tree-sitter | | Rust | Functions, structs, enums, traits, impls | Optional 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 | | Terraform / HCL | Terraform/HCL top-level blocks (resource, module, variable, moved, import, check, etc.) | Regex | | Kubernetes manifests | Deployments, Services, ConfigMaps, Secrets, Ingresses, CRDs (indexed by kind/name) | YAML-aware | | Helm charts | Chart.yaml, values*.yaml, raw templates with kind/name metadata; no template rendering | YAML/Go-template aware | | Ansible | Playbooks, role tasks/handlers/defaults/vars, inventories; no Jinja evaluation or inventory semantics | YAML/Jinja tolerant | | Markdown / plain text | Heading sections (#-######), heading paths, section metadata, paragraphs | — | | Lua | Functions, local functions, methods (dot/colon), module/table declarations | Regex | | C / C++ | Indexed and searchable with best-effort symbol metadata; chunked adaptively today | — | | Ruby | Static classes, modules, methods, singleton methods, attrs, and constants; Rails DSL/metaprogramming not interpreted | Regex | | shell / SQL | Indexed and searchable; chunked adaptively today | — | | HTML / CSS / CSV | Indexed and searchable; chunked adaptively today | — | | YAML / JSON / TOML | Adaptive line-count; Kubernetes YAML auto-detected separately | — | | Dockerfile / Make / templates / config | Dockerfile, Containerfile, Makefile, GNUmakefile, Vagrantfile, Go templates, Jinja2, .conf, .cfg, .ini | — |

The mempalace_code_search language filter is generated from the same language catalog as the miner. If a file type is mined with a language label, the MCP schema and unsupported-language hints stay aligned with that catalog.

Tree-sitter is optional (pip install "mempalace-code[treesitter]"). When a grammar is missing, Python, TypeScript/JavaScript/TSX/JSX, Go, and Rust fall back to regex structural chunking. Other recognized formats use their regex, YAML-aware, prose, or adaptive chunker as listed above.

Extensions outside the miner catalog are skipped by normal project scans unless you explicitly force-include an exact path with --include-ignored path/to/file.

mempalace-code mine ~/projects/myapp                  # all supported file types
mempalace-code mine ~/projects/myapp --wing myapp     # tag with a specific wing
mempalace-code mine ~/chats/ --mode convos            # mine conversation exports
mempalace-code mine-all ~/projects/                   # sync all projects incrementally (one wing per project)
mempalace-code mine-all ~/projects/ --new-only        # skip projects whose wing already exists (first-run only)

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

Multi-project wing naming — mine-all assigns one wing per project using this priority:

1. wing: in the project's mempalace.yaml (explicit override)
2. Git origin repo name (e.g. my-repo.git → my_repo)
3. Normalized folder name

If two projects resolve to the same wing name, mine-all exits with an error before mining anything. Fix this by adding a unique wing: value to each project's mempalace.yaml. Use --new-only to skip projects already present in the palace (useful for first-run batch ingestion).

Optional Entity Detection

mempalace-code init is config-first by default: it detects rooms from the directory structure and does not scan file contents for names. Add --detect-entities only when the directory contains prose where people or project names matter, such as meeting notes, client notes, personal notes, or conversation exports:

mempalace-code init ~/notes --detect-entities        # prompts to confirm detected people/projects
mempalace-code init ~/notes --detect-entities --yes  # auto-accept entity confirmation (no room prompts)

The detector is a lightweight bootstrap step, not the main miner. It samples up to 10 readable files, prefers prose files (.md, .txt, .rst, .csv), reads the first 5 KB of each sampled file, and looks for heuristic signals such as Alice said, thanks Bob, Apollo repo, deploy Apollo, or import Apollo. Confirmed results are written to /entities.json:

{
  "people": ["Alice", "Bob"],
  "projects": ["Apollo"]
}

Use it for human/project context. Leave it off for normal code repos unless their docs contain the entities you want captured. Full-repo scanning would be slower and noisier: class names, packages, examples, and variables often look like people or products to a heuristic pass. Code structure, symbols, languages, and architecture relationships are handled by mempalace-code mine, not by entity detection.

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-code watch ~/projects/my-app                # watch an initialized project (on commit)
mempalace-code watch ~/projects/                      # watch all initialized projects in a parent directory
mempalace-code watch ~/projects/ --on-save            # watch all file saves instead (noisier)
mempalace-code watch ~/projects/ schedule             # print launchd/cron snippet for daemon

watch accepts either an initialized project directory (has mempalace.yaml) or a parent directory containing immediate initialized project subdirectories. Pointing it at a project root that has project files but no mempalace.yaml exits with the correct mempalace-code init command.

Install as persistent daemon (macOS):

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

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [rergards](https://github.com/rergards)
- **Source:** [rergards/mempalace-code](https://github.com/rergards/mempalace-code)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.