<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

```bash
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`:

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

### Claude Code

```bash
claude mcp add cortex -- uvx cortex-mcp
```

### Cursor / Zed / Windsurf

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

---

## Local Development

```bash
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:

```json
{
  "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

```text
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](https://docs.astral.sh/uv/) (recommended) or pip

---

## License

MIT