Cortex

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:

| Step | What happens | |------|--------------| | Plan | Create or refine plans in .cortex/plans/ and register them in roadmap.md. | | Do | Apply the next PENDING roadmap step with tests and quality checks. | | Commit | Run the full pre-commit pipeline and push only healthy commits. |

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

| Tool | Purpose | | ---- | ------- | | manage_file() | Memory bank read/write (zero-arg reads activeContext.md) | | plan() | Plan create/list/get/complete/register/archive_completed | | update_memory_bank() | Roadmap/progress/activeContext mutations | | session() | Session start, orientation, compact | | run_quality_gate() | Phase A quality checks and Step 12 final gate (zero-arg) | | autofix() | Auto-fix lint/format/types/markdown (zero-arg) | | think() | Reasoning scratchpad | | ingest() | Stage raw external sources under memory-bank for /cortex/ingest | | run_docs_gate() | Phase B docs validation (zero-arg) | | pipeline_handoff() | Inter-phase state exchange (init/write/read/clear) | | write_artifact() | Allowlisted skill JSON and Synapse rule artifact writes | | compress_memory_bank() | Compress project CLAUDE.md and memory-bank markdown to reduce session tokens | | memory_wal() | Memory-bank WAL read, anomaly hints, snapshot/restore | | propose_framework_optimization() | Draft/self-test a Synapse prompt/rule change in an isolated, always-removed worktree |

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.

| Situation | Prompt | |-----------|--------| | New project, no Memory Bank | initialize | | Legacy Memory Bank under memory-bank/ or .memory-bank/ | migrate | | Share rules across projects | setup_synapse | | tiktoken cache missing (local encoding cache setup) | populate_tiktoken_cache |

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