Cortex Memory Engine

Cortex

[🧠 Try Cortex in your browser](https://gambletan.github.io/cortex/) — zero install, 124KB WASM, runs entirely client-side.

If Cortex helps your AI remember, [give it a ⭐](https://github.com/gambletan/cortex/stargazers) — it takes 1 second and helps others discover the project.

中文 | 日本語 | 한국어

Local memory for personal AI agents.

_Private. Free. Local. — a memory engine for personal AI agents._

Your AI's memory archive lives on your device. Pure Rust. 3.8MB binary. The local engine needs no hosted service and collects zero telemetry. Optional encrypted sync uses your own cloud storage; optional Muse sharing sends only the excerpts you approve to Cortex Cloud and Meta. (On-device semantic search downloads a ~30MB model once on first use, then runs fully offline — or go 100% offline with CORTEX_NO_EMBEDDINGS=1. See Security & Privacy.)

What you get

• 🔒 Private by default — memories live in a local SQLite file; sync and Muse sharing require explicit opt-in. Zero telemetry (CI-enforced).
• 🧠 Real memory, not a text file — 4 tiers, multi-signal retrieval, self-correcting Bayesian beliefs, a cross-channel people graph.
• ⚡ Sub-millisecond — 156µs ingest, 568µs search. ~528× faster than cloud memory APIs, with no network round-trip.
• 🔌 Drop-in for any agent — one MCP server gives Claude Code / Claude Desktop (or any MCP client) persistent cross-session memory.
• 🤝 Connect Meta Muse to chosen excerpts — your archive stays local. The optional service at https://cortex.alvinsclub.ai serves only your approved export, with daily disclosure limits and revocation. The server and Meta can read shared excerpts. Setup and privacy limits →
• ☁️ Yours across devices — optional end-to-end-encrypted sync through *your own* iCloud / Drive / Dropbox; this sync needs no Cortex server.

See it remember across sessions — ~30 seconds:

brew install gambletan/tap/cortex-mcp-server          # or: cargo build --release -p cortex-mcp-server

claude mcp add cortex-memory -- cortex-mcp-server ~/.cortex/memory.db

Tell Claude *"remember I deploy on Fly.io and always run tests before pushing."* Open a brand-new session and ask *"how do I deploy this project?"* — it answers from memory, 100% on your machine.

⭐ If that's useful, [give it a star](https://github.com/gambletan/cortex/stargazers) — it helps others find a memory engine that respects their privacy.

---

LLMs start blank every session — they forget your name, your preferences, yesterday's conversation, last week's decision. The usual fixes are flat text files (no ranking, no decay), keyword grep, or cloud APIs that add 200–500ms, charge you, and ship your personal data to someone else's server. Cortex gives your AI structured, self-evolving long-term memory that persists across sessions and channels — all local, all yours. Your memories are not a cloud provider's training data, a startup's monetization asset, or a surveillance target.

Cortex vs Mem0 vs OpenAI Memory

Performance Benchmarks

528x faster than Mem0 cloud. With features neither Mem0 nor OpenAI Memory offer.

Note: Benchmarks include proactive inference (auto-extracting facts, preferences, relationships) on every ingest. Raw ingest without inference is ~15µs. Numbers from cargo bench on M-series Mac.

LoCoMo Benchmark (ACL 2024)

Academic-grade long-term conversation memory evaluation — 10 conversations, 1540 QA pairs across 4 categories.

Key findings:

• Open-domain 88.8% — leads Mem0 (72.9%) by +15.9%
• Temporal 74.1% — leads Mem0 (55.5%) by +18.6%
• Single-hop 72.5% — leads Mem0 (67.1%) by +5.4%
• Multi-hop 59.5% — leads Mem0 (51.2%) by +8.3%
• Overall 73.7% — beats Mem0 (66.9%) by +6.8%, beats OpenAI Memory (52.9%) by +20.8%

Cortex outperforms Mem0 on all 4 categories — while running 100% locally, end-to-end encrypted, at $0 cost.

Setup: Claude Sonnet 4 (QA + judge), nomic-embed-text (embeddings via Ollama), top-30 retrieval. Reproducible with that setup: python3 bench/locomo_bench.py (needs ANTHROPIC_API_KEY + a local Ollama with nomic-embed-text). Numbers measured on the v1.7 engine; the v2.2 retrieval beam fix (paraphrase recall 40%→90% at 5K, see docs/scale-test-2026-06-13.md) has not yet been re-run on LoCoMo, so these are reported as the last verified figures, not a v2.2 claim.

Architecture

Cortex implements a 4-tier memory model inspired by human cognition:

                    +---------------------+

| Working Memory | Current session context +---------------------+ | +---------------------+ | Episodic Memory | Raw experiences: conversations, events, observations +---------------------+ | consolidation (decay, promotion, pattern extraction) +---------------------+ | Semantic Memory | Distilled facts, preferences, relationships +---------------------+ | +---------------------+ | Procedural Memory | Learned routines, user-specific workflows +---------------------+

Working holds the current session scratch pad. Episodic stores raw experiences with timestamps and source metadata. The Consolidation Engine periodically promotes recurring patterns into Semantic facts and decays stale episodes. Procedural captures learned workflows and routines.

Bot integration architecture

For a hosted Bot with existing PostgreSQL memory and account permissions, Cortex is an optional derived retrieval backend behind its MemoryManager. PostgreSQL remains the authority for confirmed values, scope, provenance, revisions and withdrawal; ContextProjector remains the single model-context composer, and Workflow keeps execution and approvals. Search hits must pass current authoritative validation before entering model context. A controlled projection store must not import personal archives or enable sync, automatic inference or consolidation by default.

The controlled API contract documents the implemented ControlledStore Python interface, snapshot/replay lifecycle and error codes. The implementation plan separates Cortex-side acceptance from host-owned PostgreSQL and Bot integration. Package publication and Bot deployment are separate steps; existing personal-agent interfaces remain available.

Key Components

People Graph

Cross-channel identity resolution. The same person messaging you on Telegram, emailing you, and showing up in calendar events gets unified into a single identity node. Interactions, relationship strength, and communication patterns are tracked per-person.

Bayesian Belief System

Self-correcting understanding of the world. Beliefs are formed from evidence, updated with each new observation, and can be contradicted. Confidence scores reflect actual certainty rather than recency bias.

cortex.observe_belief("user_prefers_morning_meetings", true, 0.8)?;

cortex.observe_belief("user_prefers_morning_meetings", false, 0.6)?; // Confidence adjusts automatically via Bayesian update

Consolidation Engine

Episodic-to-semantic promotion, decay of stale memories, and pattern extraction. Runs as a background cycle that keeps the memory store lean and queryable. Returns a report of what was promoted, decayed, and merged.

Multi-signal Retrieval

Queries combine five signals for relevance ranking:

• Similarity -- vector cosine distance against query embedding
• Temporal -- recency weighting with configurable decay
• Salience -- importance scoring from access patterns and explicit hints
• Social -- boost for memories involving specific people
• Channel -- filter or boost by source channel

Context Injection Protocol

Generates LLM-ready context strings from memory state. Pass a token budget, optional channel/person filters, and get back a structured text block your LLM can consume directly.

Storage

SQLite for persistence, in-memory vector index for fast similarity search. Single-file database, no external services required. Designed for edge deployment -- runs on a laptop, a R