CortexDB · Code Plane
Your agent greps because it has no memory of your code.
Code Plane indexes a registered checkout into a content-addressed, generation-pinned code graph — definitions, imports, calls, resources. Ask a development question and get back verbatim snippets with file, hash and line, a reason for each, inside a token budget you set.
- 43+ languages
- 18 ms p50 query
- 25M LOC in 93 s
Measured
A better navigator.
We ran the same infrastructure tickets twice on the same repository with the same model — a stock coding agent with Grep, Glob and Read, against the same agent given Code Plane over MCP. The agent stopped sweeping.
grep and glob sweeps on the Code Plane armThe control arm ran 11 to 14 of them per ticket.
distinct files opened, where the control opened 26Across three tickets: 26→12, 28→13, 38→12.
correctness, on both armsNavigation got sharper without trading away results.
Scope. Three infrastructure tickets on one repository, cold start, single model. These are navigation figures — how much of the repository the agent had to touch to find its answer. End-to-end session cost is a separate measurement and depends on how you budget context packs; it is not claimed here.
What comes back
Every answer carries its receipts.
A context request returns an envelope, not a blob of text. Each item names the file it came from, the content hash it was read at, the lines it spans, and the reason it was selected. The envelope reports what it spent and what it is unsure about.
citation
repo:path@hash#Lstart-Lend — resolvable, and pinned to the content that was actually read.
reason
Why this snippet is here — symbol anchor, caller, route, import, test.
tokens_used
Counted against the budget you set, and reported in every response.
uncertainty
warnings
Populated rather than implied. An empty pair is a claim, not a silence.
files_considered
files_included
The narrowing itself, so you can see how wide the search actually went.
POST /v1/code/context { "repo": "shop", "task": "What depends on settle?", "token_budget": 2000 } → 200 { "envelope": { "files_considered": 2, "files_included": 2, "token_budget": 2000, "tokens_used": 31, "uncertainty": [], "warnings": [], "items": [ { "citation": "shop:billing/settle.py@7d73590ea5b57d2b#L1-L2", "path": "billing/settle.py", "reason": "symbol-anchor", "snippet": "def settle(o, a):\n return a > 0\n", "truncated": false } ] } }
Invariants
It would rather return nothing than guess.
Four properties hold whatever you ask it. They are the reason the answer is small, and the reason you can trust the small answer.
Never guess
No global name-match fallback anywhere — it is a permanent regression test, not a policy. Every fact carries a precision tier and a resolution status, and both travel into the answer rather than collapsing into one confidence score.
Bounded work
Hard query budgets on depth, nodes and edges. Unplanned deep traversal is refused, never silently truncated, and context has an aggregate token ceiling you set.
Fenced reads
The graph is content-addressed and generation-pinned, with freshness proofs and as_of time travel. A read either sees a published generation or tells you it could not.
Off by default
Without CORTEX_CODE_PLANE nothing is constructed and /v1/code/* answers 503 CODE_PLANE_DISABLED. It costs nothing when you are not using it.
- Syntax
- Manifest
- Compiler
- History
- Runtime
The five precision tiers. Compiler facts — imported from SCIP — supersede lower tiers but never rewrite them, so you can always see which tier an answer rests on. Resolution status travels alongside: exact, import-scoped, ambiguous, unresolved, dynamic.
Benchmarks
Two configurations. Both measured.
Structural retrieval needs no embedding service at all. Semantic search is opt-in, and it is worth 6.4 points of recall — so the choice is yours to make with the numbers in front of you.
| SWE-bench Lite · 500 file-localization cases | Structural — the default | Semantic hybrid — opt-in |
|---|---|---|
| any@10 | 81.8%at least one target file in the top ten | 88.2%+6.4 points over structural |
| Embedding service | Not requiredpath, graph and BM25 only | RequiredCORTEX_CODE_EMBEDDING_*, TQ2 HNSW |
| On provider failure | — | Degrades to structuralrather than failing the query |
p50 query latency
to index 25M lines of code
of index per line of code
languages, sandboxed tree-sitter extraction with a universal text fallback
On token traffic. Against a competing indexer across 26 quality-matched cases, the full MCP exchange used 3,062 tokens where the other used 25,960 — both completing 26 of 26. That figure covers MCP traffic only: tool schemas, requests and responses. It is not a measure of total model usage, and it does not by itself predict your end-to-end session cost. Benchmarks are blind, run against pinned competitors with append-only manifests, and dated August 2026.
Run it
Three commands, on your own machine.
Code Plane reads a directory your server can see. Nothing is uploaded — you mount a checkout you already have, and the index lives in your volume.
Start CortexDB with the code plane on
Mount the repository you want to index. The container is ready in about two seconds, and serves its admin console on the same port.
docker run -d --name cortexdb \ -e CORTEX_API_KEY=$KEY \ -e CORTEX_CODE_PLANE=1 \ -p 127.0.0.1:3141:3141 \ -v cortexdb_data:/data \ -v ~/src/shop:/repos/shop:ro \ cortexdb/cortexdb:v0.9.6 3141 /data
Register the checkout
Give it the path as the container sees it — the mount point from step 1, not your host path. Initial indexing is synchronous and returns the index statistics.
curl -X POST http://127.0.0.1:3141/v1/code/repos \ -H "Authorization: Bearer $KEY" \ -H "X-Cortex-Actor: agent:you" \ -H "Content-Type: application/json" \ -d '{"name":"shop","path":"/repos/shop"}'
Ask it something
Or point your coding agent at the read-only MCP tools with --tool-profile code, and let it call these routes itself.
curl -X POST http://127.0.0.1:3141/v1/code/context \ -H "Authorization: Bearer $KEY" \ -H "X-Cortex-Actor: agent:you" \ -H "Content-Type: application/json" \ -d '{"repo":"shop","task":"What depends on settle?","token_budget":2000}'
Beyond context. Around twenty-one /v1/code/* routes ship alongside it — symbol search and resolve, callers and callees, reverse impact, bounded graph query with export in nine formats, tests for a change, history for a symbol, and hash-verified certified answers. Available from REST, the Python and TypeScript SDKs, and four read-only MCP tools.
On macOS, Docker Desktop only shares certain host paths. If a registered repository reports zero files, the bind mount resolved to an empty directory — mount from your home directory, or add the path under Docker’s file sharing settings.
The other plane
One substrate. Two kinds of memory.
Code Plane is a feature bundle inside CortexDB, not a separate product — same binary, same deployment, same surfaces. The GitHub connector emits code anchors, so pull requests, issue links and pushes land against the same graph your agents already recall from.