From 30648565a5fe26f8252b439d83914ec305d20267 Mon Sep 17 00:00:00 2001 From: LuiKlee Date: Sat, 13 Dec 2025 15:02:31 +0800 Subject: [PATCH] =?UTF-8?q?feat(docs):=20=E6=9B=B4=E6=96=B0=E8=AE=B0?= =?UTF-8?q?=E5=BF=86=E7=B3=BB=E7=BB=9F=E6=96=87=E6=A1=A3=EF=BC=8C=E5=A2=9E?= =?UTF-8?q?=E5=8A=A0=E7=B3=BB=E7=BB=9F=E6=A6=82=E8=BF=B0=E5=92=8C=E6=A0=B8?= =?UTF-8?q?=E5=BF=83=E7=89=B9=E6=80=A7=EF=BC=8C=E4=BC=98=E5=8C=96=E9=85=8D?= =?UTF-8?q?=E7=BD=AE=E7=A4=BA=E4=BE=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 更新了文档喵 --- docs/memory_graph_README.md | 398 ++++++++++++++++++++++++++++++------ 1 file changed, 332 insertions(+), 66 deletions(-) diff --git a/docs/memory_graph_README.md b/docs/memory_graph_README.md index 79a1aa83a..b02a50ae6 100644 --- a/docs/memory_graph_README.md +++ b/docs/memory_graph_README.md @@ -1,119 +1,384 @@ # 记忆图系统 (Memory Graph System) -> 基于图结构的智能记忆管理系统 +> 多层次、多模态的智能记忆管理框架 -## 🎯 特性 +## 📚 系统概述 +MoFox 记忆系统是一个受人脑记忆机制启发的完整解决方案，包含三个核心组件： + +| 组件 | 功能 | 用途 | +|------|------|------| +| **三层记忆系统** | 感知/短期/长期记忆 | 处理消息、提取信息、持久化存储 | +| **记忆图系统** | 基于图的知识库 | 管理实体关系、记忆演变、智能检索 | +| **兴趣值系统** | 动态兴趣计算 | 根据用户兴趣调整对话策略 | + +## 🎯 核心特性 + +### 三层记忆系统 (Unified Memory Manager) +- **感知层**: 消息块缓冲，TopK 激活检测 +- **短期层**: 结构化信息提取，智能决策合并 +- **长期层**: 知识图存储，关系网络，激活度传播 + +### 记忆图系统 (Memory Graph) - **图结构存储**: 使用节点-边模型表示复杂记忆关系 - **语义检索**: 基于向量相似度的智能记忆搜索 -- **自动整合**: 定期合并相似记忆,减少冗余 +- **自动整合**: 定期合并相似记忆，减少冗余 - **智能遗忘**: 基于激活度的自动记忆清理 - **LLM集成**: 提供工具供AI助手调用 -## 📦 快速开始 +### 兴趣值系统 (Interest System) +- **动态计算**: 根据消息实时计算用户兴趣 +- **主题聚类**: 自动识别和聚类感兴趣的话题 +- **策略影响**: 影响对话方式和内容选择 -### 1. 启用系统 +## � 快速开始 -在 `config/bot_config.toml` 中: +### 方案 A: 三层记忆系统 (推荐新用户) + +最简单的方式，自动处理消息流和记忆演变： ```toml -[memory_graph] +# config/bot_config.toml +[three_tier_memory] +enable = true +data_dir = "data/memory_graph/three_tier" +``` + +```python +from src.memory_graph.unified_manager_singleton import get_unified_manager + +# 添加消息（自动处理） +unified_mgr = await get_unified_manager() +await unified_mgr.add_message( + content="用户说的话", + sender_id="user_123" +) + +# 跨层搜索记忆 +results = await unified_mgr.search_memories( + query="搜索关键词", + top_k=5 +) +``` + +**特点**：自动转移、智能合并、后台维护 + +### 方案 B: 记忆图系统 (高级用户) + +直接操作知识图，手动管理记忆： + +```toml +# config/bot_config.toml +[memory] enable = true data_dir = "data/memory_graph" ``` -### 2. 创建记忆 - ```python from src.memory_graph.manager_singleton import get_memory_manager -manager = get_memory_manager() +manager = await 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 +# 搜索和操作 +memories = await manager.search_memories(query="天气", top_k=5) +node = await manager.create_node(node_type="person", label="用户名") +edge = await manager.create_edge( + source_id="node_1", + target_id="node_2", + relation_type="knows" ) ``` -## 🔧 配置说明 +**特点**：灵活性高、控制力强 -| 配置项 | 默认值 | 说明 | -|--------|--------|------| -| `enable` | true | 启用开关 | -| `search_top_k` | 5 | 检索数量 | -| `consolidation_interval_hours` | 1.0 | 整合间隔 | -| `forgetting_activation_threshold` | 0.1 | 遗忘阈值 | +### 同时启用两个系统 -完整配置参考: [使用指南](memory_graph_guide.md#配置说明) +推荐的生产配置： -## 🧪 测试状态 +```toml +[three_tier_memory] +enable = true +data_dir = "data/memory_graph/three_tier" -✅ **所有测试通过** (5/5) +[memory] +enable = true +data_dir = "data/memory_graph" -- ✅ 基本记忆操作 (CRUD + 检索) -- ✅ LLM工具集成 -- ✅ 记忆生命周期管理 -- ✅ 维护任务调度 -- ✅ 配置系统 - -运行测试: -```bash -python tests/test_memory_graph_integration.py +[interest] +enable = true ``` +## � 核心配置 + +### 三层记忆系统 +```toml +[three_tier_memory] +enable = true +data_dir = "data/memory_graph/three_tier" +perceptual_max_blocks = 50 # 感知层最大块数 +short_term_max_memories = 100 # 短期层最大记忆数 +short_term_transfer_threshold = 0.6 # 转移到长期的重要性阈值 +long_term_auto_transfer_interval = 600 # 自动转移间隔(秒) +``` + +### 记忆图系统 +```toml +[memory] +enable = true +data_dir = "data/memory_graph" +search_top_k = 5 # 检索数量 +consolidation_interval_hours = 1.0 # 整合间隔 +forgetting_activation_threshold = 0.1 # 遗忘阈值 +``` + +### 兴趣值系统 +```toml +[interest] +enable = true +max_topics = 10 # 最多跟踪话题 +time_decay_factor = 0.95 # 时间衰减因子 +update_interval = 300 # 更新间隔(秒) +``` + +**完整配置参考**: +- 📖 [MEMORY_SYSTEM_OVERVIEW.md](MEMORY_SYSTEM_OVERVIEW.md#配置说明) - 详细配置说明 +- 📖 [MEMORY_SYSTEM_QUICK_REFERENCE.md](MEMORY_SYSTEM_QUICK_REFERENCE.md) - 快速参考表 + +## 📚 文档导航 + +### 快速入门 +- 🔥 **[快速参考卡](MEMORY_SYSTEM_QUICK_REFERENCE.md)** - 常用命令和快速查询（5分钟） + +### 用户指南 +- 📖 **[完整系统指南](MEMORY_SYSTEM_OVERVIEW.md)** - 三层系统、记忆图、兴趣值详解（30分钟） +- 📖 **[三层记忆指南](three_tier_memory_user_guide.md)** - 感知/短期/长期层工作流（20分钟） +- 📖 **[记忆图指南](memory_graph_guide.md)** - LLM工具、记忆操作、高级用法（20分钟） + +### 开发指南 +- 🛠️ **[开发者指南](MEMORY_SYSTEM_DEVELOPER_GUIDE.md)** - 模块详解、开发流程、集成方案（1小时） +- 🛠️ **[原有API参考](../src/memory_graph/README.md)** - 代码级API文档 + +### 学习路径 + +**新手用户** (1小时): +- 1. 阅读本 README (5分钟) +- 2. 查看快速参考卡 (5分钟) +- 3. 运行快速开始示例 (10分钟) +- 4. 阅读完整系统指南的使用部分 (30分钟) +- 5. 在插件中集成记忆 (10分钟) + +**开发者** (3小时): +- 1. 快速入门 (1小时) +- 2. 阅读三层记忆指南 (20分钟) +- 3. 阅读记忆图指南 (20分钟) +- 4. 阅读开发者指南 (60分钟) +- 5. 实现自定义记忆类型 (20分钟) + +**贡献者** (8小时+): +- 1. 完整学习所有指南 (3小时) +- 2. 研究源代码 (2小时) +- 3. 理解图算法和向量运算 (1小时) +- 4. 实现高级功能 (2小时) +- 5. 编写测试和文档 (ongoing) + +## ✅ 开发状态 + +### 三层记忆系统 (Phase 3) +- [x] 感知层实现 +- [x] 短期层实现 +- [x] 长期层实现 +- [x] 自动转移和维护 +- [x] 集成测试 + +### 记忆图系统 (Phase 2) +- [x] 插件系统集成 +- [x] 提示词记忆检索 +- [x] 定期记忆整合 +- [x] 配置系统支持 +- [x] 集成测试 + +### 兴趣值系统 (Phase 2) +- [x] 基础计算框架 +- [x] 组件管理器 +- [x] AFC 策略集成 +- [ ] 高级聚类算法 +- [ ] 趋势分析 + +### 📝 计划优化 +- [ ] 向量检索性能优化 (FAISS集成) +- [ ] 图遍历算法优化 +- [ ] 更多LLM工具示例 +- [ ] 可视化界面 + ## 📊 系统架构 ``` -记忆图系统 -├── MemoryManager (核心管理器) -│ ├── 创建/删除记忆 -│ ├── 检索记忆 -│ └── 维护任务 -├── 存储层 -│ ├── VectorStore (向量检索) -│ ├── GraphStore (图结构) -│ └── PersistenceManager (持久化) -└── 工具层 - ├── CreateMemoryTool - ├── SearchMemoriesTool - └── LinkMemoriesTool +┌─────────────────────────────────────────────────────────────────┐ +│ 用户消息/LLM 调用 │ +└────────────────────────────┬────────────────────────────────────┘ + │ + ┌────────────────────┼────────────────────┐ + │ │ │ + ▼ ▼ ▼ +┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ +│ 三层记忆系统 │ │ 记忆图系统 │ │ 兴趣值系统 │ +│ Unified Manager │ │ MemoryManager │ │ InterestMgr │ +└────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘ + │ │ │ + ┌────┴─────────────────┬──┴──────────┬────────┴──────┐ + │ │ │ │ + ▼ ▼ ▼ ▼ +┌─────────┐ ┌────────────┐ ┌──────────┐ ┌─────────┐ +│ 感知层 │ │ 向量存储 │ │ 图存储 │ │ 兴趣 │ +│Percept │ │Vector Store│ │GraphStore│ │计算器 │ +└────┬────┘ └──────┬─────┘ └─────┬────┘ └─────────┘ + │ │ │ + ▼ │ │ +┌─────────┐ │ │ +│ 短期层 │ │ │ +│Short │───────────────┼──────────────┘ +└────┬────┘ │ + │ │ + ▼ ▼ +┌─────────────────────────────────┐ +│ 长期层/记忆图存储 │ +│ ├─ 向量索引 │ +│ ├─ 图数据库 │ +│ └─ 持久化存储 │ +└─────────────────────────────────┘ ``` -## 🛠️ 开发状态 +**三层记忆流向**: +消息 → 感知层(缓冲) → 激活检测 → 短期层(结构化) → 长期层(图存储) -### ✅ 已完成 +## � 常见场景 -- [x] Step 1: 插件系统集成 (fc71aad8) -- [x] Step 2: 提示词记忆检索 (c3ca811e) -- [x] Step 3: 定期记忆整合 (4d44b18a) -- [x] Step 4: 配置系统支持 (a3cc0740, 3ea6d1dc) -- [x] Step 5: 集成测试 (23b011e6) +### 场景 1: 记住用户偏好 +```python +# 自动处理 - 三层系统会自动学习 +await unified_manager.add_message( + content="我喜欢下雨天", + sender_id="user_123" +) -### 📝 待优化 +# 下次对话时自动应用 +memories = await unified_manager.search_memories( + query="天气偏好" +) +``` -- [ ] 性能测试和优化 -- [ ] 扩展文档和示例 -- [ ] 高级查询功能 +### 场景 2: 记录重要事件 +```python +# 显式创建高重要性记忆 +memory = await memory_manager.create_memory( + subject="用户", + memory_type="事件", + topic="参加了一个重要会议", + content="详细信息...", + importance=0.9 # 高重要性，不会遗忘 +) +``` -## 📚 文档 +### 场景 3: 建立关系网络 +```python +# 创建人物和关系 +user_node = await memory_manager.create_node( + node_type="person", + label="小王" +) +friend_node = await memory_manager.create_node( + node_type="person", + label="小李" +) -- [使用指南](memory_graph_guide.md) - 完整的使用说明 -- [API文档](../src/memory_graph/README.md) - API参考 -- [测试报告](../tests/test_memory_graph_integration.py) - 集成测试 +# 建立关系 +await memory_manager.create_edge( + source_id=user_node.id, + target_id=friend_node.id, + relation_type="knows", + weight=0.9 +) +``` + +## 🧪 测试和监测 + +### 运行测试 +```bash +# 集成测试 +python -m pytest tests/test_memory_graph_integration.py -v + +# 三层记忆测试 +python -m pytest tests/test_three_tier_memory.py -v + +# 兴趣值系统测试 +python -m pytest tests/test_interest_system.py -v +``` + +### 查看统计 +```python +from src.memory_graph.manager_singleton import get_memory_manager + +manager = await get_memory_manager() +stats = await manager.get_statistics() +print(f"记忆总数: {stats['total_memories']}") +print(f"节点总数: {stats['total_nodes']}") +print(f"平均激活度: {stats['avg_activation']:.2f}") +``` + +## 🔗 相关资源 + +### 核心文件 +- `src/memory_graph/unified_manager.py` - 三层系统管理器 +- `src/memory_graph/manager.py` - 记忆图管理器 +- `src/memory_graph/models.py` - 数据模型定义 +- `src/chat/interest_system/` - 兴趣值系统 +- `config/bot_config.toml` - 配置文件 + +### 相关系统 +- 📚 [数据库系统](../docs/database_refactoring_completion.md) - SQLAlchemy 架构 +- 📚 [插件系统](../src/plugin_system/) - LLM工具集成 +- 📚 [对话系统](../src/chat/) - AFC 策略集成 +- 📚 [配置系统](../src/config/config.py) - 全局配置管理 + +## 🐛 故障排查 + +### 常见问题 + +**Q: 记忆没有转移到长期层？** +A: 检查短期记忆的重要性是否 ≥ 0.6，或查看 `short_term_transfer_threshold` 配置 + +**Q: 搜索不到记忆？** +A: 检查相似度阈值设置，尝试降低 `search_similarity_threshold` + +**Q: 系统占用磁盘过大？** +A: 启用更积极的遗忘机制，调整 `forgetting_activation_threshold` + +**更多问题**: 查看 [完整系统指南](MEMORY_SYSTEM_OVERVIEW.md#常见问题) 或 [快速参考](MEMORY_SYSTEM_QUICK_REFERENCE.md) ## 🤝 贡献 -欢迎提交Issue和PR! +欢迎提交 Issue 和 PR！ + +### 贡献指南 +1. Fork 项目 +2. 创建功能分支 (`git checkout -b feature/amazing-feature`) +3. 提交更改 (`git commit -m 'Add amazing feature'`) +4. 推送到分支 (`git push origin feature/amazing-feature`) +5. 开启 Pull Request + +## 📞 获取帮助 + +- 📖 查看文档: [完整指南](MEMORY_SYSTEM_OVERVIEW.md) +- 💬 GitHub Issues: 提交 bug 或功能请求 +- 📧 联系团队: 通过官方渠道 ## 📄 License @@ -121,4 +386,5 @@ MIT License - 查看 [LICENSE](../LICENSE) 文件 --- -**MoFox Bot** - 更智能的记忆管理 +**MoFox Bot** - 更智能的记忆管理 +更新于: 2025年12月13日 | 版本: 2.0