@danielblomma/cortex-mcp

Cortex

The context layer for AI-assisted software engineering.

What Cortex is

Cortex is a local, repository-scoped context engine for coding assistants. It parses your source code with tree-sitter, indexes it into a structured knowledge graph of entities (files, symbols, rules, ADRs) and their relationships (calls, defines, constrains, implements, supersedes), and exposes that context through CLI commands. MCP remains available as a compatibility and integration bridge for clients that support it.

Where a general-purpose AI assistant sees your codebase as a pile of text files, Cortex gives it a precise map: what exists, how it is connected, which rules govern it, and which parts are source-of-truth versus deprecated.

Cortex runs entirely on the developer's machine. Source code never leaves the host.

When to use Cortex

Cortex is designed for engineering teams that rely on AI assistants for non-trivial work on real codebases. Use it when:

• Your codebase is large or fragmented enough that assistants waste context window on irrelevant files.
• You need assistants to respect architectural rules, deprecations, and source-of-truth decisions already made by the team.
• You work across multiple languages and want consistent, structured retrieval across all of them.
• Security or compliance requires that source code stay on-premise and that all AI interactions remain auditable.
• You want retrieval to surface existing functionality before an assistant proposes new code — reducing duplication and drift.

Cortex is not a replacement for your editor, your version control, or your coding assistant. It is the grounding layer that makes those assistants act with knowledge of your specific repository.

Benefits

• Higher-quality suggestions. Assistants see the right files and rules instead of guessing from filenames.
• Lower token cost. Targeted retrieval replaces broad file reads. Typical sessions use a fraction of the context a raw assistant would consume.
• Architectural governance. Rules and ADRs are surfaced with every answer, so assistants follow the team's established patterns rather than generic best practices.
• Multi-language coverage. A single engine indexes multiple languages through tree-sitter grammars, giving polyglot teams consistent tooling.
• Privacy by design. Your code and its derived index stay on your machine. No upload, no cloud dependency for the core product.
• Low friction. One command (cortex init --bootstrap) scaffolds everything needed for local indexing, git hooks, CLI retrieval, and optional MCP compatibility.

How it works

Cortex operates as a five-stage pipeline between your repository and your AI assistant.

• Ingestion. Source files are parsed with tree-sitter, producing structured entities (files, functions, classes, rules, ADRs) and relations (CALLS, DEFINES, CONSTRAINS, IMPLEMENTS, IMPORTS, SUPERSEDES).
• Storage. Entities and relations are persisted to a local graph database (RyuGraph). An optional vector index provides semantic search across entity content.
• Retrieval. CLI commands combine semantic search with graph traversal to assemble the smallest context package that answers the task.
• Policy. Architectural rules and source-of-truth markers filter conflicting or deprecated content before it reaches the assistant.
• Assembly. Results are delivered as compact, ranked context packages over cortex ... --json, with MCP exposing equivalent tool responses when enabled.

Git hooks keep the index fresh on every checkout, pull, commit, and rewrite. A live TUI dashboard (cortex dashboard) shows what Cortex adds to the repository in real time.

Why it works

Modern coding assistants are bottlenecked by context, not by model capability. Feeding a model more files rarely helps; feeding it the right files almost always does.

Cortex is built on one principle: prefer retrieval quality over analysis completeness. A smaller, sharper context package outperforms a broad dump of files. Every component — from tree-sitter parsing to graph traversal to rule filtering — exists to raise the signal-to-noise ratio of what the assistant sees.

The result is an assistant that behaves as if it already knows your codebase, because — through Cortex — it does.

Quick demo

Core capabilities

• Semantic search across code, rules, and ADRs.
• Graph relationships between entities and architectural constraints.
• Call-graph traversal, caller lookup, and impact analysis.
• Architectural rules and ADR enforcement at retrieval time.
• Incremental index updates driven by git hooks.
• Live TUI dashboard showing what Cortex adds to your repository.
• CLI-first retrieval commands for local agents and scripts.
• Optional MCP integrations with Claude Code, Claude Desktop, and Codex.

Requirements

• Node.js 20+
• Git repository
• Optional for MCP registration: claude and/or codex CLI in PATH

Install

npm i -g @danielblomma/cortex-mcp

Upgrading

To upgrade an already-scaffolded project to a new Cortex version:

npm i -g @danielblomma/cortex-mcp
cortex init --force   # re-scaffolds .context runtime + .context/scripts
cortex bootstrap
cortex update

cortex init --force preserves per-project files: .context/config.yaml, .context/rules.yaml, and your notes/decisions.

Version-specific notes (see CHANGELOG.md for details):

• 2.1.0: the default embedding model changed, so the first cortex update after upgrading triggers a full re-embed automatically (~2 min per 1000 entities plus a one-time model download). The CORTEX_EMBED_MAX_CHARS env var is removed and silently ignored. Existing projects keep their old ranking weights in config.yaml; the recommended block is now semantic: 0.55, graph: 0.10, trust: 0.20, recency: 0.15. If you use MCP, restart the MCP server after re-embedding. The first search after a re-embed can hit a stale embeddings cache — re-run the query.

Quick Start

From the repository you want to index:

cortex init --bootstrap

This will:

• scaffold .context/, .context/scripts/, the local context runtime (.context/mcp compatibility path), .githooks/, and docs files
• activate git hooks for checkout, pull/merge, commit, and rewrite events
• build and prepare the local context runtime
• leave MCP client registration opt-in via cortex connect or cortex init --connect
• start background sync unless disabled

Disable watcher setup:

cortex init --bootstrap --no-watch

Check context status:

cortex status

Query From The CLI

Use the CLI as the default local agent interface:

cortex search "authentication flow" --json
cortex related file:src/auth.ts --json
cortex impact "payment service" --json
cortex rules --json
cortex explain "where retries are configured" --json

These commands read the same local graph, embeddings, and rules used by the MCP server, but they do not require an MCP client registration.

Optional MCP Connection

MCP remains supported for clients that need it. Register MCP clients explicitly:

cortex connect

Then verify the client registration:

Claude:

claude mcp list

Codex:

codex mcp list

Claude Plugin Marketplace

Install via Claude Code plugin marketplace:

/plugin marketplace add DanielBlomma/cortex
/plugin install cortex@cortex-marketplace
/plugin enable cortex

Then initialize Cortex in your target repository. If you want the plugin to call the local MCP server, also run cortex connect from that repository:

cortex init --bootstrap
cortex connect

Manual MCP Configuration

If client registration is unavailable, configure MCP manually.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "cortex": {
      "command": "cortex",
      "args": ["mcp"],
      "env": {
        "CORTEX_PROJECT_ROOT": "/absolute/path/to/your-project"
      }
    }
  }
}

Codex (~/.config/codex/mcp-config.json):

{
  "mcpServers": {
    "cortex-myproject": {
      "command": "cortex",
      "args": ["mcp"],
      "cwd": "/absolute/path/to/your-project"
    }
  }
}

WSL Mode (Windows)

If you run Node.js inside WSL but use Claude Desktop or another MCP client on Windows:

• Install Cortex inside WSL:

# In a WSL terminal
npm i -g @danielblomma/cortex-mcp
cd /mnt/c/Users/yourname/your-project
cortex init --bootstrap

• Configure Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "cortex": {
      "command": "wsl.exe",
      "args": ["--distribution", "Ubuntu", "--exec", "cortex", "mcp"],
      "env": {
        "CORTEX_PROJECT_ROOT": "C:\\Users\\yourname\\your-project",
        "CORTEX_AUTO_BOOTSTRAP_ON_MCP": "1"
      }
    }
  }
}

Cortex automatically converts Windows paths (e.g. C:\Users\...) to WSL paths (/mnt/c/Users/...).

For projects on the WSL filesystem (e.g. ~/projects/myapp), use the WSL path directly:

{
  "mcpServers": {
    "cortex": {
      "command": "wsl.exe",
      "args": ["--distribution", "Ubuntu", "--exec", "cortex", "mcp"],
      "env": {
        "CORTEX_PROJECT_ROOT": "/home/yourname/projects/myapp",
        "CORTEX_AUTO_BOOTSTRAP_ON_MCP": "1"
      }
    }
  }
}

Notes:

• File watching on /mnt/ paths (Windows filesystem) automatically uses poll mode since inotify is unreliable across filesystem boundaries.
• For best performance, keep projects on the WSL filesystem (~/...) rather than /mnt/c/....

MCP Tool Compatibility

context.search

Ranked context search across indexed entities.

Input:

• query (string, required)
• top_k (int, 1-20, default 5)
• include_deprecated (bool, default false)
• include_content (bool, default false)

context.get_related

Fetch entity relationships from the graph.

Input:

• entity_id (string, required)
• depth (int, 1-3, default 1)
• include_edges (bool, default true)

context.impact

Traverse likely impact paths across config, code and SQL starting from an entity id or query.

Input:

• entity_id (string, optional) — either entity_id or query is required
• query (string, optional)
• depth (int, 1-4, default 2)
• top_k (int, 1-20, default 8)
• include_edges (bool, default true)
• profile ("all" | "config_only" | "config_to_sql" | "code_only" | "sql_only", default "all")
• sort_by ("impact_score" | "shortest_path" | "semantic_score" | "graph_score" | "trust_score", default "impact_score")

context.get_rules

List indexed rules and optionally include inactive rules.

Input:

• scope (string, optional)
• include_inactive (bool, default false)

context.reload

Reload the RyuGraph connection after updates/maintenance.

Input:

• force (bool, default true)

Example Prompts

• "Find files that handle authentication."
• "Show related files for this ADR."
• "What active architectural rules apply to this API?"

Dashboard

A live TUI that shows what Cortex adds to your repository at a glance.

cortex dashboard

The dashboard displays:

• WITHOUT vs WITH CORTEX — side-by-side comparison of raw files versus indexed entities (files, chunks, relations, rules, embeddings, trust signals).
• TOKENS — per-task token estimate comparing typical LLM file reads without Cortex (~12 files) versus Cortex searches (~3 queries). Shows the reduction ratio and percentage.
• CORTEX ADDS — summary of what Cortex layers on top: chunks, relations, rules, embeddings, and which capabilities are unlocked (semantic search, graph traversal, impact analysis).
• RELATIONS — bar chart of relation types in the graph (CALLS, DEFINES, CONSTRAINS, IMPLEMENTS, IMPORTS, SUPERSEDES) and their counts.
• HEALTH — freshness percentage (how up-to-date the index is relative to uncommitted changes), last sync timestamp, and embedding status with model name.
• TOP CONNECTED — the five most connected entities in the graph by edge count, showing which files or rules are central to the codebase.

Options:

• --interval <sec> — auto-refresh interval (default: 2 seconds).
• Press r to force refresh, q to quit.
• Non-TTY output (piped) produces a single snapshot with ANSI stripped.

Common Commands

cortex init [path] [--force] [--bootstrap] [--connect] [--no-connect] [--watch] [--no-watch]
cortex connect [path] [--skip-build]
cortex mcp
cortex bootstrap
cortex update
cortex search <query> [--json]
cortex related <entity-id> [--json]
cortex impact <query|entity-id> [--json]
cortex rules [--json]
cortex explain <query|entity-id> [--json]
cortex status
cortex dashboard [--interval <sec>]
cortex watch [start|stop|status|run|once] [--interval <sec>] [--debounce <sec>] [--mode <auto|event|poll>]
cortex help

Automated Release

This repository includes two GitHub Actions workflows:

• Release Bump (.github/workflows/release-bump.yml)

  • Manual workflow_dispatch from main
  • Bumps semver (patch/minor/major)
  • Syncs release metadata files (package.json, server.json, plugin manifests)
  • Runs tests
  • Commits and tags vX.Y.Z

• Release Publish (.github/workflows/release-publish.yml)

  • Triggers on tag push v*.*.*
  • Verifies tag/version sync
  • Runs root tests + context runtime/MCP build/tests
  • Publishes @danielblomma/cortex-mcp to npm via npm trusted publishing (GitHub OIDC)

Required npm configuration:

• Configure a trusted publisher for @danielblomma/cortex-mcp on npmjs.com
• Use GitHub Actions publisher DanielBlomma/cortex
• Workflow filename must match release-publish.yml

Embedding performance

Embedding generation tunes itself to the machine: the number of parallel workers, memory limits for long files, token budget, and skip-work caching are all derived from the available CPU cores, RAM, and repository size at run time (container memory limits included). No configuration is needed — on a laptop or a CI runner, cortex picks safe settings by itself.

The embedding token budget defaults to auto, which is quality-first but memory-aware. Cortex starts from the embedding model's own maximum context and only lowers the cap when the local memory headroom is unlikely to fit that model/context combination. Degraded auto runs are explicit in logs, for example token_budget=auto_degraded reason=memory_headroom cap=2048. To force a specific capped run, set CORTEX_EMBED_MAX_TOKENS to a number such as 2048; set it to model or full to force the full-model baseline even on tight machines. When several cortex instances share one machine, set CORTEX_EMBED_THREADS to give each its fair share of cores.

Limitations

• Requires repo initialization (cortex init --bootstrap).
• Each repository has its own local Cortex context instance.
• No cloud sync by design (privacy-first local storage).

Security and Privacy

• Cortex stores context data locally under .context/.
• No source code upload is required for core functionality.

Troubleshooting

• context runtime missing or mcp/dist/server.js missing: Run cortex bootstrap (or re-run cortex init --bootstrap).
• claude or codex not found during cortex connect: MCP registration is skipped for that client; use manual config above if needed.
• MCP tools return stale context: Run cortex update, then rerun the CLI query. If you use MCP, reconnect the client or call context.reload.

Website and Benchmarks

• frontend/ hosts the cortex website (GitHub Pages, deployed on push to main): product overview plus bootstrap evaluation metrics.
• benchmark/bootstrapbench/ runs cortex bootstrap against 69 pinned real-world repositories in isolated containers and extracts chunk, embedding and graph statistics. See benchmark/bootstrapbench/README.md.

Support

• Issues: https://github.com/DanielBlomma/cortex/issues
• MCP registry submission draft: mcp-registry-submission.json

License

MIT