codebase-memory-mcp

The fastest and most efficient code intelligence engine for AI coding agents. Full-indexes an average repository in milliseconds, the Linux kernel (28M LOC, 75K files) in 3 minutes. Answers structural queries in under 1ms. Ships as a native executable with a small verified runtime-asset set for macOS, Linux, and Windows — download, run install, done.

High-quality parsing through tree-sitter AST analysis across all 158 languages, enhanced with Hybrid LSP semantic type resolution for Python, TypeScript / JavaScript / JSX / TSX, PHP, C#, Go, C, C++, Java, Kotlin, Rust, and Perl — producing a persistent knowledge graph of functions, classes, call chains, HTTP routes, and cross-service links. 15 MCP tools. No language runtime, hosted service, or API key. Plug and play across 43 supported automatic/conditional client surfaces.

Research — The design and benchmarks behind this project are described in the preprint Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP (arXiv:2603.27277). Evaluated across 31 real-world repositories: 83% answer quality, 10× fewer tokens, 2.1× fewer tool calls vs. file-by-file exploration.

Security & Trust — This tool reads your codebase and writes to your agent configuration files. That is what it is designed to do. If you prefer to audit before running, the full source is here. For each release product, three behaviourally identical executable candidates (unstripped, debug-stripped, stripped) are submitted to VirusTotal before testing; the selected candidate is then packaged with its SHA-256 unchanged. Release notes link every measured candidate result. Publication permits only the narrowly documented single-Microsoft !ml tolerance in SECURITY.md. All processing happens 100% locally; your code never leaves your machine. Found a security issue? We want to know — see SECURITY.md. Security is Priority #1 for us.

Built-in 3D graph visualization — explore your knowledge graph at localhost:9749

Why codebase-memory-mcp

• Extreme indexing speed — Linux kernel (28M LOC, 75K files) in 3 minutes. RAM-first pipeline: LZ4 compression, in-memory SQLite, fused Aho-Corasick pattern matching. Memory released after indexing.
• Plug and play — native executable plus authenticated release-owned assets for macOS (arm64/amd64), Linux (arm64/amd64), and Windows (amd64). The native install needs no Docker, language runtime, or API keys. Download → install → restart agent → done.
• 158 languages — vendored tree-sitter grammars compiled into the binary. Nothing to install, nothing that breaks.
• 120x fewer tokens — 5 structural queries: ~3,400 tokens vs ~412,000 via file-by-file search. One graph query replaces dozens of grep/read cycles.
• 43 supported automatic/conditional client surfaces — install configures detected clients and safely activates conditional clients only when their documented platform, marker, or explicit existing config path is present. See Multi-Agent Support for the complete matrix and manual/UI-only boundaries.
• Built-in graph visualization — 3D interactive UI at localhost:9749, served from the binary itself.
• Infrastructure-as-code indexing — Dockerfiles, Kubernetes manifests, and Kustomize overlays indexed as graph nodes with cross-references. Resource nodes for K8s kinds, Module nodes for Kustomize overlays with IMPORTS edges to referenced resources.
• 15 MCP tools — search, trace, architecture, impact analysis, targeted index-coverage checks, Cypher queries, dead code detection, cross-service HTTP linking, ADR management, and more.

Quick Start

One-line install (macOS / Linux):

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

With graph visualization UI:

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

Windows (PowerShell):

# 1. Download the installer
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1

# 2. (Optional but recommended) Inspect the script
notepad install.ps1

# 3. Unblock the downloaded file (removes Mark-of-the-Web restriction added by browsers/Invoke-WebRequest)
Unblock-File .\install.ps1

# 4. Run it
.\install.ps1

Note: If you see a script execution policy error, run Set-ExecutionPolicy -Scope Process Bypass first, or invoke with PowerShell -ExecutionPolicy Bypass -File .\install.ps1.

Options: --skip-config (binary only, no agent setup), --dir=<path> (custom location).

Antivirus note: Microsoft Defender may flag a release binary as Trojan:Script/Wacatac.B!ml. This is a known false positive — typically 61 of ~62 engines return clean, and the same detection family hits gh, llama.cpp, Godot and Microsoft's own Go toolchain. See Antivirus False Positives for the evidence, how to verify the artifacts yourself, and how to report it if you think we are wrong.

Restart your coding agent. Say "Index this project" — done.

Manual install

1. Download the archive for your platform from the latest release:

2. codebase-memory-mcp-<os>-<arch>.tar.gz (macOS/Linux) or .zip (Windows)

3. Extract and install (each archive includes install.sh or install.ps1):

macOS / Linux: bash tar xzf codebase-memory-mcp-*.tar.gz ./install.sh

Windows (PowerShell): powershell Expand-Archive codebase-memory-mcp-windows-amd64.zip -DestinationPath . Unblock-File .\install.ps1 .\install.ps1

1. Restart your coding agent.

The install command automatically strips macOS quarantine attributes and ad-hoc signs the binary — no manual xattr/codesign needed.

The install command auto-detects installed coding agents and configures their documented MCP entries plus durable instructions, skills, and lifecycle hooks where supported.

Session Coordination Daemon

CBM automatically shares one per-account coordination daemon across Claude Code, Codex, OpenCode, and every other configured client. There is no opt-in setting for MCP servers or hook clients: the first daemon-backed CBM session starts it, each session registers its own work, and the final session shuts it down. The daemon owns long-lived background services such as watchers, shared indexing jobs, and the optional UI. Closing one session cancels work owned only by that session, while work still needed by another session continues.

The detached daemon does not depend on an MCP frontend's stderr. It keeps owner-only durable records under the canonical ${CBM_CACHE_DIR}/logs directory (default ~/.cache/codebase-memory-mcp/logs):

Thin frontends still write immediate startup and session-specific errors to their own stderr; MCP JSON-RPC stdout remains clean.

All active CBM processes must run the exact same version, executable build, coordination ABI, and canonical cache root. Equivalent CBM_CACHE_DIR aliases resolve to the same root; a genuinely different root is rejected while any CBM process is active. MCP servers, hooks, one-shot CLI commands, temporary index workers, and the daemon share a crash-safe OS admission barrier; starting an ordinary conflicting process fails before doing work and records an explicit conflict in ${CBM_CACHE_DIR}/logs/daemon-conflicts.ndjson.

The native install, update, and uninstall commands are the deliberate exception to that conflict rule. Download, verification, and private same-filesystem staging happen first so a bad candidate never disrupts active work. Activation then publishes account-wide maintenance intent, asks the daemon and every temporary local operation to cancel, and waits to a finite deadline for all coordinated CBM processes to exit. It holds the admission and lifetime barriers exclusively while changing the active binary, configuration, PATH, or indexes. New CBM work cannot enter during this window. Activation progress and results are recorded in ${CBM_CACHE_DIR}/logs/activation-events.ndjson, and a successful command tells you to restart open coding-agent sessions so they launch the activated build.

Package-manager setup (npm, PyPI, or Go) verifies and publishes a coherent private cached runtime set. Sidecars are replaced before the executable with per-file atomic renames; an interrupted multi-file publication is detected and repaired on the next launch rather than being described as one crash-atomic filesystem transaction. It does not replace the active native installation and therefore does not stop running CBM sessions. When that cached binary is executed, it still enters the same exact-build admission barrier. The shell and PowerShell installers invoke the verified candidate's native install command, so they do receive the full account-wide activation guarantee.

The ordinary cli mode is intentionally separate: it runs one command locally and never starts or connects to the coordination daemon, registers a daemon session, or starts watchers/UI. Its only shared state is the OS admission barrier plus per-project locks for graph mutations. While the command is running, a temporary monitor lets activation cancel that operation and its supervised worker safely; the monitor exits with the command and never becomes a standing daemon. See CLI Mode for details.

Graph Visualization UI

The graph UI is built into the binary — every install on every channel has it. Then run it:

codebase-memory-mcp --ui=true --port=9749

Open http://localhost:9749 in your browser. The UI is owned by the shared coordination daemon, so concurrent agent sessions do not start duplicate HTTP servers.

Auto-Index

Enable automatic indexing on MCP session start:

codebase-memory-mcp config set auto_index true

When enabled, new projects are indexed automatically on first connection. Previously-indexed projects are registered with the background watcher for ongoing git-based change detection. Configurable file limit: config set auto_index_limit 50000.

Watcher registration is controlled separately by auto_watch (default true). Set config set auto_watch false to keep a session from registering its project with the background watcher — useful when working across many projects and you want each session contained to explicit indexing.

Keeping Up to Date

Updates run from the install script on every platform, not from inside the running binary. codebase-memory-mcp update validates your flags and then prints the exact command to run:

# macOS / Linux
bash "<install-dir>/install.sh"

# Windows
powershell -ExecutionPolicy Bypass -File "<install-dir>\install.ps1"

The install script is placed next to the binary at install time, so the printed path resolves beside the executable. It is idempotent, so re-running it is the update: it stops the daemon, retires the running binary, installs the new one, and cleans up.

Why it works this way. On Windows it is a hard requirement — a running executable cannot replace its own image, so the swap has to happen from a process that is not the binary being replaced. On macOS and Linux it is a deliberate choice: an in-process updater is structurally a downloader (fetch an archive, verify it, unpack it, mark a file executable, run it