🧠 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:

Evidence	Recorded result
Hardening test suite	711 passed, 28 skipped, 0 failed
Coverage in hardening report	91.74%
Warm exact definition lookup	0.19–0.23 ms median
Freshness scan across 600 documents	4.25 ms median

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:

CodeCortex changes the stream:

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

Layer	What it does	Why it matters
Repository map	indexes structure and files	gives the agent a bounded map
Multi-language symbols	extracts language-aware units	moves beyond filename search
Tree-aware parsing	preserves structural code units	improves code-level context
Dependency + call graph	records relationships	supports navigation and impact
Cross-file resolution	ranks ambiguous targets	keeps uncertainty visible
Incremental graph	reparses changed state	avoids blind rebuilds
Hybrid retrieval	combines lexical, semantic, structural signals	improves task-specific recall
Context pipeline	ranks, deduplicates, slices, budgets, compacts	spends tokens on useful evidence
Git intelligence	history, blame, churn, ownership	makes change history queryable
PR intelligence	maps diffs to symbols, tests, impact, risk	reviews behavior, not only lines
Impact analysis	walks reverse relationships	estimates blast radius
Architecture inference	infers observable structure with confidence	makes architecture inspectable
Architecture drift	compares structure with a baseline	exposes architectural movement
Project memory	stores durable decisions and facts	preserves rationale
Shared team memory	revisions + conflict-aware shared state	makes team knowledge durable
Multi-repo workspace	federates search and graph evidence	supports systems split across repos
Task traces	records bounded execution evidence	makes routing behavior inspectable
Guarded semantic editing	performs preflight-aware edits	reduces broad unsafe replacements
Native MCP	exposes one stable agent surface	integrates with coding agents
Remote MCP	authenticated remote operation	enables controlled shared use
Persistent vector providers	separates storage from retrieval contract	supports larger deployments
Distributed workers	capabilities + leases + retries	makes node failure explicit
Observatory	health, traces, drift, graph, benchmark, PR signals	makes the engine observable
Precision code intelligence	resolves definitions and references by symbol identity	distinguishes packages that export the same name
Dependency intelligence	separates declared constraints from resolved versions	answers which API the repository actually runs
Structural search and rewrite	matches syntax, previews guarded migrations	finds calls, not comments that mention them
Platform API and console	HTTP surface, jobs, persistence, realtime events	drives CodeCortex from outside the CLI
Python and TypeScript SDKs	typed clients for the platform API	embeds CodeCortex in other tooling
Release evidence	scans, SBOM, signatures, provenance	ties release claims to artifacts

---

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.

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 — Every change has a blast radius

A small diff can be high risk. A large diff can be mechanical. The useful questions are: which symbols changed, who depends on them, which tests exercise them, who owns the area, and what evidence supports the risk.

Doctrine 06 — Local-first is a trust decision

Core repository intelligence works locally. Any network boundary, credential, remote tool, quota, policy, and data transfer must remain explicit.

Doctrine 07 — Reproducibility beats impressive numbers

A benchmark claim without a reproducible specification, pinned revision, environment, measured output, and artifact is not strong evidence.

Doctrine 08 — Scale through explicit coordination

Workers have identity, capability, leases, failure, retry, and state. Shared memory has synchronization and conflict behavior. Remote tools have authentication and policy.

---

Quick Start

Install

CodeCortex supports Python 3.11, 3.12, and 3.13.

Optional parser support:

Optional local neural semantic embeddings:

Start inside a repository

---

A 30-second mental model

The agent still reasons. CodeCortex changes what it gets to reason with.

---

Task streams

Bug investigation

sequenceDiagram
    participant A as Agent
    participant C as CodeCortex
    participant R as Repository
    participant G as Graph
    participant H as Git/History
    participant V as Validation

    A->>C: Trace a failing behavior
    C->>R: locate source and symbols
    C->>G: resolve callers and dependencies
    C->>H: inspect recent change and ownership
    C->>V: identify tests and validation signals
    C-->>A: compact evidence package + impact

A useful investigation should answer:

1. Where is the behavior implemented?
2. What callers and references participate?
3. What changed recently?
4. Which alternate path can invalidate the hypothesis?
5. Which test would fail if the explanation is wrong?
6. What is the smallest safe change?

Pull-request review

PR size is only one signal.

Multi-repository work

The repositories keep their identity. CodeCortex federates evidence instead of pretending they are one physical codebase.

---

Intelligence surfaces

Incremental indexing turns files and program units into durable repository state. Retrieval, architecture inference, impact analysis, and MCP tools can reuse that state instead of rediscovering the whole repository for every request.

Language-aware parsing extracts program units and keeps container identity where possible. Cross-file resolution intentionally preserves ambiguity and candidate reasons instead of silently choosing a same-name symbol.

Code is not ordinary prose. CodeCortex combines lexical evidence, semantic similarity, symbol metadata, and structural context. Context slicing favors meaningful structural units and bounded windows instead of uncontrolled file dumps.

Current source answers what the code does now. Git explains how it arrived there. History, blame, ownership, churn, and PR analysis add change evidence to the static code model.

Project memory stores reusable facts and decisions. Team memory adds revisions, actor/source metadata, optimistic concurrency, and conflict behavior. Memory can explain “why,” but current source and tests remain authoritative.

Architecture inference returns evidence and confidence. A saved fingerprint can be compared with the current graph so new dependency directions, coupling growth, and structural drift become inspectable.

Impact analysis walks reverse relationships and affected tests. Validation challenges a proposed change against repository evidence. A risk score is useful only when the evidence behind it stays visible.

---

Guarded editing

Current semantic edit operations include:

The intended change discipline is:

Not:

---

MCP: one agent-facing surface

The MCP surface exposes repository mapping, symbol search, references, dependency graph inspection, impact analysis, hybrid retrieval, compact context, architecture intelligence, Git history, PR intelligence, memory, workspace search, traces, validation, and statistics.

Category	Agent can request
Repository	map, matching nodes, graph counts
Symbols	program units and locations
References	relationships around a target
Dependencies	local call/import relationships
Impact	direct, indirect, affected-test evidence
Retrieval	semantic/lexical/structural hits
Context	compact evidence under an explicit budget
Architecture	inferred structure and drift
History	Git history, blame, ownership
Pull requests	changed symbols, impact, tests, risk
Memory	project and team knowledge
Workspace	multi-repository search
Traces	execution summaries
Validation	validation evidence
Stats	repository, graph, Git, runtime state

---

Distributed operation

flowchart TB
    AG[AI Agents] --> GW[Remote MCP Gateway]
    GW --> AUTH[Authentication]
    AUTH --> POL[Tool Policy + Quotas]
    POL --> COORD[Coordinator]

    COORD --> IDX[Index Workers]
    COORD --> RET[Retrieval Workers]
    COORD --> CTX[Context Workers]

    IDX --> GRAPH[(Graph State)]
    RET --> VEC[(Persistent Vector Store)]
    CTX --> MEM[(Synchronized Team Memory)]

    COORD --> AUDIT[(Audit + Performance History)]

Workers advertise capabilities. Work is leased. Expired work can be requeued. Remote operation adds authentication, TLS support, quotas, tool policy, organization/workspace policy, and audit evidence.

The dashboard is an observability surface, not an authorization boundary.

---

Observatory

The local observatory can surface:

A context engine should be able to explain its own routing, evidence sources, and failure states.

---

Security model

Boundary	Control direction
Source paths	constrain operations to project root
Semantic edits	preflight + bounded path handling
Task traces	bounded attributes + redaction
Optional backends	process isolation
Remote MCP	authentication before dispatch
Remote tools	policy + allow lists + quotas
Organizations	roles + workspace policy + audit retention
Dependencies	audit + dependency review
Source	static analysis + CodeQL
Releases	checksums + SBOM + signatures + provenance

Security badges are evidence, not a proof that every deployment is secure. A deployment-specific threat model still matters.

---

Quality, release, and benchmark doctrine

A credential-gated integration that cannot run is reported as skipped. It is not counted as success.

Benchmark command:

A public performance claim should map to a reproducible spec, pinned revision, environment, measured result, and artifact. CodeCortex does not invent token savings, speedups, task-success gains, or accuracy percentages.

---

Evidence Fusion Layer

Status: shipped. Implementation, tests, benchmarks, documentation, and provenance records are in the repository. All three layers are optional: CodeCortex Core runs with none of them installed and no network access.

CodeCortex fuses several kinds of evidence and tells the agent, for every result, how that result was established. Each record carries a categorical trust tier — exact, near_exact, structural, inferred_high, inferred, weak — plus a provenance label. Two properties are enforced in code, not merely documented: evidence cannot claim the exact tier unless it is fresh, and stale exact evidence never outranks fresh structural evidence.

See docs/EVIDENCE_FUSION.md for the full model, fallback behavior, and security boundaries.

1 — Precision Code Intelligence

The Precision Code Intelligence layer consumes compiler/indexer-grade occurrence evidence when available and distinguishes:

Current capabilities:

• precise definition lookup;
• precise references;
• implementation relationships;
• symbol occurrences;
• stale-index detection;
• graph fusion with exact/inferred provenance;
• graceful fallback to current intelligence.

flowchart TB
    EX[Exact index/compiler evidence] --> F[Evidence Fusion]
    SEM[Language-aware semantic evidence] --> F
    AST[AST / structural evidence] --> F
    GR[Graph inference] --> F
    HEU[Heuristic resolution] --> F
    LEX[Lexical match] --> F
    F --> CTX[Task-ranked context]

The engine should know not only what it found, but how strongly it knows it.

2 — Version-Aware Dependency Intelligence

The Dependency Intelligence layer joins:

Questions this layer answers: