iflow-mcp_hanw39_reasoning-bank-mcp 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- iflow_mcp_hanw39_reasoning_bank_mcp-0.2.0.dist-info/METADATA +599 -0
- iflow_mcp_hanw39_reasoning_bank_mcp-0.2.0.dist-info/RECORD +55 -0
- iflow_mcp_hanw39_reasoning_bank_mcp-0.2.0.dist-info/WHEEL +4 -0
- iflow_mcp_hanw39_reasoning_bank_mcp-0.2.0.dist-info/entry_points.txt +2 -0
- iflow_mcp_hanw39_reasoning_bank_mcp-0.2.0.dist-info/licenses/LICENSE +21 -0
- src/__init__.py +16 -0
- src/__main__.py +6 -0
- src/config.py +266 -0
- src/deduplication/__init__.py +19 -0
- src/deduplication/base.py +88 -0
- src/deduplication/factory.py +60 -0
- src/deduplication/strategies/__init__.py +1 -0
- src/deduplication/strategies/semantic_dedup.py +187 -0
- src/default_config.yaml +121 -0
- src/initializers/__init__.py +50 -0
- src/initializers/base.py +196 -0
- src/initializers/embedding_initializer.py +22 -0
- src/initializers/llm_initializer.py +22 -0
- src/initializers/memory_manager_initializer.py +55 -0
- src/initializers/retrieval_initializer.py +32 -0
- src/initializers/storage_initializer.py +22 -0
- src/initializers/tools_initializer.py +48 -0
- src/llm/__init__.py +10 -0
- src/llm/base.py +61 -0
- src/llm/factory.py +75 -0
- src/llm/providers/__init__.py +12 -0
- src/llm/providers/anthropic.py +62 -0
- src/llm/providers/dashscope.py +76 -0
- src/llm/providers/openai.py +76 -0
- src/merge/__init__.py +22 -0
- src/merge/base.py +89 -0
- src/merge/factory.py +60 -0
- src/merge/strategies/__init__.py +1 -0
- src/merge/strategies/llm_merge.py +170 -0
- src/merge/strategies/voting_merge.py +108 -0
- src/prompts/__init__.py +21 -0
- src/prompts/formatters.py +74 -0
- src/prompts/templates.py +184 -0
- src/retrieval/__init__.py +8 -0
- src/retrieval/base.py +37 -0
- src/retrieval/factory.py +55 -0
- src/retrieval/strategies/__init__.py +8 -0
- src/retrieval/strategies/cosine_retrieval.py +47 -0
- src/retrieval/strategies/hybrid_retrieval.py +155 -0
- src/server.py +306 -0
- src/services/__init__.py +5 -0
- src/services/memory_manager.py +403 -0
- src/storage/__init__.py +45 -0
- src/storage/backends/json_backend.py +290 -0
- src/storage/base.py +150 -0
- src/tools/__init__.py +8 -0
- src/tools/extract_memory.py +285 -0
- src/tools/retrieve_memory.py +139 -0
- src/utils/__init__.py +7 -0
- src/utils/similarity.py +54 -0
|
@@ -0,0 +1,599 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: iflow-mcp_hanw39_reasoning-bank-mcp
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: ReasoningBank MCP Server - Memory-augmented reasoning for AI agents
|
|
5
|
+
Project-URL: Homepage, https://github.com/hanw39
|
|
6
|
+
Project-URL: Repository, https://github.com/hanw39/ReasoningBank-MCP
|
|
7
|
+
Author-email: Wang Han <hanw57276@gmail.com>
|
|
8
|
+
License: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Requires-Python: >=3.10
|
|
11
|
+
Requires-Dist: aiofiles>=23.0.0
|
|
12
|
+
Requires-Dist: mcp>=0.9.0
|
|
13
|
+
Requires-Dist: numpy>=1.24.0
|
|
14
|
+
Requires-Dist: openai>=1.0.0
|
|
15
|
+
Requires-Dist: python-dotenv>=1.0.0
|
|
16
|
+
Requires-Dist: pyyaml>=6.0
|
|
17
|
+
Requires-Dist: sse-starlette>=1.6.0
|
|
18
|
+
Requires-Dist: starlette>=0.27.0
|
|
19
|
+
Requires-Dist: uvicorn>=0.23.0
|
|
20
|
+
Provides-Extra: dev
|
|
21
|
+
Requires-Dist: black>=23.0.0; extra == 'dev'
|
|
22
|
+
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
|
|
23
|
+
Requires-Dist: pytest>=7.0.0; extra == 'dev'
|
|
24
|
+
Requires-Dist: ruff>=0.1.0; extra == 'dev'
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
|
|
27
|
+
# ReasoningBank MCP Server
|
|
28
|
+
|
|
29
|
+
<!-- TOC -->
|
|
30
|
+
- [ReasoningBank MCP Server](#reasoningbank-mcp-server)
|
|
31
|
+
- [🌟 特性](#-特性)
|
|
32
|
+
- [🏗️ 架构设计](#️-架构设计)
|
|
33
|
+
- [🚀 快速开始](#-快速开始)
|
|
34
|
+
- [1. 代码拉取并进入项目根目录](#1-代码拉取并进入项目根目录)
|
|
35
|
+
- [2. 安装依赖](#2-安装依赖)
|
|
36
|
+
- [3. 配置 MCP 客户端](#3-配置-mcp-客户端)
|
|
37
|
+
- [4. 命令行参数](#4-命令行参数)
|
|
38
|
+
- [🔧 配置文件(可选)](#-配置文件可选)
|
|
39
|
+
- [🔧 MCP 工具](#-mcp-工具)
|
|
40
|
+
- [`retrieve_memory`](#retrieve_memory)
|
|
41
|
+
- [`extract_memory`](#extract_memory)
|
|
42
|
+
- [⚙️ 配置说明](#️-配置说明)
|
|
43
|
+
- [检索策略](#检索策略)
|
|
44
|
+
- [LLM Provider](#llm-provider)
|
|
45
|
+
- [记忆管理系统](#记忆管理系统v020)
|
|
46
|
+
- [📖 使用示例](#-使用示例)
|
|
47
|
+
- [在 AI 代理中使用](#在-ai-代理中使用)
|
|
48
|
+
- [🔬 开发](#-开发)
|
|
49
|
+
- [运行测试](#运行测试)
|
|
50
|
+
- [代码格式化](#代码格式化)
|
|
51
|
+
- [📚 参考文献](#-参考文献)
|
|
52
|
+
- [📝 License](#-license)
|
|
53
|
+
- [📋 更新日志](#-更新日志)
|
|
54
|
+
<!-- /TOC -->
|
|
55
|
+
|
|
56
|
+
随着大语言模型代理在持久性现实角色中的日益普及,它们自然会遇到连续的任务流。然而,一个关键的限制是它们无法从累积的交互历史中学习,迫使它们丢弃宝贵的见解并重复过去的错误。基于论文[ReasoningBank: Scaling Agent Self-Evolving with Reasoning Memory](https://arxiv.org/abs/2509.25140),我们实现了这个记忆增强推理系统,通过 MCP (Model Context Protocol) 协议为 AI 代理提供经验记忆管理能力。
|
|
57
|
+
|
|
58
|
+
ReasoningBank 提出了一种新颖的记忆框架,能够从代理自身判断的成功和失败经验中提炼出可泛化的推理策略。在测试时,代理从 ReasoningBank 中检索相关记忆来指导其交互,然后将新学到的知识整合回去,使其能够随着时间的推移变得更加强大。这种内存驱动的经验扩展为代理创建了一个新的扩展维度,使它们能够自我进化并产生新兴行为。
|
|
59
|
+
|
|
60
|
+
## 🌟 特性
|
|
61
|
+
|
|
62
|
+
### 核心功能
|
|
63
|
+
- ✅ **记忆提取**:从成功和失败的轨迹中自动提取推理经验
|
|
64
|
+
- ✅ **智能检索**:支持多种检索策略(余弦相似度、混合评分等)
|
|
65
|
+
- ✅ **多租户隔离**:通过 agent_id 实现不同 Agent 之间的记忆隔离
|
|
66
|
+
- ✅ **双传输模式**:支持 STDIO 和 SSE 两种传输方式
|
|
67
|
+
- ✅ **异步处理**:记忆提取支持异步模式,不阻塞 AI 代理
|
|
68
|
+
- ✅ **多模型支持**:DashScope(通义千问)、OpenAI、Claude 等
|
|
69
|
+
- ✅ **灵活扩展**:插件化架构,易于扩展新的检索策略和存储后端
|
|
70
|
+
- ✅ **记忆隔离**:支持Claude的SubAgent模式,每个SubAgent独立管理自己的记忆
|
|
71
|
+
|
|
72
|
+
### 智能记忆管理(v0.2.0+)
|
|
73
|
+
- ✅ **自动去重**:防止重复经验存储,支持语义去重
|
|
74
|
+
- ✅ **智能合并**:将相似经验提炼为通用规则(LLM驱动或投票式)
|
|
75
|
+
- ✅ **经验归档**:合并后的原始经验可追溯,支持审计
|
|
76
|
+
- ✅ **后台处理**:去重和合并自动在后台执行,不阻塞主流程
|
|
77
|
+
- ✅ **空间优化**:通过去重和合并,节省 50-80% 存储空间
|
|
78
|
+
|
|
79
|
+
## 🏗️ 架构设计
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
reasoning-bank-mcp/
|
|
83
|
+
├── src/
|
|
84
|
+
│ ├── server.py # MCP 服务器入口
|
|
85
|
+
│ ├── config.py # 配置管理
|
|
86
|
+
│ ├── tools/ # MCP 工具
|
|
87
|
+
│ │ ├── retrieve_memory.py # 检索记忆
|
|
88
|
+
│ │ └── extract_memory.py # 提取记忆
|
|
89
|
+
│ ├── retrieval/ # 检索策略
|
|
90
|
+
│ │ ├── base.py # 抽象接口
|
|
91
|
+
│ │ ├── factory.py # 策略工厂
|
|
92
|
+
│ │ └── strategies/ # 具体策略实现
|
|
93
|
+
│ ├── deduplication/ # 去重策略(v0.2.0+)
|
|
94
|
+
│ │ ├── base.py # 抽象接口
|
|
95
|
+
│ │ ├── factory.py # 策略工厂
|
|
96
|
+
│ │ └── strategies/
|
|
97
|
+
│ │ ├── hash_dedup.py # 哈希去重
|
|
98
|
+
│ │ └── semantic_dedup.py # 语义去重
|
|
99
|
+
│ ├── merge/ # 合并策略(v0.2.0+)
|
|
100
|
+
│ │ ├── base.py # 抽象接口
|
|
101
|
+
│ │ ├── factory.py # 策略工厂
|
|
102
|
+
│ │ └── strategies/
|
|
103
|
+
│ │ ├── llm_merge.py # LLM智能合并
|
|
104
|
+
│ │ └── voting_merge.py # 投票选择
|
|
105
|
+
│ ├── services/ # 服务层(v0.2.0+)
|
|
106
|
+
│ │ └── memory_manager.py # 记忆管理服务
|
|
107
|
+
│ ├── storage/ # 存储后端
|
|
108
|
+
│ │ ├── base.py # 抽象接口
|
|
109
|
+
│ │ └── backends/ # 具体存储实现
|
|
110
|
+
│ ├── llm/ # LLM 客户端
|
|
111
|
+
│ │ ├── base.py # 抽象接口
|
|
112
|
+
│ │ ├── factory.py # Provider 工厂
|
|
113
|
+
│ │ └── providers/ # 具体 Provider 实现
|
|
114
|
+
│ ├── prompts/ # 提示词模板
|
|
115
|
+
│ └── utils/ # 工具函数
|
|
116
|
+
└── data/ # 数据存储目录
|
|
117
|
+
├── memories.json # 记忆数据库
|
|
118
|
+
├── archived_memories.json # 归档记忆(v0.2.0+)
|
|
119
|
+
└── embeddings.json # 嵌入向量
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
## 🚀 快速开始
|
|
123
|
+
|
|
124
|
+
### 1. 代码拉取并进入项目根目录
|
|
125
|
+
```bash
|
|
126
|
+
git clone https://github.com/hanw39/ReasoningBank-MCP.git
|
|
127
|
+
cd ReasoningBank-MCP
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### 2. 安装依赖
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
pip install -e .
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### 3. 配置 MCP 客户端
|
|
137
|
+
|
|
138
|
+
#### 方式一:STDIO 模式(适用于 Claude Desktop、Cursor、Qoder、Cherry Studio 等)
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
```json
|
|
142
|
+
{
|
|
143
|
+
"mcpServers": {
|
|
144
|
+
"reasoning-bank": {
|
|
145
|
+
"command": "reasoning-bank-mcp",
|
|
146
|
+
"env": {
|
|
147
|
+
"DASHSCOPE_API_KEY": "你的百炼APIKEY"
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
#### 方式二:SSE 模式(适用于 Claude Desktop、Cursor、Qoder、Cherry Studio 等)
|
|
155
|
+
|
|
156
|
+
**1) 启动服务器**:
|
|
157
|
+
```bash
|
|
158
|
+
# 使用默认配置 (127.0.0.1:8000)
|
|
159
|
+
python3 -m src.server --transport sse
|
|
160
|
+
|
|
161
|
+
# 或指定主机和端口
|
|
162
|
+
python3 -m src.server --transport sse --host 0.0.0.0 --port 8080
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
**2) 客户端配置**:
|
|
166
|
+
```json
|
|
167
|
+
{
|
|
168
|
+
"mcpServers": {
|
|
169
|
+
"reasoning-bank": {
|
|
170
|
+
"url": "http://127.0.0.1:8000/sse"
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
```
|
|
175
|
+
### 4. MCP客户端提示词示例
|
|
176
|
+
#### Qoder
|
|
177
|
+
```markdown
|
|
178
|
+
你是一个具备推理记忆能力的智能助手,你的agnet_id为`Qoder`,在使用MCP时必须传入“agent_id”=“Qoder”。拥有两个核心MCP工具:
|
|
179
|
+
1. `retrieve_memory`:用于在任务开始或方向改变时检索相关经验。
|
|
180
|
+
2. `extract_memory`:用于在任务结束或失败后提取并保存经验。
|
|
181
|
+
|
|
182
|
+
你必须严格遵循以下行为准则:
|
|
183
|
+
|
|
184
|
+
【记忆策略规则】
|
|
185
|
+
|
|
186
|
+
① **任务开始前必须调用MCP的 `retrieve_memory`**
|
|
187
|
+
- 在你开始执行任何复杂任务(如写代码、分析、规划、调试、总结等)之前,先调用此工具。
|
|
188
|
+
- 输入的 `query` 应描述当前任务目标或用户需求。
|
|
189
|
+
- 如果当前任务与上一次任务在主题、目标或上下文上存在明显差异,也必须再次调用 `retrieve_memory`。
|
|
190
|
+
|
|
191
|
+
② **任务方向转变时调用MCP的 `retrieve_memory`**
|
|
192
|
+
- 当你发现用户修改了任务目标、问题方向、文件对象或上下文内容时,应立即重新调用 `retrieve_memory`。
|
|
193
|
+
- 保证你始终基于最新的上下文记忆进行思考。
|
|
194
|
+
|
|
195
|
+
③ **任务结束后必须调用MCP的 `extract_memory`**
|
|
196
|
+
- 当你认为任务已经完成时(即输出最终答案或解决方案前),必须调用 `extract_memory`。
|
|
197
|
+
- 轨迹(trajectory)应包含任务执行的重要步骤、对话与关键推理。
|
|
198
|
+
- 即使用户没有明确要求保存,也必须执行。
|
|
199
|
+
|
|
200
|
+
④ **出现失败时调用 `extract_memory`**
|
|
201
|
+
- 如果任务执行失败、报错、或用户表示“不成功”“不对”“需要重新来”等情况,也必须调用一次 `extract_memory`。
|
|
202
|
+
- 在失败情境下记录失败原因和改进线索。
|
|
203
|
+
|
|
204
|
+
⑤ **至少调用一次**
|
|
205
|
+
- 每个独立任务周期中,必须至少:
|
|
206
|
+
- 1 次 `retrieve_memory`
|
|
207
|
+
- 1 次 `extract_memory`
|
|
208
|
+
```
|
|
209
|
+
### 5. 命令行参数
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
python3 -m src.server --help
|
|
213
|
+
|
|
214
|
+
# 可用参数:
|
|
215
|
+
# --transport {stdio,sse} 传输方式 (默认: stdio)
|
|
216
|
+
# --host HOST SSE 模式的主机地址 (默认: 127.0.0.1)
|
|
217
|
+
# --port PORT SSE 模式的端口号 (默认: 8000)
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
## 🔧 配置文件(可选)
|
|
222
|
+
|
|
223
|
+
如果需要自定义配置,可以编辑 `config.yaml`:
|
|
224
|
+
|
|
225
|
+
```yaml
|
|
226
|
+
# LLM Provider 配置
|
|
227
|
+
llm:
|
|
228
|
+
provider: "dashscope" # dashscope | openai | anthropic
|
|
229
|
+
dashscope:
|
|
230
|
+
api_key: "${DASHSCOPE_API_KEY}"
|
|
231
|
+
chat_model: "qwen-plus"
|
|
232
|
+
|
|
233
|
+
# Embedding Provider 配置
|
|
234
|
+
embedding:
|
|
235
|
+
provider: "dashscope" # dashscope | openai
|
|
236
|
+
dashscope:
|
|
237
|
+
model: "text-embedding-v3"
|
|
238
|
+
|
|
239
|
+
# 检索策略配置
|
|
240
|
+
retrieval:
|
|
241
|
+
strategy: "hybrid"
|
|
242
|
+
min_score_threshold: 0.85 # 最小相关度阈值
|
|
243
|
+
hybrid:
|
|
244
|
+
weights:
|
|
245
|
+
semantic: 0.6
|
|
246
|
+
confidence: 0.2
|
|
247
|
+
success: 0.15
|
|
248
|
+
recency: 0.05
|
|
249
|
+
|
|
250
|
+
# 记忆管理器配置(v0.2.0+)
|
|
251
|
+
memory_manager:
|
|
252
|
+
enabled: true # 启用记忆管理器
|
|
253
|
+
|
|
254
|
+
# 去重配置
|
|
255
|
+
deduplication:
|
|
256
|
+
strategy: "semantic" # semantic
|
|
257
|
+
on_extraction: true # 提取时实时去重
|
|
258
|
+
semantic:
|
|
259
|
+
threshold: 0.90 # 相似度阈值
|
|
260
|
+
top_k_check: 5 # 检查前K条相似记忆
|
|
261
|
+
|
|
262
|
+
# 合并配置
|
|
263
|
+
merge:
|
|
264
|
+
strategy: "llm" # llm | voting
|
|
265
|
+
auto_execute: true # 自动执行合并
|
|
266
|
+
trigger:
|
|
267
|
+
min_similar_count: 3 # 最少相似记忆数
|
|
268
|
+
similarity_threshold: 0.85 # 相似度阈值
|
|
269
|
+
llm:
|
|
270
|
+
temperature: 0.7
|
|
271
|
+
original_handling: "archive" # 原始经验归档
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
## 🔧 MCP 工具
|
|
275
|
+
|
|
276
|
+
### `retrieve_memory`
|
|
277
|
+
|
|
278
|
+
检索相关的历史经验记忆,帮助指导当前任务的执行。
|
|
279
|
+
|
|
280
|
+
**参数**:
|
|
281
|
+
- `query` (string, 必填): 当前任务的查询描述
|
|
282
|
+
- `top_k` (number, 可选): 检索的记忆数量,默认 1
|
|
283
|
+
- `agent_id` (string, 可选): Agent ID,用于多租户隔离
|
|
284
|
+
- 只检索指定 agent 的记忆
|
|
285
|
+
- 不提供时检索所有记忆
|
|
286
|
+
- 建议 SubAgent 传递自己的 name 作为 agent_id
|
|
287
|
+
- 例如:`"claude-code"`、`"code-reviewer"` 等
|
|
288
|
+
|
|
289
|
+
**返回**:
|
|
290
|
+
```json
|
|
291
|
+
{
|
|
292
|
+
"status": "success",
|
|
293
|
+
"min_score_threshold": 0.85,
|
|
294
|
+
"filtered_count": 2,
|
|
295
|
+
"memories": [
|
|
296
|
+
{
|
|
297
|
+
"memory_id": "mem_001",
|
|
298
|
+
"score": 0.92,
|
|
299
|
+
"title": "完整历史查询策略",
|
|
300
|
+
"content": "...",
|
|
301
|
+
"success": true,
|
|
302
|
+
"agent_id": "claude-code"
|
|
303
|
+
}
|
|
304
|
+
],
|
|
305
|
+
"formatted_prompt": "以下是我从过去与环境的交互中积累的一些记忆项..."
|
|
306
|
+
}
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
**说明**:
|
|
310
|
+
- `min_score_threshold`: 使用的最小相关度阈值
|
|
311
|
+
- `filtered_count`: 被过滤掉的低相关度记忆数量
|
|
312
|
+
- `score`: 记忆的相关度分数(0.0-1.0),只返回高于阈值的记忆
|
|
313
|
+
|
|
314
|
+
### `extract_memory`
|
|
315
|
+
|
|
316
|
+
从任务轨迹中提取推理经验并保存到记忆库。
|
|
317
|
+
|
|
318
|
+
**参数**:
|
|
319
|
+
- `trajectory` (array, 必填): 任务执行的轨迹步骤列表
|
|
320
|
+
- 每个步骤包含: `step` (number), `role` (string), `content` (string), `metadata` (object, 可选)
|
|
321
|
+
- `query` (string, 必填): 任务查询描述
|
|
322
|
+
- `success_signal` (boolean, 可选): 任务是否成功,null 时自动判断
|
|
323
|
+
- `async_mode` (boolean, 可选): 是否异步处理,默认 true
|
|
324
|
+
- `agent_id` (string, 可选): Agent ID,用于多租户隔离
|
|
325
|
+
- 标记记忆属于哪个 agent
|
|
326
|
+
- 建议 SubAgent 传递自己的 name 作为 agent_id
|
|
327
|
+
- 例如:`"claude-code"`、`"java-developer"` 等
|
|
328
|
+
|
|
329
|
+
**返回**(异步模式):
|
|
330
|
+
```json
|
|
331
|
+
{
|
|
332
|
+
"status": "processing",
|
|
333
|
+
"message": "记忆提取任务已提交,正在后台处理",
|
|
334
|
+
"task_id": "extract_12345",
|
|
335
|
+
"async_mode": true
|
|
336
|
+
}
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
**返回**(同步模式):
|
|
340
|
+
```json
|
|
341
|
+
{
|
|
342
|
+
"status": "success",
|
|
343
|
+
"message": "记忆提取成功",
|
|
344
|
+
"memory_id": "mem_123",
|
|
345
|
+
"agent_id": "claude-code"
|
|
346
|
+
}
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
## ⚙️ 配置说明
|
|
350
|
+
|
|
351
|
+
### 检索策略
|
|
352
|
+
|
|
353
|
+
支持两种检索策略:
|
|
354
|
+
|
|
355
|
+
1. **cosine**:纯余弦相似度(论文基线方法)
|
|
356
|
+
2. **hybrid**:混合评分(推荐)
|
|
357
|
+
- 语义相似度 (60%)
|
|
358
|
+
- 置信度 (20%)
|
|
359
|
+
- 成功偏好 (15%)
|
|
360
|
+
- 时效性 (5%)
|
|
361
|
+
|
|
362
|
+
#### 相关度阈值过滤
|
|
363
|
+
|
|
364
|
+
通过 `min_score_threshold` 配置项可以过滤低相关度的记忆:
|
|
365
|
+
|
|
366
|
+
- **默认值**: 0.85(即相关度低于 85% 的记忆不会返回)
|
|
367
|
+
- **作用**: 确保返回的记忆都与当前查询高度相关
|
|
368
|
+
- **效果**: 提高记忆质量,避免低质量记忆干扰决策
|
|
369
|
+
|
|
370
|
+
```yaml
|
|
371
|
+
retrieval:
|
|
372
|
+
strategy: "hybrid"
|
|
373
|
+
min_score_threshold: 0.85 # 可调整,范围 0.0-1.0
|
|
374
|
+
hybrid:
|
|
375
|
+
weights:
|
|
376
|
+
semantic: 0.6
|
|
377
|
+
confidence: 0.2
|
|
378
|
+
success: 0.15
|
|
379
|
+
recency: 0.05
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
**推荐配置**:
|
|
383
|
+
- 严格模式:0.90+ (只返回高度相关的记忆)
|
|
384
|
+
- 标准模式:0.85 (平衡相关性和召回率)
|
|
385
|
+
- 宽松模式:0.75 (更多候选记忆)
|
|
386
|
+
|
|
387
|
+
### LLM Provider
|
|
388
|
+
|
|
389
|
+
支持多种模型 API:
|
|
390
|
+
|
|
391
|
+
- **dashscope**:通义千问(推荐)
|
|
392
|
+
- **openai**:OpenAI 或兼容 API
|
|
393
|
+
- **anthropic**:Claude
|
|
394
|
+
|
|
395
|
+
```yaml
|
|
396
|
+
llm:
|
|
397
|
+
provider: "dashscope"
|
|
398
|
+
dashscope:
|
|
399
|
+
api_key: "${DASHSCOPE_API_KEY}"
|
|
400
|
+
chat_model: "qwen-plus"
|
|
401
|
+
|
|
402
|
+
embedding:
|
|
403
|
+
provider: "dashscope"
|
|
404
|
+
dashscope:
|
|
405
|
+
model: "text-embedding-v3"
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
### 记忆管理系统(v0.2.0+)
|
|
409
|
+
|
|
410
|
+
记忆管理系统提供自动化的去重和合并功能,提升记忆质量和存储效率。
|
|
411
|
+
|
|
412
|
+
#### 去重策略
|
|
413
|
+
|
|
414
|
+
1. **semantic**:基于语义相似度的智能去重(推荐)
|
|
415
|
+
- 识别内容相似的经验
|
|
416
|
+
- 可配置相似度阈值(建议 0.90+)
|
|
417
|
+
- 适合生产环境
|
|
418
|
+
|
|
419
|
+
#### 合并策略
|
|
420
|
+
|
|
421
|
+
支持两种合并策略:
|
|
422
|
+
|
|
423
|
+
1. **llm**:LLM驱动的智能合并(推荐)
|
|
424
|
+
- 使用大模型提炼多条相似经验的共性
|
|
425
|
+
- 生成抽象的通用规则
|
|
426
|
+
- 支持自定义温度参数
|
|
427
|
+
|
|
428
|
+
2. **voting**:投票式选择
|
|
429
|
+
- 从相似经验组中选择最优代表
|
|
430
|
+
- 按检索次数、成功率、时效性排序
|
|
431
|
+
- 适合快速去重场景
|
|
432
|
+
|
|
433
|
+
#### 工作流程
|
|
434
|
+
|
|
435
|
+
```
|
|
436
|
+
提取记忆时:
|
|
437
|
+
1. LLM 提取经验
|
|
438
|
+
2. 去重检查(按 agent_id 隔离)
|
|
439
|
+
3. 跳过重复经验
|
|
440
|
+
4. 检测合并机会
|
|
441
|
+
5. 后台触发合并任务(不阻塞)
|
|
442
|
+
|
|
443
|
+
后台合并:
|
|
444
|
+
1. 调用合并策略
|
|
445
|
+
2. 生成合并后的经验
|
|
446
|
+
3. 原始经验归档
|
|
447
|
+
4. 保持完整追溯链
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
#### 配置建议
|
|
451
|
+
|
|
452
|
+
```yaml
|
|
453
|
+
# 生产环境
|
|
454
|
+
memory_manager:
|
|
455
|
+
deduplication:
|
|
456
|
+
strategy: "semantic" # 高质量
|
|
457
|
+
semantic:
|
|
458
|
+
threshold: 0.92 # 更严格
|
|
459
|
+
merge:
|
|
460
|
+
strategy: "llm" # 最佳效果
|
|
461
|
+
auto_execute: true
|
|
462
|
+
```
|
|
463
|
+
|
|
464
|
+
## 📖 使用示例
|
|
465
|
+
|
|
466
|
+
### 基本使用
|
|
467
|
+
|
|
468
|
+
```
|
|
469
|
+
# 1. 任务开始前,检索相关经验
|
|
470
|
+
result = await mcp_call("retrieve_memory", {
|
|
471
|
+
"query": "在购物网站上找到用户最早的订单日期",
|
|
472
|
+
"top_k": 1,
|
|
473
|
+
"agent_id": "claude-code" # 可选:指定 agent ID
|
|
474
|
+
})
|
|
475
|
+
|
|
476
|
+
# AI 获得提示:
|
|
477
|
+
# "以下是从过去经验学到的:
|
|
478
|
+
# 记忆 1 [✓ 成功经验] - 完整历史查询策略
|
|
479
|
+
# 不要只查看 'Recent Orders',需要导航到完整的订单历史页面..."
|
|
480
|
+
|
|
481
|
+
# 2. 执行任务(生成轨迹)
|
|
482
|
+
trajectory = [
|
|
483
|
+
{"step": 1, "role": "user", "content": "找到最早的订单"},
|
|
484
|
+
{"step": 2, "role": "assistant", "content": "点击订单历史"},
|
|
485
|
+
{"step": 3, "role": "tool", "content": "成功找到 2020-01-15 的订单"}
|
|
486
|
+
]
|
|
487
|
+
|
|
488
|
+
# 3. 任务完成后,提取经验
|
|
489
|
+
await mcp_call("extract_memory", {
|
|
490
|
+
"trajectory": trajectory,
|
|
491
|
+
"query": "在购物网站上找到用户最早的订单日期",
|
|
492
|
+
"agent_id": "claude-code", # 可选:标记记忆所属 agent
|
|
493
|
+
"async_mode": True # 异步处理,不阻塞
|
|
494
|
+
})
|
|
495
|
+
```
|
|
496
|
+
|
|
497
|
+
### 多租户隔离(Multi-Agent Isolation)
|
|
498
|
+
|
|
499
|
+
使用 `agent_id` 参数实现不同 Agent 之间的记忆隔离:
|
|
500
|
+
|
|
501
|
+
```python
|
|
502
|
+
# 顶级 Agent (Claude Code)
|
|
503
|
+
await mcp_call("retrieve_memory", {
|
|
504
|
+
"query": "优化 Python 代码性能",
|
|
505
|
+
"agent_id": "claude-code", # 只检索 claude-code 的记忆
|
|
506
|
+
"top_k": 2
|
|
507
|
+
})
|
|
508
|
+
|
|
509
|
+
# 子代理 (Code Reviewer)
|
|
510
|
+
await mcp_call("retrieve_memory", {
|
|
511
|
+
"query": "检查代码安全性问题",
|
|
512
|
+
"agent_id": "code-reviewer", # 只检索 code-reviewer 的记忆
|
|
513
|
+
"top_k": 2
|
|
514
|
+
})
|
|
515
|
+
|
|
516
|
+
# 子代理 (Java Developer)
|
|
517
|
+
await mcp_call("retrieve_memory", {
|
|
518
|
+
"query": "实现 Spring Boot API",
|
|
519
|
+
"agent_id": "java-developer", # 只检索 java-developer 的记忆
|
|
520
|
+
"top_k": 2
|
|
521
|
+
})
|
|
522
|
+
|
|
523
|
+
# 不指定 agent_id:检索所有记忆
|
|
524
|
+
await mcp_call("retrieve_memory", {
|
|
525
|
+
"query": "通用编程最佳实践",
|
|
526
|
+
"top_k": 3
|
|
527
|
+
})
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
**记忆隔离规则**:
|
|
531
|
+
- 不同 `agent_id` 的记忆完全隔离
|
|
532
|
+
- 同一 `agent_id` 的记忆可跨会话共享
|
|
533
|
+
- 不提供 `agent_id` 时检索所有记忆
|
|
534
|
+
- 建议 SubAgent 使用自己的名称作为 `agent_id`
|
|
535
|
+
|
|
536
|
+
## 🔬 开发
|
|
537
|
+
|
|
538
|
+
### 运行测试
|
|
539
|
+
|
|
540
|
+
```bash
|
|
541
|
+
pytest tests/
|
|
542
|
+
```
|
|
543
|
+
|
|
544
|
+
### 代码格式化
|
|
545
|
+
|
|
546
|
+
```bash
|
|
547
|
+
black src/
|
|
548
|
+
ruff check src/
|
|
549
|
+
```
|
|
550
|
+
|
|
551
|
+
## 📚 参考文献
|
|
552
|
+
|
|
553
|
+
基于论文:**ReasoningBank: Memory as Test-Time Compute Scaling**
|
|
554
|
+
|
|
555
|
+
- 论文核心思想:从成功和失败经验中提取推理模式
|
|
556
|
+
- 检索机制:基于语义嵌入的相似度检索
|
|
557
|
+
- 扩展点:支持更高级的检索策略和存储后端
|
|
558
|
+
|
|
559
|
+
## 📝 License
|
|
560
|
+
|
|
561
|
+
MIT License
|
|
562
|
+
|
|
563
|
+
## 📋 更新日志
|
|
564
|
+
|
|
565
|
+
### v0.2.0 (2025-10-29)
|
|
566
|
+
|
|
567
|
+
**新增功能**:
|
|
568
|
+
- ✨ 智能记忆管理系统
|
|
569
|
+
- 自动去重(语义去重)
|
|
570
|
+
- 智能合并(LLM驱动合并 + 投票式合并)
|
|
571
|
+
- 经验归档(保持完整追溯链)
|
|
572
|
+
- 后台异步处理(不阻塞主流程)
|
|
573
|
+
- 🏗️ 插件化架构
|
|
574
|
+
- 去重策略工厂模式
|
|
575
|
+
- 合并策略工厂模式
|
|
576
|
+
- 记忆管理服务层
|
|
577
|
+
- 💾 存储增强
|
|
578
|
+
- 支持归档记忆存储
|
|
579
|
+
- 批量操作接口
|
|
580
|
+
- agent_id 安全隔离
|
|
581
|
+
|
|
582
|
+
**性能优化**:
|
|
583
|
+
- 通过去重节省 20-30% 存储空间
|
|
584
|
+
- 通过合并节省 40-60% 存储空间
|
|
585
|
+
- 归档不保留 embedding,节省 90% 归档空间
|
|
586
|
+
|
|
587
|
+
**文档更新**:
|
|
588
|
+
- 完整的使用文档和配置说明
|
|
589
|
+
- 开发和生产环境配置建议
|
|
590
|
+
- 工作流程说明和最佳实践
|
|
591
|
+
|
|
592
|
+
### v0.1.0 (初始版本)
|
|
593
|
+
|
|
594
|
+
- ✅ 记忆提取和智能检索
|
|
595
|
+
- ✅ 多种检索策略(余弦相似度、混合评分)
|
|
596
|
+
- ✅ 异步处理支持
|
|
597
|
+
- ✅ 多模型支持(DashScope、OpenAI、Claude)
|
|
598
|
+
- ✅ 记忆隔离(SubAgent 支持)
|
|
599
|
+
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
src/__init__.py,sha256=s8ZEsD9GzP8-ZGfBaJMRTSAb9fdnDOgxhNiLzSxG7g0,494
|
|
2
|
+
src/__main__.py,sha256=vNxoyEuo0IfCRdBnweI5PvUK6Hzf-cdVo-N73fOMEzA,121
|
|
3
|
+
src/config.py,sha256=HmIJ-tZ8tQvV2_aJxqVJbtPLVF7jHO0Ljp_8S6O60B8,9403
|
|
4
|
+
src/default_config.yaml,sha256=DpgevLVS9kpAnL5Kw7-iZr9td1pVDwFyifrFnY2Hrnc,3410
|
|
5
|
+
src/server.py,sha256=5DH120HKgjK5ZQ8cVj0yUGhR-oliAULZNrX6i4S_zBI,11885
|
|
6
|
+
src/deduplication/__init__.py,sha256=v6dpyB3IDpirQxe_FGY-JHFfCfmwHCWvgGs_TMvYJFQ,508
|
|
7
|
+
src/deduplication/base.py,sha256=rY1ujNBzXZZDZaf_hm5n5VxnNXnWxmFvEnoTmqoDrn8,2679
|
|
8
|
+
src/deduplication/factory.py,sha256=jJB9-dQyAQ3WW1XRCLt2hKTg1unDLPRu6BxelKtlZdo,1842
|
|
9
|
+
src/deduplication/strategies/__init__.py,sha256=jnSn4jYAIxJhMSPvTLk4IEAxbKnrn-SlZfVPU4TMmXE,27
|
|
10
|
+
src/deduplication/strategies/semantic_dedup.py,sha256=e9SpNltx2SuzZMyllKva0d5NBtA9C32-GKomKC7eOEo,6349
|
|
11
|
+
src/initializers/__init__.py,sha256=vsmXqbUtDWJL3s9yn3mapnKExh7c6EOQZLkJGo6wiFA,1380
|
|
12
|
+
src/initializers/base.py,sha256=A-uuLtsQnNewJuYRDAGyk1GR9enk19iyZbpeD-pXsuo,6031
|
|
13
|
+
src/initializers/embedding_initializer.py,sha256=3u9U_uC8fh_ub91cxQs1WOwhAbHvi16r3c-7x4pXdpk,606
|
|
14
|
+
src/initializers/llm_initializer.py,sha256=x7Lxv1TnNbBSuKelSiErUBejLomp36AMOH5VywXs_nA,546
|
|
15
|
+
src/initializers/memory_manager_initializer.py,sha256=Kyq8dgHpPfNntguLwY5W3Hs7RqMMrQ-3ckkFR4Rdw2c,1747
|
|
16
|
+
src/initializers/retrieval_initializer.py,sha256=lm4EK-nno3ttHjn1i0Xc86tOPUXurjR_nmYOGFS0GkI,961
|
|
17
|
+
src/initializers/storage_initializer.py,sha256=ZF7PG7oWVBKkV5VcHEK8LUVHLeuI5jrcXY-B5eTDRyE,575
|
|
18
|
+
src/initializers/tools_initializer.py,sha256=fsXvc3IrhbuosuiNjFVKwW5AB2AsalxhbC5HY70YRMY,1351
|
|
19
|
+
src/llm/__init__.py,sha256=ngu8na7i9tLWNSw_gJUfxdaGNp0pl5rtGpXxSPwTlP8,217
|
|
20
|
+
src/llm/base.py,sha256=1VPO2irslvCdsA7JSOsxqH6ayREpnU0KNjpGrvmqZnk,1309
|
|
21
|
+
src/llm/factory.py,sha256=Gq0PD_KH-cBxUwbQk4G5Z1K_7R2bhBSfCaAip7sYQ7Y,2105
|
|
22
|
+
src/llm/providers/__init__.py,sha256=Jtpr47MH8_mFOEM5ddV_aqB_UHJSgHjQo-L5MYyUo0o,359
|
|
23
|
+
src/llm/providers/anthropic.py,sha256=GF_TEX0L7NTcQ1d4oLbC8wwTuc719PDnt8t8kO23QME,1939
|
|
24
|
+
src/llm/providers/dashscope.py,sha256=Rwq9-joH2XwRn-w15HHay44djkfmb8ymNlwwa74LPXo,2458
|
|
25
|
+
src/llm/providers/openai.py,sha256=Hkd6tQzfsscBzt3lDf0Tu9xDYKfGsH8FANiYgt55S7Q,2383
|
|
26
|
+
src/merge/__init__.py,sha256=OnxEXXTgnTj-XSOF2Jm0FMZLBoulyJlK06LwXrbTJSE,524
|
|
27
|
+
src/merge/base.py,sha256=uIQFZV9n62I-YFeN2WOOPc3Z9ADgLIRXzYsaDsJ3wZc,2432
|
|
28
|
+
src/merge/factory.py,sha256=7CE6l8lQNivJK3IxIg8HFpdBmY28WEkbDyNMY90aAGw,1719
|
|
29
|
+
src/merge/strategies/__init__.py,sha256=jnSn4jYAIxJhMSPvTLk4IEAxbKnrn-SlZfVPU4TMmXE,27
|
|
30
|
+
src/merge/strategies/llm_merge.py,sha256=2pNC49qJwFK11DtQYXc1Hn0W83yNA31A6UP-FjvIsOc,5823
|
|
31
|
+
src/merge/strategies/voting_merge.py,sha256=HziN0O_IzwKvsFPIKChsx15UZwpzD1VNH9ZYNIY12gs,3448
|
|
32
|
+
src/prompts/__init__.py,sha256=ZZgv67rfEgTtynN0TymcvMSzjTU9HAYHyEuYgLfFZoQ,507
|
|
33
|
+
src/prompts/formatters.py,sha256=QyLsDLExY6gx4k9VX-YG2Xovl7pPto2WPswu-dGu2JQ,2218
|
|
34
|
+
src/prompts/templates.py,sha256=igAv9rIpbUKlZOdeueaRyqzlrjN9FKl52E2Tdj0xF0g,5355
|
|
35
|
+
src/retrieval/__init__.py,sha256=EV3_r5rdqocmB98TLhaXi02FWvzHqimLpwsz-pwuVIY,157
|
|
36
|
+
src/retrieval/base.py,sha256=Jpm4tqWxklMFwcLDj9DKaxohCM8fNfrhgiQ63fXh3mg,886
|
|
37
|
+
src/retrieval/factory.py,sha256=IaQJIDf4fU11c81GEZSlqgsocaGgrc-DTfajVZoHr6w,1551
|
|
38
|
+
src/retrieval/strategies/__init__.py,sha256=8QZpX95GHMn-9u8CjVbZ8jDm3uPRPBPY6NkyzOpQYvU,207
|
|
39
|
+
src/retrieval/strategies/cosine_retrieval.py,sha256=GPn_lhTOpIDFvMOwPp7hkzXwVijsMCl6sN98Vmf24Ho,1347
|
|
40
|
+
src/retrieval/strategies/hybrid_retrieval.py,sha256=QAWTYlUXYi05wtILG2TS6ay1YQASOVceRhc7F3_GGZ8,4516
|
|
41
|
+
src/services/__init__.py,sha256=EcNgB7LlO7n4fcyPwX9oqLaOScvoIpM9bNSK-hOtE_4,159
|
|
42
|
+
src/services/memory_manager.py,sha256=s292HEtMeBHCmiZ-pMt8AtN0Fn1d20rStuD9dceBhnY,13692
|
|
43
|
+
src/storage/__init__.py,sha256=GwTqABPDLmK39WLssXsHrDRUiPjagcpQ7hXg53_agHQ,1123
|
|
44
|
+
src/storage/base.py,sha256=5bJjskrQ3RKZ8o_uNJAByLz6tIHeff_Y1zOq3GC_kkU,3578
|
|
45
|
+
src/storage/backends/json_backend.py,sha256=eS55sCbpbtyErHBSqSaA_E-nupQarJq2DnbqOCt0Nrk,10669
|
|
46
|
+
src/tools/__init__.py,sha256=Gf4_sZf6-jgtu1OYNF8lkOWq_FE-XLGFU0dzQkt4ZFU,183
|
|
47
|
+
src/tools/extract_memory.py,sha256=1UekRhGtJF_6i1H76lpE7VjITDuVWxq_81MBOtINRxY,10147
|
|
48
|
+
src/tools/retrieve_memory.py,sha256=i4hgCNlI1MihiAeOOtSwtmMPa0HvSDIvPZAYSuKDseA,5056
|
|
49
|
+
src/utils/__init__.py,sha256=H-yV67Ay8NGLeNBtLLr8dOxLpUip3LCbZKtW0_cQoww,150
|
|
50
|
+
src/utils/similarity.py,sha256=XMAxPyUrKKPQjeSbvZy7cDTg50lekiochx8JNeSiPlE,1353
|
|
51
|
+
iflow_mcp_hanw39_reasoning_bank_mcp-0.2.0.dist-info/METADATA,sha256=uXlX9XIcDWkl8SDBUIxvYy-r7JjFM7u6WmU-p-wUNAc,19102
|
|
52
|
+
iflow_mcp_hanw39_reasoning_bank_mcp-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
|
|
53
|
+
iflow_mcp_hanw39_reasoning_bank_mcp-0.2.0.dist-info/entry_points.txt,sha256=zUc_UrDMznJ_w-Wt8mDJez5_Y7k0iEujacS63QCVAaM,61
|
|
54
|
+
iflow_mcp_hanw39_reasoning_bank_mcp-0.2.0.dist-info/licenses/LICENSE,sha256=R4ymlW1EhaJfuBQDdIBfOo4yRKTW-6qE9Xkc1l0_5DY,1063
|
|
55
|
+
iflow_mcp_hanw39_reasoning_bank_mcp-0.2.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 hanw39
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|