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.

Related MCP server: memory-bank-mcp

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

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.

Key Tools

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.

Documentation

• Getting started

• MCP Tools API

• Prompts

• Troubleshooting

• Advanced tool use