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.

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.
• 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= (custom location).

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

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

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

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

macOS / Linux:

codebase-memory-mcp update

Windows — updates run from install.ps1, not from the running binary, because a running executable cannot replace its own image on Windows. codebase-memory-mcp update prints the exact command; it is:

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

install.ps1 is idempotent, so re-running it is the update: it stops the daemon, retires the running binary, installs the new one, and cleans up. install.ps1 sits next to the binary in your install directory. If PowerShell refuses to run it because the file came from the internet, Unblock-File it first.

Installed through npm or pip? Update with your package manager on every platform (npm install -g codebase-memory-mcp@latest / pip install -U codebase-memory-mcp).

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

• 158 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 file changes and re-indexes automatically
• 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, the artifact is written or refreshed; when a teammate clones the repo and runs codebase-memory-mcp for the first time, the artifact is decompressed and incremental indexing fills in their local diff.

• 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 for low-latency incremental updates
• Bootstrap: when no local DB exists but the artifact is present, index_repository imports the artifact first, then runs incremental indexing — avoiding the full reindex cost
• 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:

| 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-- 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 ` 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

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

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

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   (codebase-memory-mcp.exe on Windows)

Every platform builds one self-contained binary — no runtime dependencies, no companion executables to keep alongside it.

Run the test suite (6,768 tests across 120 suites):

scripts/test.sh                     # full: clean sanitizer build + all suites + guards
scripts/test.sh --suites <name>     # one suite, incremental, seconds
build/c/test-runner --list-suites   # what is available

scripts/test.sh is the same entry the CI gates run, so a local pass means the same thing a CI pass does. Packaging a release archive locally uses the same canonical script the release pipeline calls:

scripts/package-release.sh <linux|darwin|windows> <amd64|arm64>

Manual MCP Configuration

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

Multi-Agent Support

install configures 43 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.

Where a client has a documented custom-agent format, the installer creates three
exact-owned definitions from one canonical contract:

• Scout (Tier 1) — about 3–4 narrow calls for fast positive, provisional discovery; no absence, exhaustive-impact, or dead-code claims.
• Verify (Tier 2, default) — task-directed graph evidence, exact source checks, path coverage for every cited file, and scope coverage before negative claims.
• Auditor (Tier 3) — bounded scope, current index generation, complete relevant pagination, broader relationship checks, and explicit unresolved limitations.

Every direct tier batches check_index_coverage for its evidence paths and reads
flagged ranges or skipped/excluded files directly. A clean coverage result means
only “no recorded gap,” never proof of completeness. Clients without safe child
MCP access receive the same three tiers as parent-handoff agents; the parent must
supply project, generation, pagination state, graph evidence, and coverage
results. Updates migrate only byte-identical prior Verify definitions and never
overwrite user-modified agents.

| 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 (without additive whole-server exposure); 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 |

Sessions, compaction, and subagents

Hooks installed by this project are fail-open and context-only. Claude Code's
PreToolUse observes Grep/Glob and injects matching graph symbols as
additionalContext; PostToolUse on Read adds targeted coverage context when
the graph could not fully parse or index that file. It never denies or replaces
the requested tool call.

Claude Code, Codex CLI, Qwen Code, GitHub Copilot CLI, and VS Code's Copilot
runtime receive paired session/subagent context where the vendor exposes a
documented context-output contract. Codex users must review and trust installed
hooks through /hooks; changing a hook definition changes its trust hash, so an
update can require re-trust. Qoder uses SessionStart, SubagentStart, and
post-Read coverage, including its documented PowerShell executor on Windows.
Kimi uses UserPromptSubmit, while Hermes uses pre_llm_call; both retain their
documented Windows execution paths. Devin installs
UserPromptSubmit and PostCompaction on macOS/Linux and adds SessionStart
only when Claude's equivalent managed hook is not present. GitLab Duo gets a
narrowly scoped macOS/Linux user SessionStart entry on its experimental hook
surface. GitLab Duo, Devin, and Factory hooks are withheld on Windows
because those vendors do not document a deterministic shell/executor contract
there. Gemini CLI, Factory Droid, and Augment also add documented post-read/view
coverage context but expose no equivalent documented child-start context.

For runtimes without a stable context-producing lifecycle event, durable files
carry the contract across fresh sessions and compaction: verify the graph project
and index freshness, query structural facts in the parent, then pass the project,
qualified symbols, paths, and call-chain evidence in every delegated task.
Claude, Codex, Gemini, Kiro, Qwen, Copilot, CodeBuddy, OpenCode, Kilo, Vibe,
Qoder, Junie, and Factory receive Scout, Verify, and Auditor graph profiles.
Kiro embeds this MCP server with --tool-profile scout for Scout and
--tool-profile analysis for Verify/Auditor. Junie registers equivalent named
server aliases because its subagent schema filters by server rather than by
individual tool. Both process profiles use positive allowlists: Scout exposes
seven fast inspection tools, Analysis exposes eleven, and future or mutating
tools remain unavailable until explicitly reviewed. If either Junie alias
collides with user configuration, the installer preserves it and installs
parent-handoff profiles instead. Qoder combines its documented named-server
selection with exact tier-specific MCP tool IDs. Factory uses exact registered
MCP tool IDs without its additive mcpServers field, which would expose the
whole server. Codex, Kilo, Vibe, and other capable formats likewise enumerate
the narrowest supported tool set. Rovo, Cursor, Augment, Pochi, and Cline use parent handoff where direct
child MCP is unavailable or unsafe; Pochi is limited to readFile, and Cline
child agents cannot use MCP.

Cline's file hooks auto-activate when present, and current Cline does not
reliably consume their context output, so automatic adapters are withheld and
older owned adapters are cleaned up. CodeBuddy's beta, version-gated hooks are
not auto-installed. Junie's EAP
SessionStart output is documented as ignored, so no context hook is installed.
Junie custom agents remain EAP-dependent. Qoder can resolve higher-priority
project or plugin agents before user agents with the same name; reload the
client after installation or profile changes.
Cursor context
hooks are withheld: session context injection has a known race, subagentStart
is control-only, and read-only subagents cannot safely receive MCP access. Rovo
has no documented session context-output hook, and Bob
documents neither a suitable hook nor a custom-agent surface. Those surfaces are
not approximated with invented augmentation. Kimi plugins, Amp plugins, and
GitLab experimental global skills remain opt-in.

OpenClaw reinjects the Codebase Knowledge Graph (codebase-memory-mcp) AGENTS
section after compaction and places the same guidance in TOOLS.md, the bootstrap
files inherited by its subagents. Automatic augmentation covers the active/default
workspace. Separate agents.list[].workspace directories require making that
workspace active for installation or copying the managed block there.

The installed Claude shim is named cbm-code-discovery-gate for backward
compatibility; despite the legacy name, it never gates or blocks.

Manual or UI-managed integrations

These are intentionally not counted as automatic installs: Qodo MCP is added
through its UI and may be governed by enterprise allowlists; Warp MCP is managed
through Warp Drive/UI or per invocation (only the shared skill is automatic);
JetBrains AI Assistant / ACP is IDE-managed; GitHub Copilot coding agent, Jules,
and CodeRabbit are cloud/repository-managed; Replit exposes a remote/service
integration rather than a stable local user-global client; BLACKBOX AI does not
document a stable arbitrary user-global MCP/instruction/agent schema; Plandex has
no stable global registry safe to mutate; and SWE-agent uses explicit YAML and is
no longer a suitable automatic global target.

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 --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 keeps it fresh after that. |
| 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 (alias: trace_call_path). 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: ... 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), RETURN, ORDER BY, 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) 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):
```json
// .codebase-memo