CodeCortex Context Engine

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.

[CodeCortex product overview]

60-second start

Requires Python 3.11–3.13.

python -m pip install --upgrade codecortex-context-enginecortex init .cortex indexcortex doctor

Then ask the repository useful questions:

cortex architecturecortex 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 detectcortex 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

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

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

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.

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

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:

• Which version is actually resolved?
• Is the requested API valid for that version?
• Is the current pattern outdated?
• Which migration guidance applies?
• Which local files and symbols use the dependency?

External documentation remains optional, minimal-data, credential-aware, cached, and explicit. Core repository intelligence must continue to work offline. Repository source should not leave the system by default just to answer a dependency question.

3 — Structural Search & Guarded Rewrite

The Structural Search & Guarded Rewrite layer handles syntax-aware patterns:

Mutation lifecycle:

flowchart LR    Q[Migration request] --> S[Structural search]    S --> M[Match set]    M --> I[Impact analysis]    I --> P[Rewrite preview]    P --> A{Mutation allowed?}    A -- No --> STOP[Preview only]    A -- Yes --> W[Bounded rewrite]    W --> R[Reindex]    R --> V[Validation]    V --> POST[Post-change impact]

A rewrite should be previewed, bounded, content-hash checked, policy-authorized, reindexed, and validated.

Evidence fusion in practice

Example, covered end to end by an acceptance test:

Migrate authentication middleware to the supported API for the version used by this repository.

Stream:

The value is not three disconnected tools. The value is one context engine joining local code truth, precise relationships, dependency-version evidence, structural patterns, history, and validation for one task.

Measured on fixture repositories (cortex evidence-benchmark; strategies that cannot be measured are reported as skipped, never estimated):

Shipped capabilities and fallback behavior

Operating profiles

What CodeCortex is not

Design rules

1. Typed boundaries.
2. Replaceable intelligence.
3. Local operation first.
4. Explicit context budgets.
5. Project-scoped state by default.
6. Provenance survives summarization.
7. Mutation is a separate privilege.
8. Distributed state is explicit.
9. Missing evidence stays missing.
10. Release claims map to evidence.

Command map

Docker

Containerization does not replace authentication, TLS, policy, secret management, or an appropriate deployment threat model.

Project status

CodeCortex is currently alpha.

Public interfaces are still evolving. Breaking changes can occur before 1.0. Evaluate the project by what the current code, tests, CI, documentation, and reproducible artifacts demonstrate.

Engineering use cases

Community

Good First Issues · Report a Bug · Contributing Guide

Documentation

• Architecture
• Distributed operation
• Advanced intelligence
• Evidence fusion
• Integrations
• Quality
• Testing
• Release
• Licensing
• Security
• Contributing
• Governance
• Roadmap
• Cloud & Enterprise Early Access

FAQ

Maintainer, contribution, and license

CodeCortex is built and maintained by Behnam Jalali.

CodeCortex-owned material is licensed under Apache License 2.0. Third-party material remains subject to the license and attribution records kept in the repository.

See LICENSE, NOTICE, SECURITY.md, and CONTRIBUTING.md.

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

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

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)]

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]

flowchart LR    Q[Migration request] --> S[Structural search]    S --> M[Match set]    M --> I[Impact analysis]    I --> P[Rewrite preview]    P --> A{Mutation allowed?}    A -- No --> STOP[Preview only]    A -- Yes --> W[Bounded rewrite]    W --> R[Reindex]    R --> V[Validation]    V --> POST[Post-change impact]