code-cortex-mcp

code-cortex-mcp is a local MCP server for AI coding
agents. It builds a knowledge graph of your codebase: functions, classes, call graphs, HTTP
routes, and cross-service links. One graph query replaces dozens of grep-and-read cycles.
It ships as a single static binary with no runtime dependencies.

It parses 155 languages with tree-sitter
and resolves types for Go, C, C++, TypeScript/JavaScript, Java, Kotlin, Rust, Python, PHP,
and C#. It indexes llvm-project (47M lines) in 6.4 minutes and the Linux kernel (44M lines)
in 4.4 minutes on a 32-core machine. On 11 other repositories it indexes 1.1× to 5.7× faster
(median 2.4×) than codebase-memory-mcp,
the project it forked from. See
Compared to codebase-memory-mcp.

• Quick Start
• MCP Tools
• Features
• Performance
• Language Support
• Graph Data Model
• Configuration
• Build from Source
• Compared to codebase-memory-mcp
• Credits & License

Quick Start

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/tigercosmos/code-cortex-mcp/main/install.sh | bash

# Windows (PowerShell)
Invoke-WebRequest -Uri https://raw.githubusercontent.com/tigercosmos/code-cortex-mcp/main/install.ps1 -OutFile install.ps1
.\install.ps1

The installer configures Claude Code, Codex CLI, Gemini CLI, Zed, OpenCode, Aider, VS Code,
and other MCP clients: server entries, instruction files, and hooks. Restart your agent and
say "Index this project."

In Claude Code the graph mostly arrives as context rather than as a tool the agent has to
choose: a SessionStart hook prints a short architecture brief for the repository you are in,
a PreToolUse hook on searches adds what grep cannot show for an exact symbol (definition vs
declaration, caller and test counts with call-site lines, callers from other languages), and
a PostToolUse hook on edits reports the blast radius of the file you just changed. All hooks
are non-blocking and bounded (300 ms for searches, 1.5 s after edits, 3 s at session start).

Other subcommands: doctor (checks the install, hooks, and whether the current directory is
indexed), config set auto_index true, update, uninstall.

It needs no LLM and no API key. The server is the structural backend; your agent is the
language layer. All data stays in ~/.cache/code-cortex-mcp/ as SQLite.

MCP Tools

The project argument is optional for every query tool: inside an indexed repository it is
inferred from the working directory, and a name that matches nothing is answered for that
project with a project_note saying so. Names may be bare (parse), scoped
(Packet::addLayer), or fully qualified. Replies are bounded (max_bytes on
inspect_symbol and search_code) and say when they were cut and how to continue.

Every tool also runs from the CLI:

code-cortex-mcp cli inspect_symbol '{"symbol": "hexStringToByteArray"}'
code-cortex-mcp cli search_graph '{"name_pattern": ".*Handler.*", "label": "Function"}'
code-cortex-mcp cli query_graph  '{"query": "MATCH (f:Function) RETURN f.name LIMIT 5"}'

Features

• Static analysis — import-aware, type-inferred call graph; dead code; Leiden clusters;
  circular dependencies; complexity metrics; git-diff blast radius.
• Crash isolation — a supervisor contains per-file crashes and hangs during indexing,
  and a persistent worker process answers tool calls with a per-tool deadline.
• Preprocessor-aware C/C++ — recovers definitions split across #ifdef branches,
  and gives headers their own File nodes with resolved #include edges.
• Code search — BM25 full text (FTS5), structural search, and semantic similarity
  edges from algorithmic embeddings (no API key).
• Cross-service links — HTTP route ↔ call site; gRPC, GraphQL, tRPC; Socket.IO and
  pub-sub channels (EMITS / LISTENS_ON); CROSS_* edges across repositories.
• Infrastructure as code — Dockerfiles, Kubernetes manifests, and Kustomize overlays
  as graph nodes.
• Reproducible index — two full runs over the same tree produce the same graph: same
  nodes, edges, IDs and properties, byte for byte. Verified on 11 of the benchmark
  repositories.
• Team artifact — commit .code-cortex/graph.db.zst (a zstd snapshot, about 10:1)
  and teammates import it instead of a full reindex. A .gitattributes merge=ours rule
  prevents merge conflicts. Gitignore .code-cortex/ to opt out.

Performance

Full-index wall clock, median of three runs from an empty cache, on an Apple M3 Max (14 cores,
36 GB) and a 32-core Linux machine (62 GB). The full 13-repository comparison with
codebase-memory-mcp is in docs/benchmarks/2026-08-25.

Memory

Peak RAM is the peak resident set size on the M3 Max at 14 workers, median of three runs
(llvm-project two, the kernel one). It follows how much the extractors produce rather than
repository size — CPython needs 4.3 GB against Kubernetes' 4.9 GB with less than half the
lines — and stays between 0.7 and 13.4 GB across every repository measured. Indexing is the expensive
phase; answering queries afterwards reads the SQLite file and needs almost none of it.

The peak is not the graph. It is the definitions, calls and usages the pipeline keeps for every
file, from extraction until call resolution ends: about six times the graph buffer on
Elasticsearch. On top of that sits the parse working set of the files being read at that
moment, which is what CBM_WORKERS moves. The indexer also throttles workers by
itself whenever its resident size passes a budget derived from total RAM (25–50%, a larger
share on larger machines; CBM_MEM_BUDGET_MB overrides it in MiB), so a machine smaller than
the figures above still finishes, more slowly. CBM_MEM_PROFILE=1 logs a byte-level breakdown
at every phase boundary.

Query latency:

Two mechanisms keep calls fast. A persistent worker process serves tool calls, so each call
skips a process exec and a database open. A memo in _config.db records each database's
integrity verdict against its (size, mtime), so a cold process such as a hook does not
verify databases again.

Language Support

155 languages via vendored tree-sitter grammars. Benchmarked tiers:

• Excellent (≥90%) — C, C++, Lua, Kotlin, Perl, Objective-C, Groovy, 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

The other 110 languages get structural parsing only.

Graph Data Model

• Nodes — Project, Package, Folder, File, Module, Class, Function, Method,
  Interface, Enum, Type, Route, Resource
• Edges — CALLS, IMPORTS, DEFINES, IMPLEMENTS, INHERITS, OVERRIDE,
  HTTP_CALLS, ASYNC_CALLS, DATA_FLOWS, SIMILAR_TO, SEMANTICALLY_RELATED, and more
• Qualified names — <project>.<path_parts>.<name>; find them with search_graph.
• Cypher subset — MATCH / OPTIONAL MATCH, WHERE, WITH, RETURN with aggregates,
  ORDER BY, LIMIT. Read-only. Queries stop at 100k rows or 30 s.

Configuration

code-cortex-mcp config list
code-cortex-mcp config set auto_index true        # index on MCP session start
code-cortex-mcp config set auto_index_limit 50000 # max files for auto-index

• Storage — ~/.cache/code-cortex-mcp/; override with CBM_CACHE_DIR.
• Parallelism — auto-detected (cgroup-aware); override with CBM_WORKERS (1–256).
• Ignore rules — .gitignore, then .cbmignore (gitignore syntax). The indexer skips symlinks.
• Custom extensions — .code-cortex.json: {"extra_extensions": {".mjs": "javascript"}}.
• Memory — indexing is the memory-hungry phase; see Memory. CBM_MEM_BUDGET_MB
  caps the budget the indexer throttles against, and CBM_MEM_PROFILE=1 logs a byte-level
  breakdown at each phase boundary.

Build from Source

Requires CMake, a C++23 compiler, and zlib.

git clone https://github.com/tigercosmos/code-cortex-mcp.git
cd code-cortex-mcp
scripts/build.sh                    # → build/c/code-cortex-mcp
./build/c/code-cortex-mcp install   # configure your agents

Or install the binary and the skill in one step:

make install PREFIX=$HOME/.local    # binary → ~/.local/bin
sudo make install                   # binary → /usr/local/bin

Run tests with scripts/test.sh (ASan/UBSan) and linters with scripts/lint.sh.

Compared to codebase-memory-mcp

code-cortex-mcp forked from
DeusData/codebase-memory-mcp and keeps
its on-disk graph format. It indexes faster and answers most tool calls faster.
codebase-memory-mcp has features that code-cortex-mcp does not; the feature table names them.

Test conditions for every number in this section:

• Date and machines — 2026-08-25; an Apple M3 Max (14 cores, 36 GB, macOS) and a
  32-core x86-64 Linux machine (62 GB, Ubuntu 24.04, gcc 13.3). The tool-call and hook
  latency rows come from the Mac only.
• Versions — code-cortex-mcp at af4579de plus the llvm-project crash fix committed with
  these results; codebase-memory-mcp at 010569fa.
• Binaries — each project's own scripts/build.sh, without the codebase-memory-mcp web UI.
• Cache — one empty cache directory per run.

Indexing speed

Median of three full-index runs from an empty cache on 13 repositories, from Redis (0.6M lines)
to llvm-project (46.8M lines). The per-repository tables, graph sizes, repository commits, and
raw per-run data are in docs/benchmarks/2026-08-25.

Both engines build graphs of nearly the same node count on every repository except Rails
(100,649 nodes against 64,354). Edge counts differ more on Kubernetes (3.3M against 2.0M) and
Elasticsearch (5.2M against 5.7M), so read those ratios with that in mind.

Both engines crashed on llvm-project with SIGSEGV in the index worker. The cause is an
out-of-bounds read in structured-binding decomposition in the C/C++ resolver, inherited from
the common code. A NULL dereference in the preprocessor wrapper crashes the same run. This
release fixes both in code-cortex-mcp. On the Linux kernel, codebase-memory-mcp's worker grew
to 57 GB resident in 90 s, and the 62 GB machine killed it. On the Mac, we stopped the run
after 10 minutes with 19 GB of swap in use.

Embeddings do not explain the gap. In fast mode, which writes no similarity or semantic
edges, Django takes 2.9 s in code-cortex-mcp and 12.0 s in codebase-memory-mcp (Mac, measured
at 7a3196c4). The gap is in extraction and resolution: codebase-memory-mcp runs the
CALL_REFERENCE and USAGE precision passes, and code-cortex-mcp carries its own resolver
and pipeline optimizations.

Tool-call latency

Median of 20 warm calls over MCP stdio against the indexed Django graph (55K nodes, 371K
edges). The response column is the JSON-RPC response size.

codebase-memory-mcp returns a compact tree format; code-cortex-mcp returns JSON. The
get_architecture row therefore measures different amounts of output (117 KB against
1.7 KB). index_status returns the same amount on both sides and is slower in
code-cortex-mcp.

code-cortex-mcp serves each call from a supervised worker process; codebase-memory-mcp
serves it in-process. The worker adds crash isolation and a per-tool deadline for about half
a millisecond. search_graph measures 4.2 ms with CBM_TOOL_SUPERVISOR=0 and 4.8 ms
through the worker.

Cold call from an agent hook

A hook has no MCP session, so it starts one CLI process per call. Median of five sequential
cli search_graph calls against a cache that holds the 176 MB Django database.

The _config.db memo stores each database's integrity verdict against its (size, mtime),
so only the first call after a change verifies again. codebase-memory-mcp starts a
coordination daemon for every CLI command unless daemon start keeps one warm.

Features

Both engines share the tree-sitter frontend, graph schema, on-disk format, Cypher subset,
C/C++ preprocessor pass, crash-isolated index supervisor, infrastructure-as-code nodes,
cross-service linking, and team artifact export.

code-cortex-mcp also audits vendored checksums and ships an SBOM that matches each release.
Its release CI runs the build, the tests, and an end-to-end smoke test on linux-amd64,
linux-arm64, macOS-arm64, macOS-amd64, and Windows.

Credits & License

Forked from DeusData/codebase-memory-mcp
(C11), whose engine, design, and research it builds on. See the preprint Codebase-Memory:
Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP
(arXiv:2603.27277).

MIT — see LICENSE. Security policy: SECURITY.md.