Cortex Memory Engine

Cortex

[GitHub stars] [License: MIT]

🧠 Try Cortex in your browser — zero install, 124KB WASM, runs entirely client-side.

If Cortex helps your AI remember, give it a ⭐ — 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.)

[Cortex remembering across sessions — a real, local cortex-mcp-server recording]

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-serverclaude 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 — 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 Raspberry Pi, or a server.

Cloud Sync

Sync memories across devices through your own cloud storage — no third-party server involved.

Device A (Mac)              Your Cloud Storage              Device B (iPhone)┌──────────┐         ┌──────────────────────┐         ┌──────────┐│ SQLite DB │ ──W──>  │ iCloud / GDrive /    │  <──R── │ SQLite DB││ (local)   │         │ OneDrive / Dropbox   │         │ (local)  ││           │ <──R──  │                      │  ──W──> │          │└──────────┘         └──────────────────────┘         └──────────┘

• Changelog-based: Each device writes append-only operation logs to its own subfolder
• No conflicts: Devices never write to the same file. Merge uses Last-Writer-Wins with Hybrid Logical Clocks
• Encrypted: AES-256-GCM encryption (opt-in). Even if your cloud account is compromised, memories stay private
• Tamper-evident: the sync manifest and every operation carry an HMAC; tampered or plaintext-injected oplog lines are rejected, and a manifest without integrity protection refuses to load (no key-rollback path)
• Key rotation & forward secrecy: rotate to a new key version (ENC2 envelopes) without re-encrypting history; old versions stay readable, new writes are unreadable to a leaked old key
• Privacy-aware, per-memory opt-in: Private memories (the default) never leave your device. Mark a memory shared to sync it; demote it back to private and a retraction deletes it from your other devices (local copy kept)
• Survives restarts: sync settings persist in the database (passphrase never touches disk — macOS login Keychain or CORTEX_SYNC_PASSPHRASE); the server resumes sync and starts background pull (30s poll + fs watcher) automatically

Supported providers: iCloud Drive, Google Drive, OneDrive, Dropbox (auto-detected).

use cortex_core::sync::SyncConfig;use cortex_core::types::PrivacyLevel;
// Enable sync with encryption (settings persist; passphrase goes to the OS keychain)let config = SyncConfig::new(sync_dir, device_id, device_name)    .with_encryption("my-strong-passphrase");cortex.enable_sync(config)?;
// Opt a memory into sync — everything is Private unless you say otherwisecortex.set_memory_privacy(mem_id, PrivacyLevel::Shared { scope: "all".into() })?;
// Pull changes from other devices (also happens automatically in the background)let applied = cortex.sync_pull()?;println!("Applied {} remote changes", applied);

Security & Privacy

See SECURITY.md for the full threat model.

Prerequisites

Install the Rust toolchain (provides cargo):

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

After installation, either restart your terminal or run:

source "$HOME/.cargo/env"

Verify:

cargo --version

Real-World Example: A Personal AI That Actually Remembers

Imagine your AI assistant across a week of real conversations:

# Day 1 — You chat on TelegramYou: "Sarah works at Stripe. She's interested in our API."
  Cortex auto-extracts:  ├── episodic memory stored (156µs)  ├── fact: Sarah → works_at → Stripe (confidence: 0.70)  └── person resolved: sarah_telegram
# Day 2 — Sarah emails youFrom: [email protected]"Here's the technical spec we discussed."
  Cortex:  ├── person resolved: [email protected] → merged with sarah_telegram  │   (same person, different channel — automatic identity resolution)  └── fact: Sarah → sent → technical spec
# Day 3 — You ask your AIYou: "What's the status with Stripe?"
  Cortex retrieves (568µs):  ├── Sarah works at Stripe (semantic fact)  ├── Meeting went well, interested in API (episodic, Day 1)  ├── She sent technical spec (episodic, Day 2)  └── Cross-channel context: Telegram + Email unified under one person
  Your AI responds with full context — no "sorry, I don't remember" 🎯
# Day 5 — New information arrivesYou: "Sarah now works at Anthropic."
  Cortex:  ├── contradiction detected: Sarah works_at Stripe vs Sarah works_at Anthropic  ├── old fact superseded + decayed: Stripe (salience ×0.3, kept as history)  ├── new fact stored: Sarah → works_at → Anthropic  └── current employer now ranks first; self-correcting, no manual cleanup
  (Third-party relations are extracted from natural-language verbs —   "works at / works for / joined / now works at", "runs on", "hosted in",   "manages", "part of", … — between two proper-noun entities.)
# Day 7 — Consolidation runs  Cortex auto-consolidation:  ├── 3 episodic memories about Sarah → promoted to semantic summary  ├── stale memories from other topics → decayed  └── pattern detected: you have recurring Monday meetings

All of this happens locally in <1ms per operation. No cloud. No API calls. No one else sees your data.

Install

Homebrew (macOS / Linux)

brew tap gambletan/tapbrew install cortex-mcp-server

From source

cargo build --release -p cortex-mcp-servercp target/release/cortex-mcp-server ~/.local/bin/

Official packages (avoid look-alikes)

Cortex is published under the cortex-ai-memory name. Several similarly-named packages on npm/PyPI are not affiliated with this project — use exactly these:

⚠️ Not us: npm cortex-mcp, npm cortex-ai-memory (unscoped), PyPI cortex-memory. The source of truth is always this repo — github.com/gambletan/cortex. When in doubt, the binary from Releases is the canonical install.

Quick Start

use cortex_core::Cortex;
// Open (or create) a memory databaselet cortex = Cortex::open("memory.db")?;
// Ingest a memory from a Telegram conversationlet embedding = your_embedding_fn("Met with Alice about the Q3 roadmap");cortex.ingest(    "Met with Alice about the Q3 roadmap",    "telegram",               // source channel    Some("alice_123"),         // user ID (triggers identity resolution)    Some(0.8),                 // salience hint    Some(embedding),           // vector embedding)?;
// Add a semantic fact directlycortex.add_fact(    "Alice", "works_at", "Acme Corp",    0.95, "telegram", None,)?;
// Store a preferencecortex.add_preference("timezone", "America/Los_Angeles", 0.9)?;
// Retrieve relevant memorieslet results = cortex.retrieve(    "What do I know about Alice?",    5,                         // top-k    None,                      // any channel    None,                      // any person    Some(query_embedding),     // vector for similarity search)?;
// Generate LLM-ready context (token-budgeted)let context = cortex.get_context(    2000,                      // max tokens    Some("telegram"),          // channel filter    None,                      // no person filter)?;// Pass `context` as system/user message prefix to your LLM
// Run consolidation (call periodically)let report = cortex.run_consolidation()?;println!("Promoted: {}, Decayed: {}", report.promoted, report.decayed);

Python Bindings

Native module built with PyO3, published on PyPI as cortex-ai-memory (pip install cortex-ai-memory):

from cortex import Cortex
cx = Cortex.open("memory.db")cx.ingest("Had lunch with Bob at the Thai place", channel="imessage", user_id="bob")results = cx.retrieve("Where does Bob like to eat?", limit=5)

Integration with unified-channel-hub

Cortex is designed as the memory layer for unified-channel-hub. Messages flow in from any channel adapter, Cortex ingests and indexes them, and the context injection protocol feeds relevant memory back to your LLM before each response.

Telegram ─┐                          ┌─ ContextDiscord  ─┤  unified-channel-hub  →  │  Cortex  →  LLMEmail    ─┤  (ingest)                 │  (retrieve + inject)Calendar ─┘                          └─ Response

Integration with LangGraph

Add persistent memory to any LangGraph agent via langchain-mcp-adapters — no custom code needed.

from langchain_mcp_adapters.client import MultiServerMCPClientfrom langgraph.prebuilt import create_react_agentfrom langchain_openai import ChatOpenAI
model = ChatOpenAI(model="gpt-4o")
async with MultiServerMCPClient({    "cortex": {        "command": "cortex-mcp-server",        "args": ["~/.cortex/memory.db"]    }}) as client:    agent = create_react_agent(model, client.get_tools())    # Agent now has all 30 Cortex memory tools    result = await agent.ainvoke({        "messages": [{"role": "user", "content": "What do you remember about Alice?"}]    })

Your LangGraph agent gets instant access to memory_search, memory_ingest, fact_add, belief_observe, person_resolve, and 25 more tools — all running locally.

Integration with DeerFlow (ByteDance)

Cortex works as a persistent memory layer for DeerFlow — ByteDance's open-source multi-agent orchestration platform. Zero code changes needed.

# Add to DeerFlow config.yamlmcp_servers:  cortex-memory:    command: cortex-mcp-server    args:      - ~/.cortex/deerflow.db

All DeerFlow agents (Telegram, Slack, Feishu) get instant access to 30 memory tools — cross-session memory, fact storage, people graph, and belief tracking across all channels.

CLI

Cortex doubles as a standalone CLI tool — no MCP client required.

$ cortex-mcp-server --helpCortex memory engine — MCP server & CLI tools
Usage: cortex-mcp-server [DB_PATH] [COMMAND]
Commands:  ingest  Store a new memory  search  Search memories  stats   Show memory statistics  sync    Show cloud sync status and detected providers  export  Export all data as JSON  import  Import data from JSON file  info    Show version, DB path, and capabilities  digest  Show weekly memory digest  gateway Muse gateway: share an explicit slice of memory with Meta Muse over remote MCP  help    Print this message or the help of the given subcommand(s)
Arguments:  [DB_PATH]  Path to the Cortex database file (default: ~/.cortex/memory.db)
Options:  -h, --help     Print help  -V, --version  Print version

Examples:

# Store a memorycortex-mcp-server ~/.cortex/memory.db ingest "Met with Alice about Q3 roadmap"cortex-mcp-server ~/.cortex/memory.db ingest -c telegram "Sarah now works at Anthropic"
# Searchcortex-mcp-server ~/.cortex/memory.db search "Alice"cortex-mcp-server ~/.cortex/memory.db search -l 10 "Q3 roadmap"
# Statscortex-mcp-server ~/.cortex/memory.db stats
# Cloud synccortex-mcp-server ~/.cortex/memory.db sync                        # statuscortex-mcp-server ~/.cortex/memory.db sync enable                  # auto-detect providercortex-mcp-server ~/.cortex/memory.db sync enable -p icloud        # specific providercortex-mcp-server ~/.cortex/memory.db sync pull                    # pull remote changes
# Export / Import (backup & restore)cortex-mcp-server ~/.cortex/memory.db export -o backup.jsoncortex-mcp-server ~/.cortex/new.db import backup.json
# Version & capabilitiescortex-mcp-server ~/.cortex/memory.db info
# Meta Muse gateway (see docs/muse.md)cortex-mcp-server gateway allow "I prefer aisle seats"   # export one memory to Musecortex-mcp-server gateway preview "booking a flight"      # exactly what Muse would getcortex-mcp-server gateway serve --oauth --public-url https://<you>.ts.net   # Muse signs in with OAuthcortex-mcp-server gateway connect K7QM-2XDF               # approve a sign-in, on your computer onlycortex-mcp-server gateway off                             # kill switch

No subcommand = MCP stdio mode (for Claude Code / Claude Desktop integration).

MCP Server (Claude Code / Claude Desktop)

Cortex ships as an MCP server — works with any MCP-compatible client.

Setup

1. Build & install the binary:

mkdir -p ~/.local/bin ~/.cortexcargo build --release -p cortex-mcp-servercp target/release/cortex-mcp-server ~/.local/bin/

2. Register as MCP server:

Claude Code (CLI):

# Global (all projects)claude mcp add cortex --scope user -- ~/.local/bin/cortex-mcp-server ~/.cortex/memory.db
# Or per-projectclaude mcp add cortex -- ~/.local/bin/cortex-mcp-server ~/.cortex/memory.db

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{  "mcpServers": {    "cortex": {      "command": "/Users/you/.local/bin/cortex-mcp-server",      "args": ["/Users/you/.cortex/memory.db"]    }  }}

3. Allow tools in "don't ask" mode:

Add to ~/.claude/settings.json → permissions.allow:

"mcp__cortex__*"

Note: MCP tool permissions do not support parentheses format (e.g. mcp__cortex__memory_ingest(*)). Use the wildcard mcp__cortex__* instead.

4. Make it automatic — add to your CLAUDE.md (project or global ~/.claude/CLAUDE.md):

# Memory (Cortex)You have persistent memory via Cortex MCP tools. Use them automatically:- Start of conversation: call `memory_context` to load what you know about the user- When the user shares a preference, fact, or personal info: call `memory_ingest` to store it- When you learn a structured fact: call `fact_add` (e.g. "User works_at Google")- When you detect a preference: call `preference_set` (e.g. editor=neovim)- When evidence supports or contradicts a belief: call `belief_observe`- When talking to someone new: call `person_resolve` to track identity- Periodically: call `memory_consolidate` to clean up stale memories

5. Auto-inject memory on session start (Claude Code hooks — fully automatic):

Create ~/.claude/hooks/cortex-memory-inject.sh:

#!/bin/bashCORTEX_BIN="${CORTEX_BIN:-$HOME/.local/bin/cortex-mcp-server}"CORTEX_DB="${CORTEX_DB:-$HOME/.cortex/memory.db}"[ -x "$CORTEX_BIN" ] || exit 0
printf '%s\n%s\n%s\n' \  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"hook","version":"1.0"}}}' \  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"memory_context","arguments":{"max_tokens":1500}}}' \  | "$CORTEX_BIN" "$CORTEX_DB" 2>/dev/null \  | grep '"id":2' \  | python3 -c "import sys,json; r=json.load(sys.stdin); print(r['result']['content'][0]['text'])" 2>/dev/null

Add to ~/.claude/settings.json:

{  "hooks": {    "SessionStart": [      {        "matcher": "",        "hooks": [          {            "type": "command",            "command": "~/.claude/hooks/cortex-memory-inject.sh"          }        ]      }    ]  }}

Now every new Claude Code session automatically loads your memory context — zero manual effort. Claude learns as you work and remembers across sessions.

Cross-Device Memory Sync

Your Claude's memory follows you across all your devices — MacBook, iMac, work laptop — through your own cloud storage.

Enable sync (one command):

You: "Enable cross-device memory sync"
Claude calls sync_enable → auto-detects iCloud Drive →  generates device ID + AES-256-GCM encryption key → done.
Output:  Provider:   iCloud Drive  Encryption: AES-256-GCM  Passphrase: a1b2c3...  ← save this for your other devices

On your second device — one script does everything (build/install, wait for iCloud, join, restore):

git clone https://github.com/gambletan/cortex && cortex/scripts/setup-device-sync.sh# Prompts for your passphrase (hidden input; or set CORTEX_SYNC_PASSPHRASE)# → full restore on join, passphrase saved to that device's login Keychain

Or conversationally:

You: "Enable sync with passphrase a1b2c3..."
Claude calls sync_enable(passphrase: "a1b2c3...") →  connects to the same iCloud sync folder → pulls all memories.
Now both devices share the same memory — and keep sharing itautomatically (background sync: 30s poll + filesystem watcher).

What syncs and what doesn't:

• Private memories (default) never leave your device. Opt in per memory: memory_ingest with privacy: "shared", cortex-mcp-server ingest --privacy shared, or memory_set_privacy on an existing memory
• Demote a shared memory back to private and it is retracted (deleted) from your other devices — the local copy stays
• All sync data is AES-256-GCM encrypted with HMAC integrity — even if your cloud account is compromised, memories stay private and tampering is detected
• Sync survives restarts: settings persist, the passphrase lives in the OS keychain, the server resumes automatically
• No server, no API, no account — just your own cloud folder

CLI alternative:

# Device Acortex-mcp-server sync enable# Save the passphrase from the output
# Device Bcortex-mcp-server sync enable --passphrase "your-passphrase-from-device-A"
# Manual pull (background sync also pulls automatically)cortex-mcp-server sync pull

Multi-Project Isolation

Working across multiple projects? Use separate databases for physical memory isolation — no cross-project leakage, zero code changes needed.

~/.cortex/├── global.db          # User preferences, people graph, cross-project knowledge├── my-app.db          # Project A memories└── my-api.db          # Project B memories

Global config (~/.claude/settings.json) — user-level knowledge:

{  "mcpServers": {    "cortex-global": {      "command": "~/.local/bin/cortex-mcp-server",      "args": ["~/.cortex/global.db"]    }  },  "permissions": { "allow": ["mcp__cortex-global__*", "mcp__cortex-project__*"] }}

Per-project config (~/.claude/projects/<path>/settings.json) — project-specific:

{  "mcpServers": {    "cortex-project": {      "command": "~/.local/bin/cortex-mcp-server",      "args": ["~/.cortex/my-app.db"]    }  }}

Then add these memory isolation rules to your project's CLAUDE.md:

## Memory Isolation
Two Cortex MCP servers: `cortex-project` (project DB) and `cortex-global` (global DB).
### Write Policy- Save to `cortex-project` if the memory is about this repo's architecture, code,  modules, tests, workflows, configs, bugs, decisions, or terminology.- Save to `cortex-global` only for long-term user preferences, communication style,  cross-project habits, or personal background useful across repos.- **Default: if uncertain, save to `cortex-project`.**
### Read Policy1. Query `cortex-project` first.2. Query `cortex-global` second, only for user-level preferences.3. Prefer project memory when they conflict.
### Anti-Leak Rules- Never auto-copy from `cortex-project` into `cortex-global`.- Never store repo-specific paths, module names, or account names in `cortex-global`.- Never treat project implementation details as user-global preferences.
### Update Rule- Cortex is append-only. To update: search old entry → delete → ingest new.

This gives you two independent Cortex instances per project — complete isolation with shared user knowledge.

30 Tools

Tool access is governed by an optional deny-by-default capability policy: drop a capabilities.json next to your database ({"version":1,"grants":["read","write"]}) and only granted tool groups (read / write / sync / plugins / all) or exact tool names are listed and callable. No policy file = everything enabled (legacy).

OpenClaw Plugin

Give your OpenClaw agent persistent memory with auto-recall and auto-capture.

Install:

# 1. Install Cortex binarycurl -fsSL https://raw.githubusercontent.com/gambletan/cortex/main/install.sh | bash
# 2. Install the OpenClaw pluginopenclaw plugin add @cortex-ai-memory/cortex-memory

Configure (optional — works with defaults):

{  "plugins": {    "@cortex-ai-memory/cortex-memory": {      "autoCapture": true,      "autoRecall": true,      "topK": 10    }  }}

What it does:

• autoCapture: Automatically stores conversation context after each turn
• autoRecall: Injects relevant memories before each turn (your agent "remembers")
• 7 tools: memory_search, memory_store, fact_add, belief_observe, person_resolve, and more

See openclaw-plugin/README.md for full configuration options.

Project Structure

cortex/├── cortex-core/          # Rust core library (all memory logic)│   ├── src/│   │   ├── lib.rs              # Cortex entry point│   │   ├── types.rs            # MemObject, MemoryTier, etc.│   │   ├── inference.rs        # Proactive inference (EN + CN)│   │   ├── episode.rs          # Episodic memory store│   │   ├── semantic.rs         # Semantic facts + preferences│   │   ├── working.rs          # Working memory (session scratch pad)│   │   ├── procedural.rs       # Learned routines│   │   ├── people.rs           # People graph + identity resolution│   │   ├── belief.rs           # Bayesian belief system│   │   ├── consolidation.rs    # Episodic→semantic promotion + decay│   │   ├── retrieval.rs        # Multi-signal retrieval engine│   │   ├── context.rs          # LLM context generation│   │   ├── sync/               # Cloud sync (oplog, HLC, merge, encryption)│   │   └── storage/            # SQLite + in-memory vector index│   └── benches/                # Performance benchmarks├── cortex-http/          # HTTP REST API (axum, local-only)├── cortex-mcp-server/    # MCP server binary (3.8MB)├── cortex-python/        # Python bindings (PyO3, WIP)├── openclaw-plugin/      # OpenClaw memory plugin├── Dockerfile            # Self-hosted Docker image└── Cargo.toml            # Workspace root

HTTP API

Cortex ships a lightweight HTTP server for integration with any language or framework. Binds to 127.0.0.1 by default — your data never leaves your machine.

# Build & runcargo build --release -p cortex-http./target/release/cortex-http --port 3315 --db ~/.cortex/memory.db
# Or via Docker (pre-built from GHCR)docker run -v ~/.cortex:/data -p 3315:3315 ghcr.io/gambletan/cortex/cortex-http:latest
# Or build locallydocker build -t cortex .docker run -v ~/.cortex:/data -p 3315:3315 cortex

Endpoints

Examples

# Store a memorycurl -X POST http://localhost:3315/v1/memories \  -H 'Content-Type: application/json' \  -d '{"text": "I prefer dark mode", "channel": "cli"}'
# Searchcurl -X POST http://localhost:3315/v1/memories/search \  -H 'Content-Type: application/json' \  -d '{"query": "preferences", "limit": 5}'
# Export all data (backup to iCloud, NAS, etc.)curl http://localhost:3315/v1/export > ~/iCloud/cortex-backup.json
# Import from backupcurl -X POST http://localhost:3315/v1/import \  -H 'Content-Type: application/json' \  -d @~/iCloud/cortex-backup.json

Roadmap

• v0.2 ✅ — Local embedding integration (all-MiniLM-L6-v2/ONNX), batch queries, importance-aware decay + auto-consolidation
• v0.3 ✅ — Proactive inference (auto-extract facts), temporal awareness, contradiction detection, Chinese NLP
• v0.4 ✅ — HTTP REST API (axum), import/export (JSON backup), Docker packaging
• v0.5 ✅ — Conversation compression, relationship inference (EN + CN), temporal retrieval enhancement, 112 tests
• v1.0 ✅ — Feature comparison table, benchmark update, 18-feature Cortex vs Mem0 vs OpenAI
• v1.1 ✅ — HNSW vector index (50K search: 12ms → 91µs), Python SDK (pip install cortex-ai-memory)
• v1.2 ✅ — Negation detection (EN + CN), multi-hop retrieval, 117 tests
• v1.3 ✅ — Context quality optimization, query expansion, bidirectional relationships, 126 tests
• v1.4 ✅ — Incremental HNSW, SQL-indexed entity queries, LLM summarizer hook, 18 MCP tools, configurable decay, LLM-assisted inference, 131 tests
• v1.5 ✅ — Docker image (GHCR auto-publish), batch ingest, dedup, namespace isolation, plugin system, event bus, archival, 351 tests
• v1.6 ✅ — Int8 quantization (75% storage reduction), materialized column indexes, FTS5 triggers, LRU caches (MemObject + entity-facts), rayon parallel decay, Arc embedding, generation-based cache invalidation, 25 MCP tools, batch inference, enhanced Chinese NLP
• v1.7 ✅ — Cloud sync (changelog-based, HLC ordering, LWW merge), AES-256-GCM encryption (Argon2id KDF), privacy enforcement (Private/Shared/Public), zeroize (memory wiping), SECURITY.md, 27 MCP tools, 400+ tests
• v2.0 ✅ — Background sync (filesystem watcher + polling), Web Dashboard, Homebrew tap, integration docs (CrewAI/AutoGen/LangGraph/DeerFlow), /v1/memories/recent API, 12 rounds Codex review fixes, 489 tests
• v2.1 ✅ — WASM build (124KB, runs entirely in the browser, GitHub Pages demo)
• v2.2 ✅ — Security hardening series (self-evolution iterations 11–17): manifest + per-operation HMAC, plaintext-injection rejection, timing-attack hardening, key rotation with forward secrecy (ENC2), bounded query budget, deny-by-default MCP capability policy, per-memory privacy opt-in with cross-device retraction, persistent sync (Keychain) + auto background sync, frecency ranking, one-shot device setup script, 30 MCP tools, 500+ tests
• v2.3 — Mobile targets (iOS/Android), multi-modal memory

If you find Cortex useful, please consider giving it a star ⭐ — it helps others discover the project and motivates continued development!

[Star History Chart]

License

MIT