内容
# Cortex
**每个AI代理都需要的内存层。**
本地化。成本最低。今日在Claude上运行。
[](https://github.com/joetomryan/cortex/actions)
[](https://www.python.org/downloads/)
[](LICENSE)
[](#performance)
[](https://modelcontextprotocol.io/)
Cortex是用于AI代理的通用内存层。将MCP服务器放入Claude Desktop、Claude Code、Cursor、Codex或Windsurf——您的代理在每个会话、每个项目、每次对话中都记得。**读取路径上零API成本。所有数据都在您的机器上。MIT许可。**今天它在笔记本电脑上本地运行。前方的道路是一个开放的内存标准，每个平台上的每个代理都使用它。
## 为什么选择Cortex
其他内存层都要求您做出选择：按查询付费，或将对话上传到别人的云端，或锁定在一个平台上。Cortex不选择这些。
- **有史以来最便宜的内存。** $0 读取成本（100% 本地）。使用`CORTEX_NO_ENRICH=1`时，写入成本为$0。带有Haiku enrich的选件：$0.0008/写入 - 约1/1000的托管替代方案用于相同的操作。没有托管的等价物。
- **属于您，存储在您的磁盘上。** SQLite + sqlite-vec在本地文件系统上。无需API密钥即可写入或读取。无需云端。无需供应商。远程服务器上没有无声模型漂移。随身携带文件。
- **今天在您的Claude上运行。** 插件MCP服务器。14种工具（`memory_write`、`memory_search`、`memory_recall`、`memory_get_context`、`memory_get_entity`、`memory_get_timeline`、`memory_diff`、`memory_consolidate`等）。同一个服务器为Claude Desktop、Claude Code、Cursor、Codex CLI、Windsurf提供服务 - 任何MCP-capable的设备。
- **架构完整，不只是向量数据库包装器。** 类型链接图（相似性/时间/实体/取代/因果）。带有`valid_from`/`valid_to`和置信度衰减的结构化SPO事实。自动分组的剧集。8步自我维持的整合。spaCy NER + Jaro-Winkler实体解析。带有放弃信号的BGE交叉编码器重新排序。
- **开放。可复制。可分叉。** MIT许可。我们产生的每个基准测试JSON都已检入[`docs/benchmark-history/`](docs/benchmark-history/)。在约30分钟内自行运行我们的77.45% LongMemEval得分。
## Cortex与其他产品比较
| | **Cortex** | Mem0 | Supermemory | OpenAI Memory |
|---|---|---|---|---|
| 读取成本 | **$0** | 托管，付费 | 托管，付费 | 捆绑在ChatGPT中 |
| 写入成本（无增强） | **$0** | API调用 | API调用 | 不适用 |
| 您的数据存储在 | **您的磁盘上** | Mem0云 | Cloudflare + Postgres | OpenAI服务器 |
| 与Claude（任何客户端）配合使用 | **是（MCP）** | 有限 | 托管MCP | 否 |
| 切换代理而不丢失内存 | **是** | 如果您留在Mem0上 | 如果您留在Supermemory上 | 否 |
| 许可证 | **MIT** | Apache 2.0库，托管生产 | 封闭引擎 | 封闭 |
| LongMemEval（独立验证） | **77.45%** | 93.4%声称，不可复制 | 81.6–85.2% | 不适用 |
| 可审计的源代码 | **全部** | 仅限库，不包括生产引擎 | 仅限包装器 | 无 |
宣传的重点不是“**我们得分最高**”，而是“**其他选择都迫使您放弃数据、钱财或平台自由。我们不这样做**”。
## 工作原理
```mermaid
flowchart TB
A["Claude · Cursor · Codex · Windsurf · 任何MCP代理"] -->|stdio| S[Cortex MCP服务器<br/>14种工具]
S --> R["混合检索<br/>(96.3%召回率)"]
S --> W[写入管道]
S --> C[8步整合]
R --> V[sqlite-vec<br/>余弦kNN]
R --> F[FTS5<br/>BM25]
R --> G["实体图<br/>1跳扩展"]
V --> RRF["RRF融合<br/>+ 重新排序<br/>+ 放弃"]
F --> RRF
G --> RRF
W --> E[BGE小型嵌入]
W --> N[spaCy NER + 解析]
W --> H["Haiku增强<br/>(可选，$0.0008)"]
E --> DB
N --> DB
H --> DB
C --> DB[("本地SQLite +<br/>sqlite-vec + FTS5")]
```
单个SQLite文件是您的全部内存。跨机器移动，版本控制，备份，丢弃。您的代理记住重要的事情；您控制一切。
## 性能
| 操作 | 延迟p95 | 成本 |
|---|---|---|
| 写入 | ~15毫秒 | $0.0008（或使用`CORTEX_NO_ENRICH=1`时为**$0**） |
| 搜索（rerank=True） | ~270毫秒 | **$0** |
| 搜索（rerank=False，快速路径） | **~11毫秒** | **$0** |
| 上下文组装 | ~500毫秒 | **$0** |
在LongMemEval 102实例分层样本上验证：
| 类别 | 分数 |
|---|---|
| 单会话用户 | 16/17（94%） |
| 单会话助手 | 17/17（100%） |
| 单会话偏好 | 13/17（76%） |
| 多会话 | 9/17（53%） |
| 时间推理 | 10/17（59%） |
| 知识更新 | 14/17（82%） |
| **总体** | **79/102（77.45%）** |
96.3% 检索召回率 - 正确的记忆始终在前K个中。详细的方法论，每次基准测试运行，每次回归分析：[`docs/CORTEX_PROJECT_OVERVIEW.md`](docs/CORTEX_PROJECT_OVERVIEW.md)。
## 2分钟使用
```bash
git clone https://github.com/joetomryan/cortex && cd cortex
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e .[dev]
python -m spacy download en_core_web_sm
python -c "from cortex.db import init_db; init_db()"
```
然后将以下内容添加到`~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"cortex": {
"command": "/abs/path/to/cortex/.venv/bin/python",
"args": ["/abs/path/to/cortex/server.py"]
}
}
}
```
重启Claude Desktop。告诉它一些事情。打开一个新会话明天并询问它。它记得。
对于Claude Code：`claude mcp add cortex /abs/path/to/.venv/bin/python /abs/path/to/server.py`。对于Cursor / Codex / Windsurf：查看[`scripts/install_claude_code.sh`](scripts/install_claude_code.sh) - 它为每个客户端打印确切的配置代码段。
## 内部结构
```
cortex/ ← 包 - 17个模块，4,390行代码，215个测试
db.py ← SQLite + sqlite-vec + FTS5 + WAL + 在线备份
embeddings.py ← BGE-small-en-v1.5（384维）单例 + LRU缓存
reranker.py ← BGE-reranker-base交叉编码器
search.py ← 混合搜索，RRF融合，放弃，查询缓存
write.py ← 嵌入 → 实体解析 → 增强 → 链接 → 剧集
update.py ← 修订 / 取代 / 过期
context.py ← 在令牌预算内组装
consolidation.py ← 8步自我维护，速率限制的Haiku
entities.py ← spaCy NER + Jaro-Winkler解析 + 档案
facts.py ← 带有valid_from/to和衰减的SPO三元组
links.py ← 类型图：相似性/时间/实体/取代/因果
episodes.py ← 时间间隔 + 源启发式分组
classification.py ← 基于规则的内存类型分类器（零API）
enrichment.py ← 统一的Haiku调用（事实 + 观察 + 矛盾）
decomposition.py ← 多部分查询拆分
router.py ← 基于规则的查询意图分类器
schema.sql ← 包数据，通过importlib.resources加载
server.py ← MCP入口点（stdio + HTTP）
docs/
CORTEX_PROJECT_OVERVIEW.md ← 架构，历史，每次准确性尝试
ITERATION_LOG.md ← 每次基准测试运行记录，预测与实际
benchmark-history/ ← 93个原始基准测试JSON（~15 MB存档）
archive/ ← 历史实验文档
```
## 未来规划
今天，Cortex是为Claude提供持久内存的最便宜、最本地的方式。我们的目标是成为**内存层** - 每个AI代理在每个平台上都使用的内存层，就像每个Web应用程序都使用HTTP一样。
- **连接器优先。** Gmail，Roam，iMessage，Slack，LinkedIn，Telegram，日历 - 将您真实的数据拉入一个本地内存存储，而不是十几个平台孤岛。本地数据库增长；您的代理的理解力增强。
- **跨代理内存。** 相同的SQLite文件，同时为Claude Desktop + Cursor + Codex CLI提供服务。您的上下文跟随您到任何地方工作。
- **可选的云同步** - Litestream → S3 → Turso。无需放弃本地优先的多设备。静止加密。
- **内存操作的开放标准。** 内存工具在MCP-capable代理上稳定。推动一种稳定的模式，其他人可以实现，从而使内存成为可移植的基础设施，而不是供应商锁定。
不在路线图上：追逐我们无法复制的基准数字。完整的推理在[`docs/CORTEX_PROJECT_OVERVIEW.md`](docs/CORTEX_PROJECT_OVERVIEW.md)中。
## 引用
```bibtex
@software{cortex2026,
title = {Cortex: 一个用于AI代理的本地优先的通用内存层},
author = {Ryan, Tom},
year = {2026},
url = {https://github.com/joetomryan/cortex}
}
```
## 许可证
MIT - 请参阅 [LICENSE](LICENSE)。
## 进一步阅读
- [`docs/CORTEX_PROJECT_OVERVIEW.md`](docs/CORTEX_PROJECT_OVERVIEW.md) - 架构，项目路径，每次准确性尝试 + 结果
- [`docs/ITERATION_LOG.md`](docs/ITERATION_LOG.md) - 每次基准测试运行记录，预测与实际
- [`scripts/install_claude_code.sh`](scripts/install_claude_code.sh) - 一键安装程序，打印每个MCP-capable代理的配置代码段
