Every repository tells two stories: what the docs claim and what the code does. Cortex maps both into one local, evidence-backed graph, so people and agents can find what is true, stale, contradictory, or still unknown — before changing the system.
Nodes, edges, and flows are branded Neurons, Synapses, and Circuits.
flowchart LR
R[repository<br/>docs · ADRs · plans · source<br/>symbols · tests · config] --> P1[Phase 1 — Map<br/>deterministic graph of documents,<br/>claims, files, symbols, relationships]
P1 --> DB[(SQLite graph<br/>.agent/graph/graph.db<br/>generation-bound, WAL)]
DB --> P2[Phase 2 — Understand<br/>verify each doc claim against source,<br/>synthesize what holds]
P2 --> MA[machine artifacts<br/>.agent/*.json for agents]
P2 --> HD[human docs<br/>docs/product.md · docs/architecture.md]
Phase 1 is deterministic mapping. Phase 2 is judgment with receipts: every claim keeps its path, span, content hash, provider, generation, and confidence — and verdicts are sealed to exact document+code fingerprints, so unchanged inputs reuse verdicts and only affected ones recompute.
- Contradictions are surfaced, not averaged away. A doc that disagrees with the code shows up as a disagreement.
- An old plan cannot outrank current code. Documents are tracked as current, historical, superseded, or invalidly marked;
supersedeschains are kept as provenance and excluded from current truth. - Uncertainty stays visible. Unsupported languages, truncated scans, and ambiguous edges are reported, not hidden.
- Freshness by construction. Commits, dirty overlays, provider versions, and content fingerprints invalidate only the evidence they touch.
Precision and confidence are explicit ladders, not adjectives:
| Ladder | Order |
|---|---|
| Code intelligence source | COMPILER > AST > LEXICAL — Tree-sitter for supported languages, deterministic lexical fallback everywhere, optional SCIP if the repo supplies an export |
| Edge resolution confidence | EXACT_RESOLUTION > SAME_FILE_LEXICAL > CROSS_FILE_HEURISTIC > UNRESOLVED — consumers filter by minimum tier |
The store is Node's built-in node:sqlite — no database server, no native packages. Writes are transactional per generation, so readers only ever see complete generations.
cortex # orient in the current repo
cortex "add rate limiting" # orient around a task
cortex doctor --full --json # health + coverage| Query | Answers |
|---|---|
cortex graph search <term> |
where is this symbol/concept |
cortex graph neighbors <node> |
what touches it |
cortex graph path <a> <b> |
how are these connected |
cortex graph impact <node> |
what breaks if this changes |
cortex graph architecture |
component structure, from evidence |
cortex graph doc-truth |
which doc claims hold against source |
cortex graph mermaid |
render the graph as a diagram |
Beyond queries: cortex phase2 plan|seal (incremental verification), cortex grant issue|check (task-scoped path grants with TTL), cortex neighborhood <anchor> (bounded, token-budgeted graph slices), cortex orient (decision-only admission API returning allow | continue | block | noop), and a resident watch daemon (cortex-watch) that keeps freshness barriers warm across enrolled repos.
Repository content is untrusted data, never agent instruction. Secrets are redacted from outputs. Reads are confined to repository scope. Current code and executable proof outrank plans and historical documents. For federation, cross-repo graphs are never raw-merged — each repo's slices stay independently scoped by repoId.
This repo maps itself. Run cortex doctor --full --json for current file, document, claim, code-reference, stale-claim, & missing-reference counts; no snapshot count is treated as durable documentation.
Install and run from npm (no source checkout needed):
npx -y @orthic-labs/cortex init # enroll Cortex in the current repository
cortex status # freshness + coverage
cortex search "placeOrder" # query the graphFrom a source checkout:
pnpm install
pnpm test # requires Node >= 22.22.3
python3 -m pip install -r requirements-test.txt # for the full workspace suite
pnpm run test:allBins: cortex, cortex-watch, cortex-mcp (MCP server), cortex-install.
- Freshness hardening — canonicalized watcher paths, snapshot-backed freshness proofs, batched barrier writes, logically-sound incremental graph freshness.
- Federation contract — barrier fan-out across enrolled repos with independent receipts; one repo's timeout can't block another.
- MCP server + host installers, task-scoped grants, bounded neighborhoods, merkle reconciliation, resident watchman.
Parser depth varies by language (lexical fallback is broader than AST coverage). Dynamic runtime registration can stay unresolved without executable or compiler evidence. SCIP precision requires a repository-supplied export. Embeddings and semantic vector search are not active. Explorer, tray, and desktop onboarding are implemented but not yet published. Raw graph data is not copied into durable memory.
- Product overview — what this is and does (generated, code-grounded)
- Architecture — components, flows, interfaces (generated, code-grounded)
- Product, performance, competitor, & research contract
- Single implementation plan
- Implementation status — release-pinned surface summary; live status comes from
cortex doctor --full --json
Cortex is source-available, not open source. Its proprietary core is covered by the Orthic Labs Source Use License v1.0, which permits internal and evaluation use. Damned Ventures LLC may publish Cortex through owner-authorized channels, including npm, GitHub Releases, its Homebrew tap and Scoop bucket, and WinGet. That publication does not grant licensees a general right to redistribute, mirror, modify, or repackage proprietary core.
The SDK (sdk/), schemas (schemas/), and examples (examples/) are licensed
under Apache-2.0, so integrations and independently authored
plugins may build against those surfaces without relicensing proprietary core.
Trademarks: see TRADEMARKS.md.
Orthic Labs — local-first infrastructure for AI-assisted development.
Membrane · Cortex · Forge · Adapt · CutRight · claudecodeX
- Product overview — what this is and does (generated, code-grounded)
- Architecture — components, flows, interfaces (generated, code-grounded)