18 KiB
18 KiB
🧠 MoFox 记忆系统
MoFox-Core 采用三层分级记忆架构，模拟人类记忆的生物特性，实现了高效、可扩展的记忆管理系统。本文档介绍系统架构、使用方法和最佳实践。
📐 系统架构
┌─────────────────────────────────────────────────────────────────┐
│ 用户交互 (Chat Input) │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 第1层：感知记忆 (Perceptual Memory) - 即时对话流 (50块) │
│ ├─ 消息分块存储（每块5条消息） │
│ ├─ 实时激活与召回 │
│ ├─ 相似度阈值触发转移 │
│ └─ 低开销，高频率访问 │
└─────────────────────────────────────────────────────────────────┘
↓ 激活转移
┌─────────────────────────────────────────────────────────────────┐
│ 第2层：短期记忆 (Short-term Memory) - 结构化信息 (30条) │
│ ├─ LLM 驱动的决策（创建/合并/更新/丢弃） │
│ ├─ 重要性评分（0.0-1.0） │
│ ├─ 自动转移与泄压机制 │
│ └─ 平衡灵活性与容量 │
└─────────────────────────────────────────────────────────────────┘
↓ 批量转移
┌─────────────────────────────────────────────────────────────────┐
│ 第3层：长期记忆 (Long-term Memory) - 知识图谱 │
│ ├─ 图数据库存储（人物、事件、关系） │
│ ├─ 向量检索与相似度匹配 │
│ ├─ 动态节点合并与边生成 │
│ └─ 无容量限制，检索精确 │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ LLM 回复生成（带完整上下文） │
└─────────────────────────────────────────────────────────────────┘
🎯 三层记忆详解
第1层：感知记忆 (Perceptual Memory)
特点：
- 📍 位置：即时对话窗口
- 💾 容量：50 块（250 条消息）
- ⏱️ 生命周期：短暂，激活后可转移
- 🔍 检索：相似度匹配
功能：
# 添加消息到感知记忆
await perceptual_manager.add_message(
user_id="user123",
message="最近在学习Python",
timestamp=datetime.now()
)
# 召回相关块
blocks = await perceptual_manager.recall_blocks(
query="你在学什么编程语言",
top_k=3
)
转移触发条件：
- 块被多次激活（激活次数 ≥ 3）
- 块满足转移条件后提交到短期层
第2层：短期记忆 (Short-term Memory)
特点：
- 📍 位置：结构化数据存储
- 💾 容量：30 条记忆
- ⏱️ 生命周期：中等，根据重要性动态转移
- 🧠 处理：LLM 驱动决策
功能：
# LLM 提取结构化记忆
extracted = await short_term_manager.add_from_block(block)
# 检索类似记忆
similar = await short_term_manager.search_memories(
query="Python 学习进度",
top_k=5
)
# 获取待转移记忆
to_transfer = short_term_manager.get_memories_for_transfer()
决策类型：
| 决策 | 说明 | 场景 |
|---|---|---|
CREATE_NEW |
创建新记忆 | 全新信息 |
MERGE |
合并到现有 | 补充细节 |
UPDATE |
更新现有 | 信息演变 |
DISCARD |
丢弃 | 冗余/过时 |
重要性评分：
高重要性 (≥0.6) → 优先转移到长期层
低重要性 (<0.6) → 保留或在容量溢出时删除
容量管理：
- ✅ 自动转移：占用率 ≥ 50% 时开始批量转移
- 🛡️ 泄压机制：容量 100% 时删除低优先级记忆
- ⚙️ 配置：
short_term_max_memories = 30
溢出策略（新增）：
当短期记忆达到容量上限时，支持两种处理策略，可通过配置选择：
| 策略 | 说明 | 适用场景 | 配置值 |
|---|---|---|---|
| 一次性转移 | 容量满时，将所有记忆转移到长期存储，然后删除低重要性记忆（importance < 0.6） | 希望保留更多历史信息，适合记忆密集型应用 | transfer_all（默认） |
| 选择性清理 | 仅转移高重要性记忆，直接删除低重要性记忆 | 希望快速释放空间，适合性能优先场景 | selective_cleanup |
配置方式：
[memory]
# 短期记忆溢出策略
short_term_overflow_strategy = "transfer_all" # 或 "selective_cleanup"
行为差异示例：
# 假设短期记忆已满（30条），其中：
# - 20条高重要性（≥0.6）
# - 10条低重要性（<0.6）
# 策略1: transfer_all（默认）
# 1. 转移全部30条到长期记忆
# 2. 删除10条低重要性记忆
# 结果：短期剩余20条，长期增加30条
# 策略2: selective_cleanup
# 1. 仅转移20条高重要性到长期记忆
# 2. 直接删除10条低重要性记忆
# 结果：短期剩余20条，长期增加20条
第3层：长期记忆 (Long-term Memory)
特点：
- 📍 位置：图数据库（NetworkX + Chroma）
- 💾 容量：无限
- ⏱️ 生命周期：持久，可检索
- 📊 结构：知识图谱
功能：
# 转移短期记忆到长期图
result = await long_term_manager.transfer_from_short_term(
short_term_memories
)
# 图检索
results = await memory_manager.search_memories(
query="用户的编程经验",
top_k=5
)
知识图谱节点类型：
- 👤 PERSON：人物、角色
- 📅 EVENT：发生过的事件
- 💡 CONCEPT：概念、想法
- 🎯 GOAL：目标、计划
节点关系：
participated_in：参与了某事件mentioned：提及了某人/物similar_to：相似related_to：相关caused_by：由...导致
🔧 配置说明
基础配置
文件：config/bot_config.toml
[memory]
# 启用/禁用记忆系统
enable = true
# 数据存储
data_dir = "data/memory_graph"
vector_collection_name = "memory_nodes"
vector_db_path = "data/memory_graph/chroma_db"
# 感知记忆
perceptual_max_blocks = 50 # 最大块数
perceptual_block_size = 5 # 每块消息数
perceptual_similarity_threshold = 0.55 # 召回阈值
perceptual_activation_threshold = 3 # 转移激活阈值
# 短期记忆
short_term_max_memories = 30 # 容量上限
short_term_transfer_threshold = 0.6 # 转移重要性阈值
short_term_overflow_strategy = "transfer_all" # 溢出策略（transfer_all/selective_cleanup）
short_term_enable_force_cleanup = true # 启用泄压
short_term_cleanup_keep_ratio = 0.9 # 泄压保留比例
# 长期记忆
long_term_batch_size = 10 # 批量转移大小
long_term_decay_factor = 0.95 # 激活衰减因子
long_term_auto_transfer_interval = 180 # 转移检查间隔（秒）
# 检索配置
search_top_k = 10 # 默认返回数量
search_min_importance = 0.3 # 最小重要性过滤
search_similarity_threshold = 0.6 # 相似度阈值
高级配置
[memory]
# 路径评分扩展（更精确的图检索）
enable_path_expansion = false # 启用算法
path_expansion_max_hops = 2 # 最大跳数
path_expansion_damping_factor = 0.85 # 衰减因子
path_expansion_max_branches = 10 # 分支限制
# 记忆激活
activation_decay_rate = 0.9 # 每天衰减10%
activation_propagation_strength = 0.5 # 传播强度
activation_propagation_depth = 1 # 传播深度
# 遗忘机制
forgetting_enabled = true # 启用遗忘
forgetting_activation_threshold = 0.1 # 遗忘激活度阈值
forgetting_min_importance = 0.8 # 保护重要性阈值
📚 使用示例
1. 初始化记忆系统
from src.memory_graph.manager_singleton import (
initialize_unified_memory_manager,
get_unified_memory_manager
)
# 初始化系统
await initialize_unified_memory_manager()
# 获取管理器
manager = get_unified_memory_manager()
2. 添加感知记忆
from src.memory_graph.models import MemoryBlock
# 模拟一个消息块
block = MemoryBlock(
id="msg_001",
content="用户提到在做一个Python爬虫项目",
timestamp=datetime.now(),
source="chat"
)
# 添加到感知层
await manager.add_memory(block, source="perceptual")
3. 智能检索记忆
# 统一检索（从感知→短期→长期）
result = await manager.retrieve_memories(
query="最近在做什么项目",
use_judge=True # 使用裁判模型评估是否需要检索长期
)
# 访问不同层的结果
perceptual = result["perceptual_blocks"]
short_term = result["short_term_memories"]
long_term = result["long_term_memories"]
4. 手动触发转移
# 立即转移短期→长期
result = await manager.manual_transfer()
print(f"转移了 {result['transferred_memory_ids']} 条记忆到长期层")
5. 获取统计信息
stats = manager.get_statistics()
print(f"感知记忆块数：{stats['perceptual_blocks']}")
print(f"短期记忆数：{stats['short_term_memories']}")
print(f"长期记忆节点数：{stats['long_term_nodes']}")
print(f"图边数：{stats['long_term_edges']}")
🔄 转移流程
自动转移循环
系统在后台持续运行自动转移循环，确保记忆及时流转：
每 N 秒（可配置）：
1. 检查短期记忆容量
2. 获取待转移的高重要性记忆
3. 如果缓存满或容量高，触发转移
4. 发送到长期管理器处理
5. 从短期层清除已转移记忆
触发条件（任一满足）：
- 短期记忆占用率 ≥ 50%
- 缓存记忆数 ≥ 批量大小
- 距上次转移超过最大延迟
- 短期记忆达到容量上限
代码位置：src/memory_graph/unified_manager.py 第 576-650 行
转移决策
长期记忆管理器对每条短期记忆做出决策：
# LLM 决策过程
for short_term_memory in batch:
# 1. 检索相似的长期记忆
similar = await search_long_term(short_term_memory)
# 2. LLM 做出决策
decision = await llm_decide({
'short_term': short_term_memory,
'similar_long_term': similar
})
# 3. 执行决策
if decision == 'CREATE_NEW':
create_new_node()
elif decision == 'MERGE':
merge_into_existing()
elif decision == 'UPDATE':
update_existing()
🛡️ 容量管理策略
正常流程
短期记忆累积 → 达到 50% → 自动转移 → 长期记忆保存
压力场景
高频消息流 → 短期快速堆积
↓
达到 100% → 转移来不及
↓
启用泄压机制 → 删除低优先级记忆
↓
保护核心数据，防止阻塞
泄压参数：
short_term_enable_force_cleanup = true # 启用泄压
short_term_cleanup_keep_ratio = 0.9 # 保留 90% 容量
删除策略：
- 优先删除：重要性低 AND 创建时间早
- 保留：高重要性记忆永不删除
📊 性能特性
时间复杂度
| 操作 | 复杂度 | 说明 |
|---|---|---|
| 感知记忆添加 | O(1) | 直接追加 |
| 感知记忆召回 | O(n) | 相似度匹配 |
| 短期记忆添加 | O(1) | 直接追加 |
| 短期记忆搜索 | O(n) | 向量相似度 |
| 长期记忆检索 | O(log n) | 向量数据库 + 图遍历 |
| 转移操作 | O(n) | 批量处理 |
空间复杂度
| 层级 | 估计空间 | 配置 |
|---|---|---|
| 感知层 | ~5-10 MB | 50 块 × 5 消息 |
| 短期层 | ~1-2 MB | 30 条记忆 |
| 长期层 | ~50-200 MB | 根据对话历史 |
优化技巧
- 缓存去重：避免同一记忆被转移多次
- 批量转移：减少 LLM 调用次数
- 异步操作：后台转移，不阻塞主流程
- 自适应轮询：根据容量压力调整检查间隔
🔍 检索策略
三层联合检索
result = await manager.retrieve_memories(query, use_judge=True)
流程：
- 检索感知层（即时对话）
- 检索短期层（结构化信息）
- 使用裁判模型判断是否充足
- 如不充足，检索长期层（知识图）
裁判模型：
- 评估现有记忆是否满足查询
- 生成补充查询词
- 决策是否需要长期检索
路径评分扩展（可选）
启用后使用 PageRank 风格算法在图中传播分数：
enable_path_expansion = true
path_expansion_max_hops = 2
path_expansion_damping_factor = 0.85
优势：
- 发现间接关联信息
- 上下文更丰富
- 精确度提高 15-25%
🐛 故障排查
问题1：短期记忆快速堆积
症状：短期层记忆数快速增长，转移缓慢
排查：
# 查看统计信息
stats = manager.get_statistics()
print(f"短期记忆占用率: {stats['short_term_occupancy']:.0%}")
print(f"待转移记忆: {len(manager.short_term_manager.get_memories_for_transfer())}")
解决：
- 减小
long_term_auto_transfer_interval（加快转移频率） - 增加
long_term_batch_size（一次转移更多） - 提高
short_term_transfer_threshold（更多记忆被转移）
问题2：长期记忆检索结果不相关
症状：搜索返回的记忆与查询不匹配
排查：
# 启用调试日志
import logging
logging.getLogger("src.memory_graph").setLevel(logging.DEBUG)
# 重试检索
result = await manager.retrieve_memories(query, use_judge=True)
# 检查日志中的相似度评分
解决：
- 增加
search_top_k（返回更多候选） - 降低
search_similarity_threshold（放宽相似度要求） - 检查向量模型是否加载正确
问题3：转移失败导致记忆丢失
症状：短期记忆无故消失，长期层未出现
排查：
# 检查日志中的转移错误
# 查看长期管理器的错误日志
解决：
- 检查 LLM 模型配置
- 确保长期图存储正常运行
- 增加转移超时时间
🎓 最佳实践
1. 合理配置容量
# 低频场景（私聊）
perceptual_max_blocks = 20
short_term_max_memories = 15
# 中等频率（小群）
perceptual_max_blocks = 50
short_term_max_memories = 30
# 高频场景（大群/客服）
perceptual_max_blocks = 100
short_term_max_memories = 50
short_term_enable_force_cleanup = true
2. 启用泄压保护
# 对于 24/7 运行的机器人
short_term_enable_force_cleanup = true
short_term_cleanup_keep_ratio = 0.85 # 更激进的清理
3. 定期监控
# 在定时任务中检查
async def monitor_memory():
stats = manager.get_statistics()
if stats['short_term_occupancy'] > 0.8:
logger.warning("短期记忆压力高，考虑扩容")
if stats['long_term_nodes'] > 10000:
logger.warning("长期图规模大，检索可能变慢")
4. 使用裁判模型
# 启用以提高检索质量
result = await manager.retrieve_memories(
query=user_query,
use_judge=True # 自动判断是否需要长期检索
)
📖 相关文档
🎯 快速导航
核心模块
| 模块 | 功能 | 文件 |
|---|---|---|
| 感知管理 | 消息分块、激活、转移 | perceptual_manager.py |
| 短期管理 | LLM 决策、合并、转移 | short_term_manager.py |
| 长期管理 | 图操作、节点合并 | long_term_manager.py |
| 统一接口 | 自动转移循环、检索 | unified_manager.py |
| 单例访问 | 全局管理器获取 | manager_singleton.py |
辅助工具
| 工具 | 功能 | 文件 |
|---|---|---|
| 向量生成 | 文本嵌入 | utils/embeddings.py |
| 相似度计算 | 余弦相似度 | utils/similarity.py |
| 格式化器 | 三层数据格式化 | utils/three_tier_formatter.py |
| 存储系统 | 磁盘持久化 | storage/ |
📝 版本信息
- 架构：三层分级记忆系统
- 存储：SQLAlchemy 2.0 + Chroma 向量库
- 图数据库：NetworkX
- 最后更新：2025 年 12 月 16 日