Skip to main content
Glama
Sign In
Cortex MCP

Cortex MCP

by neuralnexustech
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

Cortex MCP

Persistent brain, memory, loop controller, and reminder engine for AI coding agents.

npm version License: MIT Node.js

What is Cortex?

Cortex is a local MCP server that gives AI coding agents persistent memory, task management, knowledge graphs, and a live dashboard. It runs on your machine, stores everything in SQLite, and never sends data to the cloud.

Agent starts → cortex_get_state → knows everything → works → cortex_save_snapshot → done

Related MCP server: Xanther memory Engine

Features

31 MCP Tools

  • Core Loop — get_state, get_next_task, log_progress, check_reminders, save_snapshot

  • Project Setup — init (10-question onboarding), health check with auto-repair

  • Features & Files — track features, files, checkpoints, rollback

  • Tests & Issues — register tests, log bugs, resolve issues

  • Knowledge Base — dictionary, snippets, research, decisions, FTS5 search

  • Human Interaction — ask_human (pause for input), confirm_destructive (red modal)

  • V2 Advanced — token budget (180k), agent roles (4 levels), contradiction detection

  • Knowledge Graph — relationships between features, files, tests, issues

Live Dashboard

  • 12 tabs — Overview, Pipeline, Features, FileTree, Tests, Progress, Issues, Library, Research, Dictionary, Graph, Settings

  • Pipeline tab — Start a goal, watch tasks execute live with progress bar, pause/resume/cancel

  • D3 Knowledge Graph — force-directed visualization with 27+ nodes, drag/zoom/pan

  • WebSocket Live Push — dashboard updates instantly when data changes

  • Ctrl+K Search — global search across all tables

  • shadcn/ui — modern React 19 + Tailwind CSS interface

MCP Resources (10 endpoints)

Read project data without tool calls via cortex:// URIs: cortex://project, cortex://features, cortex://files, cortex://tests, cortex://issues, cortex://dictionary, cortex://progress, cortex://todos, cortex://relationships, cortex://snapshots

MCP Prompts (5 templates)

Pre-built session workflows: start-session, debug-issue, review-code, init-project, end-session

V2.4 Modules — Autonomous Pipeline

  • Planner — natural language goal → ordered DAG of tasks with dependency resolution

  • Executor — auto-executes tasks (agent/command/test/verify), retries failures up to 3×

  • Loop Controller — pause/resume/cancel with WebSocket live push to dashboard

  • Auto-Heal — detects broken files (restores from checkpoint), resets failed tests

V2.1 Modules

  • Audit Trail — structured logging for every tool call

  • Episodic Memory — timestamped events with importance scoring

  • Context Compilation — full project state in 2ms

Quick Start

Option 1: npx (Recommended)

Add to your opencode.json:

{
  "mcp": {
    "cortex": {
      "type": "local",
      "command": ["npx", "-y", "@neuralnexustech/cortex-mcp@latest", "start", "--project", "."],
      "enabled": true,
      "env": {
        "CORTEX_PROJECT_PATH": "."
      }
    }
  }
}

Option 2: Local Install

npm install -g @neuralnexustech/cortex-mcp@latest

Then add to opencode.json:

{
  "mcp": {
    "cortex": {
      "type": "local",
      "command": ["cortex", "start", "--project", "/path/to/your/project"],
      "enabled": true,
      "env": {
        "CORTEX_PROJECT_PATH": "/path/to/your/project"
      }
    }
  }
}

Option 3: Clone & Run

git clone https://github.com/neuralnexustech/cortex-mcp.git
cd cortex-mcp
npm install
cd dashboard && npm install && npm run build && cd ..
node src/server.js

Autonomous Pipeline (V2.4)

Cortex Pipeline is a goal-driven autonomous execution engine. Give it a goal, and it plans, executes, tests, and heals itself — no step-by-step prompting required.

Goal → Planner → DAG Tasks → Executor → Test → Auto-Heal → Done
                              ↕
                    pause / resume / cancel
                         (WebSocket live)

How It Works

You type: "Build authentication system"
    ↓
Planner breaks goal into ordered DAG:
  [1] Scaffold routes        → [2] Create User model
  → [3] JWT middleware       → [4] Login endpoint
  → [5] Register endpoint    → [6] Password hashing
  → [7] Run tests            → [8] Verify security
    ↓
Executor auto-runs each task:
  ✓ Scaffold routes      (1.2s)
  ✓ Create User model    (0.8s)
  ✗ JWT middleware       → retry #1 → ✓  (2.1s)
  ✓ Login endpoint       (0.5s)
  ...
    ↓
Auto-Heal detects broken files → restores from checkpoint
Auto-Heal resets failed tests   → retries with new approach
    ↓
Done. Pipeline history saved. Dashboard updated via WebSocket.

8 Pipeline MCP Tools

Tool

Purpose

cortex_pipeline_start

Give a goal → DAG planned + executed

cortex_pipeline_status

Check progress, task states, retry counts

cortex_pipeline_pause

Pause mid-execution

cortex_pipeline_resume

Resume from where it paused

cortex_pipeline_cancel

Cancel remaining tasks

cortex_pipeline_plan

Preview task breakdown (dry run)

cortex_auto_heal

Fix broken files, reset failed tests

cortex_pipeline_history

List all past pipeline runs

Why This Is Different

Traditional AI Assistants

Cortex Pipeline

Wait for your next prompt

Executes autonomously toward a goal

You give step-by-step instructions

You give a goal, it plans the steps

You babysit each action

Auto-retry on failure (up to 3×)

No memory of past runs

Full pipeline history + checkpoints

Single-threaded Q&A

Multi-task DAG with priority ordering

You fix broken files

Auto-heal restores from checkpoints

In short: Most AI tools are reactive — you drive. Cortex Pipeline is proactive — it drives itself, and you just set the destination.

Session Lifecycle

START
  ↓
cortex_get_state        → project context (<200 tokens)
  ↓
cortex_get_next_task    → highest-priority pending todo
  ↓
WORK                    → write code, create files
  ↓
cortex_tick_file        → track each file created
  ↓
cortex_log_progress     → log completed work
  ↓
cortex_check_reminders  → handle warnings
  ↓
cortex_get_next_task    → next todo (or "ALL TASKS COMPLETE")
  ↓
...repeat...
  ↓
cortex_save_snapshot    → compress session to summary
  ↓
END

Tool Reference

Core Loop (5)

Tool

Purpose

cortex_get_state

Compressed project context

cortex_get_next_task

Highest-priority pending todo

cortex_log_progress

Log completed work

cortex_check_reminders

6 safety checks

cortex_save_snapshot

Compress session summary

Project Setup (3)

Tool

Purpose

cortex_init

Initialize project (10-question onboarding)

cortex_set_active_project

Switch between projects

cortex_health

DB integrity + auto-repair

Features & Files (5)

Tool

Purpose

cortex_add_feature

Register a feature

cortex_update_feature

Update feature status

cortex_tick_file

Track file creation (auto-checkpoints)

cortex_get_files

List all tracked files

cortex_rollback_file

Restore file from checkpoint

Tests (2)

Tool

Purpose

cortex_add_test

Register a test

cortex_update_test

Mark test passed/failed

Issues (2)

Tool

Purpose

cortex_log_issue

Log a bug or blocker

cortex_resolve_issue

Mark issue resolved with fix

Knowledge Base (6)

Tool

Purpose

cortex_write_dictionary

Document a file/feature

cortex_get_detail

Retrieve full dictionary entry

cortex_add_snippet

Save reusable code snippet

cortex_add_research

Log library research notes

cortex_add_decision

Record architectural decision

cortex_search

FTS5 + vector hybrid search

Human Interaction (2)

Tool

Purpose

cortex_ask_human

Pause, ask question, wait for answer

cortex_confirm_destructive

Red confirmation modal for dangerous ops

V2 Advanced (5)

Tool

Purpose

cortex_log_tokens

Track token usage per action

cortex_get_token_budget

Check remaining budget (180k default)

cortex_set_role

Set agent role

cortex_get_role

Get agent permissions

cortex_list_agents

List all connected agents

Knowledge Graph (3)

Tool

Purpose

cortex_add_relationship

Link entities

cortex_check_contradictions

Find conflicting data

cortex_resolve_contradiction

Resolve conflicts

Skills (2)

Tool

Purpose

cortex_get_skill

Load SKILL.md guide

cortex_list_skills

List available skills

Database

SQLite at .cortex/cortex.db with:

  • WAL mode — concurrent reads while writing

  • FTS5 — full-text search across all tables

  • 15+ tables — project, features, files, tests, issues, dictionary, progress, relationships, etc.

  • Triggers — auto-sync FTS index on insert/update/delete

Dashboard

Live at http://localhost:3001 when the server runs.

  • Ctrl+K — Global search overlay

  • Graph tab — D3 force-directed knowledge graph

  • LIVE indicator — WebSocket connection status

  • 12 tabs — Overview, Pipeline, Features, FileTree, Tests, Progress, Issues, Library, Research, Dictionary, Graph, Settings

REST API

Endpoint

Description

GET /api/health

Health check

GET /api/data

All project data

GET /api/graph

Knowledge graph (nodes + edges)

GET /api/search?q=<query>

Search across tables

GET /api/audit

Audit trail entries

GET /api/episodic

Episodic memory events

GET /api/context

Compiled project state

GET /ws-status

WebSocket status

POST /api/pipeline/start

Start a pipeline from a goal

GET /api/pipeline/:id

Get pipeline run status + tasks

GET /api/pipeline-history

List past pipeline runs

POST /api/pipeline/pause

Pause active pipeline

POST /api/pipeline/resume

Resume paused pipeline

POST /api/pipeline/cancel

Cancel active pipeline

POST /human-answer

Submit answer to pending question

MCP Resources

Read project data without tool calls:

URI

Data

cortex://project

Project config, features, todos

cortex://features

All features with status

cortex://files

All tracked files

cortex://tests

All tests

cortex://issues

All issues

cortex://dictionary

File documentation

cortex://progress

Recent activity

cortex://todos

Pending tasks

cortex://relationships

Knowledge graph edges

cortex://snapshots

Session summaries

Architecture

cortex-mcp/
├── bin/cortex.js              # CLI entry point
├── src/
│   ├── server.js              # MCP server (main entry)
│   ├── api/server.js          # Express REST API + dashboard
│   ├── db/
│   │   ├── schema.js          # Table definitions + FTS5
│   │   ├── init.js            # DB connection (WAL mode)
│   │   ├── queries.js         # Read/write functions
│   │   └── cortex_v2.sql      # V2 migration
│   ├── pipeline/              # V2.4 Autonomous pipeline
│   │   ├── planner.js         # Goal → DAG task breakdown
│   │   ├── executor.js        # Auto-execute + retry
│   │   ├── loop.js            # Pause/resume/cancel controller
│   │   └── index.js           # 8 MCP tool registration
│   ├── tools/                 # 31 MCP tools
│   │   ├── state.js           # cortex_get_state
│   │   ├── tasks.js           # cortex_get_next_task
│   │   ├── search.js          # FTS5 + hybrid search
│   │   ├── contradictions.js  # Contradiction detection
│   │   ├── tokens.js          # Token budget
│   │   ├── roles.js           # Agent roles
│   │   ├── relationships.js   # Knowledge graph
│   │   ├── health.js          # Auto-repair
│   │   └── ...
│   ├── embeddings/            # ONNX vector engine
│   ├── websocket/server.js    # WebSocket live push
│   ├── audit/index.js         # Audit trail
│   ├── memory/
│   │   ├── episodic.js        # Episodic memory
│   │   └── compiler.js        # Context compiler
│   ├── resources/project.js   # MCP Resources
│   └── prompts/index.js       # MCP Prompts
├── dashboard/                 # React 19 + shadcn/ui
│   ├── src/
│   │   ├── App.jsx            # Main app + routing
│   │   ├── components/
│   │   │   ├── tabs/          # 11 tab components
│   │   │   ├── ui/            # shadcn/ui components
│   │   │   ├── Graph.jsx      # D3 knowledge graph
│   │   │   └── GlobalSearch.jsx
│   │   └── styles/globals.css # Tailwind + shadcn vars
│   └── dist/                  # Built dashboard
├── skills/                    # Agent skill files
├── docs/                      # Documentation
└── AGENTS.md                  # Agent guide

Environment Variables

Variable

Default

Description

CORTEX_PROJECT_PATH

.

Project root directory

CORTEX_API_PORT

3001

REST API port

CORTEX_PORT

4759

Dashboard port

CORTEX_SYNC_ENABLED

false

Enable cloud sync

Requirements

  • Node.js ≥ 18.0.0

  • Works on Windows, macOS, Linux

Links

Platform

URL

Website

https://neuralnexustech.com/

GitHub

https://github.com/neuralnexustech/cortex-mcp

npm

https://www.npmjs.com/package/@neuralnexustech/cortex-mcp

License

MIT © neuralnexustech

Available Tools

42 tools
cortex_add_decisionB

Log an architectural decision

Inputs: title (required), reason (required), alternatives.

cortex_add_featureC

Add a new feature

Inputs: name (required), description, priority.

cortex_add_relationshipC

Create a relationship between two entities (feature, file, test, issue, decision).

Inputs: source_type (required), source_id (required), target_type (required), target_id (required), +1 more.

cortex_add_researchC

Save library research notes

Inputs: notes (required), library_name, library, version, +2 more.

cortex_add_snippetC

Save a code snippet to library

Inputs: title (required), code (required), language, tags.

cortex_add_testB

Add a test linked to a feature

Inputs: name (required), feature_id.

cortex_ask_humanA

Force pause, queue a question for human, block until answered via POST /api/human-answer

Inputs: question (required), agent.

cortex_auto_healA

Auto-detect and fix broken files, failed tests, and other issues. Returns list of healed items.

Inputs: auto_fix.

cortex_check_contradictionsA

Find conflicting data in the dictionary. If key provided, checks only that entry. If no key, scans recent entries.

Inputs: key.

cortex_check_remindersB

Run all 6 reminder checks — returns list of warnings/blocks based on real DB state

Inputs: no named parameters.

cortex_confirm_destructiveA

Block dangerous actions until human confirms. Shows red modal in dashboard. Falls back to terminal if no dashboard.

Inputs: action (required), target.

cortex_get_detailC

Get full dictionary entry for a file or feature

Inputs: key (required).

cortex_get_next_taskA

Get next pending todo - agent always calls this, never decides own next step

Inputs: no named parameters.

cortex_get_roleB

Get the role and permissions for an agent.

Inputs: agent_name (required).

cortex_get_skillA

Get the full content of a Cortex skill file. Call this at the start of any session to load the complete agent guide. Works with Claude Code, Gemini, Codex, Cursor, OpenCode, and any MCP client. Defaults to the main "cortex" skill (SKILL.md) if no name is given.

Inputs: name.

cortex_get_stateA

Get compressed project state (under 200 tokens) — call before every action. Includes token budget warning if >50% used.

Inputs: session_id.

cortex_get_token_budgetB

Get token budget status for the current session.

Inputs: session_id (required), budget.

cortex_healthA

Check DB integrity, missing tests, open issues, broken files. Auto-repairs common problems.

Inputs: auto_repair.

cortex_initA

Initialize Cortex project. You MUST ask the human ALL 10 onboarding questions FIRST using cortex_ask_human. Do NOT call this tool until you have all answers. The 10 mandatory questions are: 1) Project name, 2) Goal, 3) Tech stack, 4) UI style, 5) Preferred libs, 6) Forbidden libs, 7) File structure, 8) Existing codebase, 9) Core features, 10) Complexity level.

Inputs: project_name (required), goal (required), stack (required), core_features (required), +6 more.

cortex_list_agentsA

List all connected agents and their roles.

Inputs: no named parameters.

cortex_list_skillsA

List all available Cortex skills — bundled with the package (always available) plus any user-added skills. Returns name, source ("bundled" or "user"), and description for each.

Inputs: no named parameters.

cortex_log_issueC

Log a bug or blocker

Inputs: title (required), description, file_path.

cortex_log_progressC

Log a completed step

Inputs: task (required), file_path, file, notes, +1 more.

cortex_log_tokensA

Log token usage for the current action. Call after every tool call.

Inputs: session_id (required), input_tokens (required), output_tokens (required).

cortex_pipeline_cancelA

Cancel a running or paused pipeline.

Inputs: pipeline_id.

cortex_pipeline_historyB

View recent pipeline runs and their results.

Inputs: limit.

cortex_pipeline_pauseC

Pause the currently running pipeline.

Inputs: pipeline_id.

cortex_pipeline_planA

Preview what tasks a pipeline would create for a goal without starting it.

Inputs: goal (required).

cortex_pipeline_resumeB

Resume a paused pipeline.

Inputs: pipeline_id.

cortex_pipeline_startA

Start an autonomous pipeline from a goal. Breaks goal into tasks, executes them, auto-retries failures.

Inputs: goal (required), max_retries, pause_on_human, session_id, +1 more.

cortex_pipeline_statusB

Get the status of a running or completed pipeline.

Inputs: pipeline_id.

cortex_resolve_contradictionB

Resolve a contradiction by choosing which version to keep.

Inputs: id (required), keep_version (required), corrected_value.

cortex_resolve_issueB

Mark issue resolved with fix description

Inputs: id (required), fix (required).

cortex_rollbackB

Restore file to checkpoint

Inputs: file_path (required), checkpoint_id.

cortex_save_snapshotA

Compress current session to summary, save to DB and .cortex/snapshots/ on disk

Inputs: summary (required), session_id, agent.

cortex_searchA

Search across dictionary, issues, snippets, research, and progress. Supports keyword (FTS5), semantic (vector), and hybrid (RRF fusion) modes. Returns ranked results with source table, id, and matched snippet.

Inputs: query (required), mode, tables.

cortex_set_active_projectA

Switch active project (loads different .cortex DB). Blocked when process was started with --project (locked to single project).

Inputs: project_path (required).

cortex_set_roleA

Set the role for an agent. Roles control which tools the agent can call.

Inputs: agent_name (required), role (required).

cortex_tick_fileA

Mark a file as created/done in file tree. Saves checkpoint if file exists on disk.

Inputs: file_path (required), status, feature_id, test_id, +1 more.

cortex_update_featureC

Update feature status

Inputs: id (required), status (required).

cortex_update_testC

Pass or fail a test

Inputs: id (required), status (required), error_output.

cortex_write_dictionaryC

Write or update a dictionary entry

Inputs: key (required), short_summary, short, full_description, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.2/5.0

    Scored across 42 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: pipeline_* tools manage pipelines, role/agent tools manage permissions, add/update tools handle feature and test tracking. The main confusion is between cortex_health and cortex_auto_heal, which both check integrity and repair broken items, and cortex_check_reminders overlaps somewhat with both. The cortex_get_state vs cortex_get_detail distinction is clear.

    Naming Consistency4/5

    The set follows a consistent cortex_ prefix with verb_noun structure (add_feature, get_state, resolve_issue, pipeline_start). A few deviations exist: cortex_health is a bare noun instead of a verb_noun form, and cortex_tick_file uses the unusual 'tick' verb, but these are minor and decodable. Overall the pattern is predictable.

    Tool Count2/5

    42 tools is well beyond the 25+ threshold for 'too many' and requires a large surface area for an agent to internalize. The scope is broad (project state, features, tests, issues, knowledge base, skills, roles, pipelines, tokens, health), but much of it could be consolidated — e.g., pipeline alone takes 7 tools, and health/auto_heal/check_reminders could be unified. The count makes misselection more likely.

    Completeness3/5

    The core workflow is well covered: init → get_next_task → log_progress → tick_file → add/update tests → log/resolve issues, plus pipeline lifecycle has full start/pause/resume/cancel/plan/history coverage. However, there are notable gaps: no delete operations anywhere (no delete_feature, delete_test, delete_snippet, delete_issue), and no list/get_all tools — retrieval depends almost entirely on cortex_search or the compressed state. Read and removal paths are weak for a system that stores this much data.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • engram

      coinstax
      A
      license
      Not graded
      quality
      C
      maintenance
      Provides persistent project memory for AI coding agents, enabling context retention across sessions via event logging, briefing generation, and querying.
      MIT

    • Sugar

      Benjaminn581
      F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding agents to read and write persistent, local-first memory across sessions and projects, with semantic search, global guidelines, and optional autonomous task execution.
      -