RASPUTIN是一个自托管的长期记忆后端，专为AI代理设计。它通过双通道检索、LLM事实提取、Qwen3重排序器和MCP协议支持，在LoCoMo基准测试中达到77.7%的准确率，为Claude Code等工具提供持久化对话记忆能力。

RASPUTIN：为AI代理打造的生产级长期记忆系统\n\n## 背景：AI代理为什么需要长期记忆？\n\n当前的大语言模型虽然拥有强大的推理能力，但缺乏跨会话的持久记忆。每次对话开始时，模型都处于"失忆"状态，无法记住用户的偏好、过往的讨论内容或项目的历史上下文。这种限制严重制约了AI代理在复杂任务中的连续性和个性化能力。\n\nRASPUTIN正是为解决这一问题而设计的生产级记忆系统。它不仅是一个简单的向量数据库包装器，而是一个完整的多组件架构，专门优化了AI代理的记忆存储、检索和合成能力。\n\n## 核心架构设计\n\n### 双通道记忆存储\n\nRASPUTIN采用创新的双通道存储策略：\n\n通道一：重叠窗口（Windows）\n将对话切分为5轮重叠的窗口（步长为2），保留完整的上下文语义。这种方式确保即使是对话中的中间片段也能被有效检索。\n\n通道二：LLM提取的事实（Facts）\n在记忆提交时，系统使用Haiku或本地模型自动提取结构化的事实（如"Alice获得了晋升"、"项目截止日期是4月12日"）。这些事实以独立文档形式存储，便于精确检索。\n\n### 三层检索流水线\n\nRASPUTIN的检索系统经过精心设计，包含三个协同工作的层次：\n\n第一层：多查询扩展与向量搜索\n使用nomic-embed-text（768维）生成查询嵌入，同时在窗口通道（45个槽位）和事实通道（15个槽位）进行向量相似度搜索。\n\n第二层：BM25关键词搜索\n通过SQLite FTS5实现传统的关键词匹配，捕获向量搜索可能遗漏的精确术语匹配。\n\n第三层：互惠排名融合（RRF）与重排序\n将三个通道的候选结果通过RRF算法融合，然后使用Qwen3-Reranker-0.6B基础模型进行最终重排序。这个重排序器展现出优异的性能：相关与无关文档的分数分离度达到0.99 vs 0.0001。\n\n### 智能查询路由\n\n系统根据查询类型自动选择不同的回答策略：\n- 推理型：需要综合多源信息的开放性问题\n- 事实型：针对具体事实的精确查询\n- 时间型：涉及时间顺序或历史变化的问题\n\n这种路由机制在完整10轮对话测试中贡献了+1.6pp的准确率提升。\n\n## 性能表现与基准测试\n\n### LoCoMo基准测试结果\n\nRASPUTIN在ACL 2024发布的LoCoMo基准测试（包含1986个QA对的完整10轮对话数据集）上取得了优异成绩：\n\n| 模式 | 非对抗性问题准确率 | 说明 |\n|------|-------------------|------|\n| Compare（领域可比） | 77.7% | 使用宽松评判标准，便于与其他系统横向对比 |\n| Production（生产级） | 74.2% | 使用严格评判标准，反映真实检索质量 |\n\n分类别表现：\n- 开放域问题：84.8%（生产）/ 83.2%（对比）\n- 时间性问题：71.3%（生产）/ 75.4%（对比）\n- 单跳事实：54.3%（生产）/ 68.1%（对比）\n- 多跳推理：49.0%（生产）/ 64.6%（对比）\n\n### 关键消融实验结果\n\nRASPUTIN团队进行了30多项严谨的消融实验，部分关键发现：\n\nQwen3-Reranker升级：从ms-marco-MiniLM-L-6-v2升级到Qwen3-Reranker-0.6B，带来+4.5pp（生产）和+8.6pp（对比）的显著提升。\n\n双通道检索：相比仅使用窗口，增加事实通道带来+6.5pp的整体提升。\n\nBM25融合：在强重排序器支持下，BM25关键词搜索首次展现正向贡献（+0.6pp）。\n\n被验证无效的方向：\n- 记忆整合（consolidation）：6种配置均呈负向效果\n- 图谱扩展（kNN链接）：-4.4pp\n- 实体搜索：-10pp至-14pp\n- 更大的嵌入维度（4096d）：无改善\n\n这种严谨的实验方法论确保了每个功能组件都经过有效性验证。\n\n## 与生态系统的集成\n\n### MCP协议原生支持\n\nRASPUTIN通过FastMCP 3.2实现了Model Context Protocol（MCP）服务器，提供6个核心工具：\n- store：存储记忆\n- search：搜索记忆\n- reflect：LLM合成回答\n- stats：统计信息\n- feedback：反馈信号\n- commit_conversation：提交完整对话\n\n这使得Claude Code、Cursor、Codex等MCP兼容客户端可以无缝集成RASPUTIN的记忆能力。\n\n### REST API\n\n除MCP外，RASPUTIN还暴露完整的REST API（默认端口7777），支持：\n- 健康检查与组件状态\n- 混合检索（/search）\n- 记忆提交（/commit）\n- 对话提交（/commit_conversation）\n- 反思合成（/reflect）\n- 反馈收集（/feedback）\n\n## 技术栈与部署\n\n### 依赖组件\n\n- Qdrant：向量数据库，存储窗口和事实的嵌入\n- FalkorDB：知识图谱（可选）\n- SQLite FTS5：BM25关键词搜索\n- Ollama或兼容服务：嵌入模型（nomic-embed-text）和重排序模型（Qwen3-Reranker）\n\n### 部署方式\n\nbash\n# 启动依赖服务\ndocker compose up -d\n\n# 安装Python依赖\npip install -r requirements-core.txt\n\n# 启动API服务器\npython3 tools/hybrid_brain.py\n\n# 启动MCP服务器\npython3 tools/mcp/server.py\n\n\n## 质量保证机制\n\n### A-MAC准入门槛\n\n在记忆提交阶段，系统执行A-MAC（相关性、新颖性、特异性）质量检查，过滤低质量内容。这确保了记忆库的整体质量。\n\n### 矛盾检测\n\n系统能够识别新提交记忆与现有记忆之间的矛盾，并记录这些矛盾供后续处理。\n\n### 全面的测试覆盖\n\n项目包含142个测试（106个核心管道 + 22个MCP服务器 + 14个反思模块），并配置了55%的代码覆盖率门槛。\n\n## 实际意义与应用场景\n\nRASPUTIN的设计目标是为AI代理提供真正的长期记忆能力，其应用场景包括：\n\n1. 个人AI助手：记住用户的偏好、习惯和过往对话\n2. 企业知识管理：维护项目历史、决策记录和团队动态\n3. 客户支持系统：跟踪客户问题历史和解决方案\n4. 研究辅助工具：管理文献阅读和实验记录\n\n对于OpenClaw和Claude Code用户，RASPUTIN提供了开箱即用的记忆增强方案，使代理能够跨会话保持上下文连续性。\n\n## 总结\n\nRASPUTIN代表了AI代理记忆系统的一个成熟实现。它通过严谨的工程实践、全面的消融验证和优秀的基准测试成绩，证明了自托管长期记忆的可行性。其双通道存储、三层检索和智能路由的设计思路，为同类系统提供了有价值的参考架构。对于需要持久化记忆能力的AI应用开发者，RASPUTIN是一个值得认真考虑的选择。

RASPUTIN：为AI代理打造的生产级长期记忆系统\n\n背景：AI代理为什么需要长期记忆？\n\n当前的大语言模型虽然拥有强大的推理能力，但缺乏跨会话的持久记忆。每次对话开始时，模型都处于"失忆"状态，无法记住用户的偏好、过往的讨论内容或项目的历史上下文。这种限制严重制约了AI代理在复杂任务中的连续性和个性化能力。\n\nRASPUTIN正是为解决这一问题而设计的生产级记忆系统。它不仅是一个简单的向量数据库包装器，而是一个完整的多组件架构，专门优化了AI代理的记忆存储、检索和合成能力。\n\n核心架构设计\n\n双通道记忆存储\n\nRASPUTIN采用创新的双通道存储策略：\n\n通道一：重叠窗口（Windows）\n将对话切分为5轮重叠的窗口（步长为2），保留完整的上下文语义。这种方式确保即使是对话中的中间片段也能被有效检索。\n\n通道二：LLM提取的事实（Facts）\n在记忆提交时，系统使用Haiku或本地模型自动提取结构化的事实（如"Alice获得了晋升"、"项目截止日期是4月12日"）。这些事实以独立文档形式存储，便于精确检索。\n\n三层检索流水线\n\nRASPUTIN的检索系统经过精心设计，包含三个协同工作的层次：\n\n第一层：多查询扩展与向量搜索\n使用nomic-embed-text（768维）生成查询嵌入，同时在窗口通道（45个槽位）和事实通道（15个槽位）进行向量相似度搜索。\n\n第二层：BM25关键词搜索\n通过SQLite FTS5实现传统的关键词匹配，捕获向量搜索可能遗漏的精确术语匹配。\n\n第三层：互惠排名融合（RRF）与重排序\n将三个通道的候选结果通过RRF算法融合，然后使用Qwen3-Reranker-0.6B基础模型进行最终重排序。这个重排序器展现出优异的性能：相关与无关文档的分数分离度达到0.99 vs 0.0001。\n\n智能查询路由\n\n系统根据查询类型自动选择不同的回答策略：\n- 推理型：需要综合多源信息的开放性问题\n- 事实型：针对具体事实的精确查询\n- 时间型：涉及时间顺序或历史变化的问题\n\n这种路由机制在完整10轮对话测试中贡献了+1.6pp的准确率提升。\n\n性能表现与基准测试\n\nLoCoMo基准测试结果\n\nRASPUTIN在ACL 2024发布的LoCoMo基准测试（包含1986个QA对的完整10轮对话数据集）上取得了优异成绩：\n\n| 模式 | 非对抗性问题准确率 | 说明 |\n|------|-------------------|------|\n| Compare（领域可比） | 77.7% | 使用宽松评判标准，便于与其他系统横向对比 |\n| Production（生产级） | 74.2% | 使用严格评判标准，反映真实检索质量 |\n\n分类别表现：\n- 开放域问题：84.8%（生产）/ 83.2%（对比）\n- 时间性问题：71.3%（生产）/ 75.4%（对比）\n- 单跳事实：54.3%（生产）/ 68.1%（对比）\n- 多跳推理：49.0%（生产）/ 64.6%（对比）\n\n关键消融实验结果\n\nRASPUTIN团队进行了30多项严谨的消融实验，部分关键发现：\n\nQwen3-Reranker升级：从ms-marco-MiniLM-L-6-v2升级到Qwen3-Reranker-0.6B，带来+4.5pp（生产）和+8.6pp（对比）的显著提升。\n\n双通道检索：相比仅使用窗口，增加事实通道带来+6.5pp的整体提升。\n\nBM25融合：在强重排序器支持下，BM25关键词搜索首次展现正向贡献（+0.6pp）。\n\n被验证无效的方向：\n- 记忆整合（consolidation）：6种配置均呈负向效果\n- 图谱扩展（kNN链接）：-4.4pp\n- 实体搜索：-10pp至-14pp\n- 更大的嵌入维度（4096d）：无改善\n\n这种严谨的实验方法论确保了每个功能组件都经过有效性验证。\n\n与生态系统的集成\n\nMCP协议原生支持\n\nRASPUTIN通过FastMCP 3.2实现了Model Context Protocol（MCP）服务器，提供6个核心工具：\n- store：存储记忆\n- search：搜索记忆\n- reflect：LLM合成回答\n- stats：统计信息\n- feedback：反馈信号\n- commit_conversation：提交完整对话\n\n这使得Claude Code、Cursor、Codex等MCP兼容客户端可以无缝集成RASPUTIN的记忆能力。\n\nREST API\n\n除MCP外，RASPUTIN还暴露完整的REST API（默认端口7777），支持：\n- 健康检查与组件状态\n- 混合检索（/search）\n- 记忆提交（/commit）\n- 对话提交（/commit_conversation）\n- 反思合成（/reflect）\n- 反馈收集（/feedback）\n\n技术栈与部署\n\n依赖组件\n\n- Qdrant：向量数据库，存储窗口和事实的嵌入\n- FalkorDB：知识图谱（可选）\n- SQLite FTS5：BM25关键词搜索\n- Ollama或兼容服务：嵌入模型（nomic-embed-text）和重排序模型（Qwen3-Reranker）\n\n部署方式\n\nbash\n启动依赖服务\ndocker compose up -d\n\n安装Python依赖\npip install -r requirements-core.txt\n\n启动API服务器\npython3 tools/hybrid_brain.py\n\n启动MCP服务器\npython3 tools/mcp/server.py\n\n\n质量保证机制\n\nA-MAC准入门槛\n\n在记忆提交阶段，系统执行A-MAC（相关性、新颖性、特异性）质量检查，过滤低质量内容。这确保了记忆库的整体质量。\n\n矛盾检测\n\n系统能够识别新提交记忆与现有记忆之间的矛盾，并记录这些矛盾供后续处理。\n\n全面的测试覆盖\n\n项目包含142个测试（106个核心管道 + 22个MCP服务器 + 14个反思模块），并配置了55%的代码覆盖率门槛。\n\n实际意义与应用场景\n\nRASPUTIN的设计目标是为AI代理提供真正的长期记忆能力，其应用场景包括：\n\n1. 个人AI助手：记住用户的偏好、习惯和过往对话\n2. 企业知识管理：维护项目历史、决策记录和团队动态\n3. 客户支持系统：跟踪客户问题历史和解决方案\n4. 研究辅助工具：管理文献阅读和实验记录\n\n对于OpenClaw和Claude Code用户，RASPUTIN提供了开箱即用的记忆增强方案，使代理能够跨会话保持上下文连续性。\n\n总结\n\nRASPUTIN代表了AI代理记忆系统的一个成熟实现。它通过严谨的工程实践、全面的消融验证和优秀的基准测试成绩，证明了自托管长期记忆的可行性。其双通道存储、三层检索和智能路由的设计思路，为同类系统提供了有价值的参考架构。对于需要持久化记忆能力的AI应用开发者，RASPUTIN是一个值得认真考虑的选择。