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. MCP exposes a streamlined default tool set with advanced tools available on demand. Zero dependencies. Plug and play across 11 coding agents.

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.

Built-in 3D graph visualization (UI variant) — 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 — 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.
• 156 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.
• One command across supported agents — install auto-detects Claude Code, Claude Desktop, Codex CLI, Gemini CLI, Qwen Code, ForgeCode, Zed, OpenCode, Antigravity, Aider, standalone Kilo, the legacy Kilo VS Code extension, VS Code, Cursor, Windsurf, OpenClaw, Kiro, and Junie, then adds only the MCP entries, owned instruction blocks, skills, and hooks each client supports.
• 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.
• 16 MCP tools (classic mode; a streamlined subset is the default) — search, trace, architecture, impact analysis, 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.

Manual install

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.

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):

File	Contents
cbm-daemon.log	Daemon lifecycle, watcher/indexing, UI, resource, and error events.
daemon-conflicts.ndjson	Exact-build, coordination-ABI, and cache-root admission conflicts.
activation-events.ndjson	Install/update/uninstall activation progress and outcomes.

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) only verifies and atomically publishes that package's private cached binary; 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 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 is owned by the shared coordination daemon, so concurrent agent sessions do not start duplicate HTTP servers.

Auto-Index

Enable automatic indexing at MCP session startup or first graph-backed use:

codebase-memory-mcp config set auto_index true

When enabled, new projects are indexed automatically at startup or first graph-backed use. With auto_watch=true, indexed projects are registered with the background watcher for Git-based change detection; refreshes use the configured reindex policy. 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' RETURN g.name

Search

• Semantic search (semantic_query): vector search across the entire graph, powered by bundled Nomic nomic-embed-code embeddings (40K tokens, 768d int8) compiled into the binary — no API key, no Ollama, no Docker. 11-signal combined scoring (TF-IDF, RRI, API/Type/Decorator signatures, AST profiles, data flow, Halstead-lite, MinHash, module proximity, graph diffusion).
• BM25 full-text search via SQLite FTS5 with cbm_camel_split tokenizer (camelCase / snake_case aware)
• Structural search (search_graph): regex name patterns, label filters, min/max degree, file scoping
• Code search (search_code): graph-augmented grep over indexed files only

Cross-service linking

• HTTP route ↔ call-site matching with confidence scoring
• gRPC, GraphQL, tRPC service detection with protobuf Route extraction
• Channel detection (EMITS / LISTENS_ON) for Socket.IO, EventEmitter, and generic pub-sub patterns across 8 languages with constant resolution

Cross-repo intelligence

• CROSS_* edges link nodes across multiple repos indexed under the same store
• Multi-galaxy 3D UI layout for cross-repo architecture visualization
• Cross-repo architecture summary combining services, routes, and dependencies across the indexed fleet

Edge types (selected)

• CALLS, IMPORTS, DEFINES, IMPLEMENTS, INHERITS
• HTTP_CALLS, ASYNC_CALLS (cross-service)
• EMITS, LISTENS_ON (channels)
• DATA_FLOWS with arg-to-param mapping + field access chains
• SIMILAR_TO (MinHash + LSH near-clone detection, Jaccard scored)
• SEMANTICALLY_RELATED (vocabulary-mismatch, same-language, score ≥ 0.80)

Indexing pipeline

• 156 vendored tree-sitter grammars compiled into the binary
• Generic package / module resolution — bare specifiers like @myorg/pkg, github.com/foo/bar, use my_crate::foo resolved via manifest scanning (package.json, go.mod, Cargo.toml, pyproject.toml, composer.json, pubspec.yaml, pom.xml, build.gradle, mix.exs, *.gemspec)
• Infrastructure-as-code indexing — Dockerfiles, Kubernetes manifests, Kustomize overlays as graph nodes
• Hybrid LSP semantic type resolution for Python, TypeScript / JavaScript / JSX / TSX, PHP, C#, Go, C, C++, Java, Kotlin, Rust, and Perl — a lightweight C implementation of language type-resolution algorithms, structurally inspired by and compatible with major language servers including tsserver / typescript-go, pyright, gopls, Roslyn, Eclipse JDT, and rust-analyzer (parameter binding, return-type inference, generic substitution, JSX component dispatch, JSDoc inference for plain JS files, namespace + trait + late-static-binding resolution for PHP, file-scoped namespaces + records + LINQ method syntax for C#, class-hierarchy + overload + lambda resolution for Java, extension-function + scope-function resolution for Kotlin, trait-method + UFCS resolution for Rust)
• RAM-first pipeline: LZ4 compression, in-memory SQLite, single dump at end. Memory released after.

Distribution & operation

• Single static binary, zero infrastructure: SQLite-backed, persists to ~/.cache/codebase-memory-mcp/
• Auto-sync: Background watcher detects git changes and re-indexes automatically when configured
• Route nodes: REST endpoints are first-class graph entities
• CLI mode: codebase-memory-mcp cli search_graph '{"project": "my-project", "name_pattern": ".*Handler.*"}'
• Available on: npm, PyPI, Homebrew, Scoop, Winget, Chocolatey, AUR, go install

Team-Shared Graph Artifact

Commit a single compressed file to your repo and your teammates skip the reindex.

.codebase-memory/graph.db.zst is a zstd-compressed snapshot of the knowledge graph that lives next to your source. When you index with persistence enabled, the artifact is written or refreshed; when a teammate clones the repo and runs codebase-memory-mcp for the first time, the artifact can bootstrap their local graph before any configured refresh.

• Format: SQLite database, indexes stripped, VACUUM INTO compacted, then zstd 1.5.7 compressed (8–13:1 ratio typical)
• Two tiers:
  • Best (zstd -9 + index strip + VACUUM INTO) — written on explicit index_repository
  • Fast (zstd -3) — written by the watcher when it refreshes an existing artifact
• Bootstrap: when no local DB exists but the artifact is present, index_repository imports the artifact first, then applies the configured refresh policy
• No merge pain: a .gitattributes line with merge=ours is auto-created on first export, so concurrent edits don't produce conflicts on the binary artifact
• Optional: never committed unless you want it. Add .codebase-memory/ to .gitignore if you prefer everyone to reindex from scratch.

The result is similar in spirit to graphify's graphify-out/ directory, but as a single compressed file with explicit two-tier export, integrity-checked import, and zero merge friction.

How It Works

codebase-memory-mcp is a structural analysis backend — it builds and queries the knowledge graph. It does not include an LLM. Instead, it relies on your MCP client (Claude Code, or any MCP-compatible agent) to be the intelligence layer.

You: "what calls ProcessOrder?"

Agent calls: trace_path(function_name="ProcessOrder", direction="inbound")

codebase-memory-mcp: executes graph query, returns structured results

Agent: presents the call chain in plain English

Why no built-in LLM? Other code graph tools embed an LLM for natural language → graph query translation. This means extra API keys, extra cost, and another model to configure. With MCP, the agent you're already talking to is the query translator.

Performance

Benchmarked on Apple M3 Pro:

Reproducible experiment runs use the fact-table contract in Benchmark Experiments and the normative terms in Benchmark Terminology. The latter distinguishes lifecycle wall time from overlapping component work before any ratio is reported.

Operation	Time	Notes
Linux kernel full index	3 min	28M LOC, 75K files → 4.81M nodes, 7.72M edges
Linux kernel fast index	1m 12s	1.88M nodes
Django full index	~6s	49K nodes, 196K edges
Cypher query	<1ms	Relationship traversal
Name search (regex)	<10ms	SQL LIKE pre-filtering
Dead code detection	~150ms	Full graph scan with degree filtering
Trace call path (depth=5)	<10ms	BFS traversal

RAM-first pipeline: All indexing runs in memory (LZ4 HC compressed read, in-memory SQLite, single dump at end). Memory is released back to the OS after indexing completes.

Token efficiency: Five structural queries consumed ~3,400 tokens via codebase-memory-mcp versus ~412,000 tokens via file-by-file grep exploration — a 99.2% reduction.

Troubleshooting & Diagnostics

codebase-memory-mcp runs 100% locally and collects no telemetry — your code, queries, environment, and usage never leave your machine. That privacy guarantee also means that when you hit something we can't reproduce on our side (a slow memory climb over hours, a performance regression, a leak that only appears after days of real use), we have no data at all unless you choose to send it. Here is how to capture it yourself.

Capture a diagnostics log

Set CBM_DIAGNOSTICS=1 before the first daemon-backed MCP session starts, then reproduce the problem (let it run as long as it takes — a slow leak needs time to show in the trend). The shared daemon captures this setting from the session that starts it. If it is already running, close all daemon-backed sessions so it exits before changing the setting. The daemon creates a fresh owner-private cbm-diagnostics-<pid>-<random> directory below the system temp directory ($TMPDIR or /tmp on macOS/Linux, %TEMP% on Windows). The exact paths are recorded by the diagnostics.start event in ${CBM_CACHE_DIR}/logs/cbm-daemon.log:

File	What it is
trajectory.ndjson	The memory trajectory — one JSON line every 5 s with rss, committed (Windows commit charge), peak_*, page_faults, fd, and queries. This is the file we need for memory/leak reports — the trend over time is what pinpoints a leak. It is kept on disk after the server exits (so you can grab it post-mortem) and rotates to trajectory.ndjson.1 past ~8 MB.
snapshot.json	The latest snapshot only — handy for a quick live check. Removed on clean exit.

The private randomized directory prevents another local account from pre-placing a link or special file at a predictable diagnostics path. Its <pid> component is the shared daemon's process ID, also recorded by the daemon.start event. Set the variable consistently in the env block of each agent's MCP server config, or export it before launching the first session.

What to share

When you open a memory/performance issue, attach the .ndjson trajectory — it contains no source code or query text, only resource counters. If you'd rather not attach a file, paste it (or an agent's summary of it) into the issue: your assistant can read the NDJSON directly and report whether rss/committed grow monotonically, how fast, and relative to query count — which is exactly what we need to find the cause.

Installation

Pre-built Binaries

Platform	Standard	With Graph UI
macOS (Apple Silicon)	codebase-memory-mcp-darwin-arm64.tar.gz	codebase-memory-mcp-ui-darwin-arm64.tar.gz
macOS (Intel)	codebase-memory-mcp-darwin-amd64.tar.gz	codebase-memory-mcp-ui-darwin-amd64.tar.gz
Linux (x86_64)	codebase-memory-mcp-linux-amd64.tar.gz	codebase-memory-mcp-ui-linux-amd64.tar.gz
Linux (ARM64)	codebase-memory-mcp-linux-arm64.tar.gz	codebase-memory-mcp-ui-linux-arm64.tar.gz
Windows (x86_64)	codebase-memory-mcp-windows-amd64.zip	codebase-memory-mcp-ui-windows-amd64.zip

Every release includes checksums.txt with SHA-256 hashes. All binaries are statically linked — no shared library dependencies.

Windows note: SmartScreen may show a warning for unsigned software. Click "More info" → "Run anyway". Verify integrity with checksums.txt.

Setup Scripts

Automated download + install

macOS / Linux:

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

Windows (PowerShell):

irm https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/scripts/setup-windows.ps1 | iex

AUR (Arch Linux)

yay -S codebase-memory-mcp-bin

paru -S codebase-memory-mcp-bin

The codebase-memory-mcp-bin package is available at: https://aur.archlinux.org/packages/codebase-memory-mcp-bin

Install via Claude Code

You: "Install this MCP server: https://github.com/DeusData/codebase-memory-mcp"

Build from Source

Prerequisites: C compiler + zlib

Requirement	Check	Install
C compiler (gcc or clang)	gcc --version or clang --version	macOS: xcode-select --install, Linux: apt install build-essential
C++ compiler	g++ --version or clang++ --version	Same as above
zlib	—	macOS: included, Linux: apt install zlib1g-dev
Git	git --version	Pre-installed on most systems

git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
scripts/build.sh                    # standard binary
scripts/build.sh --with-ui          # with graph visualization
# Binary at: build/c/codebase-memory-mcp

The standard and release pathways use the Makefile's optimized production defaults (-O2). For an inspectable local development binary, append debug flags through the same build entry point; the final override wins over the production optimization:

scripts/build.sh EXTRA_CFLAGS="-g -O0 -fno-omit-frame-pointer" \
  EXTRA_CXXFLAGS="-g -O0 -fno-omit-frame-pointer"

Use make -f Makefile.cbm test, test-tsan, or test-leak for sanitizer and lifecycle validation; those targets already select their purpose-built compiler and allocator configurations.

Manual MCP Configuration

If you prefer not to use the install command

Add to ~/.claude.json (user scope) or project .mcp.json:

{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "/path/to/codebase-memory-mcp",
      "args": []
    }
  }
}

Restart your agent. Verify with /mcp — you should see codebase-memory-mcp with its tools listed (a streamlined subset by default; set CBM_TOOL_MODE=classic for all 16).

Multi-Agent Support

install configures 43 supported automatic/conditional client surfaces: 37 detected automatically and 6 conditional or explicit. “Conditional” means the installer writes only when the documented platform or an explicit, already-existing config path proves the target is active. It never flips experimental feature flags, enables plugins, YOLO modes, global permission bypasses, or third-party instruction trust.

Agent	Activation	MCP config	Durable context / augmentation
Claude Code	Detected	~/.claude.json	Skill + three exact-tool graph agents; SessionStart, SubagentStart, non-blocking PreToolUse for Grep/Glob, and post-Read coverage
Codex CLI	Detected	$CODEX_HOME/config.toml	AGENTS.md, skill, three read-only agents; SessionStart + SubagentStart
Gemini CLI	Detected	.gemini/settings.json	GEMINI.md, three explicit read/graph-tool subagents; BeforeTool, AfterTool read_file coverage, and SessionStart
Zed	Detected	platform settings.json (JSONC)	AGENTS.md + shared skill
OpenCode	Detected	$OPENCODE_CONFIG or resolved global config	AGENTS.md, skill, three deny-by-default read-only agents
Antigravity	Detected	.gemini/config/mcp_config.json	.gemini/GEMINI.md
Aider	Detected	—	CONVENTIONS.md via .aider.conf.yml
KiloCode	Detected	.config/kilo/kilo.jsonc	Rule + three graph-tool subagents with deny-by-default permissions
VS Code	Detected	platform Code/User/mcp.json	~/.copilot/skills, three read-only agents, sessionStart + subagentStart
Cursor	Detected	.cursor/mcp.json	Skill + three read-only parent-handoff agents; context hooks withheld because session injection races and readonly blocks MCP
Windsurf	Detected	~/.codeium/windsurf/mcp_config.json	Always-on global_rules.md
Augment / Auggie	Detected	~/.augment/settings.json	Rule, three read-only handoff subagents, SessionStart + post-view coverage
OpenClaw	Detected	$OPENCLAW_CONFIG_PATH or state openclaw.json	Active-workspace AGENTS.md + TOOLS.md; compaction reinjection
Kiro	Detected	$KIRO_HOME/settings/mcp.json	Steering, skill, three JSON agents with isolated Scout/Analysis-profile MCP and explicit graph-tool selectors (includeMcpJson: false)
Junie	Detected	.junie/mcp/mcp.json	Skill + three graph subagents for EAP-capable builds; Scout and Analysis server aliases hard-limit the tier tool surfaces; no ineffective EAP SessionStart hook
Hermes	Detected	$HERMES_HOME/config.yaml	Skill + fail-open pre_llm_call context augmentation
OpenHands	Detected	.openhands/mcp.json	Shared .agents/skills/codebase-memory/SKILL.md
Cline	Detected	~/.cline/mcp.json + ${CLINE_DATA_DIR:-~/.cline/data}/settings/cline_mcp_settings.json	Rule + skill; automatic file hooks withheld because they auto-activate and their output is not reliably consumed; child agents cannot use MCP
Warp	Detected, skill only	UI, Warp Drive, or per invocation (manual)	Shared ~/.agents/skills/codebase-memory/SKILL.md
Qwen Code	Detected	.qwen/settings.json	QWEN.md, skill, three explicit read/graph-tool agents; SessionStart, SubagentStart, and post-ReadFile coverage
GitHub Copilot CLI	Detected	$COPILOT_HOME/mcp-config.json	Instructions, skill, three read-only agents; sessionStart + subagentStart
Factory Droid	Detected	.factory/mcp.json	AGENTS.md, skill, three droids with exact per-tier graph-tool lists; SessionStart + post-Read coverage on macOS/Linux, withheld on Windows
Crush	Detected	.config/crush/crush.json	Managed context path with explicit parent-to-child handoff
Goose	Detected	.config/goose/config.yaml	.goosehints
Mistral Vibe	Detected	$VIBE_HOME/config.toml	AGENTS.md, skill, and three matched agent/prompt pairs with explicit read-only graph-tool allowlists
Qoder CLI	Detected	~/.qoder/settings.json	Skill, three directly MCP-attached agents with named-server scoping and exact per-tier graph-tool lists; SessionStart, SubagentStart, and post-Read coverage, including documented PowerShell execution on Windows
Kimi Code CLI	Detected	$KIMI_CODE_HOME/mcp.json (default ~/.kimi-code)	Same-root AGENTS.md + skill; fail-open UserPromptSubmit hook in config.toml
GitLab Duo CLI	Detected	$GLAB_CONFIG_DIR/duo/mcp.json or platform fallback	Fail-open user SessionStart on macOS/Linux; hook withheld on Windows; no experimental global skill enablement
Rovo Dev CLI	Detected	configured override or ~/.rovodev/mcp.json	Global AGENTS.md, skill + three read-only handoff subagents; no undocumented hook
Amp	Detected	~/.config/agents/skills/codebase-memory/mcp.json	Colocated skill + ~/.config/amp/AGENTS.md; no plugin
Devin CLI / Local	Detected	~/.config/devin/config.json (platform app-data path on Windows)	Same-root AGENTS.md + skill; macOS/Linux UserPromptSubmit + PostCompaction, and SessionStart only when Claude does not already provide it; hooks withheld on Windows
Tabnine	Detected	~/.tabnine/mcp_servers.json	MCP only; no experimental/YOLO setting
Continue / cn	Conditional	Existing ~/.continue/config.yaml or $CBM_CONTINUE_CONFIG_PATH	MCP only
Visual Studio	Conditional, Windows	~/.mcp.json	MCP only
TRAE	Conditional	Existing $CBM_TRAE_CONFIG_PATH	MCP only
Roo Code	Conditional	Existing $CBM_ROO_CONFIG_PATH	MCP only
Amazon Q Developer IDE	Detected	~/.aws/amazonq/default.json (preserves an existing agents/default.json or legacy mcp.json)	MCP only
CodeBuddy Code CLI	Detected	~/.codebuddy/.mcp.json (preserves an active deprecated/legacy file)	CODEBUDDY.md, skill, three read-only graph agents; beta hooks are not auto-installed
IBM Bob Shell	Detected by bob	~/.bob/mcp_settings.json	Shared rule; no invented hook or agent
Pochi	Detected	~/.pochi/config.jsonc (mcp)	README.pochi.md, skill, and three readFile-only parent-handoff agents
Pi	Detected	—	~/.pi/agent/AGENTS.md + skill; MCP/subagents require an explicit reviewed extension
IBM Bob IDE	Conditional	Existing ~/.bob/mcp.json	Shared rule + IDE skill; no invented hook or agent
Sourcegraph Cody	Explicit opt-in	Existing $CBM_CODY_CONFIG_PATH	MCP only

Claude Desktop is additionally supported as a detected MCP-only desktop surface through its platform claude_desktop_config.json; it is outside the 43 coding-agent registry matrix above.

Hooks are structurally non-blocking (exit code 0, every failure path). For Claude Code, the non-blocking PreToolUse augmenter observes Grep, Glob, and Read. It injects graph matches for searches and indexing-coverage notes for reads as additionalContext; it never denies the underlying tool call. For Codex, Gemini CLI, and Antigravity, a SessionStart hook injects a one-line code-discovery reminder as session context (Gemini CLI also keeps its BeforeTool reminder). The installed Claude shim file is named cbm-code-discovery-gate for backward compatibility with existing installs; despite the legacy name it never gates and never blocks.

CLI Mode

Every MCP tool can be invoked as a local, one-shot command. CLI tools neither start nor connect to the coordination daemon and leave no standing process behind. They hold a crash-safe exact-build admission lease only for the command lifetime. index_repository is the only exception internally: it starts a temporary, exact-build supervised worker for the index, then stops that worker before the CLI command exits; the worker holds its own lease until exit.

Commands that mutate graph data use shared OS-backed, per-project locks. This serializes conflicting work from CLI and MCP sessions on the same project while allowing unrelated projects to proceed independently.

When stderr is an interactive terminal, the CLI automatically shows lifecycle and indexing progress. Pass --progress to force the same feedback when stderr is redirected or the command is run non-interactively. Progress is written only to stderr; stdout remains reserved for the command result, so pipes and scripts stay machine-safe. Pass --json when the full MCP result envelope is needed.

Use cli <tool> --help to see the flags generated from that tool's input schema:

codebase-memory-mcp cli index_repository --repo-path /path/to/repo
codebase-memory-mcp cli list_projects

# Use the "name" returned by list_projects as the project value.
codebase-memory-mcp cli search_graph --project my-project --name-pattern '.*Handler.*' --label Function
codebase-memory-mcp cli trace_path --project my-project --function-name Search --direction both
codebase-memory-mcp cli query_graph --project my-project --query 'MATCH (f:Function) RETURN f.name LIMIT 5'

# Force human-readable progress without contaminating stdout.
codebase-memory-mcp cli --progress index_repository --repo-path /path/to/repo
codebase-memory-mcp cli search_graph --project my-project --label Function | jq '.results[].name'

JSON arguments can also be piped on stdin. Inline JSON remains accepted for backward compatibility but is deprecated in favor of flags, --args-file, or stdin.

MCP Tools

Indexing

Tool	Description
index_repository	Index a repository into the graph. Auto-sync can refresh it after that when configured.
list_projects	List all indexed projects with node/edge counts.
delete_project	Remove a project and all its graph data.
index_status	Check indexing status of a project.

Querying

Tool	Description
search_graph	Structured search by label, name pattern, file pattern, degree filters. Pagination via limit/offset.
trace_path	BFS traversal — who calls a function and what it calls. Depth 1-5.
detect_changes	Map git diff to affected symbols + blast radius with risk classification.
query_graph	Execute Cypher-like graph queries (read-only).
get_graph_schema	Node/edge counts, relationship patterns, property definitions per label. Run this first.
get_code_snippet	Read source code for a function by qualified name.
get_architecture	Codebase overview: languages, packages, routes, hotspots, clusters, ADR.
search_code	Grep-like text search within indexed project files.
manage_adr	CRUD for Architecture Decision Records.
ingest_traces	Ingest runtime traces to validate HTTP_CALLS edges.

Graph Data Model

Node Labels

Project, Package, Folder, File, Module, Class, Function, Method, Interface, Enum, Type, Route, Resource

Edge Types

CONTAINS_PACKAGE, CONTAINS_FOLDER, CONTAINS_FILE, DEFINES, DEFINES_METHOD, IMPORTS, CALLS, HTTP_CALLS, ASYNC_CALLS, IMPLEMENTS, HANDLES, USAGE, CONFIGURES, WRITES, MEMBER_OF, TESTS, USES_TYPE, FILE_CHANGES_WITH

Qualified Names

get_code_snippet uses qualified names: <project>.<path_parts>.<name>. Use search_graph to discover them first.

Supported Cypher (openCypher read subset)

query_graph is a read-only openCypher subset:

• Clauses: MATCH, OPTIONAL MATCH, multiple MATCH, WHERE, WITH (+ WITH … WHERE and later match stages), RETURN, multi-key ORDER BY on projected fields or aliases, SKIP, LIMIT, DISTINCT, UNWIND, UNION / UNION ALL, CASE.
• Patterns: labelled nodes, label alternation (n:A|B), relationship types/direction, variable-length paths [*1..3], inline property maps.
• WHERE: = <> < <= > >=, AND/OR/XOR/NOT, IN, CONTAINS, STARTS WITH, ENDS WITH, IS [NOT] NULL, regex =~, label test n:Label, and EXISTS { (n)-[:TYPE]->() } (single-hop existence — great for dead-code, e.g. WHERE NOT EXISTS { (f)<-[:CALLS]-() }).
• Aggregates: count (+DISTINCT), sum, avg, min, max, collect.
• Functions: labels, type, id, keys, properties; toLower/toUpper/toString/toInteger/toFloat/toBoolean; size, length, trim/ltrim/rtrim, reverse; coalesce, substring, replace, left, right.

Anything outside this subset (write/MERGE/CALL clauses, unsupported functions, list/map literals, comprehensions, path functions, parameters) fails with a clear unsupported … error rather than returning empty results. Valid queries that match zero rows return a hint naming any label or relationship type not present in that project's graph, plus a short summary of the vocabulary that is.

Ignoring Files

Layered: hardcoded patterns (.git, node_modules, etc.) → .gitignore hierarchy → .cbmignore (project-specific, gitignore syntax). Symlinks are always skipped.

See docs/cbmignore.md for the full .cbmignore how-to: syntax, precedence across the ignore layers, and negation semantics.

Configuration

codebase-memory-mcp config list                          # show common effective settings
codebase-memory-mcp config set auto_index true           # auto-index on startup/first use
codebase-memory-mcp config set auto_index_limit 50000    # max files for auto-index
codebase-memory-mcp config set tool_mode streamlined     # concise surface; reveal advanced tools on demand
codebase-memory-mcp config set auto_index_deps true      # index installed dependency APIs
codebase-memory-mcp config set auto_dep_limit 20         # import-ranked dependency package cap; 0=unlimited
codebase-memory-mcp config set dep_max_files 1000        # per-package source-file cap; 0=unlimited
codebase-memory-mcp config preset list                   # list named capability/API configurations
codebase-memory-mcp config preset apply streamlined-automatic-dependency-source-indexing-disabled
codebase-memory-mcp config preset apply streamlined-automatic-dependency-source-indexing-enabled
codebase-memory-mcp config set auto_watch false          # don't register background git watcher (default: true)
codebase-memory-mcp config set default_response_format json  # full JSON objects instead of compact TOON tables
codebase-memory-mcp config reset auto_index              # reset to default

Normal streamlined exploration uses the core tools without a reveal; first-use indexing and first-response codebase context are automatic when configured. Use _hidden_tools only for explicit advanced operations such as check_index_coverage, index_repository, or index_dependencies. Classic mode advertises those tools directly and uses search_graph, then trace_path, then get_code_snippet for structural discovery. Automatic repository indexing obeys auto_index/auto_index_limit; automatic dependency indexing obeys auto_index_deps/auto_dep_limit/dep_max_files and is disabled by default. Packages above dep_max_files are skipped rather than partially indexed. Explicit index_dependencies calls remain available; disabling automation does not delete dependency projects that are already indexed.

Environment Variables

Variable	Default	Description
CBM_ALLOWED_ROOT	(unset)	Restrict index_repository to paths within this directory. When set, a repo_path that resolves (after symlink / .. resolution) outside this root is refused; unset imposes no restriction. Useful when the server may be driven by an untrusted caller, e.g. agentic or multi-tenant deployments.
CBM_CACHE_DIR	~/.cache/codebase-memory-mcp	Override the database storage directory. All project indexes and config are stored here. One account can use only one canonical cache root at a time; close active CBM sessions/commands before switching it.
CBM_DIAGNOSTICS	false	Set to 1 or true to enable the shared daemon's periodic snapshot.json and retained trajectory.ndjson below a fresh owner-private directory in the system temp directory. Exact paths are logged by diagnostics.start.
CBM_DOWNLOAD_URL	(GitHub releases)	Override the download URL for updates. Used for testing or self-hosted deployments.
CBM_LOG_LEVEL	info	Set the minimum log level. Accepted values (case-insensitive): debug, info, warn, error, none — or their numeric equivalents 0–4 matching the internal enum. Thin-frontend messages go to that session's stderr; detached daemon events go to ${CBM_CACHE_DIR}/logs/cbm-daemon.log. Stdout is reserved for MCP JSON-RPC.
CBM_WORKERS	(detected)	Override the parallel-indexing worker count returned by cbm_default_worker_count. Useful inside containers where sysconf(_SC_NPROCESSORS_ONLN) reports host CPUs rather than the cgroup's effective quota. Range 1–256; invalid values are ignored with a warning.
CBM_MEM_BUDGET_MB	(detected)	Override the in-memory graph budget with an explicit cap in MiB, taking precedence over the ram_fraction × total_RAM default. Useful on bare-metal hosts without a cgroup limit, or to pin a budget below the cgroup limit so headroom is left for sibling processes. Must be a positive integer; it is clamped to detected total RAM (logged as mem.budget.clamped), and non-numeric or non-positive values are ignored with a warning (mem.budget.env.invalid).
CBM_DUMP_VERIFY_MIN_RATIO	0.5	After indexing, compare persisted SQLite node count to the in-memory dump count. When persisted nodes fall below this fraction of committed nodes (and committed > 50), index_repository returns status:"degraded" instead of silent indexed. Range 0–1; set 0 to disable. Invalid values are ignored with a warning.

Environment used by daemon-owned components—such as diagnostics, daemon logging, and process-wide indexing resource limits—is captured from the first daemon-backed session that starts the daemon. Later sessions join that process and cannot replace those values. To change them, close all daemon-backed sessions, update the relevant agent configurations consistently, and restart a session. CBM_ALLOWED_ROOT remains session-specific, a conflicting CBM_CACHE_DIR is rejected, and one-shot CLI commands read their own environment without starting the daemon.

# Store indexes in a custom directory
export CBM_CACHE_DIR=~/my-projects/cbm-data

Custom File Extensions

The JSON config files support a single key, extra_extensions, which maps additional file extensions to supported languages. Useful for framework-specific extensions like .blade.php (Laravel) or .mjs (ES modules). (For other tunables, see Environment Variables and the config subcommand above.)

Need the full config-file reference? See docs/CONFIGURATION.md.

Per-project (in your repo root):

// .codebase-memory.json
{"extra_extensions": {".blade.php": "php", ".mjs": "javascript"}}

Global (applies to all projects):

// ~/.config/codebase-memory-mcp/config.json  (or $XDG_CONFIG_HOME/...)
{"extra_extensions": {".twig": "html", ".phtml": "php"}}

Each entry maps an extension (which must start with .) to a language name. Language names are matched case-insensitively. Accepted values (aliases in parentheses) are:

bash (sh), c, c++ (cpp), c# (csharp), clojure, cmake, cobol, common lisp (commonlisp, lisp), css, cuda, dart, dockerfile, elixir, elm, emacs lisp (emacslisp), erlang, f# (fsharp), form, fortran, glsl, go, graphql, groovy, haskell, hcl (terraform), html, ini, java, javascript, json, julia, kotlin, lean, lua, magma, makefile, markdown, matlab, meson, nix, objective-c (objc), ocaml, perl, php, protobuf, python, r, ruby, rust, scala, scss, sql, svelte, swift, toml, tsx, typescript, verilog, vimscript, vue, wolfram, xml, yaml, zig.

Project config overrides global for conflicting extensions. An entry whose language name is unknown, or whose extension does not start with ., is skipped and a warning is logged to stderr (shown at the default info log level). Missing config files are ignored.

Persistence

SQLite databases stored at ~/.cache/codebase-memory-mcp/. Persists across restarts (WAL mode, ACID-safe). To reset: rm -rf ~/.cache/codebase-memory-mcp/.

Troubleshooting

Problem	Fix
/mcp doesn't show the server	Check .mcp.json path is absolute. Restart agent. Test: echo '{}' | /path/to/binary should output JSON.
index_repository fails	Pass absolute path: index_repository(repo_path="/absolute/path")
trace_path returns 0 results	Use search_graph(name_pattern=".*PartialName.*") first to find the exact name.
Queries return wrong project results	Add project="name" parameter. Use list_projects to see names.
Binary not found after install	Add to PATH: export PATH="$HOME/.local/bin:$PATH"
UI not loading	Ensure you downloaded the ui variant and ran --ui=true. Check http://localhost:9749.

Hybrid LSP

Semantic type resolution beyond tree-sitter.

Tree-sitter alone gives a syntactic AST. That handles naming, structure, and call sites well, but it can't tell you that user.profile.display_name() resolves to Profile.display_name declared three modules away — tree-sitter doesn't track imports, generics, inheritance, or stdlib types.

codebase-memory-mcp ships a lightweight C implementation of language type-resolution algorithms, structurally inspired by and compatible with major language servers (tsserver / typescript-go, pyright, gopls, Roslyn, Eclipse JDT, rust-analyzer), embedded directly into the static binary. No language server process, no per-project setup, no API key. We call this layer Hybrid LSP: it runs alongside tree-sitter on every parse and refines CALLS, USAGE, and RESOLVED_CALLS edges with type information, so the resulting graph mirrors what an IDE "Go to Definition" would resolve.

Languages with full Hybrid LSP:

Language	What it handles
Python (new in v0.7.0)	imports + dotted submodule walks, dataclasses, Self return types, generics, @property, match/case class patterns, SQLAlchemy 2.0 Mapped[T], Pydantic BaseModel, typing.Annotated / ClassVar / Final / InitVar, async/await, classmethod/staticmethod, narrowing (isinstance / is not None / walrus), typing.cast / assert_type, common stdlib (logging, pathlib, json, functools). Target ~95% resolution on idiomatic code.
TypeScript / JavaScript / JSX / TSX	generics, JSX component dispatch, JSDoc inference for plain JS, .d.ts declarations, module re-exports, method chaining via return-type propagation, per-file overlay chained to a shared cross-file registry
PHP (new in v0.7.0)	namespaces, traits, late-static-binding, PHPDoc inference, parameter binding, return-type inference
C# (new in v0.7.0)	global usings, file-scoped namespaces, records (incl. C# 12 primary constructors), LINQ method syntax, async Task<T> / ValueTask<T> unwrap, generic methods, this / base dispatch, var inference, common BCL stdlib
Go (sharpened in v0.7.0)	pre-built per-package cross-file registry, generics, embedded structs, interface satisfaction, package-aware import resolution
C / C++ (sharpened in v0.7.0)	pre-built per-language cross-file registry shared across C and C++; C side handles macros + typedef chains + header-vs-source linking; C++ side handles templates, namespaces, auto inference, and method resolution via class hierarchy
Java (new in v0.8.0)	imports (single-type, on-demand, static), class hierarchies with this / super dispatch, generics, annotations, overload matching by arity and parameter types, lambdas / method references bound to functional interfaces, field-type inference, common JDK stdlib
Kotlin (new in v0.8.0)	imports + same-package resolution, classes / objects / companion objects, extension functions, data classes, nullable-type unwrapping, scope functions (let / apply / run / also / with), infix calls, common stdlib
Rust (new in v0.8.0)	use declarations + module paths, impl blocks and trait methods, struct fields, generics with trait bounds, operator-trait desugaring, derive-macro method synthesis, UFCS static paths, common std prelude
Perl	packages + @ISA / use parent / use base inheritance with method-resolution-order dispatch, SUPER:: calls, Exporter (use Foo qw(...)) import maps, bless / ref($class)||$class self-type inference, qualified Pkg::sub static calls, curated perlfunc + CPAN OOP stdlib; unresolved receivers emit no edge (zero-edge guarantee)

Two-layer architecture:

1. Tree-sitter pass — fast, syntactic, runs for every one of the 156 languages. Extracts definitions, calls, imports.
2. Hybrid LSP pass — type-aware, runs above the tree-sitter pass per-language. Refines call edges using the import graph plus a per-file or pre-built cross-file definition registry. Languages without a Hybrid LSP pass yet fall back to textual resolution, so you always get some answer.

The result is a knowledge graph accurate enough to drive trace_path across packages, inheritance hierarchies, and stdlib calls — without paying for a language server process per project.

Language Support

156 languages, all parsed via vendored tree-sitter grammars compiled into the binary. Benchmarked against 64 real open-source repositories (78 to 49K nodes):

Tier	Score	Languages
Excellent (>= 90%)		Lua, Kotlin, C++, Perl, Objective-C, Groovy, C, Bash, Zig, Swift, CSS, YAML, TOML, HTML, SCSS, HCL, Dockerfile
Good (75-89%)		Python, TypeScript, TSX, Go, Rust, Java, R, Dart, JavaScript, Erlang, Elixir, Scala, Ruby, PHP, C#, SQL
Functional (< 75%)		OCaml, Haskell

Also supported (not yet benchmarked): Ada, Agda, Apex, Assembly (NASM), Astro, AWK, Beancount, BibTeX, Bicep, Bitbake, Blade, Cairo, Cap'n Proto, Clojure, CMake, COBOL, Common Lisp, Crystal, CSV, CUDA, D, Devicetree, Diff, .env, Elm, Emacs Lisp, F#, Fennel, Fish, FORM, Fortran, FunC, GDScript, .gitattributes, .gitignore, Gleam, GLSL, GN, Go module, Go template, GraphQL, Hare, HLSL, Hyprlang, INI, ISPC, Janet, Jinja2, JSDoc, JSON, JSON5, Jsonnet, Julia, Just, Kconfig, KDL, Lean 4, Linker Script, Liquid, LLVM IR, Luau, Magma, Makefile, Markdown, MATLAB, Mermaid, Meson, Move, Nickel, Nim, Nix, Odin, Pascal, Pkl, PO (gettext), Pony, PowerShell, Prisma, .properties, Protobuf, Puppet, PureScript, Racket, Regex, requirements.txt, ReScript, RON, reStructuredText, Scheme, Slang, Smali, Smithy, Solidity, SOQL, SOSL, Squirrel, SSH config, Starlark, Svelte, Sway, SystemVerilog, TableGen, Tcl, Teal, Templ, Thrift, TLA+, Typst, Verilog, VHDL, Vim script, Vue, WGSL, WIT, Wolfram, XML, Zsh.

Architecture

src/
  main.c              Entry point (MCP stdio server + CLI + install/update/config)
  daemon/             Per-account session coordination, IPC, lifecycle, shared jobs/watchers
  mcp/                MCP server (16 classic tools, JSON-RPC 2.0, session detection, auto-index)
  cli/                Install/uninstall/update/config (43 client surfaces, hooks, instructions)
  store/              SQLite graph storage (nodes, edges, traversal, search, Louvain)
  pipeline/           Multi-pass indexing (structure → definitions → calls → HTTP links → config → tests)
  cypher/             Cypher query lexer, parser, planner, executor
  discover/           File discovery (.gitignore, .cbmignore, symlink handling)
  watcher/            Background auto-sync (git polling, adaptive intervals)
  traces/             Runtime trace ingestion
  ui/                 Embedded HTTP server + 3D graph visualization
  foundation/         Platform abstractions (threads, filesystem, logging, memory)
internal/cbm/         Vendored tree-sitter grammars (156 languages) + AST extraction engine

Security

Every release binary is verified through a multi-layer pipeline before publication:

• VirusTotal — all binaries scanned by 70+ antivirus engines (zero detections required to publish)
• SLSA Level 3 — cryptographic build provenance generated by the trusted GitHub Actions build workflow; verify with gh attestation verify <file> --repo DeusData/codebase-memory-mcp --signer-workflow DeusData/codebase-memory-mcp/.github/workflows/_build.yml
• Sigstore cosign — keyless signatures on all artifacts; bundles included in every release
• SHA-256 checksums — checksums.txt published with every release; verified by both install scripts before extraction
• CodeQL SAST — blocks release pipeline if any open alerts remain
• Zero runtime dependencies — no transitive supply chain; all libraries vendored at compile time

v0.7.0 VirusTotal scans

Binary	SHA-256	VirusTotal
linux-amd64	8e12bb2d6ead7f20a6d3...	0/72 ✅
linux-arm64	10f7136bfbf3950c6b2a...	0/72 ✅
darwin-arm64	7062a7408906344bf4f8...	0/72 ✅
darwin-amd64	28c6d640e1a0ac7bfcab...	0/72 ✅
windows-amd64	9c3ddcf78368fd4fa891...	0/72 ✅

Scan links for every release are also included in the GitHub Release notes automatically.

License

MIT