Cortex MCP — Persistent AI Memory

Give your AI coding assistant a brain that remembers across sessions.

Cortex is an MCP (Model Context Protocol) server that provides persistent, intelligent memory to any AI coding assistant — Cursor, Claude Code, Windsurf, Cline, or any MCP-compatible tool.

What's New in v1.2

• 3-5x faster force_recall — Brain layers 6-12 now run in parallel (was 15-19s, now 3-5s)
• Result caching — Repeated force_recall calls return instantly (30s TTL)
• 7 SQL queries → 1 — Context builder consolidated for faster startup
• 17 fixes across performance, robustness, and code quality
• Shared tag utility — Cleaner codebase, single source of truth for tag extraction

See CHANGELOG.md for full details.

The Problem

Every time you start a new conversation, your AI assistant forgets everything:

• Coding conventions you already explained
• Bugs you already fixed
• Decisions you already made
• What files you were working on

Cortex solves this. It stores, ranks, and proactively recalls context so your AI never starts from zero.

Quick Start

Option 1: npm install (recommended)

npm install -g cortex-mcp

Then add to your MCP config:

{
  "mcpServers": {
    "cortex": {
      "command": "cortex-mcp",
      "transportType": "stdio"
    }
  }
}

Option 2: Clone from source

git clone https://github.com/jaswanthkumarj1234-beep/cortex-mcp.git
cd cognitive-memory
npm install
npm run build

Then add to your MCP config:

{
  "mcpServers": {
    "cortex": {
      "command": "node",
      "args": ["<path-to>/cognitive-memory/dist/mcp-stdio.js"],
      "transportType": "stdio"
    }
  }
}

Restart your IDE and Cortex is active.

Option 3: Direct Download (Binaries)

No Node.js required. Download from the latest release:

• Windows
• macOS
• Linux

Then configure your MCP client to run the executable directly.

Try the Demo

See Cortex in action without any AI client:

npm run demo          # Interactive demo — store, search, dedup
npm run benchmark     # Performance benchmark — write, read, FTS ops/sec

IDE-Specific Setup Guides

Step-by-step instructions for your IDE: Cursor · Claude Code · Windsurf · Cline · Copilot

Recipes & Use Cases

10 practical examples: docs/recipes.md — conventions, bug tracking, anti-hallucination, team onboarding, and more.

Features

Why Cortex?

16 MCP Tools

12+ Layer Brain Pipeline

Every conversation starts with force_recall, which runs 12+ layers (layers 6-12 run in parallel for speed):

Cognitive Features

• Confidence decay — old unused memories fade, frequently accessed ones strengthen
• Attention ranking — debugging context boosts bug-fix memories, coding boosts conventions
• Contradiction detection — new memories automatically supersede conflicting old ones
• Memory consolidation — similar memories merge into higher-level insights
• Cross-session threading — related sessions link by topic overlap
• Learning rate — topics corrected 3+ times get CRITICAL priority

Performance & Reliability

• force_recall latency: ~3-5s first call, instant on cache hit (v1.2 — was 15-19s)
• recall_memory latency: <1ms average (local SQLite + WAL)
• Throughput: 1800+ ops/sec (verified via Soak Test)
• Stability: Zero memory leaks over sustained operation
• Protocol: Full JSON-RPC 2.0 compliance (passed E2E suite)
• CI: Tested on Node 18, 20, 22 with lint + build + E2E on every push

Anti-Hallucination

• Deep export map scans every source file for all exported functions, classes, types
• When AI references a function that doesn't exist, verify_code suggests the closest real match
• Architecture graph shows actual project layers and dependencies

Optional: LLM Enhancement

Cortex works fully without any API key. Optionally, add an LLM key for smarter memory extraction:

# Option 1: OpenAI
set OPENAI_API_KEY=sk-your-key

# Option 2: Anthropic
set ANTHROPIC_API_KEY=sk-ant-your-key

# Option 3: Local (Ollama, free)
set CORTEX_LLM_KEY=ollama
set CORTEX_LLM_BASE_URL=http://localhost:11434

Memory Types

Architecture

src/
├── server/          # MCP handler (12+ layer brain pipeline) + dashboard
├── memory/          # 17 cognitive modules (decay, attention, anticipation, etc.)
├── scanners/        # Project scanner, code verifier, export map, architecture graph
├── db/              # SQLite storage, event log
├── security/        # Rate limiter, encryption
├── hooks/           # Git capture
├── config/          # Configuration
└── cli/             # Setup wizard

Pricing & Features

Cortex is open core. The basic version is free forever. To unlock deep cognitive features, upgrade to PRO.

Launch Edition: All features are currently free. Get started now and lock in lifetime access.

Activate PRO

1. Get a license key from your Cortex AI Dashboard
2. Set it in your environment:

   # Option A: Environment variable
   export CORTEX_LICENSE_KEY=CORTEX-XXXX-XXXX-XXXX-XXXX
   
   # Option B: License file
   echo CORTEX-XXXX-XXXX-XXXX-XXXX > ~/.cortex/license
   

3. Restart your IDE / MCP server.

Architecture

graph TB
    AI["AI Client (Cursor, Claude, etc.)"]
    MCP["MCP Server (stdio)"]
    ML["Memory Layer"]
    DB["SQLite Database"]
    SEC["Security Layer"]
    API["License API"]

    AI -->|"JSON-RPC via stdio"| MCP
    MCP --> ML
    ML --> DB
    MCP --> SEC
    SEC -->|"verify license"| API

    subgraph "Memory Layer"
        ML --> EMB["Embedding Manager"]
        ML --> AL["Auto-Learner"]
        ML --> QG["Quality Gates"]
        ML --> TD["Temporal Decay"]
    end

    subgraph "Retrieval"
        ML --> HR["Hybrid Retriever"]
        HR --> VS["Vector Search"]
        HR --> FTS["Full-Text Search"]
        HR --> RR["Recency Ranker"]
    end

FAQ / Troubleshooting

Contributing

See CONTRIBUTING.md for development setup, coding conventions, and the PR process.

License

MIT