Cortex

Persistent shared memory for every AI agent, across every MCP client, from one local file.

The Problem

Every agent you run today has amnesia.

Claude Desktop forgets what Cursor found. Cursor does not know what Claude Code wrote yesterday. Each session starts from zero.

Cortex is the persistent nervous system that connects them all.

What is Cortex?

Cortex is a local-first MCP server that gives every AI agent a shared, semantically searchable memory layer.

• No cloud. No Docker. No API keys.
• One SQLite file at ~/.cortex/cortex.db — shared across all clients
• Every memory is origin-tagged: who wrote it, from which client, with which model
• Hybrid search: BM25 keyword + cosine semantic retrieval fused with RRF
• Built-in deduplication: exact hash + near-duplicate detection (cosine ≥ 0.95)
• Soft-delete and audit trail on every write and delete

Quick Start

uvx cortex-mcp

That's it. The server starts, creates ~/.cortex/cortex.db, and is ready to accept connections from any MCP client.

Client Configuration

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cortex": {
      "command": "uvx",
      "args": ["cortex-mcp"]
    }
  }
}

Claude Code

claude mcp add cortex -- uvx cortex-mcp

Cursor / Zed / Windsurf

{
  "mcpServers": {
    "cortex": {
      "command": "uvx",
      "args": ["cortex-mcp"]
    }
  }
}

Local Development

git clone https://github.com/yourusername/cortex-mcp
cd cortex-mcp
uv sync
uv run cortex-mcp

Point any MCP client at your local clone:

{
  "mcpServers": {
    "cortex": {
      "command": "uv",
      "args": ["--directory", "/path/to/cortex-mcp", "run", "cortex-mcp"]
    }
  }
}

Tools

| Tool | Description | | --- | --- | | remember_fact | Store a single atomic fact with automatic deduplication | | save_memory | Compact a full session into structured, searchable memories | | recall | Hybrid semantic + keyword search across all stored memories | | list_memories | Chronological listing with optional filters | | forget | Soft-delete a memory by ID (retained for audit) | | correct_memory | Replace an incorrect memory with a corrected version | | verify_memory | Explicitly mark a memory as verified | | get_agents | List all agents that have written memories | | get_stats | Operational health snapshot (counts, DB size, expiry) | | cortex_ping | Health check — verify the server is running |

How Memory Works

Session ends
    │
    ▼
save_memory / remember_fact
    │
    ├── Exact dedup (SHA-256 hash)
    ├── Near-dedup (cosine similarity ≥ 0.95)
    ├── Embed (BAAI/bge-small-en-v1.5, 384-dim)
    └── Write to SQLite + FTS5 index
                │
                ▼
            recall(query)
                │
                ├── FTS5 pre-filter (top 200 candidates)
                ├── BM25 keyword rank
                ├── Cosine semantic rank
                └── RRF fusion → top_k results

Configuration

All settings are environment variables with the CORTEX_ prefix:

| Variable | Default | Description | | --- | --- | --- | | CORTEX_DB_PATH | ~/.cortex/cortex.db | SQLite database path | | CORTEX_EMBED_MODEL | BAAI/bge-small-en-v1.5 | Sentence embedding model | | CORTEX_TOP_K_DEFAULT | 5 | Default recall result count | | CORTEX_DEDUP_THRESHOLD | 0.95 | Near-duplicate cosine threshold | | CORTEX_LOG_LEVEL | INFO | Log level (DEBUG/INFO/WARNING/ERROR) |

Requirements

• Python 3.11+
• uv (recommended) or pip

License

MIT