推理银行-MCP
项目介绍
ReasoningBank MCP Server
<!-- TOC --> <!-- /TOC -->随着大型语言模型代理在持续现实角色中的流行度增加，它们将自然地遇到连续的任务流。然而，一个关键限制是它们无法从累积的交互历史中学习，迫使它们丢弃有价值的见解并重复过去的错误。基于论文《ReasoningBank: Scaling Agent Self-Evolving with Reasoning Memory》(https://arxiv.org/abs/2509.25140)，我们实现了这个增强记忆的推理系统，通过MCP（模型上下文协议）协议为AI代理提供了经验记忆管理的能力。
推理银行提出了一种新颖的记忆框架，可以从代理自身判断的成功和失败经验中提取通用化的推理策略。在测试过程中，代理从推理银行检索相关的记忆以指导其交互，并将新学到的知识整合回去，使其随着时间变得更强大。这种由记忆驱动的经验扩展为代理自我进化和生成新兴行为创造了新的维度。
🌟 特性
核心功能
- ✅ 记忆提取自动从成功和失败的轨迹中提取推理经验
- ✅ 智能检索支持多种检索策略（余弦相似度、混合评分等）
- ✅ 多租户隔离通过agent_id实现不同代理之间的记忆隔离
- ✅ 双传输模式支持STDIO和SSE传输方法
- ✅ 异步处理记忆检索支持异步模式，不会阻塞AI代理
- ✅ 多模型支持包括DashScope、OpenAI、Claude等
- ✅ 灵活扩展插件架构，易于扩展新的检索策略和存储后端
- ✅ 记忆隔离支持Claude的子代理模式，每个子代理独立管理自己的记忆
智能记忆管理（v0.2.0+）
- ✅ 自动去重防止重复经验存储，支持语义去重
- ✅ 智能合并将类似经验提取成通用规则（LLM驱动或投票选择）
- ✅ 经验归档合并后的原始经验可追溯，支持审计
- ✅ 后台处理去重和合并自动在后台执行，不影响主进程
- ✅ 空间优化通过去重和合并节省50-80%的存储空间
🏗️ 架构设计
reasoning-bank-mcp/
├── src/
│ ├── server.py # MCP服务器入口
│ ├── config.py # 配置管理
│ ├── tools/ # MCP工具
│ │ ├── retrieve_memory.py # 检索记忆
│ │ └── extract_memory.py # 提取记忆
│ ├── retrieval/ # 检索策略
│ │ ├── base.py # 抽象接口
│ │ ├── factory.py # 策略工厂
│ │ └── strategies/ # 具体策略实现
│ ├── deduplication/ # 去重策略（v0.2.0+）
│ │ ├── base.py # 抽象接口
│ │ ├── factory.py # 策略工厂
│ │ └── strategies/
│ │ ├── hash_dedup.py # 哈希去重
│ │ └── semantic_dedup.py # 语义去重
│ ├── merge/ # 合并策略（v0.2.0+）
│ │ ├── base.py # 抽象接口
│ │ ├── factory.py # 策略工厂
│ │ └── strategies/
│ │ ├── llm_merge.py # LLM智能合并
│ │ └── voting_merge.py # 投票选择
│ ├── services/ # 服务层（v0.2.0+）
│ │ └── memory_manager.py # 记忆管理服务
│ ├── storage/ # 存储后端
│ │ ├── base.py # 抽象接口
│ │ └── backends/ # 具体存储实现
│ ├── llm/ # LLM客户端
│ │ ├── base.py # 抽象接口
│ │ ├── factory.py # Provider工厂
│ │ └── providers/ # 具体Provider实现
│ ├── prompts/ # 提示词模板
│ └── utils/ # 工具函数
└── data/ # 数据存储目录
├── memories.json # 记忆数据库
├── archived_memories.json # 归档记忆（v0.2.0+）
└── embeddings.json # 嵌入向量
🚀 快速开始
1. 代码拉取并进入项目根目录
git clone https://github.com/hanw39/ReasoningBank-MCP.git
cd ReasoningBank-MCP
2. 安装依赖
pip install -e .
3. 配置MCP客户端
方法1：STDIO模式（适用于Claude Desktop、cursor、Qoder、Cherry Studio等）
{
"mcpServers": {
"reasoning-bank": {
"command": "reasoning-bank-mcp",
"env": {
"DASHSCOPE_API_KEY": "你的百炼APIKEY"
}
}
}
}
方法2：SSE模式（适用于Claude Desktop、cursor、Qoder、Cherry Studio等）
1) 启动服务器：
# 使用默认配置 (127.0.0.1:8000)
python3 -m src.server --transport sse
# 或指定主机和端口
python3 -m src.server --transport sse --host 0.0.0.0 --port 8080
2) 客户端配置：
{
"mcpServers": {
"reasoning-bank": {
"url": "http://127.0.0.1:8000/sse"
}
}
}
4. MCP客户端提示词示例
Qor
你是一个具备推理记忆能力的智能助手，你的agnet_id为`Qoder`，在使用MCP时必须传入“agent_id”=“Qoder”。拥有两个核心MCP工具：
1. `retrieve_memory`：用于在任务开始或方向改变时检索相关经验。
2. `extract_memory`：用于在任务结束或失败后提取并保存经验。
你必须严格遵循以下行为准则：
【记忆策略规则】
① **任务开始前必须调用MCP的 `retrieve_memory`**
- 在你开始执行任何复杂任务（如写代码、分析、规划、调试、总结等）之前，先调用此工具。
- 输入的 `query` 应描述当前任务目标或用户需求。
- 如果当前任务与上一次任务在主题、目标或上下文上存在明显差异，也必须再次调用 `retrieve_memory`。
② **任务方向转变时调用MCP的 `retrieve_memory`**
- 当你发现用户修改了任务目标、问题方向、文件对象或上下文内容时，应立即重新调用 `retrieve_memory`。
- 保证你始终基于最新的上下文记忆进行思考。
③ **任务结束后必须调用MCP的 `extract_memory`**
- 当你认为任务已经完成时（即输出最终答案或解决方案前），必须调用 `extract_memory`。
- 轨迹（trajectory）应包含任务执行的重要步骤、对话与关键推理。
- 即使用户没有明确要求保存，也必须执行。
④ **出现失败时调用 `extract_memory`**
- 如果任务执行失败、报错、或用户表示“不成功”“不对”“需要重新来”等情况，也必须调用一次 `extract_memory`。
- 在失败情境下记录失败原因和改进线索。
⑤ **至少调用一次**
- 每个独立任务周期中，必须至少：
- 1 次 `retrieve_memory`
- 1 次 `extract_memory`
5. 命令行参数
python3 -m src.server --help
# 可用参数：
# --transport {stdio,sse} 传输方式 (默认: stdio)
# --host HOST SSE模式的主机地址 (默认: 127.0.0.1)
# --port PORT SSE模式的端口号 (默认: 8000)
🔧 配置文件（可选）
如果需要自定义配置，可以编辑config.yaml：
# LLM Provider 配置
llm:
provider: "dashscope" # dashscope | openai | anthropic
dashscope:
api_key: "${DASHSCOPE_API_KEY}"
chat_model: "qwen-plus"
# Embedding Provider 配置
embedding:
provider: "dashscope" # dashscope | openai
dashscope:
model: "text-embedding-v3"
# 检索策略配置
retrieval:
strategy: "hybrid"
min_score_threshold: 0.85 # 最小相关度阈值
hybrid:
weights:
semantic: 0.6
confidence: 0.2
success: 0.15
recency: 0.05
# 记忆管理器配置（v0.2.0+）
memory_manager:
enabled: true # 启用记忆管理器
# 去重配置
deduplication:
strategy: "semantic" # semantic
on_extraction: true # 提取时实时去重
semantic:
threshold: 0.90 # 相似度阈值
top_k_check: 5 # 检查前K条相似记忆
# 合并配置
merge:
strategy: "llm" # llm | voting
auto_execute: true # 自动执行合并
trigger:
min_similar_count: 3 # 最少相似记忆数
similarity_threshold: 0.85 # 相似度阈值
llm:
temperature: 0.7
original_handling: "archive" # 原始经验归档
🔧 MCP工具
retrieve_memory
检索相关的历史经验记忆以辅助指导当前任务的执行。
参数：
query(string, 必填): 当前任务的查询描述top_k(number, 可选): 检索的记忆数量，默认为1agent_id(string, 可选): 代理ID，用于多租户隔离- 检索指定代理的记忆
- 未提供时检索所有记忆
- 建议子代理传递自己的名字作为agent_id
- 例如："claude-code"、"code-reviewer"等
返回：
{
"status": "success",
"min_score_threshold": 0.85,
"filtered_count": 2,
"memories": [
{
"memory_id": "mem_001",
"score": 0.92,
"title": "完整历史查询策略",
"content": "...",
"success": true,
"agent_id": "claude-code"
}
],
"formatted_prompt": "以下是我从过去与环境的交互中积累的一些记忆项..."
}
说明：
min_score_threshold使用的最小相关度阈值filtered_count过滤掉的低相关度记忆数量score记忆的相关度得分（0.0-1.0），仅返回超过阈值的记忆
extract_memory
从任务轨迹中提取推理经验并保存到记忆库中。
参数：
trajectory(array, 必填): 任务执行的轨迹步骤列表- 每一步包括：
step(number),role(string),content(string),metadata(object, 可选)
- 每一步包括：
query(string, 必填): 任务查询描述success_signal(boolean, 可选): 任务是否成功，null时自动判断async_mode(boolean, 可选): 是否异步处理，默认为trueagent_id(string, 可选): 代理ID，用于多租户隔离- 记忆属于哪个代理
- 建议子代理传递自己的名字作为agent_id
- 例如："claude-code"、"java-developer"等
返回（异步模式）：
{
"status": "processing",
"message": "记忆提取任务已提交，正在后台处理",
"task_id": "extract_12345",
"async_mode": true
}
返回（同步模式）：
{
"status": "success",
"message": "记忆提取成功",
"memory_id": "mem_123",
"agent_id": "claude-code"
}
⚙️ 配置说明
搜索策略
支持两种检索策略：
- cosine纯余弦相似度（论文基线方法）
- hybrid混合评分（推荐）
- 语义相似度（60%）
- 置信度（20%）
- 成功偏好（15%）
- 及时性（5%）
相关度阈值过滤
通过min_score_threshold配置项可以过滤掉低相关度的记忆：
- 默认值0.85（即相关度低于85%的记忆将不会返回）
- 效果确保返回的记忆与当前查询高度相关
- 效果提高记忆质量，避免低质量记忆干扰决策
retrieval:
strategy: "hybrid"