Complete AI coding tasks ran 57.7% to 59.4% faster than shell tools and 36.9% to 37.8% faster than upstream codebase-memory-mcp, depending on codebase size.
| Codebase size | Faster than shell | Faster than upstream |
|---|---|---|
| 10K lines | 57.7% (8/8) | 37.8% (8/8) |
| 1M lines | 56.1% (6/8) | 36.9% (6/8) |
| 100M lines | 59.4% (8/8) | Unavailable * |
The table includes only source-correct, exact pairs. * Upstream exceeded the sealed 4 GiB and 32 GiB memory budgets before the 100M-line task run.
A local MCP server that gives AI coding agents a knowledge graph of your codebase: functions, classes, call graphs, HTTP routes, and cross-service links. Graph queries can replace repeated searches when a task depends on indexed relationships.
The installer configures Claude Code, Codex CLI, Gemini CLI, Zed, OpenCode, Antigravity,
Aider, KiloCode, VS Code, Cursor, OpenClaw, Kiro, and Junie: MCP server entries,
instruction files, and pre-tool hooks.
One static binary for macOS, Linux, and Windows. No Docker, no Node, no Python, no API key.
All data stays on your machine in ~/.cache/code-cortex-mcp/.
The engine parses every file with tree-sitter, resolves calls and types (LSP-style hybrid resolution for Go, C, C++, TypeScript/JavaScript, Java, Kotlin, Rust, Python, PHP, and C#), and stores the graph in SQLite. A persistent worker process answers warm graph queries in 0.1–0.5 ms on the measured graph. Complete agent tasks include startup, retrieval, and model execution.
| Area | Previous path | Current bounded path |
|---|---|---|
| Extraction state | Full file results remained in memory through resolution. | CBM_RESULT_STORE=1 stores full results in temporary storage and retains compact summaries. |
| Known call chain | A broad trace could explore unrelated callers. | from_function searches forward from the known entry point. |
| Traversal state | Depth and output limits did not identify exhausted search work. | max_work, path_found, and traversal_truncated expose the bound and outcome. |
| Release check | MCP initialization started a background check. | CBM_UPDATE_CHECK=0 disables it for sealed runs. |
Temporary extraction storage is run-local and not durable. The memory budget is a soft
back-pressure target, not a hard resident-memory limit. The result store has a 64 GiB
per-run limit and needs sufficient free space on the system temporary volume. An
ENOSPC store-write failure cancels the run; free space before retrying.
Architecture details.
| Tool | Purpose |
|---|---|
index_repository, index_status, list_projects, delete_project | Index and manage projects |
inspect_symbol | Definition, source head, callers, tests, and trust signals |
search_graph | Search by label, name pattern, file pattern, or degree |
trace_path | Callers, callees, and bounded endpoint, data-flow, or cross-service paths |
query_graph | Read-only Cypher-subset queries |
get_code_snippet | Source of a symbol by qualified name |
get_architecture | Languages, packages, routes, hotspots, clusters, cycles, ADRs |
get_graph_schema | Node and edge counts, property shapes |
search_code | Graph-augmented grep over indexed files |
detect_changes | Blast radius of a git diff |
manage_adr | Read or replace Architecture Decision Records |
ingest_traces | Runtime trace ingestion stub |
Agent-level run on 2026-10-03: a fresh Claude Code session per task, the task as the
only prompt, the agent free to use any tool. The mcp arm has the product
installed; the shell arm has an empty configuration and no MCP servers.
Paired wall-time ratio mcp / shell, geometric mean over pairs both arms answered
correctly. Lower is faster. The table is the synthetic C++ task set, where every symbol
resolves exactly. On real repositories the final build measured 0.65 (Opus) and 0.66 (Fable)
over 32 tasks in seven languages, and 0.73 and 0.60 over 34 C/C++ tasks, with
exact-match accuracy at 100% in the mcp arm.
| Model | Pairs | Time ratio | Reduction | Call chains | Lookups |
|---|---|---|---|---|---|
| Claude Opus 5.5 | 48 / 48 | 0.557 | 44% | 0.381 | 0.815 |
| Claude Fable 5.1 | 38 / 48 | 0.622 | 38% | 0.362 | 0.854 |
24 tasks (definition lookups and three-hop call chains on synthetic C++ at 10K, 1M and
100M lines), two repetitions, one idle 32-core Linux host, serial sessions, Claude Code
2.1.287, warm indexes. The agent called no MCP tool; the time came from the hooks that
install registers. Fable's ten shell-arm misses were exact-match failures
with a sentence before a correct answer (lenient ratio 0.642 over 48 pairs). Not covered:
edits, cold indexing, other languages, other task shapes. Harness:
scripts/benchmark-agent/.
Full index from an empty cache, median of three runs. Apple M3 Max (14 cores, 36 GB) and a 32-core Linux machine (62 GB), release builds.
| Repository | Lines | Nodes / edges | M3 Max | 32-core Linux | Peak RAM |
|---|---|---|---|---|---|
| etcd (Go) | 0.3M | 15K / 95K | 1.4 s | 1.2 s | 0.7 GB |
| Redis (C) | 0.6M | 38K / 146K | 2.8 s | 2.8 s | 1.0 GB |
| Django (Python) | 1.1M | 55K / 372K | 4.8 s | 3.8 s | 1.9 GB |
| CPython (C, Python) | 3.3M | 137K / 1.0M | 14 s | 12 s | 4.3 GB |
| PyTorch (C++, Python) | 5.1M | 235K / 2.1M | 32 s | 26 s | 8.7 GB |
| Kubernetes (Go) | 7.3M | 288K / 3.3M | 56 s | 57 s | 4.9 GB |
| Elasticsearch (Java) | 8.8M | 692K / 5.2M | 94 s | 63 s | 7.9 GB |
| llvm-project (C++) | 46.8M | 2.2M / 7.8M | 487 s | 382 s | 12 GB |
| Linux kernel (C) | 43.8M | 4.7M / 11.6M | 368 s | 264 s | 13.4 GB |
search_graph, trace_path (warm query) | 0.1–0.5 ms | ||||
PreToolUse hook (Grep or Read) | ~10 ms |
Peak RAM is the peak resident set size on the M3 Max at 14 workers. It follows extractor output rather than repository size. The memory budget applies soft back-pressure; it is not a hard resident-memory limit. Set CBM_RESULT_STORE=1 to move full extraction results to bounded temporary storage while compact registry summaries remain in memory.
Vendored tree-sitter grammars compiled into the binary. Type-resolved call graphs for 10 languages; structural parsing for the rest.
Import-aware, type-inferred call graph. Dead code, Leiden clusters, circular dependencies, complexity metrics, git-diff blast radius.
Two runs over the same tree produce the same nodes, edges, IDs and properties, byte for byte, whatever order the workers finish in. Verified on eleven repositories. Diff two snapshots and only real code changes show up.
Each git worktree has its own graph. A branch switch parks the old branch's index and restores the new one, so switching back re-indexes only the changed files. Stale indexes expire to a restorable trash.
A supervisor contains per-file crashes and hangs during indexing. A persistent worker answers tool calls with a per-tool deadline.
An optional result store moves full extraction state to temporary storage. Compact summaries remain in memory for resolution.
from_function and max_work bound known call-chain searches. Result fields distinguish no path from truncated work.
Recovers definitions split across #ifdef branches. Headers get their own File nodes with resolved #include edges.
BM25 full text (FTS5), structural search, and semantic similarity edges from algorithmic embeddings. No API key.
HTTP route ↔ call site; gRPC, GraphQL, tRPC; Socket.IO and pub-sub channels; CROSS_* edges across repositories.
Commit .code-cortex/graph.db.zst and teammates import the graph instead of a full reindex. A merge=ours rule prevents conflicts.
code-cortex-mcp forked from DeusData/codebase-memory-mcp and keeps its on-disk graph format. Historical cold-index and warm-tool measurements show lower times for most measured operations. The complete-task table above measures the newer agent-task boundary. codebase-memory-mcp retains features that this fork omits.
Measured 2026-08-25 on an Apple M3 Max (14 cores, 36 GB) and a 32-core Linux machine (62 GB):
code-cortex-mcp at af4579de plus the llvm-project crash fix, codebase-memory-mcp
at 010569fa, each built with its own scripts/build.sh, from an empty cache.
| Apple M3 Max (14 cores, 36 GB) | 32-core Linux (62 GB) | |
|---|---|---|
| Repositories both engines complete | 11 of 13 | 11 of 13 |
| Speedup, median | 2.4× | 2.4× |
| Speedup, range | 1.1× (Kubernetes) – 5.7× (etcd) | 1.1× (Kubernetes) – 4.4× (etcd) |
| etcd (Go, 0.3M lines) | 1.42 s vs 8.11 s | 1.15 s vs 5.08 s |
| CPython (C, Python, 3.3M lines) | 14.4 s vs 47.6 s | 11.9 s vs 28.2 s |
| PyTorch (C++, Python, 5.1M lines) | 31.9 s vs 77.8 s | 25.8 s vs 70.3 s |
| Elasticsearch (Java, 8.8M lines) | 94.0 s vs 112.8 s | 63.1 s vs 116.2 s |
| llvm-project (C++, 46.8M lines) | 487 s vs crash | 382 s vs crash |
| Linux kernel (C, 43.8M lines) | 368 s vs stopped | 264 s vs out of memory |
Node counts match closely except on Rails (100,649 against 64,354); edge counts differ on Kubernetes (3.3M against 2.0M) and Elasticsearch (5.2M against 5.7M). Both engines crashed on llvm-project with the same inherited bug, fixed in code-cortex-mcp; codebase-memory-mcp's kernel index exceeded 57 GB and was killed.
| Tool | code-cortex-mcp | codebase-memory-mcp |
|---|---|---|
search_graph | 5.1 ms | 18.2 ms |
query_graph | 1.6 ms | 15.8 ms |
list_projects | 0.2 ms | 13.7 ms |
search_code | 239.8 ms | 271.3 ms |
get_graph_schema | 406.3 ms | 480.9 ms |
index_status | 60.6 ms | 20.0 ms |
get_architecture * | 251.0 ms | 54.7 ms |
| Cold CLI call from a hook | 0.02 s | 4.4 s |
* get_architecture returns 117 KB of JSON in code-cortex-mcp and 1.7 KB of compact
tree output in codebase-memory-mcp, so the two times measure different amounts of output.
The cold hook row is a memo hit; the first call after the database changes takes 0.74 s.
| Area | code-cortex-mcp | codebase-memory-mcp |
|---|---|---|
| Language and build system | C++23, CMake | C11, Make |
| Binary size (macOS arm64, no UI) | 218 MB | 283 MB |
| Semantic embeddings | algorithmic random indexing | 31 MB pretrained vector blob |
| Tool-call isolation | supervised worker, per-tool deadline | in-process |
| Integrity memo for cold starts | _config.db | none |
| Languages | 155 | 158 |
| Hybrid LSP resolvers | 10 | 11 (adds Perl) |
| MCP tools | 15 | 15 |
Reference precision (CALL_REFERENCE / USAGE) | no | yes |
| Session coordination daemon | no | yes |
| 3D graph web UI | no | yes |
| Compact tree output format | no, JSON | yes |
Agent surfaces configured by install | 13 | 43 |
Full test conditions and graph sizes: README →