Cortex Memory Engine

Cortex

🧠 在浏览器中试用 Cortex — 无需安装，WASM 仅 124KB，完全在客户端运行。

如果 Cortex 能帮你的 AI 记住信息，给它一个 ⭐ — 只需 1 秒，也能帮助其他人发现这个项目。

中文 | 日本語 | 한국어

为个人 AI Agent 提供本地记忆。

私密、免费、本地。——个人 AI Agent 的记忆引擎。

AI 的记忆档案保存在你的设备上。 纯 Rust 实现。二进制文件仅 3.8MB。本地引擎无需托管服务，也不会收集任何遥测数据。可选的加密同步使用你自己的云存储；可选的 Muse 分享只会将你批准的摘录发送给 Cortex Cloud 和 Meta。（设备端语义搜索会在首次使用时下载一个约 30MB 的模型，之后完全离线运行；你也可以通过 CORTEX_NO_EMBEDDINGS=1 实现 100% 离线。参见安全与隐私。）

你将获得

• 🔒 默认私密 — 记忆保存在本地 SQLite 文件中；同步和 Muse 分享都需要明确选择加入。零遥测数据（由 CI 强制执行）。
• 🧠 真正的记忆，而非文本文件 — 4 个层级、多信号检索、自我修正的贝叶斯信念，以及跨渠道的人物关系图。
• ⚡ 亚毫秒级 — 写入耗时 156µs，搜索耗时 568µs。速度约为云端记忆 API 的 528 倍，无需网络往返。
• 🔌 适用于任何 Agent，即插即用 — 一个 MCP 服务即可为 Claude Code / Claude Desktop（或任何 MCP 客户端）提供跨会话持久记忆。
• 🤝 将 Meta Muse 连接到选定的摘录 — 你的档案仍保存在本地。位于 https://cortex.alvinsclub.ai 的可选服务只提供你批准导出的内容，并设有每日披露限额和撤销机制。该服务和 Meta 可以读取已分享的摘录。设置与隐私限制 →
• ☁️ 跨设备归你所有 — 可选的端到端加密同步，通过你自己的 iCloud / Drive / Dropbox 完成；此同步无需 Cortex 服务。

看看它如何跨会话记忆信息——约 30 秒：

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

告诉 Claude：“记住，我用 Fly.io 部署，并且推送前总是运行测试。”开启一个全新会话，然后问：“如何部署这个项目？”——它会从记忆中作答，整个过程 100% 在你的设备上完成。

⭐ 如果这对你有帮助，给它一个 star——这能帮助其他人找到一款尊重隐私的记忆引擎。

---

大模型每次会话开始时都是空白的——它们会忘记你的名字、偏好、昨天的对话和上周的决定。常见的解决办法是使用纯文本文件（没有排序，也不会衰减）、关键词 grep，或云端 API；后者会增加 200–500ms 的延迟、向你收费，还会把个人数据发送到别人的服务上。Cortex 为你的 AI 提供结构化、不断自我演进的长期记忆，可在不同会话和渠道间持续保留——完全本地，完全属于你。 你的记忆不会成为云服务提供商的训练数据、初创公司的变现资产或监控目标。

Cortex、Mem0 与 OpenAI Memory 对比

	Cortex	Mem0	OpenAI Memory
隐私	本地存档；可选择通过 Muse 导出到云端	云 API（你的数据存储在其服务器上）	OpenAI 服务器
延迟	写入 156µs，搜索 568µs	约 200-500ms	约 300-800ms
成本	永久免费	$99+/mo（Pro）	ChatGPT Plus（$20/mo）
记忆层级	4 层（工作/情景/语义/程序性）	1 层（扁平）	1 层（扁平）
贝叶斯信念	基于证据自动纠正	不支持	不支持
人物关系图谱	跨渠道身份解析	仅限付费层级	不支持
对话压缩	自动生成会话摘要	不支持	不支持
关系推断	基于模式（EN + CN）	不支持	不支持
时间检索	感知意图（“最近”/“第一次”）	不支持	不支持
矛盾检测	自动检测并提供置信度评分	不支持	不支持
整合	情景记忆 → 语义记忆自动提升	不支持	不支持
上下文注入	按令牌预算生成适用于大模型的输出	手动	自动，但不透明
导入/导出	完整 JSON 备份与恢复	仅 API	不支持导出
可自托管	原生二进制文件、Docker、MCP	仅云端	仅云端
二进制文件大小	3.8 MB	npm 软件包	不适用
依赖项	0 个运行时服务（单一二进制文件）	Node.js + 云端	不适用
开源	MIT	部分开源	否
加密	AES-256-GCM 加密同步（可选启用）	不支持	不支持
密钥轮换	版本化信封、前向保密	不支持	不支持
隐私级别	私密（默认，永不同步）/ 共享 / 公开 — 每条记忆可单独选择加入；降级后会从其他设备撤回	不支持	不支持
工具授权	MCP 接口采用默认拒绝的能力策略	不支持	不支持
零遥测	无分析、无回传，可验证	未知	不支持
成本	永久免费，无限使用	$99+/mo（Pro）	$20/mo（Plus）
中文 NLP	原生支持（推断、检索、关系）	不支持	有限支持
命名空间隔离	按用户/上下文分离记忆	不支持	不支持
插件系统	用于写入/检索/整合的编译时钩子	不支持	不支持
MCP 工具	30 个工具，用于与 Claude/大模型集成	第三方	不适用

性能基准测试

操作	Cortex	Mem0（云端）	基于文件
写入	156µs	约 200ms	约 1ms
搜索（前 10 条）	568µs	约 300ms	约 10ms
上下文生成	621µs	约 500ms	手动
信念更新	66µs	不适用	不适用
人物关系图谱	51µs	付费层级	不适用
结构化事实	45µs	不适用	不适用
搜索 1K 条记忆	1.6ms	约 500ms	约 50ms

比 Mem0 云端快 528 倍，并具备 Mem0 和 OpenAI Memory 均不提供的功能。

注意： 基准测试包含每次写入时的主动推断（自动提取事实、偏好和关系）。不含推断的原始写入耗时约为 15µs。数据来自 M 系列 Mac 上的 cargo bench。

LoCoMo 基准测试（ACL 2024）

学术级长期对话记忆评估——包含 10 段对话、1540 组问答，涵盖 4 个类别。

系统	单跳	多跳	开放域	时间	总体
Backboard	89.4%	75.0%	91.2%	91.9%	90.0%
MemMachine v0.2	—	—	—	—	84.9%
Cortex	72.5%	59.5%	88.8%	74.1%	73.7%
Mem0-Graph	65.7%	47.2%	75.7%	58.1%	68.4%
Mem0	67.1%	51.2%	72.9%	55.5%	66.9%
OpenAI Memory	—	—	—	—	52.9%

主要发现：

• 开放域 88.8%——比 Mem0（72.9%）高 15.9%
• 时间 74.1%——比 Mem0（55.5%）高 18.6%
• 单跳 72.5%——比 Mem0（67.1%）高 5.4%
• 多跳 59.5%——比 Mem0（51.2%）高 8.3%
• 总体 73.7%——比 Mem0（66.9%）高 6.8%，比 OpenAI Memory（52.9%）高 20.8%

Cortex 在全部 4 个类别中均优于 Mem0，同时完全在本地运行、端到端加密，且成本为 0 美元。

**设置：**Claude Sonnet 4（问答 + 评判）、nomic-embed-text（通过 Ollama 生成嵌入）、检索前 30 条。使用该设置可复现：python3 bench/locomo_bench.py（需要 ANTHROPIC_API_KEY，以及本地安装了 nomic-embed-text 的 Ollama）。数据是在 v1.7 引擎上测得的；v2.2 检索波束修复（在 5K 时将释义召回率从 40% 提升至 90%，参见 docs/scale-test-2026-06-13.md）尚未在 LoCoMo 上重新运行，因此这里报告的是最后一次验证的数据，而非 v2.2 的结果。

架构

Cortex 实现了一个受人类认知启发的 4 层记忆模型：

                    +---------------------+
                    |   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
                    +---------------------+

工作记忆保存当前会话的临时内容。情景记忆存储带时间戳和来源元数据的原始经历。整合引擎会定期将重复出现的模式提升为语义记忆事实，并衰减过时的情景记忆。程序性记忆记录习得的工作流和惯例。

Bot 集成架构

对于使用现有 PostgreSQL 记忆和账户权限的托管 Bot，Cortex 可作为其 MemoryManager 后端中一个可选的派生检索后端。PostgreSQL 仍是已确认值、范围、来源、修订和撤回的权威来源；ContextProjector 仍是唯一的模型上下文组合器，而 Workflow 负责执行和审批。搜索结果必须通过当前权威数据的验证，才能进入模型上下文。受控投影存储不得导入个人档案，也不得默认启用同步、自动推理或整合。

受控 API 契约记录了已实现的 ControlledStore Python 接口、快照／重放生命周期和错误代码。实现计划将 Cortex 侧的接收流程与由宿主负责的 PostgreSQL 和 Bot 集成分开。软件包发布与 Bot 部署是独立步骤；现有个人 Agent 接口仍可使用。

核心组件

人物关系图谱

跨渠道身份解析。在 Telegram 上给你发消息、给你发邮件并出现在日历事件中的同一个人，会被统一为一个身份节点。系统会按人追踪互动、关系强度和沟通模式。

贝叶斯信念系统

能够自我修正的世界认知。信念基于证据形成，并随每次新观察更新，也可能受到反证。置信度分数反映实际确定性，而非受近期信息偏差影响。

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

整合引擎

将情景记忆提升为语义记忆、衰减过时记忆并提取模式。它作为后台周期任务运行，让记忆存储保持精简且便于查询。运行后会报告哪些内容已提升、衰减和合并。

多信号检索

查询结合五种信号进行相关性排序：

• 相似度 -- 根据查询嵌入计算向量余弦距离
• 时间性 -- 根据可配置的衰减进行近期性加权
• 显著性 -- 根据访问模式和显式提示进行重要性评分
• 社交性 -- 提升涉及特定人物的记忆的排序
• 渠道 -- 按来源渠道筛选或提升排序

上下文注入协议

根据记忆状态生成可供 LLM 使用的上下文字符串。传入令牌预算以及可选的渠道／人物筛选条件，即可获得结构化文本块，供 LLM 直接使用。

存储

使用 SQLite 持久化，并通过内存向量索引快速进行相似度搜索。数据库为单文件，无需外部服务。专为边缘部署设计，可在笔记本电脑、Raspberry Pi 或服务器上运行。

云同步

通过你自己的云存储在设备间同步记忆——不涉及第三方服务器。

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

• 基于变更日志：每台设备将仅追加的操作日志写入自己的子文件夹
• 无冲突：设备不会写入同一个文件。合并使用基于混合逻辑时钟的最后写入者胜出策略
• 加密：使用 AES-256-GCM 加密（可选）。即使你的云账户遭到入侵，记忆仍会保持私密
• 防篡改：同步清单和每项操作都带有 HMAC；遭篡改或注入明文的 oplog 行会被拒绝，没有完整性保护的清单也会拒绝加载（不存在密钥回滚路径）
• 密钥轮换与前向保密：轮换到新密钥版本（ENC2 信封），无需重新加密历史数据；旧版本仍可读取，新写入的数据无法被泄露的旧密钥读取
• 兼顾隐私，逐条记忆选择加入：私密记忆（默认）永远不会离开你的设备。将记忆标记为 shared 即可同步；将其改回 private 后，撤回操作会从你的其他设备中删除该记忆（本地副本保留）
• 重启后仍可使用：同步设置会持久保存在数据库中（口令不会写入磁盘——存储于 macOS 登录钥匙串或 CORTEX_SYNC_PASSPHRASE）；服务会自动恢复同步并启动后台拉取（每 30 秒轮询一次 + fs watcher）

支持的提供商：iCloud Drive、Google Drive、OneDrive、Dropbox（自动检测）。

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 otherwise
cortex.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);

安全与隐私

特性	详情
加密	使用 Argon2id 派生密钥的 AES-256-GCM（每行使用随机 nonce）
密钥轮换	使用按版本通过密码短语派生密钥的版本化 ENC2 信封，可防范 AES 密钥泄露后的风险，无需完整重新加密
完整性	同步清单和每项同步操作均使用 HMAC；加密操作日志中的明文行会被直接拒绝（防注入）
隐私级别	Private（默认，永不同步）、Shared、Public——可在摄取时设置（privacy 参数 / --privacy），或稍后通过 memory_set_privacy 设置；降级为 Private 后，该记忆会从其他设备撤回
能力策略	MCP 接口默认拒绝工具授权：capabilities.json 可授权工具组（read/write/sync/plugins）或指定工具；未获授权的工具既不可见，也无法调用；策略格式错误时会默认拒绝
查询预算	每次检索都有上限（候选数量上限 + 墙钟时间上限）——查询成本不会随存储总量增长；同时防范 DoS 和限制时序侧信道
机密信息处理	Cortex 绝不会将同步密码短语写入磁盘——仅使用 macOS 登录钥匙串或环境变量；未提供密码短语时会安全失败（关闭同步，绝不使用明文）
内存清零	丢弃时从 RAM 中清除敏感数据（zeroize crate）
零遥测	不收集分析数据或遥测信息。本地核心的网络依赖由 CI 强制检查（scripts/check-no-network-egress.sh）：如果任何网络/遥测 crate 进入 cortex-core 的默认依赖树，构建就会失败；该检查还会验证 --no-default-features 二进制完全不使用网络。
嵌入模型下载（一次性）	默认的 cortex-mcp-server 启用设备端语义搜索，会在首次摄取时从 Hugging Face CDN 下载一个约 30 MB 的模型（all-MiniLM-L6-v2），之后完全离线运行，且不会发送你的任何数据。若要实现 100% 离线设置：使用 CORTEX_NO_EMBEDDINGS=1 运行（关键词/FTS 召回，零网络），或使用 --no-default-features 构建。下载前会向 stderr 打印一次提示——绝不会在无提示的情况下下载任何内容。
Muse 共享（选择加入）	托管版 Cortex Cloud 仅提供已批准的摘录，并使用 OAuth、已签名的设备管理、每日预算和仅含元数据的审计。muse_unshare 会移除摘录；muse_disconnect 会删除云租户。也提供可自托管的网关。Muse 可能会保留已披露的副本；Cortex 无法将其删除。指南
本地使用无需账户	本地引擎无需 API 密钥、注册或云服务。托管版 Muse 共享会创建由设备管理的云租户，无需 Web 账户。

完整威胁模型请参阅 SECURITY.md。

前置条件

安装 Rust 工具链（提供 cargo）：

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

安装后，重新启动终端，或运行：

source "$HOME/.cargo/env"

验证：

cargo --version

真实示例：真正有记忆的个人 AI

想象一下，你的 AI 助手如何记住一周内真实对话中的内容：

# Day 1 — You chat on Telegram
You: "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 you
From: [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 AI
You: "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 arrives
You: "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

所有操作都在本地完成，每次操作耗时不到 1ms。没有云端。没有 API 调用。没有其他人能看到你的数据。

安装

Homebrew（macOS / Linux）

brew tap gambletan/tap
brew install cortex-mcp-server

从源代码安装

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

官方软件包（避免混淆）

Cortex 以 cortex-ai-memory 的名称发布。npm/PyPI 上有几个名称相似的 软件包与本项目无关——请务必使用以下软件包：

生态系统	官方软件包	用途
二进制文件 / MCP 服务	GitHub Releases，或 brew install gambletan/tap/cortex-mcp-server	记忆引擎（主要用途）
PyPI	cortex-ai-memory	Python 绑定
npm	@cortex-ai-memory/cortex-memory（带作用域）	OpenClaw 记忆插件

⚠️ 非本项目软件包： npm cortex-mcp、npm cortex-ai-memory（无作用域）、PyPI cortex-memory。 唯一可信来源始终是此仓库：github.com/gambletan/cortex。如有疑问， Releases 中的二进制文件是权威安装版本。

快速开始

use cortex_core::Cortex;

// Open (or create) a memory database
let cortex = Cortex::open("memory.db")?;

// Ingest a memory from a Telegram conversation
let 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 directly
cortex.add_fact(
    "Alice", "works_at", "Acme Corp",
    0.95, "telegram", None,
)?;

// Store a preference
cortex.add_preference("timezone", "America/Los_Angeles", 0.9)?;

// Retrieve relevant memories
let 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 绑定

使用 PyO3 构建的原生模块，已发布到 PyPI，名称为 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)

与 unified-channel-hub 集成

Cortex 专为用作 unified-channel-hub 的记忆层而设计。消息从任意渠道适配器流入，Cortex 接收并建立索引，然后上下文注入协议会在每次响应前将相关记忆提供给你的大模型。

Telegram ─┐                          ┌─ Context
Discord  ─┤  unified-channel-hub  →  │  Cortex  →  LLM
Email    ─┤  (ingest)                 │  (retrieve + inject)
Calendar ─┘                          └─ Response

与 LangGraph 集成

通过 langchain-mcp-adapters，为任何 LangGraph Agent 添加持久记忆——无需编写自定义代码。

from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent
from 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?"}]
    })

你的 LangGraph Agent 可立即使用 memory_search、memory_ingest、fact_add、belief_observe、person_resolve 以及另外 25 个工具——全部在本地运行。

与 DeerFlow（ByteDance）集成

Cortex 可作为 DeerFlow 的持久记忆层——DeerFlow 是 ByteDance 的开源多 Agent 编排平台。无需修改代码。

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

所有 DeerFlow Agent（Telegram、Slack、Feishu）都可立即使用 30 个记忆工具——跨会话记忆、事实存储、人物图谱，以及跨所有渠道的信念跟踪。

命令行工具

Cortex 也可作为独立命令行工具使用——无需 MCP 客户端。

$ cortex-mcp-server --help
Cortex 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

示例：

# Store a memory
cortex-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"

# Search
cortex-mcp-server ~/.cortex/memory.db search "Alice"
cortex-mcp-server ~/.cortex/memory.db search -l 10 "Q3 roadmap"

# Stats
cortex-mcp-server ~/.cortex/memory.db stats

# Cloud sync
cortex-mcp-server ~/.cortex/memory.db sync                        # status
cortex-mcp-server ~/.cortex/memory.db sync enable                  # auto-detect provider
cortex-mcp-server ~/.cortex/memory.db sync enable -p icloud        # specific provider
cortex-mcp-server ~/.cortex/memory.db sync pull                    # pull remote changes

# Export / Import (backup & restore)
cortex-mcp-server ~/.cortex/memory.db export -o backup.json
cortex-mcp-server ~/.cortex/new.db import backup.json

# Version & capabilities
cortex-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 Muse
cortex-mcp-server gateway preview "booking a flight"      # exactly what Muse would get
cortex-mcp-server gateway serve --oauth --public-url https://<you>.ts.net   # Muse signs in with OAuth
cortex-mcp-server gateway connect K7QM-2XDF               # approve a sign-in, on your computer only
cortex-mcp-server gateway off                             # kill switch

不指定子命令 = MCP stdio 模式（用于集成 Claude Code / Claude Desktop）。

MCP 服务（Claude Code / Claude Desktop）

Cortex 以 MCP 服务的形式提供，可与任何兼容 MCP 的客户端配合使用。

设置

1. 构建并安装二进制文件：

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

2. 注册为 MCP 服务：

Claude Code（CLI）：

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

# Or per-project
claude mcp add cortex -- ~/.local/bin/cortex-mcp-server ~/.cortex/memory.db

Claude Desktop — 添加到 ~/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. 在“不询问”模式下允许使用工具：

添加到 ~/.claude/settings.json → permissions.allow：

"mcp__cortex__*"

注意：MCP 工具权限不支持括号格式（例如 mcp__cortex__memory_ingest(*)）。请改用通配符 mcp__cortex__*。

4. 设置为自动执行 — 添加到你的 CLAUDE.md（项目级或全局 ~/.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. 在会话开始时自动注入记忆（Claude Code hooks — 全自动）：

创建 ~/.claude/hooks/cortex-memory-inject.sh：

#!/bin/bash
CORTEX_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

添加到 ~/.claude/settings.json：

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

现在，每个新的 Claude Code 会话都会自动加载你的记忆上下文——完全无需手动操作。Claude 会在你工作时不断学习，并在不同会话间记住信息。

跨设备记忆同步

Claude 的记忆会通过你自己的云存储，在所有设备间同步——MacBook、iMac、工作笔记本电脑皆可。

启用同步（一条命令）：

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

在第二台设备上——一个脚本即可完成所有操作（构建/安装、等待 iCloud、加入、恢复）：

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

也可以通过对话操作：

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 it
automatically (background sync: 30s poll + filesystem watcher).

同步内容与不同步内容：

• 私有记忆（默认）绝不会离开你的设备。可针对每条记忆选择加入：使用 memory_ingest 并设置 privacy: "shared"、使用 cortex-mcp-server ingest --privacy shared，或对现有记忆使用 memory_set_privacy
• 将共享记忆降级回 private 后，它会从其他设备撤回（删除）——本地副本会保留
• 所有同步数据都经过 AES-256-GCM 加密和 HMAC 完整性校验——即使云账户遭到入侵，记忆仍会保持私密，并能检测到篡改
• 同步可在重启后继续：设置会持久保存，密码短语存储在 OS 钥匙串中，服务会自动恢复
• 无需服务端、API 或账户——只需使用你自己的云文件夹

CLI 替代方案：

# Device A
cortex-mcp-server sync enable
# Save the passphrase from the output

# Device B
cortex-mcp-server sync enable --passphrase "your-passphrase-from-device-A"

# Manual pull (background sync also pulls automatically)
cortex-mcp-server sync pull

多项目隔离

同时处理多个项目？使用独立数据库实现物理记忆隔离——避免项目间信息泄漏，无需修改任何代码。

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

全局配置（~/.claude/settings.json）——用户级知识：

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

项目级配置（~/.claude/projects/<path>/settings.json）——项目专属：

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

然后将以下记忆隔离规则添加到项目的 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 Policy
1. 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.

这样，每个项目都会拥有两个相互独立的 Cortex 实例，实现完全隔离，同时共享用户知识。

30 个工具

工具访问受可选的默认拒绝能力策略管理：在数据库旁边放置 capabilities.json（{"version":1,"grants":["read","write"]}），只有列出的授权工具组（read / write / sync / plugins / all）或确切工具名称才可调用。没有策略文件 = 全部启用（旧版行为）。

工具	用途
memory_ingest	存储一条记忆（文本、渠道、人物上下文、可选的 privacy）
memory_set_privacy	更改记忆的隐私级别——提升为 shared 以进行同步，降为 private 以从其他设备撤回
memory_search	跨所有记忆层进行语义搜索
memory_context	生成适合大模型使用的上下文摘要（按 token 预算控制）
memory_consolidate	运行衰减 + 提升 + 清理周期
memory_infer	预览推断结果，但不存储
memory_compress	压缩较早的对话会话
memory_stats	获取记忆统计信息（各层数量、索引大小）
memory_decay	对情景记忆运行时间衰减
belief_observe	使用证据更新贝叶斯信念
belief_list	查询置信度高于阈值的信念
fact_add	存储结构化知识（主体-谓词-客体）
fact_query	按实体查询事实（使用 SQL 索引）
preference_set	存储带置信度的用户偏好
preference_query	按键模式查询偏好
person_resolve	跨渠道身份解析
person_list	列出所有已知人物
contradiction_check	检查事实是否矛盾
relationship_extract	从文本中提取关系
sync_status	云同步状态（提供方、设备、待处理操作）
sync_providers	检测可用的云存储提供方
sync_enable	启用跨设备云同步，并可选择加密
sync_pull	拉取并应用其他设备的远程更改
memory_archive	将记忆归档到冷存储
memory_restore	将已归档的记忆恢复到活动层
memory_delete	按 ID 永久删除记忆
memory_ingest_batch	在单个事务中导入多条记忆
tag_list_taxonomy	列出记忆中使用的所有标签及其数量
namespace_list	列出所有命名空间及其记忆数量
person_merge	将两个身份合并为一个

OpenClaw 插件

为你的 OpenClaw Agent 提供持久记忆，并支持自动召回和自动捕获。

安装：

# 1. Install Cortex binary
curl -fsSL https://raw.githubusercontent.com/gambletan/cortex/main/install.sh | bash

# 2. Install the OpenClaw plugin
openclaw plugin add @cortex-ai-memory/cortex-memory

配置（可选——使用默认设置即可运行）：

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

功能：

• autoCapture：在每轮对话后自动存储对话上下文
• autoRecall：在每轮对话前注入相关记忆（你的 Agent 会“记住”）
• 7 个工具：memory_search、memory_store、fact_add、belief_observe、person_resolve 等

完整配置选项请参阅 openclaw-plugin/README.md。

项目结构

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 提供轻量级 HTTP 服务，可与任何语言或框架集成。默认绑定到 127.0.0.1——你的数据永远不会离开你的设备。

# Build & run
cargo 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 locally
docker build -t cortex .
docker run -v ~/.cortex:/data -p 3315:3315 cortex

端点

方法	路径	描述
GET	/health	健康检查
POST	/v1/memories	写入一条记忆
POST	/v1/memories/search	语义搜索
GET	/v1/memories/context	生成大模型上下文
POST	/v1/memories/consolidate	运行整合周期
POST	/v1/memories/infer	预览推理（不存储）
POST	/v1/facts	添加一条语义事实
POST	/v1/facts/contradictions	检查矛盾
POST	/v1/preferences	设置一项偏好
GET	/v1/beliefs	列出信念
POST	/v1/beliefs/observe	根据证据更新信念
POST	/v1/people	解析人物身份
POST	/v1/memories/compress	压缩较早的对话会话
POST	/v1/relationships/extract	从文本中提取关系
GET	/v1/export	导出所有数据（JSON 备份）
POST	/v1/import	从备份导入数据

示例

# Store a memory
curl -X POST http://localhost:3315/v1/memories \
  -H 'Content-Type: application/json' \
  -d '{"text": "I prefer dark mode", "channel": "cli"}'

# Search
curl -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 backup
curl -X POST http://localhost:3315/v1/import \
  -H 'Content-Type: application/json' \
  -d @~/iCloud/cortex-backup.json

路线图

• v0.2 ✅ — 本地嵌入集成（all-MiniLM-L6-v2/ONNX）、批量查询、感知重要性的衰减和自动整合
• v0.3 ✅ — 主动推理（自动提取事实）、时间感知、矛盾检测、中文 NLP
• v0.4 ✅ — HTTP REST API（axum）、导入/导出（JSON 备份）、Docker 打包
• v0.5 ✅ — 对话压缩、关系推理（英语 + 中文）、时间检索增强、112 项测试
• v1.0 ✅ — 功能对比表、基准测试更新、Cortex、Mem0 与 OpenAI 的 18 项功能对比
• v1.1 ✅ — HNSW 向量索引（50K 搜索：12ms → 91µs）、Python SDK（pip install cortex-ai-memory）
• v1.2 ✅ — 否定检测（英语 + 中文）、多跳检索、117 项测试
• v1.3 ✅ — 上下文质量优化、查询扩展、双向关系、126 项测试
• v1.4 ✅ — 增量式 HNSW、SQL 索引实体查询、大模型摘要器钩子、18 个 MCP 工具、可配置衰减、大模型辅助推理、131 项测试
• v1.5 ✅ — Docker 镜像（GHCR 自动发布）、批量写入、去重、命名空间隔离、插件系统、事件总线、归档、351 项测试
• v1.6 ✅ — Int8 量化（存储空间减少 75%）、物化列索引、FTS5 触发器、LRU 缓存（MemObject + entity-facts）、rayon 并行衰减、Arc 嵌入、基于代数的缓存失效、25 个 MCP 工具、批量推理、增强的中文 NLP
• v1.7 ✅ — 云同步（基于变更日志、HLC 排序、LWW 合并）、AES-256-GCM 加密（Argon2id KDF）、隐私执行（Private/Shared/Public）、zeroize（内存擦除）、SECURITY.md、27 个 MCP 工具、400 多项测试
• v2.0 ✅ — 后台同步（文件系统监视器 + 轮询）、Web 仪表板、Homebrew tap、集成文档（CrewAI/AutoGen/LangGraph/DeerFlow）、/v1/memories/recent API、12 轮 Codex 审查修复、489 项测试
• v2.1 ✅ — WASM 构建（124KB，可完全在浏览器中运行，GitHub Pages 演示）
• v2.2 ✅ — 安全加固系列（自我演进迭代 11–17）：清单 + 每操作 HMAC、拒绝明文注入、计时攻击加固、支持前向保密的密钥轮换（ENC2）、有界查询预算、默认拒绝的 MCP 能力策略、支持跨设备撤回的单条记忆隐私选择加入、持久化同步（Keychain）+ 自动后台同步、frecency 排名、一次性设备设置脚本、30 个 MCP 工具、500 多项测试
• v2.3 — 移动平台目标（iOS/Android）、多模态记忆

---

如果你觉得 Cortex 有用，请考虑点亮星标 ⭐ — 这能帮助其他人发现此项目，并激励我们持续开发！

许可证

MIT