aiagent/docs/chat-assistant/智能体聊天助手记忆存储说明.md

智能体聊天助手记忆存储说明

一、数据存储位置

1. 主要存储：Redis

智能体聊天助手使用 Redis 作为记忆数据的持久化存储后端。

• 存储键名格式：user_memory_{user_id}
  • 例如：user_memory_default、user_memory_12345
• 存储位置：Redis 数据库（默认 DB 0）
• 数据格式：JSON 字符串

2. 备用存储：内存缓存

如果 Redis 不可用，系统会回退到内存缓存（Memory Cache）。

⚠️ 重要提示：内存缓存只在单次执行会话内有效，执行结束后数据会丢失，无法跨会话保留。

3. 存储结构

每个用户的记忆数据包含以下字段：

{
  "conversation_history": [
    {
      "role": "user",
      "content": "我的名字叫老七",
      "timestamp": "2024-01-01T10:00:00"
    },
    {
      "role": "assistant",
      "content": "好的，我记住了你的名字是老七。",
      "timestamp": "2024-01-01T10:00:01"
    }
  ],
  "user_profile": {
    // 用户画像信息（可扩展）
  },
  "context": {
    // 上下文信息（可扩展）
  }
}

二、数据大小限制

1. Redis 存储限制

• 单条记录大小：

  • Redis 理论上单个 key 的值最大可达 512MB（默认配置）
  • 实际使用中，受 Redis 服务器配置的 maxmemory 限制
  • 当前系统：无硬编码限制（取决于 Redis 服务器配置）

• 对话历史累积：

  • 对话历史会不断累积，没有自动截断机制
  • 每次对话会添加 2 条记录（用户消息 + 助手回复）
  • 假设每条消息平均 200 字（约 600 字节），1000 轮对话约 1.2MB

2. 实际使用情况

根据当前系统检查：

• 当前用户记忆 key 数量：1 个
• 示例 key 大小：约 5.73 KB（20 条对话历史）
• Redis 已使用内存：2.52 MB
• Redis 最大内存限制：无限制（取决于服务器配置）

3. 建议的容量规划

对话轮数	预估大小	说明
100 轮	~120 KB	适合短期对话
500 轮	~600 KB	适合中期对话
1000 轮	~1.2 MB	适合长期对话
5000 轮	~6 MB	需要监控内存使用
10000 轮	~12 MB	建议实施截断策略

三、数据持久化与丢失风险

1. 数据持久化机制

Redis 持久化（推荐）

• 持久化方式：取决于 Redis 配置
  • RDB：定期快照，默认开启
  • AOF：追加日志，可选开启
• Docker 卷持久化：
  • 使用 redis_data 卷存储数据
  • 即使容器重启，数据也会保留
  • 数据存储在 Docker 卷中，位置：/var/lib/docker/volumes/redis_data

内存缓存（不持久化）

• 数据仅存在于进程内存中
• 进程重启后数据丢失
• 仅用于 Redis 不可用时的临时回退

2. 数据丢失风险分析

场景	数据是否丢失	说明
Redis 正常重启	❌ 不丢失	数据已持久化到磁盘
Docker 容器重启	❌ 不丢失	数据存储在 Docker 卷中
Redis 数据卷被删除	✅ 会丢失	需要重新创建卷
超过 TTL 时间	✅ 会过期	默认 24 小时后过期
Redis 服务器故障	⚠️ 取决于持久化配置	如果持久化配置不当可能丢失
使用内存缓存时	✅ 会丢失	每次执行后丢失

3. TTL（生存时间）设置

当前配置：

• TTL：86400 秒（24 小时）
• 位置：cache-update 节点的 ttl 配置
• 默认值：如果未配置，默认 3600 秒（1 小时）

⚠️ 重要：如果用户在 24 小时内没有新的对话，记忆数据会自动过期删除。

四、配置说明

1. Redis 配置

环境变量（docker-compose.dev.yml）：

REDIS_URL=redis://redis:6379/0

配置文件（backend/.env）：

REDIS_URL=redis://localhost:6379/0

2. Cache 节点配置

查询记忆节点（cache-query）：

{
    "id": "cache-query",
    "type": "cache",
    "data": {
        "operation": "get",
        "key": "user_memory_{user_id}",
        "default_value": '{"conversation_history": [], "user_profile": {}, "context": {}}'
    }
}

更新记忆节点（cache-update）：

{
    "id": "cache-update",
    "type": "cache",
    "data": {
        "operation": "set",
        "key": "user_memory_{user_id}",
        "value": '{"conversation_history": {{memory.conversation_history}} + [...], ...}',
        "ttl": 86400  # 24小时
    }
}

五、优化建议

1. 对话历史截断策略

如果对话历史过长，建议实施截断策略：

方案 A：保留最近 N 条

# 在 cache-update 节点中，限制 conversation_history 长度
conversation_history = memory.conversation_history[-100:]  # 只保留最近100条

方案 B：按时间截断

# 只保留最近7天的对话
from datetime import datetime, timedelta
cutoff_date = (datetime.now() - timedelta(days=7)).isoformat()
conversation_history = [
    msg for msg in memory.conversation_history 
    if msg.get('timestamp', '') > cutoff_date
]

方案 C：智能摘要

# 将旧对话历史压缩为摘要
# 使用 LLM 节点生成摘要，保留关键信息

2. 增加 TTL 时间

如果需要更长的记忆保留时间，可以修改 TTL：

"ttl": 604800  # 7天
"ttl": 2592000  # 30天
"ttl": 0  # 永不过期（不推荐，可能导致内存溢出）

3. 监控 Redis 内存使用

定期检查 Redis 内存使用情况：

# 进入 Redis 容器
docker exec -it aiagent-redis-1 redis-cli

# 查看内存信息
INFO memory

# 查看所有用户记忆 key
KEYS user_memory_*

# 查看特定 key 的大小
MEMORY USAGE user_memory_default

4. 数据备份策略

定期备份 Redis 数据：

# 备份 Redis 数据
docker exec aiagent-redis-1 redis-cli SAVE
docker cp aiagent-redis-1:/data/dump.rdb ./backup/dump_$(date +%Y%m%d).rdb

恢复 Redis 数据：

# 恢复 Redis 数据
docker cp ./backup/dump_20240101.rdb aiagent-redis-1:/data/dump.rdb
docker restart aiagent-redis-1

六、常见问题

Q1: 数据会丢失吗？

A:

• 如果使用 Redis 且配置了持久化：不会丢失（除非数据卷被删除或超过 TTL）
• 如果使用内存缓存：会丢失（每次执行后丢失）

Q2: 可以存储多少对话？

A:

• 理论上：取决于 Redis 服务器内存限制
• 实际建议：1000-5000 轮对话（约 1-6 MB）
• 超过 10000 轮建议实施截断策略

Q3: 如何延长记忆保留时间？

A:

• 修改 cache-update 节点的 ttl 配置
• 设置为更大的值（如 2592000 = 30 天）
• 或设置为 0（永不过期，需谨慎）

Q4: 如何清理特定用户的记忆？

A:

# 通过 Redis CLI
docker exec -it aiagent-redis-1 redis-cli DEL user_memory_{user_id}

# 或通过工作流添加 delete 操作节点

Q5: 多个用户的数据会互相影响吗？

A:

• 不会，每个用户使用独立的 key：user_memory_{user_id}
• 数据完全隔离

七、总结

当前配置

• ✅ 存储位置：Redis（持久化）
• ✅ TTL：24 小时
• ✅ 数据格式：JSON（包含对话历史、用户画像、上下文）
• ✅ 大小限制：无硬编码限制（取决于 Redis 配置）
• ⚠️ 数据丢失风险：低（除非数据卷被删除或超过 TTL）

建议

1. 短期使用（< 1000 轮对话）：当前配置足够
2. 长期使用（> 5000 轮对话）：建议实施对话历史截断策略
3. 生产环境：建议定期备份 Redis 数据，监控内存使用
4. 高可用场景：考虑 Redis 主从复制或集群模式

---

文档版本：v1.0
最后更新：2024年
维护人员：AI Assistant