记忆系统的多实体作用域隔离

记忆系统的多实体作用域隔离

学习目标

读完本章后，你将能够：

• 理解记忆系统中三层作用域（user/agent/session）的设计动机
• 设计基于 filters 的灵活记忆过滤机制
• 实现存储元数据模板与查询过滤器的双通道构建
• 评估多实体隔离在多租户场景下的适用性

核心概念

三层作用域模型

AI 记忆系统需要同时服务多种粒度的”记忆主体”：

作用域	标识符	生命周期	典型用途
User	user_id	永久	用户偏好、个人信息、历史交互
Agent	agent_id	永久	Agent 配置、知识库、推荐历史
Session	run_id	单次运行	临时上下文、任务状态、运行日志

双通道构建器

添加或查询记忆时，需要同时构建存储元数据模板和查询过滤器：

存储元数据模板：用于写入新记忆时附加的元数据，包含所有提供的 session 标识符和用户自定义 metadata。

查询过滤器：用于检索已有记忆时的过滤条件，包含 session 标识符、用户自定义 filters，以及可选的 actor_id（用于区分同一会话中的不同发言者）。

实体 ID 验证与规范化

实体 ID 需要满足：

• 去除首尾空白
• 禁止空字符串或纯空白
• 禁止包含内部空白（防止 “user 123” 这类带空格的 ID 导致过滤异常）

Actor 过滤

actor_id 是一个可选的额外过滤维度，用于区分同一会话中的不同发言者（如多 speaker 对话中的 “John”、“Maria”）。它不加入存储元数据模板——因为 actor 通常在消息内容中派生，而非预先指定。

设计优势与代价

优势

1. 灵活组合：可同时使用多个标识符（如 user_id + agent_id 表示”该 Agent 与该用户的交互记忆”）
2. 强制隔离：至少需要一个标识符，防止”全局记忆”泄露
3. 深拷贝安全：metadata 和 filters 使用深拷贝，防止跨调用污染
4. 可选 Actor 过滤：支持多 speaker 场景的精细化过滤

代价

1. API 复杂度：filters 需要构造嵌套字典，对新手不友好
2. 组合爆炸：多个标识符组合时，过滤逻辑可能变复杂
3. Actor 元数据不一致：actor 不在存储模板中，仅在查询时作为过滤条件

陷阱与对策

陷阱	对策
未提供任何标识符导致全局查询	强制验证：至少一个标识符，否则抛异常
标识符含空格导致过滤异常	规范化验证：拒绝含内部空格的 ID
metadata 跨调用污染	使用 deepcopy 隔离每次调用的 metadata
filters 中逻辑运算符（AND/OR/NOT）不被向量存储支持	在应用层预处理，转换为向量存储兼容的格式