# 记忆图系统 (Memory Graph System)

> 多层次、多模态的智能记忆管理框架

## 📚 系统概述

MoFox 记忆系统是一个受人脑记忆机制启发的完整解决方案，包含三个核心组件：

| 组件 | 功能 | 用途 |
|------|------|------|
| **三层记忆系统** | 感知/短期/长期记忆 | 处理消息、提取信息、持久化存储 |
| **记忆图系统** | 基于图的知识库 | 管理实体关系、记忆演变、智能检索 |
| **兴趣值系统** | 动态兴趣计算 | 根据用户兴趣调整对话策略 |

## 🎯 核心特性

### 三层记忆系统 (Unified Memory Manager)
- **感知层**: 消息块缓冲，TopK 激活检测
- **短期层**: 结构化信息提取，智能决策合并
- **长期层**: 知识图存储，关系网络，激活度传播

### 记忆图系统 (Memory Graph)
- **图结构存储**: 使用节点-边模型表示复杂记忆关系
- **语义检索**: 基于向量相似度的智能记忆搜索
- **自动整合**: 定期合并相似记忆，减少冗余
- **智能遗忘**: 基于激活度的自动记忆清理
- **LLM集成**: 提供工具供AI助手调用

### 兴趣值系统 (Interest System)
- **动态计算**: 根据消息实时计算用户兴趣
- **主题聚类**: 自动识别和聚类感兴趣的话题
- **策略影响**: 影响对话方式和内容选择

## � 快速开始

### 方案 A: 三层记忆系统 (推荐新用户)

最简单的方式，自动处理消息流和记忆演变：

```toml
# 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"
```

```python
from src.memory_graph.manager_singleton import get_memory_manager

manager = await get_memory_manager()

# 创建记忆
memory = await manager.create_memory(
    subject="用户",
    memory_type="偏好",
    topic="喜欢晴天",
    importance=0.7
)

# 搜索和操作
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"
)
```

**特点**：灵活性高、控制力强

### 同时启用两个系统

推荐的生产配置：

```toml
[three_tier_memory]
enable = true
data_dir = "data/memory_graph/three_tier"

[memory]
enable = true
data_dir = "data/memory_graph"

[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工具示例
- [ ] 可视化界面

## 📊 系统架构

```
┌─────────────────────────────────────────────────────────────────┐
│                      用户消息/LLM 调用                            │
└────────────────────────────┬────────────────────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
        ▼                    ▼                    ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│  三层记忆系统     │ │  记忆图系统      │ │  兴趣值系统      │
│  Unified Manager │ │  MemoryManager   │ │  InterestMgr     │
└────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘
         │                    │                    │
    ┌────┴─────────────────┬──┴──────────┬────────┴──────┐
    │                      │             │               │
    ▼                      ▼             ▼               ▼
┌─────────┐        ┌────────────┐  ┌──────────┐   ┌─────────┐
│ 感知层  │        │ 向量存储   │  │ 图存储   │   │ 兴趣    │
│Percept  │        │Vector Store│  │GraphStore│   │计算器   │
└────┬────┘        └──────┬─────┘  └─────┬────┘   └─────────┘
     │                    │              │
     ▼                    │              │
┌─────────┐               │              │
│ 短期层  │               │              │
│Short    │───────────────┼──────────────┘
└────┬────┘               │
     │                    │
     ▼                    ▼
┌─────────────────────────────────┐
│      长期层/记忆图存储           │
│  ├─ 向量索引                    │
│  ├─ 图数据库                    │
│  └─ 持久化存储                  │
└─────────────────────────────────┘
```

**三层记忆流向**:
消息 → 感知层(缓冲) → 激活检测 → 短期层(结构化) → 长期层(图存储)

## � 常见场景

### 场景 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="小李"
)

# 建立关系
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！

### 贡献指南
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

MIT License - 查看 [LICENSE](../LICENSE) 文件

---

**MoFox Bot** - 更智能的记忆管理  
更新于: 2025年12月13日 | 版本: 2.0