Cortex

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.

Related MCP server: Awareness Local

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

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:

Requirements

• Python 3.11+

• uv (recommended) or pip

License

MIT