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.

🇬🇧 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:

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 — 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.

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

Optional parser support:

python -m pip install "codecortex-context-engine[parsers]"

Optional local neural semantic embeddings:

python -m pip install "codecortex-context-engine[semantic]"

Start inside a repository

cortex init .
cortex index
cortex doctor

cortex architecture
cortex semantic "authentication and session lifecycle"
cortex impact AuthService
cortex symbol-history src/auth.py 10 80

cortex mcp --path .

A 30-second mental model

          ┌────────────────────────────┐
          │       Coding Agent         │
          └─────────────┬──────────────┘
                        │ task
          ┌─────────────▼──────────────┐
          │        CodeCortex          │
          │ map · symbols · history    │
          │ graph · retrieval · memory │
          │ impact · architecture      │
          │ validation · policy        │
          └─────────────┬──────────────┘
                        │ bounded evidence
          ┌─────────────▼──────────────┐
          │       Coding Agent         │
          │ reasons with a better map  │
          └────────────────────────────┘

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

diff
→ changed files
→ changed symbols
→ downstream impact
→ affected tests
→ churn / ownership
→ architecture movement
→ risk evidence
→ review context

PR size is only one signal.

Multi-repository work

frontend repo ───────┐
backend repo ────────┼── federated evidence ──→ task context
contracts repo ──────┘

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:

cortex edit rename src/auth.py AuthService SessionService
cortex edit replace src/auth.py AuthService/refresh --body-file ./replacement.txt
cortex edit insert-before src/auth.py AuthService --body-file ./imports.txt
cortex edit insert-after src/auth.py AuthService --body-file ./helper.txt

The intended change discipline is:

read enough to understand
→ estimate impact
→ mutate narrowly
→ validate

Not:

replace text everywhere
→ hope tests catch it

MCP: one agent-facing surface

cortex mcp --path /path/to/repository

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

cortex dashboard -p /path/to/repository

The local observatory can surface:

backend health
routing distribution
context use
engine latency
graph hotspots
task traces
architecture drift
benchmark history
pull-request risk

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

exact commit
→ quality matrix
→ security checks
→ build
→ smoke test
→ checksums
→ SBOM
→ signing / attestations
→ release

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

Benchmark command:

python scripts/run_production_benchmark.py

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:

exact definition/reference
        vs
structural relationship
        vs
heuristic candidate
        vs
lexical coincidence

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:

manifest
+ lockfile
+ declared version
+ resolved version
+ repository usage
+ version-relevant documentation evidence

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:

find calls shaped like old_api($X)
find constructors using a legacy option shape
find handlers that swallow a particular exception form
find all structural usages before a framework migration

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:

dependency manifest
→ resolved version
→ current middleware
→ precise references
→ version-relevant documentation
→ structural occurrences
→ affected symbols and tests
→ guarded rewrite preview
→ mutation policy
→ validation
→ post-change impact

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

cortex init .
cortex index
cortex architecture
cortex architecture-drift
cortex semantic "authentication refresh"
cortex impact AuthService
cortex symbol-history src/auth.py 10 80
cortex pr main --head HEAD
cortex workspace-add backend ../backend
cortex workspace-search "payment service"
cortex definition src/auth.py 12 7
cortex references src/auth.py 12 7
cortex implementations src/auth.py 12 7
cortex precision-status
cortex dependency next
cortex dependency-docs next "middleware authentication"
cortex structural-search --lang python --pattern 'old_api($X)'
cortex rewrite-preview --lang python --pattern 'old_api($X)' --replacement 'new_api($X)'
cortex rewrite-apply <preview-id>
cortex benchmark
cortex evidence-benchmark
cortex dashboard
cortex doctor
cortex mcp --path .

Docker

docker build --target core -t codecortex:core .
docker build --target full -t codecortex:full .
docker compose up dashboard

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

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.

python -m pip install -e ".[dev]"
ruff check .
mypy src/codecortex
pytest

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.

جست‌وجوی اسم فایل
→ باز کردن فایل‌های زیاد
→ کشف دوباره معماری
→ حدس زدن مالکیت سیمبل
→ حدس referenceها
→ بررسی دستی Git
→ حدس blast radius
→ مصرف کانتکست زیاد
→ ویرایش
→ کشف یک dependency پنهان در مرحله بعد

تسک
→ تشخیص intent
→ جمع‌آوری evidence ریپو
→ rank کردن برای همین تسک
→ حفظ provenance و uncertainty
→ جا دادن evidence داخل context budget
→ ارائه از یک سطح واحد به ایجنت
→ validation تغییر پیشنهادی

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

شاهد دقیق          → دقیق نمایش بده
استنباط قوی        → provenance را نگه دار
استنباط مبهم       → گزینه‌های دیگر را نگه دار
شاهد وجود ندارد    → missing گزارش کن
شاهد قدیمی است     → stale گزارش کن

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

python -m pip install "codecortex-context-engine[parsers]"

python -m pip install "codecortex-context-engine[semantic]"

cortex init .
cortex index
cortex doctor

cortex architecture
cortex semantic "authentication and session lifecycle"
cortex impact AuthService
cortex symbol-history src/auth.py 10 80

cortex mcp --path .

          ┌────────────────────────────┐
          │       Coding Agent         │
          └─────────────┬──────────────┘
                        │ task
          ┌─────────────▼──────────────┐
          │        CodeCortex          │
          │ map · symbols · history    │
          │ graph · retrieval · memory │
          │ impact · architecture      │
          │ validation · policy        │
          └─────────────┬──────────────┘
                        │ evidence محدود
          ┌─────────────▼──────────────┐
          │       Coding Agent         │
          │  با نقشه بهتر reasoning می‌کند │
          └────────────────────────────┘

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

diff
→ فایل تغییرکرده
→ سیمبل تغییرکرده
→ downstream impact
→ affected tests
→ churn / ownership
→ حرکت معماری
→ risk evidence
→ review context

frontend repo ───────┐
backend repo ────────┼── federated evidence ──→ task context
contracts repo ──────┘

cortex edit rename src/auth.py AuthService SessionService
cortex edit replace src/auth.py AuthService/refresh --body-file ./replacement.txt
cortex edit insert-before src/auth.py AuthService --body-file ./imports.txt
cortex edit insert-after src/auth.py AuthService --body-file ./helper.txt

به‌اندازه کافی بخوان
→ impact را بفهم
→ محدود mutate کن
→ validate کن

همه‌جا replace کن
→ امیدوار باش testها بگیرند

cortex mcp --path /path/to/repository

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

cortex dashboard -p /path/to/repository

backend health
routing distribution
context use
engine latency
graph hotspots
task traces
architecture drift
benchmark history
pull-request risk

commit دقیق
→ quality matrix
→ security checks
→ build
→ smoke test
→ checksum
→ SBOM
→ signature / attestation
→ release

python scripts/run_production_benchmark.py

definition/reference دقیق
        با
relationship ساختاری
        با
candidate heuristic
        با
lexical coincidence

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]

manifest
+ lockfile
+ نسخه declared
+ نسخه resolved
+ usage داخل repository
+ documentation مربوط به همان نسخه

callهایی با شکل old_api($X)
constructor با option قدیمی
handler با exception pattern خاص
همه usageهای ساختاری قبل از migration

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]

dependency manifest
→ نسخه resolved
→ middleware فعلی
→ reference دقیق
→ documentation مربوط به نسخه
→ structural occurrence
→ symbol و test متاثر
→ guarded rewrite preview
→ mutation policy
→ validation
→ impact بعد از تغییر

cortex init .
cortex index
cortex architecture
cortex architecture-drift
cortex semantic "authentication refresh"
cortex impact AuthService
cortex symbol-history src/auth.py 10 80
cortex pr main --head HEAD
cortex workspace-add backend ../backend
cortex workspace-search "payment service"
cortex definition src/auth.py 12 7
cortex references src/auth.py 12 7
cortex precision-status
cortex dependency next
cortex dependency-docs next "middleware authentication"
cortex structural-search --lang python --pattern 'old_api($X)'
cortex rewrite-preview --lang python --pattern 'old_api($X)' --replacement 'new_api($X)'
cortex rewrite-apply <preview-id>
cortex benchmark
cortex evidence-benchmark
cortex dashboard
cortex doctor
cortex mcp --path .

docker build --target core -t codecortex:core .
docker build --target full -t codecortex:full .
docker compose up dashboard

python -m pip install -e ".[dev]"
ruff check .
mypy src/codecortex
pytest