The
Manual.
Integrate universal memory into your AI agents using the Model Context Protocol (MCP).
Quickstart
Self-host (BYOK)
The local server is a stdio MCP server: your own Gemini key, memories in a local SQLite file, nothing phones home.
- Get a free Gemini key at aistudio.google.com/apikey.
- Add the config below to your MCP client (Claude Code:
~/.claude.jsonor.mcp.json; Cursor:~/.cursor/mcp.json; Claude Desktop:claude_desktop_config.json; VS Code:.vscode/mcp.json). - Restart the client. Six tools are now available:
memorize,recall,recall_about,recall_timeline,list_memories,forget.
{
"mcpServers": {
"cortex": {
"command": "uvx",
"args": ["--from", "cortex-protocol", "cortex-mcp"],
"env": { "GEMINI_API_KEY": "your-key-here" }
}
}
}Published on PyPI as cortex-protocol — note the --from flag above; a bare uvx cortex-mcp resolves to an unrelated package. To run from a checkout instead:
# Prefer the published package above. To run from a checkout instead:
python -m cortex.mcp.server
# ...or point your client's config at it directly:
{
"command": "uv",
"args": ["run", "--with", "fastmcp", "python", "-m", "cortex.mcp.server"]
}Hosted (multi-user)
The hosted server shares one memory across ChatGPT, Claude, Cursor, and Claude Code. Generate a Personal Access Token from your dashboard → Connections panel, then jump to Connect Clients below for the exact snippet per client.
Core Concepts
Memory kinds
Every memorize call classifies content into one of six kinds — preference, fact, project, instruction, event, relationship — so recall can reason about what a memory means, not just its text.
Hybrid retrieval + RRF
Dense Gemini embeddings and Okapi BM25 keyword search run side by side, fused with Reciprocal Rank Fusion. Deep top-k drives session-level retrieval recall@k ≈ 0.998 — that is, the session holding the gold evidence lands in the retrieved set.
Chain-of-Note reader (benchmark path)
Not on the product recall path — recall returns raw ranked memories and your agent does the reasoning. The benchmark harness ships a reference reader that first notes the relevant facts from retrieved memories, then answers only from those notes (Yu et al., 2023), abstaining when the memories genuinely lack the answer. It is what our published numbers are measured with, and a template for the reader prompt you write in your own agent.
Episodic memory
One cheap gemini-2.5-flash-lite call per memorize structures the event's time, actor, and location, powering recall_timeline. This is a write-time cost only — the recall path stays exactly one embed plus one hybrid retrieve, with no LLM on it. On by default on the hosted server.
Entity graph
At memorize time, the same cheap gemini-2.5-flash-lite call that does episodic extraction also extracts entities and relationships — no new per-write cost. Builds an ego knowledge graph rooted at a synthetic self entity, with typed nodes (person / place / org / project / thing) joined by labeled, directed relationships, each memory attached to the entity it's about. Powers recall_about and the dashboard's Connections view. Write-time cost only — the recall path is unchanged. On by default on the hosted server; opt out with CORTEX_GRAPH=0.
Anti-saturation
Write-time, embedding-only dedup bounds how fast the store grows. A contradiction soft-update supersedes stale facts so recall returns only the latest value. Available at the engine level, off by default.
Decades-scale retrieval
Self-host SQLite recall is O(n). The hosted PostgresStore pushes hybrid search into pgvector — HNSW dense search fused with full-text search via RRF — so a query visits roughly O(log n) nodes.
MCP Tools
Cortex is an MCP server. Your client connects over stdio (self-host) or streamable HTTP (hosted) and calls these tools directly — recall does no server-side LLM generation; it embeds your query once and returns raw memories for your agent to reason over. There is no server-side router: the tool descriptions below are what steer your connected agent to pick recall for a point lookup versus recall_about for an exhaustive dossier.
memorize(content, kind?, tags?)Save a durable memory. Optionally classify it into one of six kinds (preference, fact, project, instruction, event, relationship).
recall(query, limit?)Retrieve the most relevant memories — hybrid dense + BM25 search fused with Reciprocal Rank Fusion. No server-side LLM generation.
recall_about(entity, limit?)Exhaustive dossier for one entity — a person, place, project, org, thing, or yourself — every relationship (both directions) plus every attached memory. A pure keyed read, no LLM or embedding call. Answers 'tell me everything about X', which top-k recall structurally can't.
list_memories(limit?)List the most recently saved memories, newest first.
recall_timeline(since?, until?, limit?)Retrieve memories by when the underlying event happened, not when it was saved. Powered by episodic extraction, on by default on the hosted server.
forget(memory_id)Delete a memory. A short id prefix works if it's unambiguous.
Connecting Clients
Six ways to connect to the hosted server at {API_BASE}/mcp. Claude Code, Cursor, and Antigravity authenticate with a Bearer PAT (ctx_…) generated in your dashboard; ChatGPT and Claude.ai are added as a custom connector by URL and sign in via OAuth 2.1 (PKCE, auto-discovery).
# Terminal — add the hosted Cortex over streamable HTTP
claude mcp add --transport http cortex \
https://cortex-api-685740048714.us-central1.run.app/mcp \
--header "Authorization: Bearer ctx_YOUR_TOKEN"Generate or revoke a token anytime from your dashboard → Connections panel.
Security & Privacy
Self-hosted, Cortex is BYOK with zero phone-home: your Gemini key is read from the environment and used only to call Google's embedding API. The local server has no backend of its own and sends nothing anywhere else. Memory text lives unencrypted in a plain SQLite file — don't store secrets in it.
- Granular ControlCreate a unique PAT for each hosted client (Cursor, ChatGPT) and monitor access independently.
- Instant RevocationCompromised a token? Revoke it instantly from the dashboard to cut off all access.
Open Source
The engine, MCP server, and benchmark harness are open-source under Apache-2.0. The hosted control plane and this web dashboard are proprietary — see the open-core split. Run it yourself with uvx --from cortex-protocol cortex-mcp.