Content
# Cortex
**The memory layer every AI agent will need.**
Local. The lowest cost ever. Working in your Claude today.
[](https://github.com/joetomryan/cortex/actions)
[](https://www.python.org/downloads/)
[](LICENSE)
[](#performance)
[](https://modelcontextprotocol.io/)
Cortex is the universal memory layer for AI agents. Drop the MCP server into Claude Desktop, Claude Code, Cursor, Codex, or Windsurf — your agent remembers across every session, every project, every conversation. **Zero API cost on the read path. All data on your machine. MIT licensed.** Today it runs locally on a laptop. The path forward is one open memory standard that every agent on every platform speaks.
---
## Why Cortex
Every other memory layer makes you choose: pay per query, or upload your conversations to someone else's cloud, or stay locked to one platform. Cortex picks none of those.
- **Cheapest memory ever, full stop.** $0 read cost (100% local). $0 write cost with `CORTEX_NO_ENRICH=1`. With optional Haiku enrichment: $0.0008/write — about 1/1000th of a hosted alternative for the same operation. There is no hosted equivalent for $0.
- **Yours, on your disk.** SQLite + sqlite-vec on the local filesystem. No API key required to write or read. No cloud. No vendor. No silent model drift on a remote server. Take the file with you.
- **Works in your Claude today.** Drop-in MCP server. 14 tools (`memory_write`, `memory_search`, `memory_recall`, `memory_get_context`, `memory_get_entity`, `memory_get_timeline`, `memory_diff`, `memory_consolidate`, +6 more). Same server serves Claude Desktop, Claude Code, Cursor, Codex CLI, Windsurf — anything MCP-capable.
- **Architecturally complete, not a vector-DB wrapper.** Typed-link graph (similarity / temporal / entity / supersedes / causal). Structured SPO facts with `valid_from`/`valid_to` and confidence decay. Auto-grouped episodes. 8-step self-maintaining consolidation. spaCy NER + Jaro-Winkler entity resolution. BGE cross-encoder reranking with abstention signaling.
- **Open. Reproducible. Forkable.** MIT licensed. Every benchmark JSON we've ever produced is checked into [`docs/benchmark-history/`](docs/benchmark-history/). Run our 77.45% LongMemEval score yourself in ~30 minutes.
---
## How Cortex compares to what's out there
| | **Cortex** | Mem0 | Supermemory | OpenAI Memory |
|---|---|---|---|---|
| Cost per read | **$0** | Hosted, paid | Hosted, paid | Bundled w/ ChatGPT |
| Cost per write (no enrichment) | **$0** | API call | API call | N/A |
| Your data lives on | **Your disk** | Mem0 cloud | Cloudflare + Postgres | OpenAI servers |
| Works with Claude (any client) | **Yes (MCP)** | Limited | Hosted MCP | No |
| Switch agents without losing memory | **Yes** | If you stay on Mem0 | If you stay on Supermemory | No |
| License | **MIT** | Apache 2.0 lib, hosted prod | Closed engine | Closed |
| LongMemEval (independently verifiable) | **77.45%** | 93.4% claimed, not reproducible | 81.6–85.2% | N/A |
| Source code you can audit | **All of it** | Library only, not the prod engine | Wrappers only | None |
The pitch isn't *"we score highest."* The pitch is *"every other choice forces you to give up your data, your money, or your platform freedom. We don't."*
---
## How it works
```mermaid
flowchart TB
A["Claude · Cursor · Codex · Windsurf · any MCP agent"] -->|stdio| S[Cortex MCP Server<br/>14 tools]
S --> R["Hybrid Retrieval<br/>(96.3% recall)"]
S --> W[Write Pipeline]
S --> C[8-step Consolidation]
R --> V[sqlite-vec<br/>cosine kNN]
R --> F[FTS5<br/>BM25]
R --> G["Entity graph<br/>1-hop expansion"]
V --> RRF["RRF fusion<br/>+ rerank<br/>+ abstention"]
F --> RRF
G --> RRF
W --> E[BGE-small embed]
W --> N[spaCy NER + resolve]
W --> H["Haiku enrich<br/>(optional, $0.0008)"]
E --> DB
N --> DB
H --> DB
C --> DB[("Local SQLite +<br/>sqlite-vec + FTS5")]
```
A single SQLite file is your entire memory. Take it across machines, version-control it, back it up, throw it away. Your agent remembers what matters; you control everything.
---
## Performance
| Operation | Latency p95 | Cost |
|---|---|---|
| Write | ~15ms | $0.0008 (or **$0** with `CORTEX_NO_ENRICH=1`) |
| Search (rerank=True) | ~270ms | **$0** |
| Search (rerank=False, fast path) | **~11ms** | **$0** |
| Context assembly | ~500ms | **$0** |
Verified on the LongMemEval 102-instance stratified sample:
| Category | Score |
|---|---|
| Single-session-user | 16/17 (94%) |
| Single-session-assistant | 17/17 (100%) |
| Single-session-preference | 13/17 (76%) |
| Multi-session | 9/17 (53%) |
| Temporal-reasoning | 10/17 (59%) |
| Knowledge-update | 14/17 (82%) |
| **Overall** | **79/102 (77.45%)** |
96.3% retrieval recall — the right memory is in the top-K every time. Detailed methodology, every benchmark run, every regression analysis: [`docs/CORTEX_PROJECT_OVERVIEW.md`](docs/CORTEX_PROJECT_OVERVIEW.md).
---
## Use it in 2 minutes
```bash
git clone https://github.com/joetomryan/cortex && cd cortex
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e .[dev]
python -m spacy download en_core_web_sm
python -c "from cortex.db import init_db; init_db()"
```
Then add this to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"cortex": {
"command": "/abs/path/to/cortex/.venv/bin/python",
"args": ["/abs/path/to/cortex/server.py"]
}
}
}
```
Restart Claude Desktop. Tell it something. Open a new session tomorrow and ask about it. It remembers.
For Claude Code: `claude mcp add cortex /abs/path/to/.venv/bin/python /abs/path/to/server.py`. For Cursor / Codex / Windsurf: see [`scripts/install_claude_code.sh`](scripts/install_claude_code.sh) — it prints the exact config snippet for each.
---
## What's inside
```
cortex/ ← the package — 17 modules, 4,390 LOC, 215 tests
db.py ← SQLite + sqlite-vec + FTS5 + WAL + online backup
embeddings.py ← BGE-small-en-v1.5 (384-dim) singleton + LRU cache
reranker.py ← BGE-reranker-base cross-encoder
search.py ← hybrid search, RRF fusion, abstention, query cache
write.py ← embed → entity-resolve → enrich → link → episode
update.py ← amend / supersede / expire
context.py ← assemble within a token budget
consolidation.py ← 8-step self-maintenance, rate-limited Haiku
entities.py ← spaCy NER + Jaro-Winkler resolution + dossier
facts.py ← SPO triples with valid_from/to + decay
links.py ← typed graph: similarity / temporal / entity / supersedes / causal
episodes.py ← time-gap + source heuristic grouping
classification.py ← rule-based memory-type classifier (zero API)
enrichment.py ← unified Haiku call (facts + observations + contradictions)
decomposition.py ← multi-part query splitting
router.py ← rule-based query intent classifier
schema.sql ← package data, loaded via importlib.resources
server.py ← MCP entry point (stdio + HTTP)
docs/
CORTEX_PROJECT_OVERVIEW.md ← architecture, history, every accuracy attempt
ITERATION_LOG.md ← every benchmark run with prediction vs actual
benchmark-history/ ← 93 raw benchmark JSONs (~15 MB archive)
archive/ ← historical experiment writeups
```
---
## Where this is going
Cortex today is the cheapest, most-local way to give Claude persistent memory. The path is to be **the** memory layer — the one every AI agent on every platform speaks to, the way every web app speaks HTTP.
- **Connectors first.** Gmail, Roam, iMessage, Slack, LinkedIn, Telegram, calendar — pull your real data into one local memory store, not a dozen platform silos. The local DB grows; your agent's understanding compounds.
- **Cross-agent memory.** Same SQLite file, served simultaneously to Claude Desktop + Cursor + Codex CLI. Your context follows you wherever you work.
- **Optional cloud sync** — Litestream → S3 → Turso. Multi-device without giving up local-first. Encrypted at rest.
- **Open standard for memory operations.** Memory tools are stable across MCP-capable agents already. Push toward a stable schema others can implement against, so memory becomes portable infrastructure rather than vendor lock-in.
Not on the roadmap: chasing benchmark numbers we can't reproduce. The full reasoning is in [`docs/CORTEX_PROJECT_OVERVIEW.md`](docs/CORTEX_PROJECT_OVERVIEW.md).
---
## Citation
```bibtex
@software{cortex2026,
title = {Cortex: a local-first universal memory layer for AI agents},
author = {Ryan, Tom},
year = {2026},
url = {https://github.com/joetomryan/cortex}
}
```
## License
MIT — see [LICENSE](LICENSE).
---
## Further reading
- [`docs/CORTEX_PROJECT_OVERVIEW.md`](docs/CORTEX_PROJECT_OVERVIEW.md) — architecture, project path, every accuracy attempt + result
- [`docs/ITERATION_LOG.md`](docs/ITERATION_LOG.md) — every benchmark run logged with prediction vs actual
- [`scripts/install_claude_code.sh`](scripts/install_claude_code.sh) — one-command installer that prints config snippets for every MCP-capable agent
