Codebase Memory MCP

v0.10.8

Note on v0.10.7: this release supersedes v0.10.7, which was lost to a release-pipeline

publishing error (published under the tag 0.10.7 instead of v0.10.7; package installers

resolve the v-prefixed tag, and release immutability makes the name unrecoverable). The npm

and PyPI 0.10.7 packages are deprecated/yanked for that reason — their binaries were fine,

their download URLs were not. v0.10.8 carries the identical code content plus the pipeline

hardening that prevents a recurrence.

A community-heavy patch release: 19 pull requests merged since v0.10.6, most from

contributors. Thank you all!

Graph correctness

• Cypher aggregates no longer undercount (#1196). Both truncation mechanisms are fixed:

unlabeled scans stopped collecting candidates at max_rows before aggregation ran

(#1323, @Enferlain), and relationship-expansion buffers were capped so aggregation never

saw rows beyond an internal growth limit (#1698). count()/collect() now see the

complete match set; max_rows limits only the rows returned, as documented.

• Python aliased from-imports resolve to the real definition (#1371, @Joseph-MingEn).

from .gate import execute as bridge_execute now produces a CALLS edge to execute

itself rather than losing the call, and aliased base-class imports land on the real class

node. On our django benchmark this recovered 26 INHERITS and 42 OVERRIDE edges with zero

losses elsewhere, and left TypeScript graphs byte-identical.

• Cross-language suffix matching for qualified-name lookups (#1647, @rudi193-cmd).
• search_graph stops returning semantic-only ghosts — results backed by nothing but a

similarity edge no longer surface as if they were definite matches (#1319, @JJordan0C).

• List-valued fields extract correctly instead of collapsing to their first element

(#1325, @Enferlain).

• Index responses report persisted coverage truthfully (#1326, @Enferlain): an

incremental run that does not revisit a file with recorded parse gaps no longer reports

those gaps as vanished — the response now composes its skipped/parse-partial summaries

from the stored coverage state, falling back to per-run data only if that read fails.

Windows

• Non-ASCII search content no longer degrades to ? (#1704). The search_code raw scan

pipes PowerShell output, and PowerShell 5.1 encodes that pipe in the console OEM

codepage — so Cyrillic, CJK, or accented content turned into question marks depending on

which console the server inherited. The pipe is now pinned to UTF-8 unconditionally.

• search_code understands UTF-8 output paths and gains a context column for matches

(#1253, @anfedoro).

• Code search is bounded and cancellable — abandoning a query no longer leaves an

orphaned scan running (#1608, @ertankucukoglu).

Platforms & tools

• FreeBSD support (#1467, @PR9000).
• list_projects pagination: a lean default response plus offset/limit and

include_details for the full view (#1181, @tmonestudio).

• Extensionless shebang scripts detect their language (#1203, @ibaldr89).
• Index-mode capability rebuild (#1263, @astandrik).
• is_test detection for tests/ directories (#1308) and a **diff-aware clang-tidy

hook** (#1310, both @Yyunozor).

Release pipeline (the v0.10.7 lesson, hardened)

• Release gates fail closed on cancelled jobs: a timed-out gate can no longer cascade into

a silently skipped test matrix (#1719).

• Malformed version inputs are refused preflight — a bare, non-v-prefixed version can never

again publish an unresolvable tag (#1719).

Internal

• Test harnesses use isolated daemon runtimes so suite runs cannot touch the account

daemon (#1695, @astandrik); LF checkout contracts for shell entrypoints and git hooks

(#1314 @mlandolfi90, #1699 with @xumian520); the stdin-gate regression tests no longer

depend on the registry shipping a zero-argument tool (#1704).

<!-- cbm-security-verification:sta

codebase-memory-mcp

GitHub Release

License

CI

Tests

Languages

Hybrid LSP

Agents

Pure C

Platform

OpenSSF Scorecard

SLSA 3

VirusTotal

arXiv

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

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

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

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

<p align="center">

<img src="docs/graph-ui-screenshot.png" alt="Graph visualization UI showing the codebase-memory-mcp knowledge graph" width="800">

<br>

<em>Built-in 3D graph visualization — explore your knowledge graph at localhost:9749</em>

</p>

Why codebase-memory-mcp

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

Quick Start

One-line install (macOS / Linux):

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

With graph visualization UI:

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

Windows (PowerShell):

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

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

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

# 4. Run it
.\install.ps1

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

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

Antivirus note: Microsoft Defender may flag a release binary as

Trojan:Script/Wacatac.B!ml. This is a known false positive — typically 61 of

~62 engines return clean, and the same detection family hits gh, llama.cpp,

Godot and Microsoft's own Go toolchain. See

Antivirus False Positives for the

evidence, how to verify the artifacts yourself, and how to report it if you

think we are wrong.

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

<details>

<summary>Manual install</summary>

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

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

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

1. Restart your coding agent.

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

</details>

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

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

Graph Visualization UI

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

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

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

Auto-Index

Enable automatic indexing on MCP session start:

codebase-memory-mcp config set auto_index true

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

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

Keeping Up to Date

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

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

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

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

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