docs(memory-graph): 添加完整的使用文档
- 创建memory_graph_guide.md (完整使用指南) - 创建memory_graph_README.md (快速开始) - 更新TODO.md (标记记忆图系统完成) 文档内容: - 系统概述和核心特性 - 配置说明 (35+配置项) - LLM工具使用示例 - 代码使用示例 - 最佳实践建议 - 故障排除指南 - 迁移指南 - API参考 完成状态: Step 1-5 全部完成 所有集成测试通过 (5/5) 文档完整
This commit is contained in:
Windpicker-owo
8
TODO.md
8
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通过)
|
||||
|
||||
|
||||
- 大工程
|
||||
|
||||
124
docs/memory_graph_README.md
Normal file
124
docs/memory_graph_README.md
Normal file
@@ -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** - 更智能的记忆管理
|
||||
349
docs/memory_graph_guide.md
Normal file
349
docs/memory_graph_guide.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user