jcartu/rasputin-memory

# RASPUTIN Memory v0.9  [](https://github.com/jcartu/rasputin-memory/actions/workflows/ci.yml) [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) 一个用于 AI 代理的本地长期记忆后端。RASPUTIN 将对话存储为 重叠窗口和 LLM 提取的事实，存储在 Qdrant 中，使用 Qwen3-Reranker 进行重排序， 通过 SQLite FTS5 进行 BM25 关键词搜索，支持每问提示路由，并为 Claude Code、Cursor 以及任何 MCP 兼容客户端提供原生 MCP 支持。 适用于 AI 代理的生产级长期记忆： - **MCP 服务器**，支持 Claude Code、Cursor、Codex 及任意 MCP 客户端（FastMCP 3.2，streamable-http） - **LLM 记忆合成**（`/reflect`）——检索记忆并综合生成连贯回答 - 向量搜索（Qdrant），采用双通道检索（窗口 + 事实） - BM25 关键词搜索（SQLite FTS5）结合递归倒数排名融合 - 摄入时进行 LLM 事实提取 - Qwen3-Reranker-0.6B 基础模型重排序（GPU，0.99/0.0001 分数分离） - 每问提示路由（推理/事实/时间） - 提交时的 A-MAC 质量门禁 - 知识图谱（FalkorDB）结合实体提取 - 142 个测试，30 多项使用科学方法的消融实验 API 服务器：`[tools/hybrid_brain.py](tools/hybrid_brain.py)` — MCP 服务器：`[tools/mcp/server.py](tools/mcp/server.py)` ## 架构概述 ``` MCP Client (Claude Code / Cursor / any MCP client) │ └─► tools/mcp/server.py (port 8808, FastMCP 3.2) 6 tools: store, search, reflect, stats, feedback, commit_conversation │ └─► HTTP proxy ─► tools/hybrid_brain.py (port 7777) Memory Commit │ ├─► A-MAC quality gate (relevance/novelty/specificity) ├─► 5-turn overlapping windows (stride 2) ├─► LLM fact extraction (Haiku or local model) ├─► Embedding (nomic-embed-text, 768d) └─► Persist to Qdrant Search │ ├─► Multi-Query Expansion ├─► Query Embedding (nomic-embed-text, 768d) │ ├─► Lane 1: Window search (45 slots) ──┐ ├─► Lane 2: Fact search (15 slots) ──┤ ├─► Lane 3: BM25 keyword (FTS5, 10) ──┼─► RRF Fusion ─► Qwen3-Reranker-0.6B ─► Top-60 to LLM │ │ └─► Answer Prompt Routing ──────────────┘ (inference / factual / temporal) Reflect (LLM Synthesis) │ ├─► hybrid_search(query, limit=20) ├─► Format top memories as context ├─► LLM call (Anthropic or Ollama) └─► Coherent synthesized answer + source citations ``` ### 核心组件 - API 服务器：`tools/hybrid_brain.py` - MCP 服务器：`tools/mcp/server.py`（轻量 HTTP 代理，FastMCP 3.2） - LLM 综合：`tools/brain/reflect.py` - 事实提取：`tools/brain/fact_extractor.py` - 交叉编码器重排序：`tools/brain/cross_encoder.py` - 维护任务：`tools/memory_decay.py`、`tools/memory_dedup.py` ## 对比分析 | 功能 | RASPUTIN | Mem0 | Zep | LightRAG | |------|----------|------|-----|----------| | MCP 协议支持 | ✅ FastMCP 3.2 | ❌ | ❌ | ❌ | | LLM 记忆合成 | ✅ `/reflect` | ❌ | ❌ | ❌ | | 向量搜索 | ✅ Qdrant | ✅ | ✅ | ✅ | | BM25 关键词搜索 | ✅ SQLite FTS5 + RRF | ❌ | ❌ | ❌ | | LLM 事实提取 | ✅ | ❌ | ❌ | ❌ | | 双通道检索 | ✅ 窗口 + 事实 | ❌ | ❌ | ❌ | | 基础模型重排序 | ✅ Qwen3-Reranker-0.6B（GPU） | ❌ | ❌ | ❌ | | LLM 质量门禁 | ✅ A-MAC | ❌ | ❌ | ❌ | | 矛盾检测 | ✅ | ❌ | ❌ | ❌ | | 本地部署 / 无供应商锁定 | ✅ | ✅ | ❌（SaaS） | ✅ | ## 基准测试 在 [LoCoMo](https://github.com/snap-research/locomo)（ACL 2024）上进行评估。完整 10 轮对话数据集 （1986 个问答对）。两种基准模式：生产（Haiku 回答，严格评判器——衡量检索质量） 和对比（Haiku 回答，宽松评判器——与现场环境可比）。 ### LoCoMo 完整 10 轮对话（v0.9 — 当前） | 模式 | 非对抗性 | 问题数 | |------|----------------|-----------| | **对比（现场可比）** | **77.7%** | 1540 | | 生产（检索信号） | **74.2%** | 1540 | | 类别 | 生产 | 对比 | 问题数 | 说明 | |----------|-----------|---------|-----------|-------| | 开源领域 | 84.8% | 83.2% | 841 | 比 v0.8 提升 +2.9pp | | 时间性 | 71.3% | 75.4% | 321 | 比 v0.8 提升 +6.5pp | | 单跳 | 54.3% | 68.1% | 282 | 比 v0.8 提升 +17.1pp — Qwen3 CE 带来的最大提升 | | 多跳 | 49.0% | 64.6% | 96 | 生产模式比 v0.8 下降 -6.2pp（详见说明） | | 对抗性 | 13.0% | 23.1% | 446 | 非优化目标 | **宽检索池选项：** 设置 `BENCH_LANE_WINDOWS=75 BENCH_LANE_FACTS=25` 可用于以单跳为主的工作负载。牺牲开环域（-1.2pp）换取单跳（+4.2pp，58.5%）。总体保持在 74.1%。详见下文 [检索池调优](#retrieval-pool-tuning)。 **多跳说明：** 多跳在生产模式中下降（55.2% → 49.0%），因为 Qwen3 重排序器更擅长排序，这有助于排序主导的类别（单跳 +12.8pp，开环域 +3.0pp），但略微损害检索主导的类别（黄金内容不在候选池中）。对比模式数值（64.6%）更高，因为宽松评判器会给予部分答案认可。我们的检索分析显示，86% 的多跳失败是由于检索遗漏（黄金未出现在任何分块中），而非排序失败——重排序器无法修复检索未找到的内容。 ### 已测试内容（30+ 实验） | 实验 | 结果 | 状态 | |-----------|--------|--------| | **Qwen3-Reranker-0.6B** | **生产 +4.5pp，对比 +8.6pp** | ✅ 已发布（v0.9） | | **BM25 FTS5 + RRF 融合** | **配合 Qwen3 CE 提升 +0.6pp** | ✅ 已发布（v0.9） | | **宽检索池（75w+25f）** | **单跳 +4.2pp，开环域 −1.2pp** | ✅ 可选项（v0.9） | | 提示路由（推理/事实/时间） | 完整 10 轮对话 +1.6pp | ✅ 已发布（v0.8） | | 双通道搜索（窗口 + 事实） | 整体 +6.5pp | ✅ 已发布（v0.7） | | 交叉编码器重排序 | 双通道检索的关键 | ✅ 已发布（v0.7） | | 仅窗口分块（w5s2） | +5.2pp | ✅ 已发布（v0.7） | | 流水线精简（700 → 427 行） | 0pp 变化，代码更清晰 | ✅ 已发布（v0.8） | | BM25 配合 L-6 CE（3 种变体） | −14pp 至 −28pp | ❌ CE 过滤能力过弱 | | 整合（6 种变体） | 整体为负，所有配置 | ❌ 暂停 | | 图谱扩展（kNN 链接） | −.4pp | ❌ 暂停 | | 实体搜索（3 种变体） | −10pp 至 −14pp | ❌ 暂停 | | CE L-12 交叉编码器 | 单跳 −12.6pp | ❌ 已回滚 | | 对比模式使用 gpt-4o-mini 答案 | 相比 Haiku 下降 −10.8pp | ❌ Haiku 更优 | | 嵌入升级（Qwen3 768d，4096d） | 0pp 或更差 | ❌ 无提升 | 完整实验记录位于 `experiments/`。 ### 基准测试方法论说明 不同记忆系统的已发布 LoCoMo 分数不可直接比较。每个系统测量的内容不同，使用的模型不同，且在不同条件下报告。 **各系统变化的变量：** | 变量 | 对分数的影响 | 示例 | |------|----------------|---------| | 答案生成模型 | GPT-4o 与 Haiku 相差约 20pp | 强大的模型可以弥补检索不足 | | 评判器宽松度 | “宽松”与中性相差约 5-10pp | 宽松评判器宽容模糊答案 | | 上下文窗口大小 | 60 个分块对比 10 个：约 15pp | 更多上下文意味着排序不重要 | | 指标类型 | 检索召回率对比答案准确性 | 本质上不同的测量 | **各系统实际测量的内容：** | 系统 | 指标 | 测试内容 | |--------|--------|---------------| | MemPalace | 检索召回率 | 是否找到正确证据（无答案生成，无 LLM） | | LoCoMo 原始 | Token F1 | 对照标准答案的答案质量（无 LLM 评判） | | AMB/事后验证 | LLM 评判准确性 | 端到端：检索 + 答案 + LLM 评估 | | RASPUTIN | LLM 评判准确性 | 端到端，使用公开的方法论 | | Memvid | LLM 评判（声称） | 方法论未公开 | 例如，MemPalace 的 96.6% LongMemEval 分数是一个检索召回率指标——它衡量系统是否找到了正确的段落，而不是是否生成了正确答案。这是一个有效且有用的指标，但无法与其他系统的答案准确性分数直接比较。 同样，使用 GPT-4o 或 Claude Opus 生成答案的系统主要衡量的是 LLM 能力，而非检索质量。一个强大的模型可以从大型、排序不佳的上下文窗口中提取正确答案——这正是我们的消融实验所证明的：在 60 个分块的上下文中，整个排序流水线（BM25、关键词增强、实体增强、Cohere 重排序、交叉编码器重排序）贡献为 0pp，因为答案模型补偿了这一点。 **RASPUTIN 的方法论完全公开：** - 生产模式：Claude Haiku 答案 + 严格评判器（隔离检索质量） - 对比模式：Claude Haiku 答案 + 宽松评判器（与现场环境可比的基线） - 评判模型固定为 `gpt-4o-mini-2024-07-18`（防止版本漂移） - 所有基准代码、评判提示和实验结果均在本仓库中 我们以生产模式数字作为主要报告，因为它反映了实际的检索质量。对比模式数字提供与其他系统的粗略参考，但需注意方法论差异使得直接比较最多只是近似。 要实现标准化比较，我们推荐使用 [Agent Memory Benchmark](https://github.com/vectorize-io/agent-memory-benchmark)（AMB），它在相同条件下评估所有系统，并使用公开的评判提示。 | 系统 | 报告分数 | 基准 | 方法论 | |--------|---------------|-----------|-------------| | Hindsight | 92.0% | LoCoMo | AMB 框架，公开方法论 | | Backboard | 90.00% | LoCoMo | GPT-4.1，宽松评判器 | | MemMachine | 84.87% | LoCoMo | 未公开 | | **RASPUTIN（对比）** | **77.7%** | **LoCoMo 完整 10 轮对话** | **Haiku 答案，宽松评判器** | | Memobase | 75.78% | LoCoMo | 未公开 | | Zep | 75.14% | LoCoMo | 未公开 | | **RASPUTIN（生产）** | **74.2%** | **LoCoMo 完整 10 轮对话** | **Haiku 答案，严格评判器** | | mem0 | 66.88% | LoCoMo | 未公开 | † 仅 RASPUTIN 和 Hindsight 公开了完整的评估方法、评判提示和实验数据。其他分数在未公开条件下自报。请参阅下文 [基准方法论](#on-benchmark-methodology) 了解这些数字为何不可直接比较。 ## 流水线 ``` nomic-embed-text (768d) → Two-lane search (windows + facts) + BM25 FTS5 → RRF fusion → Qwen3-Reranker-0.6B → Haiku → gpt-4o-mini judge ``` 请参阅 `benchmarks/README.md` 了解如何运行基准测试并复现数字。参阅 `experiments/` 获取完整的消融程序和科学记录。 ## 快速开始 ### 1) 基础设施（Docker Compose） ``` docker compose up -d ``` 这将启动 Qdrant 和 FalkorDB。 ### 2) Python 环境设置 ``` python3 -m venv .venv source .venv/bin/activate pip install -r requirements-core.txt ``` ### 3) 启动 API 服务器 ``` python3 tools/hybrid_brain.py ``` 服务器默认运行在 `http://127.0.0.1:7777`。 ### 4) 启动 MCP 服务器（可选 — 用于 Claude Code、Cursor 等） ``` pip install "fastmcp>=3.2.0" python3 tools/mcp/server.py # MCP 服务器地址 http://127.0.0.1:8808/mcp # 连接 Claude Code: claude mcp add --transport http rasputin http://localhost:8808/mcp ``` ### 5) 烟雾测试 ``` curl http://localhost:7777/health curl "http://localhost:7777/search?q=test&limit=3" curl -X POST http://localhost:7777/commit \ -H 'Content-Type: application/json' \ -d '{"text":"Rasputin memory test event happened on 2026-03-01.","source":"conversation"}' ``` ## 配置参考（`config/rasputin.toml`） 运行时加载器读取此 TOML 并允许环境变量覆盖（参见 `tools/config.py`）。 ### `[server]` - `host`（字符串）：绑定主机 - `port`（整数）：API 端口 ### `[qdrant]` - `url`（字符串）：Qdrant 基础 URL - `collection`（字符串）：活跃内存集合 ### `[graph]` - `host`（字符串）：FalkorDB 主机 - `port`（整数）：FalkorDB 端口 - `graph_name`（字符串）：图键 - `disabled`（布尔值）：禁用图谱搜索路径 ### `[embeddings]` - `url`（字符串）：嵌入端点 - `model`（字符串）：嵌入模型名称 - `prefix_query`（字符串）：查询嵌入前缀 - `prefix_doc`（字符串）：文档嵌入前缀 ### `[reranker]` - `url`（字符串）：重排序端点 - `timeout`（整数）：超时秒数 - `enabled`（布尔值）：启用重排序阶段 ### `[amac]` - `threshold`（浮点数）：低于此综合分数时拒绝 - `timeout`（整数）：评分超时秒数 - `model`（字符串）：用于准入评分的模型 ### `[scoring]` - `decay_half_life_low`（整数） - `decay_half_life_medium`（整数） - `decay_half_life_high`（整数） ### `[constraints]` - `enabled`（布尔值）：在提交时启用隐式约束提取 - `model`（字符串）：用于约束提取的 LLM 模型 - `timeout`（整数）：提取超时秒数 ### `[reflect]` - `provider`（字符串）：用于综合的 LLM 提供者（`anthropic` 或 `ollama`） - `model`（字符串）：模型名称（默认 `claude-haiku-4-5-20251001`） - `max_tokens`（整数）：综合答案的最大令牌数（默认 `1000`） ### `[entities]` - `known_entities_path`（字符串）：实体字典 JSON 路径 ### 检索池调优 默认检索池每次查询获取 45 个窗口 + 15 个事实 + 10 个 BM25 关键词 = 每种查询变体 70 个候选。Qwen3-Reranker 从中选择最佳的 60 个供答案模型使用。 对于以单跳事实性问题为主的工作（例如“Alice 的工作是什么？”、“Bob 住在哪里？”），更宽的检索池可以提高准确性，因为重排序器有更多候选项可供选择： ``` export BENCH_LANE_WINDOWS=75 # default: 45 export BENCH_LANE_FACTS=25 # default: 15 ``` | 配置 | 整体 | 单跳 | 开环域 | 时间性 | |------|---------|------------|-------------|----------| | 默认（45w+15f） | **74.2%** | 54.3% | **84.8%** | **71.3%** | | 宽（75w+25f） | 74.1% | **58.5%** | 83.6% | 70.4% | 更宽的池子会以约 1pp 开环域为代价，换取约 4pp 单跳。应在用户提问的具体事实性问题多于广泛开环域问题时使用。总体准确率保持不变。 两种配置均使用相同的 Qwen3-Reranker 和 BM25 FTS5 流水线——仅初始候选项数量不同。 ## API 参考 所有响应均为 JSON。 ### `GET /health` 返回服务健康状态和组件状态。 ``` curl http://localhost:7777/health ``` ### `GET /search?q=&limit=&source=&expand=` 混合检索端点。 ``` curl "http://localhost:7777/search?q=payment+issue&limit=5" ``` ### `POST /search` 基于请求体的搜索变体。 ``` curl -X POST http://localhost:7777/search \ -H 'Content-Type: application/json' \ -d '{"query":"project timeline","limit":5,"expand":true}' ``` ### `POST /commit` 在质量检查和重复检查后提交记忆。 ``` curl -X POST http://localhost:7777/commit \ -H 'Content-Type: application/json' \ -d '{"text":"Vendor contract moved to April 12 with revised pricing.","source":"conversation","importance":75}' ``` ### `GET /graph?q=&limit=&hops=` 直接图谱查询。 ### `GET /stats` Qdrant 和图谱计数摘要。 ### `GET /amac/metrics` A-MAC 准入计数器和拒绝统计。 ### `GET /contradictions?limit=` 列出存储的矛盾记录。 ### `POST /proactive` 返回基于最近上下文的前瞻性记忆建议。 ``` curl -X POST http://localhost:7777/proactive \ -H 'Content-Type: application/json' \ -d '{"messages":["We are discussing launch timelines"],"max_results":3}' ``` ### `POST /commit_conversation` 对多轮对话进行自动窗口分块并提交。 ``` curl -X POST http://localhost:7777/commit_conversation \ -H 'Content-Type: application/json' \ -d '{"turns":[{"speaker":"Alice","text":"I got a promotion today!"},{"speaker":"Bob","text":"Congratulations!"}],"source":"conversation","window_size":5,"stride":2}' ``` ### `POST /reflect` 检索相关记忆并通过 LLM 综合生成连贯回答。 ``` curl -X POST http://localhost:7777/reflect \ -H 'Content-Type: application/json' \ -d '{"q":"What do we know about the auth service?","limit":20}' ``` 返回 `{"answer": "...", "sources": [...], "search_elapsed_ms": ..., "reflect_model": "..."}`。 ### `POST /feedback` 更新检索有用性信号。 ``` curl -X POST http://localhost:7777/feedback \ -H 'Content-Type: application/json' \ -d '{"point_id":123,"helpful":true}' ``` ## 开发指南 ### 本地工作流 ``` # lint ruff check . # type check mypy tools/hybrid_brain.py tools/bm25_search.py --ignore-missing-imports # unit tests (default suite) pytest tests/ -k "not integration" -v # integration tests (Qdrant required) pytest tests/test_integration.py -v ``` ### 安全添加功能 1. 在 `tests/` 中添加/更新测试 2. 尽可能保持 API 向后兼容 3. 优先使用 `config/rasputin.toml` 和环境变量覆盖 4. 提交前进行代码检查、类型检查和测试 ## 测试说明 ### 单元测试 ``` pytest tests/ -k "not integration" -v ``` ### 集成测试 ``` pytest tests/test_integration.py -v ``` ### 覆盖率 ``` pytest tests/ --cov=tools --cov-report=term-missing ``` 覆盖率阈值为 `pyproject.toml` 中配置的 `fail_under = 55`。 测试统计：106 个核心流水线 + 22 个 MCP 服务器代理 + 14 个 reflect 模块 = **142 个测试**。 ## 版本说明 ### v0.9.0 - **Qwen3-Reranker-0.6B**：取代 ms-marco-MiniLM-L-6-v2 的基础模型重排序器 — 生产模式提升 +4.5pp，对比模式提升 +8.6pp - **BM25 关键词搜索**：基于内存的 SQLite FTS5 配合递归倒数排名融合（+0.6pp）— 首个正向 BM25 结果，得益于更强的重排序器 - **生产模式：74.2% 非对抗**（较基线 +6.7pp），**对比模式：77.7% 非对抗**（较基线 +10.2pp） - 单跳：37.2% → 54.3%（+17.1pp）— 重排序器升级带来的最大类别提升 - 30 多项使用科学方法的实验（合并 ×6、图谱扩展、实体搜索 ×3、BM25 ×4、CE A/B、对比模式变体） - 多跳检索分析：60% 缺失于提取，40% 缺失于嵌入 — 无排序失败 - 重排序器服务器同时支持经典 CrossEncoder 和 Qwen3 聊天模板推理 ### v0.8.0 - **MCP 服务器**（`tools/mcp/server.py`）：通过 FastMCP 3.2 的 streamable-http 传输提供 6 个工具 — 支持 Claude Code、Cursor、Codex - **LLM 记忆合成**（`/reflect` 端点）：搜索 → 格式化 → LLM → 带来源引用的连贯回答 - **`tools/brain/reflect.py`**：Anthropic 与 Ollama LLM 提供者，自动降级 - Docker 服务用于 MCP 服务器及部署文档 - 新增 36 个测试（22 个 MCP + 14 个 reflect），总计 142 个测试 - 完整 10 轮对话验证：非对抗模式下 69.1% - 提示路由：多跳 +16.7pp，单跳 +3.9pp - 流水线从 700 行精简至 427 行（经消融验证移除冗余代码） - 跨编码器 GPU 服务器用于远程推理 - 事实提取模块、整合引擎、kNN 链接计算 - 21 项使用科学方法的实验 - 合并测试（6 种变体）结果为负并暂停 ### v0.7.0 - 双通道检索：窗口（45 个槽位）+ LLM 提取的事实（15 个槽位） - 交叉编码器重排序（ms-marco-MiniLM-L-6-v2，CPU） - 结构化事实提取（在摄入时通过 Claude Haiku） - 仅窗口分块（独立轮次验证为 0pp） - 消融测试：BM25、关键词/实体/时间增强、MMR、Cohere 重排序器均为 0pp - LoCoMo 轮次 0：生产模式 69.7%，对比模式 72.4%（非对抗） ### v0.5.0 — 搜索质量突破 - 关键词重叠增强、实体聚焦评分 - recall@5：0.67 → 0.82（+22%），recall@10：0.745 → 0.885（+19%） 详见 [`CHANGELOG.md`](CHANGELOG.md) 获取完整记录。 ## 许可证 MIT — 参见 [`LICENSE`](LICENSE)。

标签：AI代理, AI风险缓解, A-MAC质量门, API服务器, BM25, Claude Code, Cursor, FalkorDB, FastMCP, LLM记忆合成, LoCoMo, MCP服务器, Qdrant, Qwen3重排序, REST API, SQLite FTS5, 事实提取, 内存窗口, 向量搜索, 多车道检索, 开源, 持久化存储, 推理引擎, 提示路由, 流式HTTP, 测试, 消融实验, 混合大脑, 科学方法, 自托管, 记忆后端, 语义搜索, 逆向工具, 重排序, 长期记忆