Cortex - AI Memory & Context Management Server

Powered by Enlighter and Hyperskill.

Learn how to setup and use Memory Bank directly in Cursor: http://enlightby.ai/projects/37

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 .cursor/mcp.json (or .claude/mcp.json) rather than in the global IDE config. Project-level config lets Cortex resolve the correct workspace root immediately. A global config makes your IDE 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 in Cursor 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=13 resources=6 prompts-max=4 -->

Cortex exposes 13 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

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 IDE .cursor/ (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