Mofox-Core/docs/memory_graph_guide.md

记忆图系统使用指南

概述

记忆图系统是MoFox Bot的新一代记忆管理系统,基于图结构存储和管理记忆,提供更智能的记忆检索、整合和遗忘机制。

核心特性

1. 图结构存储

• 使用节点-边模型表示记忆
• 支持复杂的记忆关系网络
• 高效的图遍历和邻接查询

2. 智能记忆检索

• 向量相似度搜索: 基于语义理解检索相关记忆
• 查询优化: 自动扩展查询关键词
• 重要性排序: 优先返回重要记忆
• 图扩展: 可选择性扩展到相邻记忆

3. 自动记忆整合

• 相似度检测: 自动识别相似记忆
• 智能合并: 合并重复记忆,提升激活度
• 时间窗口: 可配置整合时间范围
• 定期执行: 每小时自动整合(可配置)

4. 记忆遗忘机制

• 激活度衰减: 未使用的记忆逐渐降低激活度
• 自动清理: 低激活度记忆自动遗忘
• 重要性保护: 高重要性记忆不会被遗忘

配置说明

基本配置 (bot_config.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

示例:

{
  "subject": "用户",
  "memory_type": "偏好",
  "topic": "喜欢晴天",
  "importance": 0.7
}

返回:

{
  "name": "create_memory",
  "content": "成功创建记忆（ID: mem_xxx）",
  "memory_id": "mem_xxx"
}

2. 搜索记忆 (search_memories)

描述: 根据查询搜索相关记忆。

参数:

• query (必填): 搜索查询文本
• top_k (可选): 返回数量,默认5
• expand_depth (可选): 图扩展深度,默认1

示例:

{
  "query": "天气偏好",
  "top_k": 3
}

3. 关联记忆 (link_memories)

描述: 在两个记忆之间建立关联(暂不对LLM开放)。

代码使用示例

初始化记忆管理器

from src.memory_graph.manager_singleton import initialize_memory_manager, get_memory_manager

# 初始化(在bot启动时调用一次)
await initialize_memory_manager()

# 获取管理器实例
manager = get_memory_manager()

创建记忆

memory = await manager.create_memory(
    subject="用户",
    memory_type="事件",
    topic="询问天气",
    object_="上海",
    attributes={"时间": "早上"},
    importance=0.7
)
print(f"创建记忆: {memory.id}")

搜索记忆

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}")

激活记忆

# 访问记忆时会自动激活
await manager.activate_memory(memory.id, strength=0.5)

手动执行维护

# 整合相似记忆
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} 条记忆")

获取统计信息

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/     # 节点向量集合

备份建议

# 备份整个记忆图目录
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: 记忆检索返回空

可能原因:

• 向量数据库未初始化
• 查询关键词过于模糊
• 相似度阈值设置过高

解决方案:

# 降低相似度阈值
memories = await manager.search_memories(
    query="具体关键词",
    top_k=10,
    min_similarity=0.0  # 降低阈值
)

问题2: 记忆整合过于激进

可能原因:

• 相似度阈值设置过低

解决方案:

# 提高整合阈值
consolidation_similarity_threshold = 0.90  # 从0.85提高到0.90

问题3: 内存占用过高

可能原因:

• 记忆数量过多
• 向量维度过高

解决方案:

# 启用更激进的遗忘策略
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通过)

---

相关文档:

• 系统架构
• API文档
• 开发指南