Cortex — Engineering Knowledge Graph

Cortex is a persistent, workspace-level knowledge graph for software engineering. It models relationships (Services, APIs, Decisions, People, Documents, ...) rather than files, survives project deletion, and exposes that knowledge to any AI model or dev tool over MCP and a REST API.

This repo is a working implementation of the technical roadmap for Cortex, built in Python (Kuzu/LanceDB/SQLite embedded stores, in place of the roadmap's suggested Rust core — see "Design notes" below) and organized into the roadmap's 7 delivery phases.

Install

# Recommended (isolated global CLI):
pipx install cortex-kg

# Or with pip:
pip install cortex-kg

From source (development):

git clone https://github.com/RoshanGamage01/Cortex.git
cd Cortex
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Quickstart

# 1. Ingest a project (or the bundled sample from a clone):
cortex --workspace demo ingest examples/sample_repo --project SampleApp
# Or any local repo:
# cortex ingest /path/to/your/repo --project MyApp

# 2. Open Cortex Brain in your browser (API + UI, no extra frontend setup):
cortex --workspace demo serve-api
# → http://localhost:8420  (set Workspace = "demo" in the top bar)

# Ask questions from the CLI:
cortex --workspace demo search "what depends on AuthService"
cortex --workspace demo context "AuthService" --format markdown

# Wire Cursor into a project (optional):
cortex setup project --write --project MyApp
cortex --workspace demo serve-mcp   # MCP over stdio

Data lives at ~/.cortex/<workspace>/ (override with CORTEX_HOME) — portable, backup-able, and independent of any project's lifecycle.

See docs/cortex-brain.md for the UI walkthrough.

User guides

Full setup for Cursor, other platforms, and automation:

Connect Cursor to a project in two commands:

cortex ingest . --project MyApp
cortex setup project --write --project MyApp   # writes .cursor/mcp.json + agent rule

Reload Cursor after setup.

Architecture

Sources (code, git, docs, PDFs, images, DB schemas, APIs, notes, plugins)
   -> Extractors (deterministic first, LLM-assisted where structure is ambiguous)
   -> Entity Resolver (Candidate -> canonical Node/Edge, with provenance)
   -> Storage: Kuzu (graph) + LanceDB (vectors) + SQLite FTS5 (keyword) + SQLite (provenance/jobs/ACLs/ontology)
   -> Hybrid Query Engine (keyword + vector seeds -> graph expansion -> RRF fusion -> re-rank)
   -> Context Generator (token-budgeted, provenance-carrying context)
   -> Access layer: MCP server + REST API + TS/Python SDKs

Every node/edge type is data, not code: the ontology lives in a schema registry (cortex.ontology.registry) seeded with the roadmap's default taxonomy but extensible at runtime by extractors, plugins, or API/MCP clients — no migration required.

Project layout

src/cortex/
  config.py              workspace data-dir layout (~/.cortex/<id>/...)
  models.py               Node / Edge / Candidate / Provenance
  daemon.py                CortexDaemon: owns every store for one workspace
  cli.py                    `cortex` command-line entrypoint
  ontology/                schema registry (ontology-as-data)
  storage/                 GraphStore (Kuzu), VectorStore (LanceDB), KeywordStore (FTS5), ProvenanceStore
  ingestion/                content-hashing, entity resolver, the Detect->...->Emit pipeline
  extractors/               code (tree-sitter), git, db schema, OpenAPI, markdown, PDF, image, notes, LLM-assisted relations
  sync/                     file watcher, job queue, change feed (pub/sub)
  retrieval/                embeddings, RRF fusion, graph traversal/impact analysis, query planner, hybrid query engine
  context/                  token-budgeted context generation for LLMs
  mcp_server/                MCP server (tools + resources)
  api/                       REST API (FastAPI) + graph_viz (Brain UI API)
  static/brain/              Packaged Cortex Brain SPA (served by serve-api)
  plugins/                   out-of-process plugin interface/loader + example plugin
  security/                  ACLs, secrets scanning, encryption-at-rest, audit log
  workspace/                 multi-workspace registry + cross-workspace links + federation
  versioning/                 bitemporal nodes/edges, supersede/tombstone, history chains
  server_profile/              Neo4j/Memgraph GraphStore adapter (team-scale server profile)
  replication/                  CRDT/oplog multi-device sync
  offline/                       connectivity check + durable cloud-augmentation queue
  agents/                         agent write-back API + change-feed hooks
sdk/
  python/cortex_sdk/         Python REST client SDK
  typescript/src/index.ts     TypeScript REST client SDK
examples/sample_repo/          tiny multi-service demo repo used by the tests + quickstart
web/                           Cortex Brain source (Vite/React); build via scripts/build_brain_ui.sh
scripts/benchmark.py            ingestion/search/context performance benchmark
scripts/build_brain_ui.sh       build + copy UI into src/cortex/static/brain/
tests/                           60+ tests covering every phase below

Phases (see the plan for full detail)

Design notes / deviations from the roadmap

• Core engine is Python, not Rust. The roadmap's storage picks (Kuzu, LanceDB, SQLite) and every architectural boundary (GraphStore / VectorStore / Extractor / plugin protocol) are implemented exactly as specified; only the host language differs, for iteration speed and because Kuzu/LanceDB both ship first-class embedded Python bindings. A Rust rewrite of the core would implement the same GraphStore / extraction / retrieval contracts.
• Keyword index is SQLite FTS5, not Tantivy. Zero extra dependency, same "exact-term/symbol search" role in the hybrid retrieval recipe; swappable behind KeywordStore if Tantivy bindings are preferred later.
• Default embedding model is a deterministic offline hashing embedding (cortex.retrieval.embeddings.HashingEmbeddingProvider), not a trained semantic model — by design, so the whole system (including tests/CI) runs fully offline with no model download. Swap in a real local/cloud model by implementing EmbeddingProvider.
• LLM-assisted extraction/planning ship transparent local-heuristic defaults (cortex.extractors.llm_relation_extractor, cortex.retrieval.planner) rather than calling a cloud model, again for offline-by-default operation; both are written to the exact request/response contract a real LLM backend would fill in via CORTEX_LLM_PROVIDER.

Testing

python3 -m pytest tests/ -q

60 tests cover the full pipeline end-to-end (ingest the sample repo through every extractor, resolve into the graph, hybrid-search it, generate context, serve it over MCP/REST) plus targeted tests per phase (ACLs, secrets scanning, encryption, CRDT merge, bitemporal versioning, plugin sandboxing, multi-workspace federation, and the performance cache).