CodeCortex Context Engine

🧠 CodeCortex Context Engine

Open-source context intelligence infrastructure for AI coding agents

Map the repository · resolve symbols · retrieve task-specific evidence · estimate impact · edit with guardrails

⭐ Star CodeCortex · ❤️ Support Project · Documentation · Latest Release · Contribute

🇬🇧 English · 🇮🇷 فارسی

---

Why CodeCortex?

A coding agent can read code. The harder problem is deciding what matters, what is connected, what can break, and how much context is actually worth sending to the model.

CodeCortex turns a repository into a query-specific evidence system for coding agents:

• Repository + symbol intelligence — structure, definitions, references, dependencies, and call relationships.
• Evidence-aware retrieval — lexical, semantic, structural, graph, Git, architecture, and memory signals are ranked together.
• Impact before edits — reverse dependencies, affected tests, ownership, and change risk are inspectable before mutation.
• Guarded changes — semantic edits and structural rewrite previews keep source boundaries and review steps explicit.
• Persistent project context — architecture, history, project/team memory, traces, and multi-repo workspaces survive beyond one chat.

Core rule: retrieve evidence before generating confidence.

60-second start

Requires Python 3.11–3.13.

python -m pip install --upgrade codecortex-context-engine

cortex init . cortex index cortex doctor

Then ask the repository useful questions:

cortex architecture

cortex semantic "authentication and session lifecycle" cortex impact AuthService

Or expose the repository to an MCP-capable coding agent:

cortex mcp --path .

Works with coding agents

CodeCortex includes merge-safe project configuration for Claude Code, Codex, Cursor, Gemini CLI, and OpenCode.

cortex agents detect

cortex agents configure --dry-run

or configure every supported target explicitly:

cortex agents configure --all

The configurator only manages CodeCortex-owned MCP entries and keeps user-owned configuration intact.

See it work locally

The repository ships a deterministic demo project and demo runner:

python scripts/demo.py

The demo indexes the fixture repository, analyzes the blast radius of AuthService, routes an evidence request, and reports measured context/trace data. It does not fabricate benchmark values.

Reproducible evidence snapshot

These are committed hardening measurements, not generalized performance promises:

See HARDENING_REPORT.md and benchmarks/ for scope, methodology, limitations, and reproducibility notes.

❤️ Support CodeCortex — If CodeCortex saves you time, consider supporting its continued open-source development. Crypto support →

---

🇬🇧 English

Give the coding agent a map before asking it to navigate the codebase.

CodeCortex in one sentence

CodeCortex turns a software repository into a query-specific evidence system for AI coding agents.

It sits between an agent and a codebase. It builds durable intelligence about repository structure, symbols, relationships, Git history, ownership, architecture, team decisions, impact, and validation. For each task, it tries to return the smallest useful evidence package instead of forcing the model to reopen broad parts of the repository and reconstruct the same facts again.

CodeCortex is not another general chat UI. It is not a model provider. It does not claim that an agent becomes infallible. It is context infrastructure: a layer that improves what the agent gets to reason with.

Core rule: retrieve evidence before generating confidence.

---

Why this exists

A strong coding model can read code. The harder engineering problem is deciding what deserves attention, what is connected to it, what changed, what is ambiguous, who owns the area, and what can break after a change.

Without a context engine, the work often looks like this:

search filenames → open broad files → rediscover architecture → guess symbol ownership → infer references → inspect Git manually → guess blast radius → consume a large context window → edit → discover a hidden dependency later

CodeCortex changes the stream:

task → classify intent → gather repository evidence → rank evidence for this task → preserve provenance and uncertainty → fit evidence into a context budget → expose one agent-facing surface → validate the proposed change

The goal is not more context.

The goal is higher-value evidence per token.

---

Architecture

Live evidence stream

flowchart LR

A[AI Coding Agent] --> G[CodeCortex Gateway] G --> R[Adaptive Router]

R --> REP[Repository Intelligence] R --> SYM[Symbol Intelligence] R --> RET[Hybrid Retrieval] R --> GIT[Git + PR Intelligence] R --> MEM[Project + Team Memory] R --> ARC[Architecture + Drift] R --> IMP[Impact + Validation]

REP --> E[Evidence Surface] SYM --> E RET --> E GIT --> E MEM --> E ARC --> E IMP --> E

E --> C[Context Pipeline] C --> B[Rank + Dedup + Slice + Budget] B --> G G --> A

The repository remains the source of executable truth. Graphs, memory, semantic retrieval, architecture inference, and summaries help interpretation. They do not replace current source, configuration, and tests.

---

Current capability map

---

The CodeCortex Doctrine

These are engineering rules, not marketing slogans.

Doctrine 01 — Evidence before confidence

A resolved symbol, a semantic match, an inferred edge, a memory entry, and a Git observation are different evidence classes. CodeCortex should not flatten them into one certainty level.

exact evidence → present as exact strong inference → preserve provenance ambiguous inference → keep alternatives visible missing evidence → report missing stale evidence → report stale

Doctrine 02 — Smallest useful context

The best context package is not the largest package that fits. It is the smallest package that contains enough source, relationships, history, and validation evidence to reason about the current task.

Doctrine 03 — Source remains source

Memory can explain intent. Git can explain history. Graphs can explain relationships. Retrieval can suggest relevance. Current source, configuration, tests, and reproducible artifacts remain authoritative for executable behavior.

Doctrine 04 — Uncertainty is information

If two symbols are plausible targets, that ambiguity matters. If architecture is inferred, missing signals matter. If an optional integration cannot run, “unavailable” is more useful than a fabricated success.

Doctrine 05 — Eve