feat(docs): 更新记忆系统文档，增加系统概述和核心特性，优化配置示例

更新了文档喵
2025-12-13 15:02:31 +08:00
parent f3b42dbbd9
commit 30648565a5
1 changed files with 332 additions and 66 deletions
--- 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. 启用系统
+## <20> 快速开始

-在 `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
 ```

+## <20> 核心配置
+
+### 三层记忆系统
+```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    │───────────────┼──────────────┘
+└────┬────┘               │
+     │                    │
+     ▼                    ▼
+┌─────────────────────────────────┐
+│      长期层/记忆图存储           │
+│  ├─ 向量索引                    │
+│  ├─ 图数据库                    │
+│  └─ 持久化存储                  │
+└─────────────────────────────────┘
 ```

-## 🛠️ 开发状态
+**三层记忆流向**:
+消息 → 感知层(缓冲) → 激活检测 → 短期层(结构化) → 长期层(图存储)

-### ✅ 已完成
+## <20> 常见场景

- [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