内容
# MCP Roo 内存
**基于模型上下文协议（MCP）的持久化、图谱式内存，用于 Roo 代码。**
大型语言模型（LLMs）的记忆力有限。每次新的对话都是从头开始的 —— 上下文窗口溢出、过去的决策被遗忘、推理链条消失。
**MCP Roo 内存** 为您的 AI 代理提供结构化的、持久化的“大脑”：
- **图谱内存** —— 知识不是扁平的存储，而是由任务、实体、事实和决策组成的分形图谱
- **语义搜索** —— 通过意义而非关键词查找相关信息（支持 50+ 种语言）
- **上下文窗口控制** —— 热/冷/存档层级，防止 token 泛滥
- **知识演化** —— 决策可以被更新，事实可以被修订，过期数据会被存档
- **时间感知** —— 时间作为一等公民：时间轴遍历、会话时间线、时间向量过滤
> **⚠️ 免责声明**
>
> 该项目为**实验性项目** —— 正在探索形式和架构。
> 它可以运行，有测试，但请将其视为**概念验证（PoC）**。
> 软件按“现状”提供，不提供任何形式的保证。
> 请自行承担风险。详见 [`LICENSE`](LICENSE) 了解更多。
---
## 快速开始
### 🐳 Docker（推荐）
零系统依赖 —— 仅需 Docker。所有内容都在容器中运行，无需 Python、venv 或 pip。
#### 1. 启动服务栈
```bash
git clone https://github.com/mcasdfgf/mcp-roo-memory.git
cd mcp-roo-memory
docker compose up -d
```
这将启动两个容器：
| 容器 | 功能 |
|-----------|-------------|
| `cortex-qdrant` | 向量数据库（端口 6333） |
| `cortex-mcp` | Cortex 服务器（空闲，等待 MCP 连接） |
#### 2. 全局 MCP 配置
将 Cortex 添加为所有项目的**全局 MCP 服务器**。服务器始终在 Docker 中运行，因此任何项目都可以连接。
编辑 `~/.config/VSCodium/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json`（或 VS Code 的等效路径）：
```json
{
"mcpServers": {
"cortex": {
"command": "docker",
"args": ["exec", "-i", "cortex-mcp", "python3", "-m", "src.cortex"]
}
}
}
```
> **VSCode 用户：** 将路径中的 `VSCodium` 替换为 `Code`。
#### 3. 项目级配置（用于工作区隔离）
如果您希望每个项目都有**独立的内存**，请将 `.roo/` 目录复制到您的项目中：
```bash
cp -r ./mcp-roo-memory/.roo ./your-project/
```
然后编辑项目中的 `.roo/mcp.json` 并添加 `--workspace your-project-name`：
```json
{
"mcpServers": {
"cortex": {
"command": "docker",
"args": [
"exec", "-i", "cortex-mcp", "python3",
"-m", "src.cortex", "--workspace", "your-project-name"
],
"alwaysAllow": ["desktop_open", "graph_add_node", "vector_search", "graph_get_node",
"graph_add_relation", "graph_search", "desktop_focus",
"desktop_history", "graph_traverse", "graph_walk",
"graph_decompose", "graph_update_node", "graph_supersede",
"graph_delete_node", "vector_store",
"temporal_walk", "session_timeline"]
}
}
}
```
用唯一标识符替换 `your-project-name` —— 例如 `mcp-roo-memory`、`researcher`、`ai-pulse` 等。
> **隔离机制：**
> - `desktop_open()` 和 `graph_add_node()` —— 始终写入**您的项目**的工作区
> - 不带 `workspace_id` 的 `vector_search()` —— 跨项目搜索（跨项目回忆）
> - `vector_search(workspace_id="project")` —— 将搜索范围缩小到**一个项目**
#### 4. 完成
重启 Roo Code。您的代理现在具有持久性内存 —— 零系统污染。
---
### 🏠 原生 pip（高级）
如果您更喜欢不使用 Docker 运行 —— 或者您正在开发 Cortex 本身：
```bash
# 要求：Python 3.11+
git clone https://github.com/mcasdfgf/mcp-roo-memory.git
cd mcp-roo-memory
python -m venv .venv
source .venv/bin/activate
pip install -e .
# Qdrant 仍然需要：
docker run -d --name qdrant -p 6333:6333 qdrant/qdrant
```
MCP 配置：
```json
{
"mcpServers": {
"cortex": {
"command": "python",
"args": ["-m", "src.cortex"],
"env": {
"CORTEX_DB_PATH": "/path/to/cortex.db",
"CORTEX_QDRANT_HOST": "localhost",
"CORTEX_QDRANT_PORT": "6333"
}
}
}
}
```
---
## 解决问题
| 问题 | Cortex 如何解决它 |
|---------|---------------------|
| **扁平内存** —— 事实以无关的片段存储 | **分形图谱** —— 任务分解为子任务，事实连接到决策，实体索引文件 |
| **上下文窗口溢出** —— 所有内容都无限增长 | **桌面视口** —— 热（始终加载）/ 冷（聚焦时）/ 存档（仅搜索）层级 |
| **无法导航** —— 无法遍历推理链 | **图谱遍历** —— 跟随 `supersedes`、`derives_from`、`leads_to` 关系 |
| **过时事实滞留** —— 旧决策污染上下文 | **突变策略** —— 更新（修复错误）/ 更新（方法更改）/ 过时级联（重构） |
| **关键词搜索失败** —— “auth 实现” 找不到 “JWT with RS256” | **语义向量搜索** —— 通过 Qdrant + fastembed 的多语言嵌入（50+ 种语言） |
| **没有时间轴** —— 无法回答“发生了什么顺序” | **时间层** —— 时间轴遍历，会话时间线，时间向量过滤 |
---
## 架构
```
┌──────────────────────────────────────────────┐
│ MCP 客户端（Roo Code） │
└──────────────────────┬───────────────────────┘
│ stdio（MCP 协议）
┌──────────────────────▼───────────────────────┐
│ Cortex 服务器 │
│ 17 种工具 · 4 种资源 │
├──────────┬──────────┬──────────┬─────────────┤
│ 图谱 │ 向量 │ 桌面 │ 数据库 │
│ CRUD、 │ Qdrant + │ 热/ │ SQLite │
│ 遍历、 │ fastembed│ 冷/ │ 图谱 + │
│ 行走 │ 语义 │ 存档 │ 历史记录 │
└──────────┴──────────┴──────────┴─────────────┘
```
**三层智能：**
1. **图谱** （SQLite）—— 谁与谁相关，什么分解成什么
2. **向量** （Qdrant）—— 这是什么意思，什么在语义上相似
3. **桌面** （视口）—— 当前上下文窗口中适合什么
---
## 作为主要 Roo 内存使用
通过将 `.roo/` 目录复制到您的项目中，使 Cortex 成为您的代理的默认内存系统：
```bash
# 从此仓库复制参考配置
cp -r ./mcp-roo-memory/.roo ./your-project/
```
`.roo/` 目录包含可直接使用的参考配置：
| 文件/目录 | 目的 |
|------------|---------|
| [`custom_instructions.md`](.roo/custom_instructions.md) | Cortex 启动 —— 必需序列，核心原则 |
| [`mcp.json`](.roo/mcp.json) | 参考 MCP 服务器配置（编辑 `--workspace` 以适应您的项目） |
| [`rules/`](.roo/rules) | 启动、保存、模板、触发器 —— 内存生命周期 |
| [`rules-architect/`](.roo/rules-architect) | 架构模式的内存规则 |
| [`rules-ask/`](.roo/rules-ask) | 问答模式的内存规则 |
| [`rules-code/`](.roo/rules-code) | 代码模式的内存规则 |
| [`rules-coding-teacher/`](.roo/rules-coding-teacher) | 编程教师模式的内存规则 |
| [`rules-debug/`](.roo/rules-debug) | 调试模式的内存规则 |
| [`rules-documentation-writer/`](.roo/rules-documentation-writer) | 文档编写者模式的内存规则 |
| [`rules-orchestrator/`](.roo/rules-orchestrator) | 协调器模式的内存规则 |
| [`rules-project-research/`](.roo/rules-project-research) | 项目研究的内存规则 |
有关内存模型的深入理解，请参见 [`CONCEPT.md`](CONCEPT.md)。
---
## 工具概览
| 工具 | 功能 |
|------|-------------|
| `desktop_open` | 打开/恢复工作区会话 |
| `desktop_focus` | 将节点带入热上下文 |
| `desktop_history` | 获取工作区的导航历史 |
| `graph_add_node` | 存储任何知识：实体、事实、决策、任务... |
| `graph_get_node` | 检索具有其关系的节点 |
| `graph_add_relation` | 在两个节点之间创建关系 |
| `graph_traverse` | 从起始节点遍历图谱 |
| `graph_walk` | 沿推理链行走 |
| `graph_decompose` | 将任务分解为结构化的子任务 |
| `graph_update_node` | 更新节点的in-place 数据 |
| `graph_supersede` | 替换过时的知识（保留历史） |
| `graph_delete_node` | 删除节点及其向量 |
| `vector_search` | 按含义查找事物，支持 50+ 种语言 |
| `vector_store` | 存储具有自动向量化的文本 |
| `graph_search` | 混合：语义 + 图谱子图扩展 |
| `temporal_walk` | 时间轴图谱遍历（时间轴） |
| `session_timeline` | 会话的时间线 |
| 就是这 17 种工具 | 详见 [`CONCEPT.md §8`](CONCEPT.md#8-mcp-protocol) |
---
## 配置
所有配置均通过 `CORTEX_*` 环境变量进行：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `CORTEX_DB_PATH` | `cortex.db` | SQLite 数据库路径 |
| `CORTEX_QDRANT_HOST` | `localhost` | Qdrant 主机 |
| `CORTEX_QDRANT_PORT` | `6333` | Qdrant 端口 |
| `CORTEX_QDRANT_TIMEOUT` | `30` | 连接超时（秒） |
| `CORTEX_COLLECTION_NAME` | `cortex_memory` | Qdrant 集合名称 |
| `CORTEX_EMBEDDING_MODEL` | `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2` | 嵌入模型（50+ 种语言） |
| `CORTEX_ARCHIVE_DAYS_THRESHOLD` | `7` | 自动存档前的天数 |
| `CORTEX_DESKTOP_HOT_LIMIT` | `5` | 视口中热节点的 maximum 数 |
| `CORTEX_DESKTOP_HISTORY_LIMIT` | `10` | 历史记录的最大条目数 |
---
## 项目结构
```
.
├── docker-compose.yml ← 两项服务：cortex + qdrant
├── Dockerfile ← 多阶段，python:3.11-slim
├── .dockerignore
├── src/cortex/
│ ├── __init__.py — Cortex 工厂（组件组装）
│ ├── __main__.py — MCP 服务器入口点（stdio）
│ ├── config.py — 配置（pydantic-settings）
│ ├── db.py — 数据库管理器（SQLite）
│ ├── desktop.py — 桌面管理器（视口 + 时间线）
│ ├── graph.py — 图谱管理器（CRUD、导航、突变、时间轴）
│ ├── models.py — Pydantic 模型（节点、关系、视口）
│ ├── server.py — MCP 服务器（17 种工具，4 种资源）
│ └── vector.py — 向量管理器（Qdrant、嵌入、时间过滤器）
└── tests/
```
---
## 深入了解
| 文档 | 您将发现什么 |
|----------|-----------------|
| [`CONCEPT.md`](CONCEPT.md) | 完整的哲学、数据模型、节点分类法（17 种）、关系分类法（22 种）、SQL 架构 |
| [`ADR-001`](plans/ADR-001-fractal-memory.md) | 分形内存架构决策 |
| [`ADR-002`](plans/ADR-002-sqlite-graph.md) | 使用 SQLite + JSON 而非 Neo4j/Cayley 的图谱 |
| [`ADR-003`](plans/ADR-003-qdrant-vectors.md) | 使用 Qdrant 进行向量（现有） |
| [`ADR-004`](plans/ADR-004-fastembed.md) | 使用 fastembed 进行嵌入（paraphrase-multilingual-MiniLM-L12-v2） |
| [`ADR-005`](plans/ADR-005-desktop-viewport.md) | 桌面视口 —— 上下文窗口策略 |
| [`ADR-006`](plans/ADR-006-mutation-strategy.md) | 知识演化：更新 / 取代 / 过时 |
| [`ADR-007`](plans/ADR-007-regression-pattern.md) | 回归搜索：含义 → 上下文 → 文件 |
| [`ADR-008`](plans/ADR-008-temporal-layer.md) | 时间层 —— 时间作为一等公民 |
| [`CHANGELOG.md`](CHANGELOG.md) | 项目发布历史 |
| [`CONTRIBUTING.md`](CONTRIBUTING.md) | 开发指南 |
---
## 开发
```bash
# 原生安装（在 venv 内）
pip install -e .
pip install pytest pytest-asyncio
# 运行所有测试（188+ 测试）
pytest tests/ -v
# 带有覆盖率
pytest tests/ --cov=src.cortex -v
```
测试涵盖每个组件：模型（17）、配置（19）、数据库（26）、图谱（19）、桌面（14）、向量（19）、服务器（19）、集成（3）—— 总共 136+。
详见 [`CONTRIBUTING.md`](CONTRIBUTING.md) 了解指南。
---
## 许可证
MIT © 2026
