# CodeCortex

> Open-source context intelligence engine for AI coding agents — repository graph, precise code navigation, MCP, impact analysis, memory, and guarded edits.

- **Type:** MCP server
- **Install:** `agentstack add mcp-behnamjalalico-codecortex`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [BehnamJalaliCo](https://agentstack.voostack.com/s/behnamjalalico)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [BehnamJalaliCo](https://github.com/BehnamJalaliCo)
- **Source:** https://github.com/BehnamJalaliCo/CodeCortex
- **Website:** https://behnamjalalico.github.io/CodeCortex

## Install

```sh
agentstack add mcp-behnamjalalico-codecortex
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🧠 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**

[](https://pypi.org/project/codecortex-context-engine/)
[](https://pypi.org/project/codecortex-context-engine/)
[](https://github.com/BehnamJalaliCo/CodeCortex/actions/workflows/ci.yml)
[](https://github.com/BehnamJalaliCo/CodeCortex/actions/workflows/codeql.yml)
[](https://codecov.io/gh/BehnamJalaliCo/CodeCortex)
[](https://www.bestpractices.dev/projects/14379)
[](https://securityscorecards.dev/viewer/?uri=github.com/BehnamJalaliCo/CodeCortex)
[](LICENSE)

[**⭐ Star CodeCortex**](https://github.com/BehnamJalaliCo/CodeCortex) · [**❤️ Support Project**](docs/SUPPORT.md) · [**Documentation**](https://behnamjalalico.github.io/CodeCortex/) · [**Latest Release**](https://github.com/BehnamJalaliCo/CodeCortex/releases/latest) · [**Contribute**](CONTRIBUTING.md)

[🇬🇧 English](#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.

```bash
python -m pip install --upgrade codecortex-context-engine
cortex init .
cortex index
cortex doctor
```

Then ask the repository useful questions:

```bash
cortex architecture
cortex semantic "authentication and session lifecycle"
cortex impact AuthService
```

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

```bash
cortex mcp --path .
```

## Works with coding agents

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

```bash
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:

```bash
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](HARDENING_REPORT.md) and [benchmarks/](benchmarks/) for scope, methodology, limitations, and reproducibility notes.

> ❤️ **Support CodeCortex** — If CodeCortex saves you time, consider supporting its continued open-source development. [**Crypto support →**](docs/SUPPORT.md)

---

# 🇬🇧 English

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

[](https://github.com/BehnamJalaliCo/CodeCortex)

## 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

```mermaid
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.

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

```mermaid
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

Repository Intelligence — structure before speculation

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.

Symbol Intelligence — names, containers, signatures, references

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.

Hybrid Retrieval — lexical + semantic + structural

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.

Git & PR Intelligence — code has history

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.

Memory — durable rationale, not a truth replacement

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 Intelligence — make structural movement visible

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 & Validation — reason about blast radius

Impact analysis walks reverse relationships and affected tests. Validation challenges a proposed change against repository evi

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [BehnamJalaliCo](https://github.com/BehnamJalaliCo)
- **Source:** [BehnamJalaliCo/CodeCortex](https://github.com/BehnamJalaliCo/CodeCortex)
- **License:** Apache-2.0
- **Homepage:** https://behnamjalalico.github.io/CodeCortex

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-behnamjalalico-codecortex
- Seller: https://agentstack.voostack.com/s/behnamjalalico
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.