codebase-memory-mcp

What It Does

codebase-memory-mcp is a code-intelligence backend that builds a persistent knowledge graph from a source tree and exposes it to any MCP-compatible coding agent. It is a single static C binary (257MB on macOS arm64) with 158 vendored tree-sitter grammars compiled in, plus a layer it calls "Hybrid LSP" that adds type resolution for nine languages (Python, TypeScript/JavaScript, PHP, C#, Go, C/C++, Java, Kotlin, Rust). An agent says "index this project", the binary parses every file into nodes (functions, classes, routes, resources) and edges (calls, imports, HTTP links, data flows), stores it in SQLite, and then answers 14 MCP tools: structural search, Cypher queries, call-path tracing, dead-code detection, architecture overviews, and git-diff impact mapping. It targets developers using Claude Code, Codex CLI, Gemini CLI, Cursor, or any of the 11 agents it auto-detects.

The Good

Indexing speed and accuracy are real and measurable. On the GearScope repo (227 files, mostly Python and HTML), index_repository finished in 776ms and produced 3,079 nodes and 4,691 edges. The README's headline claim (Linux kernel, 28M LOC, in 3 minutes) is consistent with the per-file throughput observed here. Every subsequent query tool returned results that matched the actual code: trace_path on a function named analyze correctly listed its inbound callers across the analytics/optimizer.py module, and detect_changes mapped seven uncommitted git files to 26 specific impacted symbols.

The Cypher query engine is not a toy. query_graph accepts a read-only openCypher subset including variable-length paths, EXISTS { ... } subqueries, and aggregates. A dead-code query (MATCH (f:Function) WHERE NOT EXISTS { (f)<-[:CALLS]-() } RETURN count(f)) returned 6, a plausible count of uncalled functions for this repo. The tool reports a clear unsupported ... error for clauses outside the subset rather than silently returning empty rows, which is the correct behavior for a partial implementation.

Zero-dependency single binary is the strongest install story in this category. No Docker, no Node runtime, no Python virtualenv, no language server process per project. The tarball ships one Mach-O executable plus a LICENSE and THIRD_PARTY_NOTICES. The SHA-256 checksum in checksums.txt matched the downloaded archive exactly on the first try. The install command auto-detects agents and writes MCP config, instruction files, skills, and (for Claude Code) a structurally non-blocking PreToolUse hook that injects graph context alongside grep results.

The output schema is rich enough to drive real agent reasoning. search_graph returns not just names and file paths but cyclomatic complexity, cognitive complexity, loop counts, parameter counts, MinHash fingerprints, byte-token vectors, and semantic profiles per function. get_code_snippet returns the actual source with caller and callee counts. This is the data an agent needs to decide what to read next, and it arrives in a single JSON-RPC response instead of a dozen read calls.

Cross-repo and infra-as-code indexing extend the graph beyond application code. Dockerfiles, Kubernetes manifests, and Kustomize overlays become first-class graph nodes, and CROSS_* edges link symbols across multiple repositories indexed under the same store. The team-shared .codebase-memory/graph.db.zst artifact lets a teammate skip a full reindex by committing a compressed snapshot.

The Bad

The SLSA-3 attestation badge does not verify as documented. The README prominently displays a SLSA Level 3 badge and instructs users to run gh attestation verify --repo DeusData/codebase-memory-mcp. Running that exact command against both the extracted binary and the original release tarball returns HTTP 404 from the GitHub attestations API. The per-release SHA-256 checksums do verify correctly (confirmed manually), and the binaries are VirusTotal-scanned and cosign-signed, so integrity is sound. But the specific SLSA provenance path the README tells users to follow does not resolve. This is a gap between a marketing claim and a verifiable artifact.

Version strings are inconsistent across surfaces. The CLI reports codebase-memory-mcp 0.8.1, the GitHub release tag is v0.8.1, but the MCP initialize handshake returns serverInfo.version: "0.10.0". A user inspecting /mcp output sees one number while the binary reports another. The language count also drifts: the README says 158 languages, the bundled server.json description says 159. These are small, but in a tool whose value proposition is precise structural data, internal inconsistency undercuts trust in the numbers.

The binary is large and the security story is load-bearing. At 257MB extracted (37.8MB compressed), this is one of the heaviest single-file installs in the pipeline, because 158 tree-sitter grammars and the Nomic code-embedding model are vendored into the executable. That design choice is what makes the zero-dependency story work, and it is defensible, but it means every user downloads a quarter-gigabyte binary that the README itself acknowledges reads your codebase and writes your agent config files. The "inspect the source first" guidance is correct; just know the source is a 163MB C codebase you are unlikely to audit line by line before running.

The install flow is opinionated about rebuilding indexes. Running install when existing SQLite indexes are present prompts to delete and rebuild them, and the prompt requires a terminal (the -n/-y flags are mandatory in non-interactive contexts). This is safe behavior, but a first-time user who indexed a test repo before running install hits an unexpected rebuild gate.

Smoke Test Results

Testing was done on the host machine (macOS 26.5, Apple Silicon). The v0.8.1 darwin-arm64 binary was downloaded directly from the GitHub release, checksum-verified, extracted, and exercised through both the CLI and the MCP stdio transport.

Install and integrity

$ curl -fsSL -o cbm.tar.gz <release>/codebase-memory-mcp-darwin-arm64.tar.gz
$ shasum -a 256 cbm.tar.gz
fbd047509852021b5446a11141bcb0a3d1dcaebf6e5112460960f29f052c1c58
$ grep darwin-arm64 checksums.txt
fbd047509852021b5446a11141bcb0a3d1dcaebf6e5112460960f29f052c1c58 ...
$ ./codebase-memory-mcp --version
codebase-memory-mcp 0.8.1 OK

Pass rate: 3 of 3. Checksum matches, binary runs, version prints. The --help output lists all 14 tools and the 9 auto-detected agents cleanly.

Server starts

$ printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize",...}' | ./codebase-memory-mcp
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18",
 "serverInfo":{"name":"codebase-memory-mcp","version":"0.10.0"},
 "capabilities":{"tools":{}}}} OK (handshake)

Pass rate: 1 of 1. The MCP stdio server responds to initialize with the correct protocol version and a tools capability. Note the version string mismatch documented above: the server reports 0.10.0 while the CLI reports 0.8.1.

Tools respond

$ cli index_repository '{"repo_path": "/Users/openclaw/gearscope"}'
pipeline.done nodes=3079 edges=4691 elapsed_ms=776 OK (776ms)

$ cli query_graph '{"query":"MATCH (f:Function) WHERE NOT EXISTS { (f)<-[:CALLS]-() } RETURN count(f) AS dead"}'
{"columns":["dead"],"rows":[["6"]]} OK (dead-code = 6)

$ cli trace_path '{"function_name":"analyze","direction":"inbound","depth":2}'
{"callers":[{"name":"analyze","hop":1},{"name":"main","hop":1},...]} OK

$ cli detect_changes '{}' (7 uncommitted git files)
impacted_symbols: 26, including safari_js, post_tweet, check_mentions OK

$ cli get_code_snippet '{"qualified_name":"...optimizer.analyze"}'
returns full 198-line source + complexity metrics OK

Tools respond: 5 of 5. Every tool tested returned accurate, structured JSON within milliseconds. Indexing a 227-file repo took under a second. The Cypher dead-code query, call-path trace, git-diff impact map, and source retrieval all produced correct results.

What the runs tell you

The install path is one-shot: download, verify the SHA-256, run. The server starts and advertises tools over MCP stdio without configuration. The core value claim (graph queries replace grep/read loops at a fraction of the tokens) holds up under direct testing, since every query tool returned real data on the first attempt. The only thing that did not work as documented was the SLSA attestation verification, which is a provenance-marketing gap rather than a functional failure.

Setup Walkthrough

1. Download the archive for your platform from the latest release. On macOS arm64 that is codebase-memory-mcp-darwin-arm64.tar.gz (37.8MB compressed).
2. Verify the SHA-256 against checksums.txt from the same release. The hash matched on the first try in testing.
3. Extract and run ./install.sh, or just run the binary directly. The installer auto-detects installed coding agents and writes their MCP config, instruction files, and hooks. Use install -n or install -y in non-interactive shells.
4. Alternatively use the one-line installer: curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash. The installer strips macOS quarantine attributes and ad-hoc signs the binary, so no manual xattr or codesign step is needed.
5. Restart your agent. In Claude Code, run /mcp and confirm codebase-memory-mcp appears with 14 tools.
6. Say "index this project". The first index builds the SQLite graph under ~/.cache/codebase-memory-mcp/. Subsequent sessions use the background watcher for incremental updates.

To test without committing agent config, set CBM_CACHE_DIR to a throwaway directory and call tools via cli mode, as the smoke tests above did.

Alternatives

1. graphify (safishamsi/graphify, 69.5K stars) - the larger code-graph entrant in the pipeline. Produces a graphify-out/ directory rather than a queryable MCP server, so it is more of a static artifact generator than a live query backend. Prefer codebase-memory-mcp when you need an agent-callable server.
2. CodeGraphContext (3.4K stars) - an earlier code-graph MCP server. Smaller language coverage and no Hybrid LSP type resolution. Prefer codebase-memory-mcp for the broader grammar set and the type-aware edge refinement.
3. jcodemunch-mcp (jgravelle/jcodemunch-mcp, 1.9K stars) - positions itself on the token-efficiency axis with tree-sitter AST slicing for GitHub source exploration. Narrower scope (GitHub-hosted code) but a lighter footprint. Prefer it for ad-hoc remote-repo exploration without a local index.