Cortex - AI Memory & Context Management Server

Powered by Enlighter and Hyperskill.

What it's for

Cortex is an MCP server that helps build and maintain a project Memory Bank so AI assistants always have up-to-date context, plans, and rules. It follows the Memory Bank pattern and keeps your .cortex/ files (roadmap, activeContext, progress, rules) in sync so agents can reliably run a plan → do → commit loop instead of ad-hoc edits. Use Cortex when you want reproducible, high-quality AI-driven development that survives restarts, editor changes, and long-running projects.

How to use it

1. Install prerequisites: Python 3.13+ and the Rust-based rumdl Markdown linter (installed via the Python dev environment; see Prerequisites).
2. Run the server: Add the config snippet from Running the Server to your mcp.json (most users pick uvx).
3. Start with the plan → do → commit loop (see below).

In your IDE/assistant, ask the agent to orchestrate these commands:

• Start a session (get an orientation brief)
• Load task-specific context
• Follow the plan → do → commit loop

For new projects, use the initialize prompt to create the Memory Bank and .cortex/ structure.

Plan → do → commit

This is the daily workflow:

See docs/prompts for setup/migration prompt details.

If Cortex MCP cannot be reached in your environment, you can still do a read-only audit of the repo under the boundaries in AGENTS.md (MCP unavailable: read-only audit fallback) and the runbook MCP unavailable: read-only audits.

Features

• Memory Bank — structured project context that persists across sessions
• Session & Context — orientation briefs, token-budgeted context loading, end-of-session compaction
• Validation & Quality — schema validation, lint/format/type auto-fix, pre-commit checks
• Plans & Roadmap — plan lifecycle management tied to a roadmap
• DRY Linking — transclusion engine to embed content without duplication
• Shared Rules (Synapse) — cross-project rule and prompt sharing via Git submodule
• Refactoring — pattern analysis, suggestions, safe execution with rollback
• Token Optimization — context summarization and relevance scoring

Recent changes

2026-10-05

• Reviews, analyses, and queries now use canonical directories directly under

.cortex/, shared by filing, search, and recent/deep context retrieval. Architectural findings retain their memory-bank destination.

• Added preview-first, digest-approved manage_file(operation="migrate_artifacts")

relocation with reference/index preservation, recoverable byte preimages, immutable historical provenance, and unchanged wiki-mirror allocation rules. See the migration guide.

Prerequisites

• Python 3.13+
• rumdl — Markdown linter/formatter installed into the Python environment (for example via uv sync --extra dev, which adds the rumdl CLI to .venv/bin/rumdl)

Running the Server

With uvx (recommended)

{
  "mcpServers": {
    "cortex": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/igrechuhin/Cortex.git",
        "cortex"
      ]
    }
  }
}

First run / IDE timeouts: uvx --from git+… must resolve GitHub HEAD, download dependencies, and build the package into uv’s cache. That can take minutes on a cold machine or right after uv cache clean. Some MCP clients time out during the first Initialize if the server is not ready yet. Pre-warm once in a terminal (same command you use in mcp.json), then start or reload the MCP client:

uvx --from git+https://github.com/igrechuhin/Cortex.git cortex --help

Details: Getting started — Stable MCP setup, Troubleshooting — uvx cold start.

Project-level vs global config: Place the snippet in your project's .mcp.json rather than in the global client config. Project-level config lets Cortex resolve the correct workspace root immediately. A global config makes your client launch Cortex with CWD set to the home directory; Cortex falls back to a heuristic root-finder that can pick up stale .cortex/ state left in ~/ and show spurious setup prompts.

With Smithery

{
  "mcpServers": {
    "cortex": {
      "command": "npx",
      "args": [
        "-y",
        "@smithery/cli@latest",
        "run",
        "@igrechuhin/cortex",
        "--key",
        "your_smithery_key"
      ]
    }
  }
}

With Docker

{
  "mcpServers": {
    "cortex": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "19283744/cortex:latest"
      ]
    }
  }
}

Manually

Clone the repository, then:

bash scripts/bootstrap.sh

Optionally initialize the Synapse submodule for shared rules:

git submodule update --init --recursive

Add to your mcp.json:

{
  "mcpServers": {
    "cortex": {
      "command": "uv",
      "args": ["run", "cortex"]
    }
  }
}

Developer commands

For local development, use these Make targets (after running bash scripts/bootstrap.sh once to create the virtualenv and install dependencies):

• Dependency setup / connectivity triage: If uv sync or installs fail (proxy, SSL, or registry access), use Dependency and network verification to separate environment setup failures from actual test failures.
• `make preflight`: Probe PyPI or UV_INDEX_URL before uv sync when triaging connectivity; see Dependency and network verification.
• `make bootstrap`: Run scripts/bootstrap.sh to create or update the .venv and install all dependencies.
• `make check`: Non-mutating local gate: verify Black on src/ and tests/, Ruff lint, Pyright, then the fast test suite. Does not rewrite files; use make fix when checks fail for formatting or auto-fixable lint.
• `make fix`: Apply Black, Ruff import sorting (I), and Ruff --fix on src/ and tests/ (mutating).
• `make check-ci-parity`: Run a broader subset of the GitHub Actions Code Quality workflow via uv run (synapse format/lint scripts, type checks, file/function limits, rumdl, pytest with coverage). Requires uv on your PATH. Still not identical to CI: spell check (cspell), the eval suite, Codecov, and health-check upload steps run only in Actions—see Troubleshooting — Local make check vs CI.
• `make test`: Run the default suite in parallel (-n auto), skip @pytest.mark.slow, no coverage (timeouts). Use make check-ci-parity for the full pytest+coverage command that matches CI.
• `make test-full`: Run the full test suite (including slower tests) with a longer timeout.
• `make commit-check`: Run the same checks as make check before using /cortex/commit for the full commit pipeline. With Cortex MCP connected, Phase A / Step 12 use the zero-arg tools documented in docs/api/tools.md.

For Swift Package Manager projects, the native quality gate runs the complete suite with swift test --enable-code-coverage --no-parallel. Test cases are scheduled serially; concurrent tasks and task groups inside each test remain concurrent. This native adapter invokes Swift directly, not the Synapse test script, and records the same arguments in its test transcript.

Key Tools

<!-- cortex-published-inventory: tools=14 resources=6 prompts-max=4 -->

Cortex exposes 14 MCP tools, 6 static `cortex://` resources, and up to 4 setup prompts (one always-on plus up to three configuration-dependent). Machine-readable inventory: docs/_generated/tool-inventory.json (must match cortex.discovery.published_inventory; CI enforces parity).

Published tools (canonical TOOL_CATEGORIES order — see docs/api/tools.md):

Read-only discovery uses resources (not in this table): cortex://health/connection, cortex://structure, cortex://context, cortex://rules, cortex://validation, cortex://analysis. Quick “do not” guidance: AGENTS.md quick reference.

Prompts

Prompts are for setup and migration; for daily work use plan → do → commit tools.

Full prompt list: docs/prompts

Memory Bank Structure

The Memory Bank lives under .cortex/ and works with any editor, LLM, or agent.

• .cortex/memory-bank/ — core files: projectBrief, productContext, activeContext, systemPatterns, techContext, progress, roadmap
• .cortex/plans/ — development plans linked to the roadmap
• .cortex/synapse/ — shared rules and prompts (Git submodule)
• .cortex/config/, .cortex/history/, .cortex/index.json — configuration, history, and metadata

Legacy layouts are migrated by the migrate prompt; see Getting started.

Limitations

• Token counts are tiktoken-based; when tiktoken is unavailable offline, a character-count heuristic (~1 token per 4 characters) is used. It tracks English prose closely but under-counts source code (~0.6x), Cyrillic (~0.7x), CJK (~0.3x) and emoji (~0.1x), so budgets enforced on such content while offline can overflow.
• Memory-bank summarization never rewrites what it keeps: under the default extract_key_sections strategy kept sections are replayed verbatim and dropped sections are disclosed by name or count. It is not lossless — whole sections are removed to meet the budget — and it may miss its target reduction rather than rewrite content. The compress_verbose and headers_only strategies additionally rewrite lines, elide code blocks and keep partial bodies, so a path, error string or constraint can disappear mid-section. Prefer the default when content must survive intact.
• AS-OF reconstruction is unavailable for WAL entries whose reverse delta was pruned or dropped by compaction; those historical versions cannot be recovered.
• BM25 relevance (retrieval/bm25.py) computes IDF over the per-call candidate corpus only — there is no global index, so scores are not comparable across calls.
• The Memory Bank format is deliberately editor/LLM/agent-agnostic; Cortex does not attempt semantic understanding beyond retrieval and summarization heuristics.

Documentation

• Getting started
• MCP Tools API
• Prompts
• Troubleshooting
• Advanced tool use