Cortex 实战：为 AI Agent 搭建本地加密记忆引擎

你有没有遇到过这种情况：跟 Claude 聊了一个小时的架构设计，第二天打开新会话，它又问你 “你的项目用了什么技术栈”？LLM 的会话记忆是短暂的，每次对话都是从零开始。目前主流的云端记忆方案（如 Mem0、OpenAI Memory）虽然能解决这个问题，但代价不小——数据上传到别人的服务器、延迟 200-800ms、还要按月付费。

Cortex 是一个完全不同的思路：100% 本地运行的加密记忆引擎，纯 Rust 编写，单个二进制仅 3.8MB，通过 MCP 协议给 Claude Code、Cursor 等 AI Agent 提供持久的跨会话记忆。它只有一个依赖——Rust 工具链——不需要注册账号、不需要 API Key、不产生任何订阅费用。

本文带你从安装到实战，完整体验 Cortex。

安装 Cortex

Cortex 的安装方式非常灵活，最推荐的是 Homebrew：

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

如果你没有 Homebrew，也可以从源码构建：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

git clone https://github.com/gambletan/cortex
cd cortex
cargo build --release -p cortex-mcp-server
cp target/release/cortex-mcp-server ~/.local/bin/

装好后验证一下：

cortex-mcp-server --version

快速上手：两行命令体验记忆之力

Cortex 既是一个 MCP 服务器，也是一个独立的 CLI 工具。先创建数据库：

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

存一条记忆：

cortex-mcp-server ~/.cortex/memory.db ingest "用户偏好：使用 Neovim 编辑器和暗色主题"

搜索记忆：

cortex-mcp-server ~/.cortex/memory.db search "编辑器"

输出会显示已存储的语义事实。这个 CLI 模式非常适合快速测试——不需要配置任何 MCP 客户端，一条命令即可完成存储和检索。

集成到 Claude Code

真正发挥 Cortex 威力的是将它作为 MCP 服务器集成到 Claude Code 中。注册只需一条命令：

claude mcp add cortex --scope user -- ~/.local/bin/cortex-mcp-server ~/.cortex/memory.db

然后在 ~/.claude/settings.json 中添加通配符权限：

{
  "permissions": {
    "allow": ["mcp__cortex__*"]
  }
}

现在你的 Claude Code 有了 30 个记忆工具——它可以在对话中自动存储你分享的信息，下次会话直接调取。为了让它自动工作，在 ~/.claude/CLAUDE.md 中添加一段简单的记忆策略说明，告诉 Claude 什么时候该调用 memory_ingest、fact_add、memory_context 等工具即可。

四层记忆架构

Cortex 的核心设计灵感来自人类认知模型——四层记忆体系：

• 工作记忆（Working） ——当前会话的临时上下文，会话结束后清空
• 情景记忆（Episodic） ——原始经验记录，带时间戳和来源元数据
• 语义记忆（Semantic） ——经过提炼的事实、偏好、关系（由情景记忆定期归并而来）
• 程序记忆（Procedural） ——学习到的工作流程和例行操作

这种分层设计的优势在于：不需要的记忆自动衰减，重要的模式自动提升到语义层。底层有一个归并引擎（Consolidation Engine）周期性运行，把重复出现的情景模式提炼为语义事实。

核心功能实战

1. 语义事实与偏好存储

除了存对话片段，Cortex 还能存结构化知识：

cortex-mcp-server ~/.cortex/memory.db ingest "Alice works at Stripe, interested in our API"

cortex-mcp-server ~/.cortex/memory.db ingest "用户偏好早上 9 点开会，PST 时区"

当你再次问 “What do I know about Alice?” 时，Cortex 会在 568 微秒内返回所有相关信息——包括她所在的公司、之前讨论过的技术细节、以及你们的沟通历史。

2. 跨设备加密同步

Cortex 最实用的功能之一是通过你自己的云存储同步记忆，而无需第三方服务器：

cortex-mcp-server ~/.cortex/memory.db sync enable

同步使用 AES-256-GCM 加密 + Argon2id 密钥衍生——即使云存储账户被攻破，记忆数据也无法被读取。每次同步操作都有 HMAC 完整性校验，篡改的行会被自动拒绝。

隐私控制也很灵活：默认所有记忆是 Private（不出设备），你可以按记忆设置为 Shared 来同步，降级回 Private 时其他设备上的副本会被自动删除。

3. 多项目隔离

如果你同时在维护多个项目，可以用独立数据库避免记忆交叉污染。在 ~/.claude/settings.json 中注册两个 Cortex 实例：

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

一个存个人偏好（全局），一个存项目架构知识（项目专用），物理隔离，互不干扰。

4. Bayesian 信念系统

Cortex 的一项独特能力是贝叶斯信念系统。当信息出现矛盾时，它不会简单地覆盖旧记忆，而是通过贝叶斯更新自动调整置信度：

Day 1: "Alice works at Stripe"   → 置信度 0.95
Day 7: "Alice now works at Anthropic" → 旧事实衰减到 0.3（保留为历史）
                                         新事实置信度 0.80

下次问 “Where does Alice work?”——Cortex 会优先返回 Anthropic，同时标注之前的 Stripe 作为历史记录。这种自纠偏机制在长期使用中极为重要。

LangGraph 集成

如果你在用 LangGraph 构建 Agent，通过 langchain-mcp-adapters 只需几行代码就能给 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 现在有了 30 个记忆工具

性能基准：本地 vs 云端

Cortex 的作者在 Mac M 系列芯片上做了完整的性能基准测试：

这意味着 Cortex 比 Mem0 云端方案快 528 倍。LoCoMo 基准测试（ACL 2024）中，Cortex 在所有 4 个维度（单跳、多跳、开放域、时序）上都超过了 Mem0，综合得分 73.7% vs Mem0 66.9%。

安全隐私要点

Cortex 在安全方面做了详细的设计：AES-256-GCM 加密、HMAC 完整性校验、零遥测（CI 中强制检查）、默认拒绝的 MCP 能力策略、内存零化（zeroize crate）。具体的威胁模型文档在项目的 SECURITY.md 中。

适合谁用

• Claude Code / Cursor 的重度用户——不想每次开新会话都重复介绍自己的偏好和项目背景
• 关注数据隐私的开发者——拒绝将记忆数据上传到云端 API
• 需要记忆跨项目隔离的团队——不同项目使用独立数据库，无信息泄露
• 对性能有要求的用户——微秒级操作延时，不拖慢 Agent 响应

Cortex 目前版本 v2.2，MIT 许可证，30 个 MCP 工具，500+ 测试用例，代码质量成熟可靠。项目地址：github.com/gambletan/cortex。给你的 AI Agent 装上一个本地记忆引擎，它会真正记得你。