内容
# Rekall MCP
**给 Claude 一个具有联想记忆的记忆。** 三步，五分钟。
Rekall MCP 是一个持久性记忆系统，具有 **知识图谱** 层。它以 YAML + 向量嵌入的方式存储记忆，通过类型化的关系连接它们，并使用图增强的语义搜索来检索上下文。
---
## 本地优先代理神经系统
Rekall 为软件工作提供本地代理持久性、检查性、跨会话和跨项目的记忆。利用记忆存储助手偏好；Rekall 存储工作教给代理的内容：决策、根本原因、程序、危险区域和具有来源的项目熟悉度。
---
## 安装
### 试用 - 无 Docker，一条命令
```bash
claude mcp add rekall -- uvx rekall-mcp
```
这是试用层级：stdio 传输，嵌入式向量存储在 `~/.rekall/qdrant`，记忆以 YAML 形式存储在 `~/.claude/memory`。第一次运行下载约 90 MB 的嵌入模型（stderr 上显示进度）。没有钩子/自动捕获，一次一个会话 - 升级后每天分配一个时间段。
### 每天使用 - 一体化 Docker
```bash
docker run -d -v rekall-data:/data -p 127.0.0.1:8000:8000 ghcr.io/jfr992/rekall-mcp
claude mcp add --transport http rekall http://localhost:8000
```
一个容器，嵌入模型内置，数据存储在命名卷中。通过 `curl http://localhost:8000/health` 验证。
### 完整栈 - 编排（添加驾驶舱 UI）
```bash
git clone https://github.com/jfr992/rekall-mcp.git
cd rekall-mcp
docker compose up -d # Qdrant (:6333) + MCP 后端 (:8000) + 驾驶舱 (:3333)
claude mcp add --transport http rekall http://localhost:8000
```
数据存储在命名卷中（`rekall-memory`，`rekall-qdrant`）。现有安装的数据位于 `~/.claude/`，通过 `docker-compose.bind-mounts.example.yaml` 保留绑定挂载 - 请参阅 [docs/MIGRATION.md](docs/MIGRATION.md)。（`scripts/start-rekall.sh` 仍用于在开发过程中运行后端/UI。）
> **需要 Docker？** 在 [docker.com/get-started](https://www.docker.com/get-started) 上免费获取。
### 哪个层级？
| 层级 | 安装 | 传输 | 钩子 / 自动捕获 | 嵌入器 | 存储 |
| --- | --- | --- | --- | --- | --- |
| 试用 | `uvx rekall-mcp` | stdio | 否 | fastembed | 嵌入式 `~/.rekall/qdrant` + YAML `~/.claude/memory` |
| 每天（pip） | `uv tool install rekall-mcp && rekall serve` | HTTP 环路 | 是 | fastembed | 与试用版相同 |
| 每天（docker） | `docker run -v rekall-data:/data -p 127.0.0.1:8000:8000 ghcr.io/jfr992/rekall-mcp` | HTTP 环路 | 是 | fastembed（内置于镜像） | 命名卷 |
| 完整栈 | `docker compose up -d` | HTTP + 驾驶舱 | 是 | 按编排 | 外部 Qdrant 容器 |
试用层级诚实：没有钩子意味着没有自动捕获 - 您需要显式保存和回忆。过滤是线性的嵌入式扩展，只有单个进程可以持有嵌入式存储（运行 `rekall serve` 以便会话共享一个守护进程）。共享环境 `pip install` 不受支持；使用隔离安装（`uvx` / `uv tool install`）。
### 连接 Claude Code（钩子和配置）
MCP 服务器本身提供 Claude 记忆 *工具*；钩子使记忆 *自动化*。从存储库检出：
```bash
bash claude/setup/install.sh
```
幂等，备份 `~/.claude/settings.json` 首先。它连接四个钩子和九个斜杠命令：
| 钩子 | 事件 | 功能 | 关闭开关 |
| --- | --- | --- | --- |
| `rekall-restore.sh` | UserPromptSubmit | 一次会话状态行，无注入 | `REKALL_AUTOSAVE=0` |
| `rekall-observe.sh` | Stop | 受控 Haiku 评判器自动保存持久观察 + 发布会话摘要（馈送强化） | `REKALL_AUTOSAVE=0` |
| `rekall-reflex.sh` | PreToolUse（Bash） | 在风险命令之前显示相关记忆 | `REKALL_REFLEX=0` |
| `memory-prune.sh` | SessionStart | 每日受控修剪维护 | `REKALL_AUTOSAVE=0` |
可选第五个（手动，注入一个薄项目胶囊在会话开始）：`cp claude/hooks/session-start-memory.sh ~/.claude/hooks/` + 一个 SessionStart 条目 - 请参阅 [`claude/INSTALL.md`](claude/INSTALL.md)。
使用配置文件（`CLAUDE_CONFIG_DIR`）？安装程序以 `~/.claude` 为目标；重复设置项在每个配置文件的 `settings.json` 中（钩子文件可以通过绝对路径共享）。
推荐的 CLAUDE.md 代理策略（何时回忆，保存什么）：复制 [`docs/CLAUDE_MEMORY_SETTINGS.md`](docs/CLAUDE_MEMORY_SETTINGS.md) 中的块到您的 `~/.claude/CLAUDE.md`（全局）或项目 `CLAUDE.md` 中。
**完成。** Claude 现在使用会话之间的记忆 - 并在风险命令之前回忆它们。
---
## 如何使用
正常对话。Claude 自动记住：
- **决策** - “我们使用 PostgreSQL”
- **偏好** - “我更喜欢 TypeScript”
- **经验教训** - “那个 bug 是由...引起的”
检查记忆：*“你们记得这个项目什么？”*
### Python API
```python
from memory import MemoryManager
memory = MemoryManager()
# 保存（自动链接到知识图谱中的相关记忆）
memory.save("选择 PostgreSQL 支持 JSON", type="decision", project="my-app")
memory.save("用户更喜欢简洁的回应", type="preference")
# 回忆（图增强：向量搜索 + 关系遍历）
results = memory.recall("我们选择了什么数据库？")
for r in results:
print(f"[{r['score']:.2f}] {r['content']}")
# 项目上下文（扁平或分层）
context = memory.get_project_context("my-app")
```
### 命令行界面
```bash
# 保存
python -m memory.cli save "决定使用 PostgreSQL" --type decision --project my-app
# 回忆
python -m memory.cli recall "数据库选择"
python -m memory.cli recall "最近的工作" --limit 3 --days 7
# 统计信息
python -m memory.cli stats
```
#### 操作
| 动词 | 功能 |
| --- | --- |
| `rekall doctor [--project P] [--json]` | 健康检查 — 退出 0 健康，1 降级，3 不可达 |
| `rekall backup [--out DIR]` | 记忆 + Qdrant 归档；流式传输工件路径 |
| `rekall migrate [--dry-run] [--no-backup]` | 迁移到混合模式；默认先备份 |
| `rekall startup-preview [--project P]` | 预览 SessionStart 钩子将注入的内容（近似钩子输出；退出 3 如果后端不可达） |
| `rekall install-claude [--skills-only] [--hooks-only] [--skip-backend]` | 从存储库检出安装 Claude Code 包 |
软件评估：`uv run --extra dev pytest tests/test_software_evals.py`
实用程序报告：`uv run python scripts/utility_report.py`
冲突边缘修复：`QDRANT_URL=... uv run python scripts/repair_contradicts.py` - 重新判断未精炼的 `contradicts` 边，默认干燥运行（请参阅 [docs/TUNING.md](docs/TUNING.md)）
---
## 知识图谱
每个记忆都是一个节点。关系是自动创建的类型化边：
| 关系 | 含义 | 示例 |
| --- | --- | --- |
| `related_to` | 语义相似 | 两个 PostgreSQL 事实 |
| `led_to` | 时间因果关系 | 决策导致学习 |
| `depends_on` | 结构依赖 | 决策依赖于需求 |
| `supersedes` | 更新替换旧 | 更新决策覆盖旧决策 |
| `contradicts` | 对立内容 | 冲突记忆 |
### 图增强回忆
回忆使用一个三阶段管道而不是扁平的余弦搜索：
```
1. SEED - 向量搜索（前 K x 2 个候选）
2. EXPAND - 遍历种子结果的 1 跳图邻居
3. RANK - 综合：向量（40%）+ 重要性（20%）+ 邻近度（15%）+ 层级（15%）+ 最近度（10%）
```
这找到 *结构相关* 的记忆，而不仅仅是文本相似的记忆。当图为空时，退回到纯向量搜索。
### 新鲜度 - 读取时的冲突检测
当同一记忆类型出现在结果集中时，Rekall 通过图边和存储的向量余弦（θ ≥ 0.9）检测冲突条目。`recall_formatted` 输出以最新条目为第一顺序渲染；过时条目折叠为一个占位行，以便代理仅对当前信息采取行动。不会删除数据 - 检测是短暂的，完全在读取时发生。
### 驾驶舱 UI
在 `http://localhost:3333/brain` 浏览知识图谱 - Next.js 驾驶舱作为容器启动，由 `docker compose up -d` 与 Qdrant 和后端一起启动。（对于 UI 开发，`cd ui && npm run dev -- -p 3333` 仍然有效。） 表面：
- `/brain` - 受力图视图，节点是记忆，边显示类型化关系
- `/kb` - 类型列（决策、需求、偏好、学习），以及 **导出 OKF** 选项卡，将记忆提炼成可移植的 [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) 包
- `/continuity` - 简历数据包和交接摘要
- `/hygiene` - 压力指标，修剪流程，生命周期回填
---
## Claude Code 包（可选）
上述三容器堆栈通过 MCP 工具为 Claude 提供记忆。`claude/` 包添加 Claude Code 集成层 - 自动保存钩子、斜杠命令和推荐的记忆策略。所有这些都是可选的；没有任何自动加载。
### 一次性安装
```bash
bash claude/setup/install.sh
```
幂等，备份现有的 `~/.claude/settings.json` 首先。它：
- 复制四个钩子到 `~/.claude/hooks/` (`rekall-restore`, `rekall-observe`, `rekall-reflex`, `memory-prune`)
- 合并 `UserPromptSubmit`, `Stop`, `SessionStart` 和 `PreToolUse`（Bash 匹配器）条目到 `~/.claude/settings.json`（去重；修复错误/缺少反射匹配器）
- 复制所有九个斜杠命令到 `~/.claude/skills/`
- 验证后端健康
**重启您的 Claude Code 会话**，然后加载斜杠命令。随时从 Claude Code 内部通过 `/rekall-setup` 重新运行。完整的手动步骤和标志（`--skills-only`、`--hooks-only`、`--skip-backend`）位于 [`claude/INSTALL.md`](claude/INSTALL.md)。
### 钩子（自动保存层）
- **`rekall-restore.sh`**（UserPromptSubmit）- 一次会话状态行（`Rekall ready — N 记忆…`）。无上下文注入。
- **`rekall-observe.sh`**（Stop）- 一个 Haiku 评判器自动保存持久观察，受控于廉价信号检测（耐久性关键词、新 git 提交或会话长度），因此它不会在每个回合触发。 关闭开关：`REKALL_AUTOSAVE=0`。
- **`rekall-reflex.sh`**（PreToolUse，Bash）- 在风险命令之前显示相关记忆（破坏性操作，IaC，记忆数据，钩子，helm）。本地单词边界提示匹配控制检索（无网络错误），每会话每个提示一次回调。 在匹配时，它执行一个受限的 `curl`（0.1s 连接 / 1s 总计）到 `/api/memory/reflex` 并注入一个有上限的、不受信任的框架作为 `additionalContext`。它永远不会阻止工具调用 - 每个失败路径都退出 0。 关闭开关：`REKALL_AUTOSAVE=0`（主）或 `REKALL_REFLEX=0`（专用）。
### 斜杠命令（手动，不会自动触发）
| 斜杠命令 | 功能 |
| --- | --- |
| `/memory-observe <note>` | 手动保存并自动分类 |
| `/memory-recall <query>` | 图增强语义搜索 |
| `/memory-restore` | 手动上下文恢复（重要性排名） |
| `/memory-stats` | 健康检查 + 图谱指标 |
| `/memory-rebuild` | 重建知识图谱 |
| `/memory-consolidate` | 检测重复和矛盾的记忆 |
| `/memory-skills` | 显示从记忆集群中提取的技能 |
| `/rekall-publish` | 导出记忆到 OKF 知识包 |
| `/rekall-setup` | 从 Claude Code 内部重新运行包安装程序 |
### 推荐的 CLAUDE.md 策略
为了让代理有效使用记忆 - 在会话开始时调用 `get_cached_context()`，谨慎保存 - 复制 [`docs/CLAUDE_MEMORY_SETTINGS.md`](docs/CLAUDE_MEMORY_SETTINGS.md) 中的块到您的 `~/.claude/CLAUDE.md`（全局）或项目 `CLAUDE.md` 中。
---
## 您的数据
所有内容都存储在您的计算机的可编辑文件中：
```
~/.claude/memory/
<project>/
2026-02-02.yaml <- 人类可编辑的记忆（每个项目嵌套）
_graph.json <- 知识图谱（自动管理）```
不发送任何内容。备份 = 复制文件夹。
在存储之前自动清理凭证：
```
输入：`Set api_key to sk-abc123def456`
存储：`Set api_key to [REDACTED]`
```
### 安全非本地部署
服务器默认绑定 `127.0.0.1`，并且 **未经身份验证** - 信任模型是 localhost。Docker 在容器内设置 `HOST=0.0.0.0`（需要端口映射）；编排将端口仅映射到 localhost。如果您故意将服务器公开暴露在网络上（`HOST=0.0.0.0` 在裸金属上），请启用 bearer auth：
```bash
export REKALL_API_TOKEN=$(openssl rand -hex 32) # 在服务器上
```
设置后，除 `/health` 之外的每个请求都需要令牌。指向它：
```bash
# Claude Code
claude mcp add --transport http rekall http://localhost:8000 \
--header "Authorization: Bearer $REKALL_API_TOKEN"
# 驾驶舱：ui/.env.local
echo "NEXT_PUBLIC_REKALL_API_TOKEN=$REKALL_API_TOKEN" >> ui/.env.local
```
内存类型
| 示例 | AI 行为 | 重要性 |
|------|---------|-------------|------------|
| `requirement` | "必须使用3.11+" |** 遵循 | 1.0 |
| `decision` | "选择 PostgreSQL" | 参考，可以重新审视 | |
| `pre | "倾向于 Terraform建议，提供替代方案 | 0.75 |
| ` | "JWT 错误修复 应用于类似案例 | 65 |
| `fact "项目使用 AWS"景上下文 | 0.55 |
| `note` |观察" | 低优先级上下文 | 0.35 |
session` | 会话摘要连续性上下文 | |
`summary`一个有效的类型 — 由内存（`POST /api`），不由手动保存。
### MCP 工具
| 工具 | 用途 |
|------|---------|
| `observe(summary)` | 自动分类和保存（接受调用者的 `cwd` 作为项目范围） |
| `recall_memories(query, task_hint_id?)` |增强的语义搜索；`task_hint`（2 个以上单词）优先显示与匹配 |
| `recall_across_projects(query, current_project)` | 跨项目、相关项目和全局内存的跨项目转移回忆 |
| `close_loop(memory_id` | 关闭一个循环：追加一个 RES 时间戳，将其从 Open Loops 胶囊桶中删除 `save_memory(content, | 显式类型手动|(memory_id)` | 单个内存 + 邻居 + 范| `memory_kb(project)` | 类型切片 / 需求 / 偏好 / 学习） `memory_pressure(project)` | 压力指标 + 标记候选者 |
| `memory_pressure_snapshot()` | 详细的压力快照 |
| `prune_plan(project, limit)` | 构建修剪计划（仅通过 REST 应用） |
| `backfill_lifecycle(project,)` | 现有内存的层级元数据回填 |
| `resume_packet | 连续性恢复 |
| `handoff_summary(project)` |性总结 |
| `agent_startup(project)` | 统一启动负载 |
| `project_capsule(project)` | 薄项目熟悉囊 |
| `publish_team_memory(project)` | 提炼的项目胶囊和剧本的团队安全包 |
| `reflex_re, project, session_id?)` | 在风险命令或编辑前触发回忆 |
| `memory_lifecycle()` | 行为分类器输出 |
| `memory_do)` | YAML/Qdrant/vector/graph/源健康信任报告 `get_cached_context(project)` | 平坦上下文（提示| `get_hierarchical_context(project)` | 主题分组上下文树 |
| `skill_context()` | 从内存集群中提取的技能 |
| `memory_stats()` | 健康 +指标 |
| `cons_memories()` |和| `proactive_context_summary()` | 按重要性 x 时间排名的信号 |
| `rebuild_knowledge_graph()` | 从所有现有内存中重建图 |
| `publish_memory(project, format)` | 将内存导出到 OKF 知识包 |
| `list_available_tools()` | 列出已注册的工具提供者和状态 |
| `lemetry_summary()` |调用遥测### 团队内存团队内存发布会发出的项目胶囊和剧本摘要。它会从生成的去已知的原始、会话记录、私人子负载字段，但这不是内容编辑传递：分享前请查看胶囊/剧本文本。默认情况下，请保留。
### REST API
点 | 方法 | 用----------|--------|---------|
health` | GET | |
| `/api/memory/save` | POST | 保存内存 |
| `/api/memory/recall POST | 图形（可选 `task_hint`：优先显示上下文匹配的结果；可选 `cwd`：将回忆事件归因于调用者的可选 `session_id`：传递到 `memory_recalled） |
| `/apiall/cross-project` 跨项目转移| `/api/memory/ref POST | 用于风险编辑的触发回忆数据包（可选 `cwd`：将回忆事件归因于调用者的项目；可选 `session_id`：传递到 `memory_re 事件） |
|/memory/observe` | 自动分类和保存（cwd` 作为范围） |
api/memory/stats` | GET | 统计数据形指标 |
| `//doctor` | GETdrant/vector/graph/源健康信任报告 |
api/memory/projects` | GET | 项目列表 + 内存 `/api/memory/context` | GET | 平坦项目上下文 |
| `/api/memory/context/hierarchy` | GET | 主树（`=N` 用于日期过滤| `/api/memory/context GET | 标记智能上下文（`?max_tokens=`） |
| `/api/memory/context/proactive | 信号冲突检测 |
| `/api/memory/context/skills` | GET | 从内存集群中推断的技能上下文 |
| `/api/memory/context/startup` | GET | 统一代理启动负载 |
| `/api/memory/capsule` | GET | 薄项目熟悉度胶囊 |
| `/api/memory/by-entity` | GET | 实体反向链接：内存的 `entities` 包含 `?entity=`（不区分大小写；`?project=&limit=`) |
| `/api/memory/detail/{id}` | GET | 完整的内存 + v2 块：关系（进出方向）、源、生命周期、存储、警告；`neighbors` 别名为向后兼容 |
| `/api/memory/kb` | GET | 类型切片 |
| `/api/memory/pressure GET | 压力 标记候 |
| `/api/memory` | GET | 数据包 |
| `/api/memory/prune/plan` | POST | 构建修剪计划（计划 ID，15，200 删除 |
| `/api/memory` | POST类型 ID 确认应用限 REST） `/api/memory/pruneeded` | POST | 超过时的内存自动修剪（牌，≤10 次/次，≤20天，先备份；仅限 |
| `/ifecycle/backfill` | POST | 层级元数据回填（干预运行 + 执行） |
| `/api/memory/resparse` | POST | 事务性 BM词汇表重装拒绝模式/奇偏差，中断时失效（仅） |
| `/api/memory/{id}` | DELETE | 删除单个内存 |
| `/api/memory/{id` | POST |/撤销身份固定（`{pinned: bool}`；仅限人类，MCP 工具不可用） |
| `/api/memory/{` | POST | 清除（或设置）争议标志（`{disputed: bool}`；最小解决权限） |
| `/api/memory/cleanup` | POST | 批量清理（修剪过期，基于年龄） |
| `/api/memory/graph` | GET | 图形可视化数据 |
| `/api/memory/graph/rebuild` | POST | 重建知识图 |
| `/api/memory/consolidate` | GET | 检测过期/冲突对 |
| `/api/memory/recall/quick` | GET | 用于每提示注入的快速高阈值回忆 |
|/memory/compact` | LLM 提炼（默认干预运行） |
| `/api/memory` | GET, 将内存导出到 v0.1 包（`mode=preview\|tar\|dir`） |
| `/api/memory/publish/synthesize` | POST | 为项目范围启动（或报告）后台 LLM 合成作业 |
| `/api/memory/publish/status` | GET | 轮询合成作业的进度 |
| `/api/memory/events` | GET, POST | GET：光标分页事件（`cursor=&limit=`，安全截POST：追加客户端事件 |
| `/api/memory/review` | POST |决（`keep\|kill`kill` 删除然后记录，`fix` 是 直到 U3| `/api/memory` | GET | 会话透明度列表从事件折叠（`?limit`?project=` 限定为一个项目，包括其无属性桶，缺失或 `all` = 每个项目；`after`` 是包含 `YYYY-MM-DD` 日期界会话上一次活动的；`window` =部上限；`.oldest_at` 标记折叠截断的位置；发出 `view_opened`） |
|/memory/sessions/{id GET | 完整：注入内存 + 回片与分数；回忆在 `unattproject>` 下 |
api/memory/feedback` | 一键回忆`useful\|wrong\|`）→ `memory_feedback` 事件；仅标记证据，不读取排名 |
| `/api/memory/insights` | GET | 驾驶舱聚合（project=`）：总数计数，7 天回忆/错过/晋升与诚实分母级计数；`` = 有界事件尾部截断信息 |
api/memory/stream` | GET | 最新活动提要（`?project=&limit=&after=&before=`）：`recalled\|promconsolidated` 行记录 + 有界事件尾部合并；`after`/`before` 是包含 `YYYY-MM-DD` 日期界`event_window.old` 标记回忆/行截断的位置；工作层保存携带 `fades_in_hours` |
</details>
---
<details>
<summary>面向开发者</b></summary>
### 本
```bash
pip install -e ".[dev]"
docker compose up -d qdrant
cd src && MCP_TRANSPORT=streamable-http python -m server
```
### 测试
测试在隔离环境中运行，**不会影响生产数据**。
```bash
# 运行所有测试（快速，当地）
uv run --extra dev pytest -v
# 运行所有测试（隔离 Docker）
docker compose --profile test run --rm test
# 运行特定测试文件
docker compose --profile test run --rm test pytest tests/test_memory.py# 清理
docker compose --profile test down发生了什么： `qdrant-test 6334 上启动，使用临时 tmpfs- 测试使用 `/tmp/test_memory` 进行 YAML 文件内）
- 生产数据位于 `~/./memory/` 和 `~/.claude/qdrant/`，保持不变
- 测试结束后，所有内容自动删除
### 项目结构
```
src/
├── server.py # MCP 服务器 + REST API 端点
├── core/ 嵌入向量存储、遥测、实用工具
│ └── utils.py _hash_id() 用于字符串到 int64 ├── memory/
│ ├── manager.py #管理器（保存、获取统计信息）
│ ├── knowledge_graph.py # 知识图（networkx DiGraph，持久性）
│ ├── linker.py # 自动链接时分类关系
│ .py # 可视化图形构建器
│ ├── cache_context.py # 稳定可缓存上下文 + 分层变体
│ ├── topics.py # 主题自动分类（凝聚聚类）
│ └── skills.py # 从内存集群中提取技能 crawler/ # 文档爬虫（Scrapy）
├── indexer/ # 文档分块器 + Qdrant 索引器
└── tools/ # MCP 工具```
### 文档
| 文档 | 用途 |
|-----|---------|
| [docs/ARCHITECTURE.md/ARCHITECTURE.md) | 技术设计，知识| [docs/SETUP.md](docsUP.md) | 设置，嵌入式提供者，迁移 |
| [docs/TUNING.md](docs/TUNING.md) | 自定义 Claude 记忆的内容 |
| [claude/INSTALL.md](claude/INSTALL.md) | Claude 代码包：技能和钩子安装 |
| [docs/CLAUDE_MEMORY_SETTINGS.md](docs/CLAUDE_MEMORY_SETTINGS.md) | Claude 特有的策略和调整旋钮 |
| [docs/MIGRATION.md](docs/MIGRATION.md) | 版本升级说明 |
</details>
---
## 需求
- Docker（或 Python 3.11+）
- [uv](https://docs.astral.sh/uv/)（用于贯穿整个过程的 `uv run）
- ~500MB 磁盘（首次下载嵌入式- macOS， Windows（WSL）
---
## 许可证
Apache-2.0
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器