From c5c70d3cf71dbc166477b738c8129fac294d06af Mon Sep 17 00:00:00 2001 From: Windpicker-owo <3431391539@qq.com> Date: Wed, 5 Nov 2025 20:45:44 +0800 Subject: [PATCH] =?UTF-8?q?docs(memory-graph):=20=E6=B7=BB=E5=8A=A0?= =?UTF-8?q?=E5=AE=8C=E6=95=B4=E7=9A=84=E4=BD=BF=E7=94=A8=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 创建memory_graph_guide.md (完整使用指南) - 创建memory_graph_README.md (快速开始) - 更新TODO.md (标记记忆图系统完成) 文档内容: - 系统概述和核心特性 - 配置说明 (35+配置项) - LLM工具使用示例 - 代码使用示例 - 最佳实践建议 - 故障排除指南 - 迁移指南 - API参考 完成状态: Step 1-5 全部完成 所有集成测试通过 (5/5) 文档完整 --- TODO.md | 8 + docs/memory_graph_README.md | 124 +++++++++++++ docs/memory_graph_guide.md | 349 ++++++++++++++++++++++++++++++++++++ 3 files changed, 481 insertions(+) create mode 100644 docs/memory_graph_README.md create mode 100644 docs/memory_graph_guide.md diff --git a/TODO.md b/TODO.md index f66768422..f6363f4d4 100644 --- a/TODO.md +++ b/TODO.md @@ -25,6 +25,14 @@ - [ ] 修复generate_responce_for_image方法有的时候会对同一张图片生成两次描述的问题 - [x] 主动思考的通用提示词改进 - [x] 添加贴表情聊天流判断，过滤好友 +- [x] 记忆图系统 (Memory Graph System) + - [x] 基于图结构的记忆存储 + - [x] 向量相似度检索 + - [x] LLM工具集成 (create_memory, search_memories) + - [x] 自动记忆整合和遗忘 + - [x] 提示词构建集成 + - [x] 配置系统支持 + - [x] 完整集成测试 (5/5通过) - 大工程 diff --git a/docs/memory_graph_README.md b/docs/memory_graph_README.md new file mode 100644 index 000000000..79a1aa83a --- /dev/null +++ b/docs/memory_graph_README.md @@ -0,0 +1,124 @@ +# 记忆图系统 (Memory Graph System) + +> 基于图结构的智能记忆管理系统 + +## 🎯 特性 + +- **图结构存储**: 使用节点-边模型表示复杂记忆关系 +- **语义检索**: 基于向量相似度的智能记忆搜索 +- **自动整合**: 定期合并相似记忆,减少冗余 +- **智能遗忘**: 基于激活度的自动记忆清理 +- **LLM集成**: 提供工具供AI助手调用 + +## 📦 快速开始 + +### 1. 启用系统 + +在 `config/bot_config.toml` 中: + +```toml +[memory_graph] +enable = true +data_dir = "data/memory_graph" +``` + +### 2. 创建记忆 + +```python +from src.memory_graph.manager_singleton import get_memory_manager + +manager = get_memory_manager() +memory = await manager.create_memory( + subject="用户", + memory_type="偏好", + topic="喜欢晴天", + importance=0.7 +) +``` + +### 3. 搜索记忆 + +```python +memories = await manager.search_memories( + query="天气偏好", + top_k=5 +) +``` + +## 🔧 配置说明 + +| 配置项 | 默认值 | 说明 | +|--------|--------|------| +| `enable` | true | 启用开关 | +| `search_top_k` | 5 | 检索数量 | +| `consolidation_interval_hours` | 1.0 | 整合间隔 | +| `forgetting_activation_threshold` | 0.1 | 遗忘阈值 | + +完整配置参考: [使用指南](memory_graph_guide.md#配置说明) + +## 🧪 测试状态 + +✅ **所有测试通过** (5/5) + +- ✅ 基本记忆操作 (CRUD + 检索) +- ✅ LLM工具集成 +- ✅ 记忆生命周期管理 +- ✅ 维护任务调度 +- ✅ 配置系统 + +运行测试: +```bash +python tests/test_memory_graph_integration.py +``` + +## 📊 系统架构 + +``` +记忆图系统 +├── MemoryManager (核心管理器) +│ ├── 创建/删除记忆 +│ ├── 检索记忆 +│ └── 维护任务 +├── 存储层 +│ ├── VectorStore (向量检索) +│ ├── GraphStore (图结构) +│ └── PersistenceManager (持久化) +└── 工具层 + ├── CreateMemoryTool + ├── SearchMemoriesTool + └── LinkMemoriesTool +``` + +## 🛠️ 开发状态 + +### ✅ 已完成 + +- [x] Step 1: 插件系统集成 (fc71aad8) +- [x] Step 2: 提示词记忆检索 (c3ca811e) +- [x] Step 3: 定期记忆整合 (4d44b18a) +- [x] Step 4: 配置系统支持 (a3cc0740, 3ea6d1dc) +- [x] Step 5: 集成测试 (23b011e6) + +### 📝 待优化 + +- [ ] 性能测试和优化 +- [ ] 扩展文档和示例 +- [ ] 高级查询功能 + +## 📚 文档 + +- [使用指南](memory_graph_guide.md) - 完整的使用说明 +- [API文档](../src/memory_graph/README.md) - API参考 +- [测试报告](../tests/test_memory_graph_integration.py) - 集成测试 + +## 🤝 贡献 + +欢迎提交Issue和PR! + +## 📄 License + +MIT License - 查看 [LICENSE](../LICENSE) 文件 + +--- + +**MoFox Bot** - 更智能的记忆管理 diff --git a/docs/memory_graph_guide.md b/docs/memory_graph_guide.md new file mode 100644 index 000000000..291070063 --- /dev/null +++ b/docs/memory_graph_guide.md @@ -0,0 +1,349 @@ +# 记忆图系统使用指南 + +## 概述 + +记忆图系统是MoFox Bot的新一代记忆管理系统,基于图结构存储和管理记忆,提供更智能的记忆检索、整合和遗忘机制。 + +## 核心特性 + +### 1. 图结构存储 +- 使用**节点-边**模型表示记忆 +- 支持复杂的记忆关系网络 +- 高效的图遍历和邻接查询 + +### 2. 智能记忆检索 +- **向量相似度搜索**: 基于语义理解检索相关记忆 +- **查询优化**: 自动扩展查询关键词 +- **重要性排序**: 优先返回重要记忆 +- **图扩展**: 可选择性扩展到相邻记忆 + +### 3. 自动记忆整合 +- **相似度检测**: 自动识别相似记忆 +- **智能合并**: 合并重复记忆,提升激活度 +- **时间窗口**: 可配置整合时间范围 +- **定期执行**: 每小时自动整合(可配置) + +### 4. 记忆遗忘机制 +- **激活度衰减**: 未使用的记忆逐渐降低激活度 +- **自动清理**: 低激活度记忆自动遗忘 +- **重要性保护**: 高重要性记忆不会被遗忘 + +## 配置说明 + +### 基本配置 (`bot_config.toml`) + +```toml +[memory_graph] +# 启用开关 +enable = true + +# 数据存储目录 +data_dir = "data/memory_graph" + +# 向量数据库配置 +vector_collection_name = "memory_nodes" +vector_db_path = "" # 为空则使用data_dir + +# 检索配置 +search_top_k = 5 # 返回最相关的5条记忆 +search_min_importance = 0.0 # 最低重要性阈值 +search_similarity_threshold = 0.0 # 相似度阈值 +search_optimize_query = true # 启用查询优化 + +# 记忆整合配置 +consolidation_enabled = true # 启用自动整合 +consolidation_interval_hours = 1.0 # 每小时执行一次 +consolidation_similarity_threshold = 0.85 # 相似度>=0.85认为重复 +consolidation_time_window_hours = 24 # 整合过去24小时的记忆 + +# 记忆遗忘配置 +forgetting_enabled = true # 启用自动遗忘 +forgetting_activation_threshold = 0.1 # 激活度<0.1的记忆会被遗忘 +forgetting_min_importance = 0.3 # 重要性>=0.3的记忆不会被遗忘 + +# 激活度配置 +activation_decay_rate = 0.95 # 每天衰减5% +activation_propagation_strength = 0.1 # 传播强度10% +activation_propagation_depth = 2 # 传播深度2层 + +# 性能配置 +max_nodes_per_memory = 50 # 每个记忆最多50个节点 +max_related_memories = 10 # 最多返回10个相关记忆 +``` + +### 配置项说明 + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `enable` | bool | true | 启用记忆图系统 | +| `data_dir` | string | "data/memory_graph" | 数据存储目录 | +| `search_top_k` | int | 5 | 检索返回数量 | +| `search_optimize_query` | bool | true | 启用查询优化 | +| `consolidation_enabled` | bool | true | 启用自动整合 | +| `consolidation_interval_hours` | float | 1.0 | 整合间隔(小时) | +| `consolidation_similarity_threshold` | float | 0.85 | 相似度阈值 | +| `forgetting_enabled` | bool | true | 启用自动遗忘 | +| `forgetting_activation_threshold` | float | 0.1 | 遗忘阈值 | +| `activation_decay_rate` | float | 0.95 | 激活度衰减率 | + +## LLM工具使用 + +### 1. 创建记忆 (`create_memory`) + +**描述**: 创建一个新的记忆,包含主体、主题和相关信息。 + +**参数**: +- `subject` (必填): 记忆主体,如"用户"、"AI助手" +- `memory_type` (必填): 记忆类型,如"事件"、"知识"、"偏好" +- `topic` (必填): 记忆主题,简短描述 +- `object` (可选): 记忆对象 +- `attributes` (可选): 附加属性,JSON格式 +- `importance` (可选): 重要性0.0-1.0,默认0.5 + +**示例**: +```json +{ + "subject": "用户", + "memory_type": "偏好", + "topic": "喜欢晴天", + "importance": 0.7 +} +``` + +**返回**: +```json +{ + "name": "create_memory", + "content": "成功创建记忆（ID: mem_xxx）", + "memory_id": "mem_xxx" +} +``` + +### 2. 搜索记忆 (`search_memories`) + +**描述**: 根据查询搜索相关记忆。 + +**参数**: +- `query` (必填): 搜索查询文本 +- `top_k` (可选): 返回数量,默认5 +- `expand_depth` (可选): 图扩展深度,默认1 + +**示例**: +```json +{ + "query": "天气偏好", + "top_k": 3 +} +``` + +### 3. 关联记忆 (`link_memories`) + +**描述**: 在两个记忆之间建立关联(暂不对LLM开放)。 + +## 代码使用示例 + +### 初始化记忆管理器 + +```python +from src.memory_graph.manager_singleton import initialize_memory_manager, get_memory_manager + +# 初始化(在bot启动时调用一次) +await initialize_memory_manager() + +# 获取管理器实例 +manager = get_memory_manager() +``` + +### 创建记忆 + +```python +memory = await manager.create_memory( + subject="用户", + memory_type="事件", + topic="询问天气", + object_="上海", + attributes={"时间": "早上"}, + importance=0.7 +) +print(f"创建记忆: {memory.id}") +``` + +### 搜索记忆 + +```python +memories = await manager.search_memories( + query="天气", + top_k=5, + optimize_query=True # 启用查询优化 +) + +for mem in memories: + print(f"- {mem.get_subject_node().content}: {mem.importance}") +``` + +### 激活记忆 + +```python +# 访问记忆时会自动激活 +await manager.activate_memory(memory.id, strength=0.5) +``` + +### 手动执行维护 + +```python +# 整合相似记忆 +result = await manager.consolidate_memories( + similarity_threshold=0.85, + time_window_hours=24 +) +print(f"合并了 {result['merged_count']} 条记忆") + +# 遗忘低激活度记忆 +forgotten = await manager.auto_forget_memories( + activation_threshold=0.1, + min_importance=0.3 +) +print(f"遗忘了 {forgotten} 条记忆") +``` + +### 获取统计信息 + +```python +stats = manager.get_statistics() +print(f"总记忆数: {stats['total_memories']}") +print(f"激活记忆数: {stats['active_memories']}") +print(f"平均激活度: {stats['avg_activation']:.3f}") +``` + +## 最佳实践 + +### 1. 记忆重要性评分 + +- **0.8-1.0**: 非常重要(用户核心偏好、关键事件) +- **0.6-0.8**: 重要(常见偏好、重要对话) +- **0.4-0.6**: 一般(普通事件) +- **0.2-0.4**: 次要(临时信息) +- **0.0-0.2**: 不重要(无关紧要的细节) + +### 2. 记忆类型选择 + +- **事件**: 发生的具体事情(提问、回答、活动) +- **知识**: 事实性信息(定义、解释) +- **偏好**: 用户喜好(喜欢/不喜欢) +- **关系**: 实体之间的关系 +- **技能**: 能力或技巧 + +### 3. 性能优化 + +- 定期清理: 每周手动执行一次深度整合 +- 调整阈值: 根据实际情况调整相似度和遗忘阈值 +- 限制数量: 控制单个记忆的节点数量(<50) +- 批量操作: 使用批量API减少调用次数 + +### 4. 维护建议 + +- **每天**: 自动整合和遗忘(系统自动执行) +- **每周**: 检查统计信息,调整配置 +- **每月**: 备份记忆数据(`data/memory_graph/`) + +## 数据持久化 + +### 存储结构 + +``` +data/memory_graph/ +├── memory_graph.json # 图结构数据 +└── chroma_db/ # 向量数据库 + └── memory_nodes/ # 节点向量集合 +``` + +### 备份建议 + +```bash +# 备份整个记忆图目录 +cp -r data/memory_graph/ backup/memory_graph_$(date +%Y%m%d)/ + +# 或使用git +cd data/memory_graph/ +git add . +git commit -m "Backup: $(date)" +``` + +## 故障排除 + +### 问题1: 记忆检索返回空 + +**可能原因**: +- 向量数据库未初始化 +- 查询关键词过于模糊 +- 相似度阈值设置过高 + +**解决方案**: +```python +# 降低相似度阈值 +memories = await manager.search_memories( + query="具体关键词", + top_k=10, + min_similarity=0.0 # 降低阈值 +) +``` + +### 问题2: 记忆整合过于激进 + +**可能原因**: +- 相似度阈值设置过低 + +**解决方案**: +```toml +# 提高整合阈值 +consolidation_similarity_threshold = 0.90 # 从0.85提高到0.90 +``` + +### 问题3: 内存占用过高 + +**可能原因**: +- 记忆数量过多 +- 向量维度过高 + +**解决方案**: +```toml +# 启用更激进的遗忘策略 +forgetting_activation_threshold = 0.2 # 从0.1提高到0.2 +forgetting_min_importance = 0.4 # 从0.3提高到0.4 +``` + +## 迁移指南 + +### 从旧记忆系统迁移 + +旧记忆系统(`[memory]`配置)已废弃,建议迁移到新系统: + +1. **备份旧数据**: 备份`data/memory/`目录 +2. **更新配置**: 删除`[memory]`配置,启用`[memory_graph]` +3. **重启系统**: 新系统会自动初始化 +4. **验证功能**: 测试记忆创建和检索 + +**注意**: 旧记忆数据不会自动迁移,需要手动导入(如需要)。 + +## API参考 + +完整API文档请参考: +- `src/memory_graph/manager.py` - MemoryManager核心API +- `src/memory_graph/plugin_tools/memory_plugin_tools.py` - LLM工具 +- `src/memory_graph/models.py` - 数据模型 + +## 更新日志 + +### v7.6.0 (2025-11-05) +- ✅ 完整的记忆图系统实现 +- ✅ LLM工具集成 +- ✅ 自动整合和遗忘机制 +- ✅ 配置系统支持 +- ✅ 完整的集成测试(5/5通过) + +--- + +**相关文档**: +- [系统架构](architecture/memory_graph_architecture.md) +- [API文档](api/memory_graph_api.md) +- [开发指南](development/memory_graph_dev.md)