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 single static binary 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. Zero dependencies. 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 — every release binary is signed, checksummed, and scanned by 70+ antivirus engines. 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.

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 — single static binary for macOS (arm64/amd64), Linux (arm64/amd64), and Windows (amd64). No Docker, no runtime dependencies, no 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 (optional UI binary variant).
• 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 -s -- --ui

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: --ui (graph visualization), --skip-config (binary only, no agent setup), --dir=<path> (custom location).

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

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

   • codebase-memory-mcp-<os>-<arch>.tar.gz (macOS/Linux) or .zip (Windows) — standard
   • codebase-memory-mcp-ui-<os>-<arch>.tar.gz / .zip — with graph visualization

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

   macOS / Linux:

   tar xzf codebase-memory-mcp-*.tar.gz
   ./install.sh
   

   Windows (PowerShell):

   Expand-Archive codebase-memory-mcp-windows-amd64.zip -DestinationPath .
   Unblock-File .\install.ps1
   .\install.ps1
   

3. 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.

Graph Visualization UI

The UI ships as a separate ui build (it embeds the frontend). The default install on every channel is the lean, headless server; opt into the UI build with:

• install.sh: add --ui (see Quick Start)
• npm: CBM_VARIANT=ui npm install -g codebase-memory-mcp
• PyPI: CBM_VARIANT=ui pip install codebase-memory-mcp
• Manual: download the codebase-memory-mcp-ui-<os>-<arch> archive

Then run it:

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

Open http://localhost:9749 in your browser. The UI runs as a background thread alongside the MCP server — it's available whenever your agent is connected.

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

codebase-memory-mcp update

The MCP server also checks for updates on startup and notifies on the first tool call if a newer release is available.

Uninstall

codebase-memory-mcp uninstall

Removes owned agent config entries, skills, hooks, instructions, and the installed binary. Existing graph indexes are listed and deleted only after confirmation.

Features

Graph & analysis

• Architecture overview: get_architecture returns languages, packages, entry points, routes, hotspots, boundaries, layers, and clusters in a single call
• Architecture Decision Records: manage_adr persists architectural decisions across sessions
• Louvain community detection: Discovers functional modules by clustering call edges
• Git diff impact mapping: detect_changes maps uncommitted changes to affected symbols with risk classification
• Call graph: Resolves function calls across files and packages (import-aware, type-inferred)
• Dead code detection: Finds functions with zero callers, excluding entry points
• Cypher-like queries: `MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main