Cortex

<p align="center"> <img src="cortex.png" alt="Cortex" width="200" /> </p>

<h1 align="center">Cortex</h1>

<p align="center"> <strong>Persistent shared memory for every AI agent, across every MCP client, from one local file.</strong> </p>

<p align="center"> <img src="https://img.shields.io/badge/Python-3.11+-3776AB?logo=python&logoColor=white" alt="Python"> <img src="https://img.shields.io/badge/FastMCP-2.0+-blueviolet?logo=fastapi&logoColor=white" alt="FastMCP"> <img src="https://img.shields.io/badge/SQLite-FTS5%20%2B%20WAL-003B57?logo=sqlite&logoColor=white" alt="SQLite"> <img src="https://img.shields.io/badge/fastembed-BAAI%2Fbge--small-orange?logoColor=white" alt="fastembed"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e" alt="MIT License"></a> </p>

---

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