内容
# 🧠 CORTEX 内存
> **AI 代理的持久语义记忆。**
> TypeScript · LangGraph.js · Qdrant · fastembed ONNX · Ollama — 100% 本地运行，无需云服务。
[](https://www.typescriptlang.org/)
[](https://github.com/langchain-ai/langgraphjs)
[](https://qdrant.tech/)
[](https://modelcontextprotocol.io/)
[](LICENSE)
---
## 什么是 CORTEX？
CORTEX 是一个 **模型上下文协议（MCP）服务器**，为 AI 代理提供持久的、语义可搜索的长期记忆。与简单的键值存储不同，CORTEX 了解 *哪些信息很重要*、*记忆之间如何关联* 以及 *哪些记忆正在变得过时*。
为在 **仅限 CPU 环境**中运行的代理而设计 — 无需 GPU，无需云依赖。
---
## 架构 — 3 层记忆
```
┌─────────────────────────────────────────────────────────┐
│ CORTEX v3.2 │
│ │
│ ① 工作记忆 temp_memories (Qdrant) │
│ └─ quick_observe → 即时写入，无需 LLM │
│ │
│ ② 语义记忆 cortex_<project> (Qdrant) │
│ └─ 稠密（all-MiniLM-L6-v2）+ 稀疏（SPLADE） │
│ └─ 由 qwen3 评分 · 链接 · 衰减加权 │
│ │
│ ③ 情景记忆 cortex_episodes_<project> (Qdrant) │
│ └─ 会话，带有时间戳事件，无需 LLM │
└─────────────────────────────────────────────────────────┘
```
---
## 主要功能
| 功能 | 详情 |
|---|---|
| **摄入时的 LLM 评分** | `qwen3` 为每个记忆分配重要性（1-10）、类型和标签 |
| **混合搜索** | 通过 Qdrant RRF 融合实现稠密（all-MiniLM-L6-v2）+ 稀疏（SPLADE_PP_en_v1） |
| **交叉编码器重新排序** | 单个 `qwen3` 调用评估所有（查询，候选）对 |
| **双重衰减引擎** | 贝叶斯（DECISION/FACT/ERROR）+ FSRS 启发（PREFERENCE/CONTEXT） |
| **矛盾检测** | 自动标记摄入时相互矛盾的记忆 |
| **情景会话** | 无 LLM 会话跟踪，带有类型事件 |
| **操作员配置文件** | 持久的代码偏好和工作模式 |
| **20 种 MCP 工具** | 完整的 CRUD + 搜索 + 分析接口 |
| **100% 本地运行** | fastembed ONNX 用于嵌入，Ollama 用于 LLM — 无需 API 密钥 |
---
## 竞争格局（2026 年 6 月）
| | **CORTEX** | mem0 | Graphiti | Basic Memory | MCP Official |
|---|---|---|---|---|---|
| **摄入时的 LLM 评分** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **混合搜索（稠密 + 稀疏）** | ✅ | ⚠️ 云服务 | ❌ | ❌ | ❌ |
| **交叉编码器重新排序** | ✅ | ⚠️ 云服务 | ❌ | ❌ | ❌ |
| **情景层（无需 LLM）** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **双重衰减引擎** | ✅ | ✅ | ✅ 双时态 | ❌ | ❌ |
| **矛盾检测** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **TypeScript + LangGraph.js** | ✅ | ❌ Python | ❌ Python | ❌ Python | ✅ |
| **100% 本地运行** | ✅ | ⚠️ MCP=云服务 | ✅ | ✅ | ✅ |
---
## 先决条件
```bash
# 1. Qdrant（Docker）
docker run -d -p 6333:6333 --name qdrant qdrant/qdrant
# 2. Ollama + 模型
ollama pull qwen3:8b # 评分、标记、重新排序、合并
# 可选的更快的替代方案：
# ollama pull qwen3:1.7b # 速度快 3-5 倍，精度略低
```
> **fastembed** （嵌入）作为 npm 依赖项捆绑 — 无需单独安装。
> 模型在首次使用时自动下载到 `.fastembed_cache/` (~22 MB 稠密，~110 MB 稀疏)。
---
## 安装
```bash
git clone git@github.com:alainrc2005/cortex_memory_mcp.git
cd cortex_memory_mcp
npm install
npm run build
```
### 环境配置
在项目根目录下创建 `.env` 文件：
```env
QDRANT_URL=http://localhost:6333
FASTEMBED_CACHE_DIR=/absolute/path/to/cortex_memory_mcp/.fastembed_cache
# 可选 — 仅当 Qdrant 启用身份验证时需要
# QDRANT_API_KEY=your_key
# 可选 — 默认值为 http://localhost:11434
# OLLAMA_URL=http://localhost:11434
```
---
## MCP 配置
将以下内容添加到您的 MCP 客户端配置文件（例如 `~/.gemini/config/mcp_config.json`）：
```json
{
"mcpServers": {
"langgraph-memory-mcp": {
"command": "/absolute/path/to/cortex_memory_mcp/cortex-mcp.sh"
}
}
}
```
---
## 工具参考 — 20 种工具
### 语义记忆（17 种工具）
| 工具 | 描述 | 触发器 |
|---|---|---|
| `observe` | 通过全流程存储记忆：评分 → 嵌入 → 链接 → 持久化 | 手动 / 会话结束 |
| `recall` | 带有 LLM 交叉编码器重新排序的混合 BM25+稠密搜索 | 按需 |
| `get_context_for` | 为项目 + 消息注入 RAG 样式的上下文 | 自动（冷启动） |
| `consolidate` | 使用 LLM 合并重复/相似的记忆 | 长会话结束 |
| `detect_patterns` | 提取操作员行为模式，更新操作员配置文件 | 周期性 |
| `get_operator_profile` | 读取代码偏好和检测到的模式 | 自动（冷启动） |
| `cortex_status` | 系统健康：集合、记忆计数、待处理缓冲区 | 诊断 |
| `delete_memory` | 按 ID 删除单个记忆 | 按需 |
| `update_memory` | 更新记忆内容，重新计算嵌入 + 评分 | 按需 |
| `get_all_memories` | 列出项目的所有记忆，按衰减评分排序 | 审计 |
| `delete_all_memories` | ⚠️ 不可逆转的项目重置（需要 `confirm: true`） | 显式 |
| `batch_observe` | 一次存储最多 20 个记忆 | 批量导入 |
| `export_memories` | 导出项目为 JSON（备份/迁移） | 按需 |
| `quick_observe` | 写入工作缓冲区 — 无 LLM，无嵌入 | 自动（回合后钩子） |
| `list_pending` | 按项目查看工作缓冲区内容 | 诊断 |
| `index_temp` | 将缓冲区提升到语义记忆，带有 ONNX 嵌入 + LLM 评分 | 自动（下一次冷启动） |
| `recall_hybrid` | 同时搜索缓冲区（关键词）和索引记忆（语义） | 按需 |
### 情景记忆（3 种工具）
| 工具 | 描述 |
|---|---|
| `start_session` | 为项目打开情景会话。自动关闭任何以前打开的会话。返回 `sessionId`。 |
| `log_event` | 在活动会话中记录类型事件。类型：`DECISION` `ERROR` `SOLUTION` `INSIGHT` `CONTEXT_CHANGE` |
| `recall_sessions` | 使用 fastembed ONNX 对过去的会话摘要进行语义搜索 |
---
## 索引流程
```
quick_observe(content)
│
▼ （即时，无 LLM，无嵌入）
temp_memories ◄──── 工作缓冲区（Qdrant，虚拟向量）
│
│ index_temp() — 在下一次会话冷启动时调用
▼
fastembed ONNX
├─ AllMiniLML6V2 → 稠密向量 384d
└─ SpladePPEnV1 → 稀疏 BM25 向量
│
qwen3 （Ollama）
├─ 重要性：1-10
├─ 类型：DECISION | FACT | ERROR | PATTERN | PREFERENCE | CONTEXT
└─ 标签：[关键词，...]
│
矛盾检测（qwen3）
└─ 如果相似度 > 0.88，则标记过时的记忆
│
▼
Qdrant 更新（稠密 + 稀疏向量）
└─ 与相关记忆的双向链接
```
---
## 衰减引擎
CORTEX 使用 **双重衰减模型**，针对每种记忆类型进行调整：
**贝叶斯（DECISION · FACT · ERROR · PATTERN）**
```
utility = alpha / (alpha + beta)
alpha += 访问时的权重
beta += 1 天无访问
```
**FSRS 启发（PREFERENCE · CONTEXT）**
```
stability = log1p(访问次数) × (权重 / 5)
retrievability = exp(-自访问天数 / 稳定性)
```
频繁访问的记忆变得更加稳定。陈旧、未访问的记忆会逐渐衰减，最终成为合并的候选者。
---
## 项目结构
```
src/
├── server.ts # MCP 服务器 — 20 种工具，~1500 LOC
├── bootstrap.ts # Qdrant 集合初始化
├── graph/
│ ├── observe/
│ │ ├── workflow.ts # LangGraph 流程：评分→嵌入→链接→持久化
│ │ ├── state.ts # 图状态类型
│ │ └── nodes/
│ │ ├── score.ts # qwen3：权重 + 类型 + 标签
│ │ ├── embed.ts # fastembed ONNX：稠密 + 稀疏向量
│ │ ├── link.ts # Qdrant 中的双向链接
│ │ └── persist.ts # 最终更新
│ └── consolidate/
│ └── nodes.ts # LLM 合并重复记忆
├── services/
│ ├── qdrant.ts # Qdrant 客户端，集合，混合搜索
│ ├── fastembed.ts # ONNX 嵌入：稠密（AllMiniLM）+ 稀疏（SPLADE）
│ ├── ollama.ts # qwen3：评分，重新排序，矛盾检测
│ ├── decay.ts # 双重衰减引擎：贝叶斯 + FSRS 启发
│ └── episode.ts # 情景会话管理
└── types/
├── engrama.ts # Engram TypeScript 类型
└── episode.ts # 事件类型
```
---
## 运行测试
```bash
npm test
# 涵盖所有 20 种工具的有效、无效和连接性测试用例
```
---
## 记忆生命周期
```
会话 N（活动）
代理检测到可存储的事实
↓
quick_observe() ← 即时，无 CPU 成本
↓
写入 temp_memories
会话 N+1 冷启动
get_context_for() + get_operator_profile() ← 并行
↓
temp_memories 中待处理？→ index_temp()
↓
fastembed ONNX + qwen3 评分应用
↓
提升到 cortex_<project>，带有完整嵌入
↓
可用于 recall() 和 get_context_for()
```
---
## License
MIT © 2026 — 由 Zeus 使用 [Antigravity](https://antigravity.ai) 构建
