Cortex Protocol

🧠 One memory. Every agent. — user-owned, cross-agent AI memory over the Model Context Protocol.

Works with Claude Code · Cursor · Claude Desktop · VS Code

You own one portable memory, and any AI agent connects to it over MCP with your consent. Self-host it as a local stdio server — a single SQLite file, your own Gemini key (BYOK), nothing phones home — and recall does no server-side LLM generation, so the only runtime cost is your own embedding tokens.

📊 0.932 LongMemEval_S · 0.813 LoCoMo — #1 on accuracy-per-dollar — premium-tier retrieval quality paired with a cheap Gemini reader at ~$0.008/question, not raw accuracy at any cost.

Architecture

Two hot paths — memorize embeds once and persists; recall embeds once and runs a pure hybrid retrieval with no server-side generation. Three enrichment layers bolt on at write time only, so recall stays byte-identical whether they are on or off (grounded in docs/ARCHITECTURE.md).

flowchart TD
    subgraph WRITE["memorize(content) · write path"]
        direction TB
        A["content"] --> B["provider.embed (BYOK)"]
        B --> C[("SQLiteStore.add")]
        C -.->|"opt-in, write-time only"| D["L4 episodic · G2 graph · L5 anti-saturation"]
    end
    subgraph READ["recall(query) · read path — no server-side LLM"]
        direction TB
        E["query"] --> F["provider.embed (BYOK)"]
        F --> G["SQLiteStore.build_index"]
        G --> H["hybrid_retrieve: dense + BM25 → RRF"]
        H --> I["ranked raw memories → your agent reasons"]
    end
    C ==>|"persist"| G

Why Cortex

• User-owned, not company-owned. You decide which agents see your memory — versus incumbents where the business owns it. One memory, every agent.
• #1 on accuracy-per-dollar. Cortex targets the best accuracy per dollar, not raw accuracy at any cost: premium-tier retrieval quality with a cheap Gemini reader (~$0.008/question on LongMemEval_S), with $/question published.
• Run anywhere, no operator cost. Self-host is a single SQLite file — no Docker, no DB server. One config snippet wires it into any MCP client.

Results

📊 0.932 LongMemEval_S · 0.813 LoCoMo — #1 on accuracy-per-dollar. Two public long-term-memory benchmarks; positioning stated honestly — not raw SOTA, but #1 accuracy-per-dollar (a cheap Gemini reader at a fraction of the leaders' premium-reader cost).

How Cortex compares (LongMemEval_S)

_{Numbers from the verified leaderboard research. Not apples-to-apples: competitor scores are self-reported under their own judges; Cortex is graded by a gemini-3.5-flash judge (likely more lenient than the canonical gpt-4o-2024-08-06), and ~$/q is only published where Cortex measures it. ¹Mem0 has no verifiable LongMemEval_S number that survived verification — it reports LoCoMo (0.61–0.66) instead. Leaders use pricier readers.}

Judge disclosure (load-bearing). All Cortex numbers above are graded by an LLM judge = gemini-3.5-flash. The canonical LongMemEval judge is gpt-4o-2024-08-06; a Gemini judge is likely more lenient, so a GPT-4o re-grade (pending an OpenAI key) may lower these. As one cross-model sanity check, an independent Claude panel re-graded all 282 LoCoMo multi-hop cases and closely tracked the harness (panel 0.528 vs harness 0.589). The accuracy-per-dollar claim does not depend on the judge.

LongMemEval_S 0.932 — per question type: single-session-user 0.957, single-session-assistant 0.982, single-session-preference 0.900, knowledge-update 0.949, temporal-reasoning 0.925, multi-session 0.902, abstention 0.867 (mean ~25.7k input tokens/q). Under our judge, 0.932 sits above ByteRover (0.928, claimed) and Hindsight (0.914) and below only the premium-reader leader Mastra (0.949, gpt-5-mini) — while clearing Emergence (0.860), Supermemory (0.852), and Zep (0.712), all of which use pricier readers. (Competitor rows use their own judges — the leaderboard is not apples-to-apples; canonical judge is GPT-4o.)

LoCoMo 0.813 — per category: single-hop 0.864, multi-hop 0.695, temporal 0.857, open-domain 0.458, adversarial/abstention 0.836. This beats the graph-memory systems (Mem0 0.61–0.66, Zep 0.585–0.62) and is on par with the strong retrieval baseline EMem (0.78–0.84), behind only Cognis (~0.925, Claude-Opus reader + reranker). Doubling retrieval depth (k=50→100) is what recovers multi-hop (+10.6pt) — the LoCoMo frontier is retrieval depth, not reader capability.

Beyond a benchmark — does memory make an agent better?

bench/agent_uplift/ runs the same multi-session tasks three ways and grades them deterministically. Each answer depends on a fact stated in an earlier session, so an agent with no memory of it cannot succeed (9 scenarios, top_k=5, live Gemini):

Memory is the difference between 0% and 100%. Cortex matches full-context accuracy while feeding the agent only the relevant recalled memories — and unlike full-context, its cost stays bounded by top-k instead of growing with total history. On the secret-store scenario (one fact buried in 12 sessions), cortex feeds 5 recalled memories vs full-context's 12 (125 vs 212 input tokens, a 0.59 ratio); the gap widens with history length. That is the point: memory that holds accuracy at a cost that does not blow up over a long relationship.

Reproduce

# LongMemEval_S — 0.932 headline (full 500):
python -m cortex_bench.run --system cortex-v0 --variant s --limit 500 \
  --reader-model gemini-3.5-flash --top-k 50 --preference-mode --answer-first \
  --max-output-tokens 8192 --judge gemini --judge-votes 3

# LoCoMo — 0.813 (put locomo10.json in bench/data/ first):
python -m cortex_bench.run --system cortex-v0 --locomo --reader-model gemini-2.5-flash \
  --top-k 100 --answer-first --max-output-tokens 8192 --judge gemini

# agent uplift:
uv run python bench/agent_uplift/harness.py --provider gemini

Full methodology + per-type tables: bench/results/PHASE3_authoritative.md (LongMemEval) and bench/results/LOCOMO_results.md (LoCoMo); verified competitor leaderboard: bench/results/leaderboard_research.md.

Features

See docs/L6_Decades_Scale.md for the decades-scale retrieval analysis (self-host SQLite recall is O(n): measured ~95 ms @ 1k memories → ~7.7 s p50 @ 50k).

Quickstart — self-host (local memory in your agent)

The local server (cortex-mcp) is a stdio MCP server: your own Gemini key (BYOK), memories in a local SQLite file (~/.cortex/memory.db), nothing phones home.

1. Get a Gemini key (free): https://aistudio.google.com/apikey
2. Add Cortex to your MCP client. Every client uses the same mcpServers shape — only the file differs:

{
  "mcpServers": {
    "cortex": {
      "command": "uvx",
      "args": ["--from", "cortex-protocol", "cortex-mcp"],
      "env": { "GEMINI_API_KEY": "your-key-here" }
    }
  }
}

Restart the client. That exposes six tools (the last two are gated on opt-in memory layers — see Config (env) below):

From a checkout (before the package is on PyPI): python -m cortex.mcp.server, or in the client config use "command": "uv", "args": ["run", "--with", "fastmcp", "python", "-m", "cortex.mcp.server"].

Config (env): GEMINI_API_KEY / GOOGLE_API_KEY (required); optional CORTEX_DB_PATH, CORTEX_USER_ID, CORTEX_EMBED_MODEL, CORTEX_EMBED_DIM, CORTEX_TOP_K (default recall depth 5).

Opt-in memory layers (off by default). CORTEX_GRAPH=1 builds the entity graph and enables recall_about; CORTEX_EPISODIC=1 structures event time / actor / location and enables recall_timeline; CORTEX_EXTRACT_MODEL (default gemini-2.5-flash-lite) is the model that does that extraction. Enabling either adds one cheap flash-lite call per memorize (write-time only, on your own key — when both are on they share a single extraction call). recall stays byte-identical, so the accuracy-per-dollar guarantee is unchanged. See examples/ and .env.example.

Claude Desktop one-click: build the .mcpb bundle and drag it onto Desktop — it prompts for your Gemini key and runs the same six tools. See packaging/mcpb/.

Security & privacy

• BYOK, no phone-home. Your Gemini key is read from the environment and used only to call Google's API. The local server has no backend and sends nothing anywhere else.
• Your memory text is embedded by Google. Each memorize/recall sends the content/query to Google's embedding API under your own key — pick a key/project whose data-handling terms you're comfortable with.
• Local storage is a plain file. Memories live unencrypted in ~/.cortex/memory.db (CORTEX_DB_PATH). Don't store secrets; protect the file like any local data, and set CORTEX_DB_PATH only from trusted config (not from untrusted/agent input).

Develop

uv run pytest            # offline, deterministic test suite (FakeProvider — no live LLM calls)
uvx ruff check server    # lint

See CHANGELOG.md for release notes and bench/README.md for the benchmark harness.

License

Apache-2.0