最佳实践：多 Agent 记忆与生产架构
七天实战
边学边练请访问 7 天学会 Memory Engineering：首页记忆分层可视化、/learn 七天课表、/lab 五个本地沙盒、社区与资源矩阵。
前置
开发期流水线见 开发指南。本篇对齐子站 Day6（多 Agent） 与 Day7（生产架构）。
设计原则（写进团队手册）
- Working 是稀缺资源：一切从 Token 预算倒推。
- 写入有门禁：importance、去重、冲突、权限不过则不进 LTM。
- 检索带证据：注入条目必须带来源与时间。
- 遗忘是功能：删除、归档、衰减、合规擦除可产品化。
- 评估驱动：无离线集与在线指标，禁止玄学调参。
- 多租户默认隔离：
tenant_id/user_id是索引前缀，不是可选字段。 - 多 Agent 有协议：共享不等于无权限广播。
1. 多 Agent 记忆：是什么、为什么、怎么发展、怎么落地（Day6）
1.1 四种架构模式
| 模式 | 是什么 | 优点 | 风险 | 落地建议 |
|---|---|---|---|---|
| 共享池 Shared Pool | 全员读写同一存储 | 实现简单 | 污染与竞争 | 仅限只读世界知识 |
| 分层 Hierarchical | 全局 + 团队 + 个人 | 清晰隔离 | 同步复杂 | 生产默认首选 |
| 消息传递 | 经消息交换片段 | 解耦 | 易丢、难审计 | 配投递保证与日志 |
| 联邦 Federated | 私有库 + 按需摘要共享 | 隐私好 | 摘要失真 | 敏感域/跨公司协作 |
为什么需要分层？ 一个 Agent 写错偏好，共享池会让全队立刻「信谣」。分层让错误半径可控。
怎样发展？ 从单 Bot 外挂向量 → 多角色 Crew 共用 State → 出现 Memory Specialist / 记忆中枢 → 企业级 RBAC 与联邦摘要。
1.2 团队记忆写什么
- 规范与 Definition of Done
- 决策记录（ADR 式：背景、选项、结论、反对意见）
- 任务状态与交接日志
- 共享约束（安全基线、品牌语气）
- 不写：个人凭证、未脱敏用户 PII、测试沙箱脏数据
1.3 写入协议
| 协议 | 流程 | 适用 |
|---|---|---|
| 提议-投票-提交 | propose → quorum → commit | 决策、规范变更 |
| 权威覆盖 | Tech Lead / 记忆管理员直接写 | 紧急热修 |
| 三路合并 | 以时间为基线合并冲突字段 | 分布式异步编辑 |
class TeamMemory:
def __init__(self) -> None:
self.global_kb: dict = {}
self.team: dict = {}
self.private: dict[str, dict] = {}
def propose(self, agent: str, key: str, value: object) -> dict:
return {"key": key, "value": value, "by": agent, "votes": set()}
def vote(self, proposal: dict, voter: str) -> None:
proposal["votes"].add(voter)
def commit(self, proposal: dict, quorum: int = 2) -> bool:
if len(proposal["votes"]) >= quorum:
self.team[proposal["key"]] = {
"value": proposal["value"],
"by": proposal["by"],
"voters": sorted(proposal["votes"]),
}
return True
return False
1.4 共享协议与冲突
| 机制 | 用途 |
|---|---|
| 订阅 | A 关注 B 的某类更新（如偏好变更） |
| 查询 | 经中枢检索，统一鉴权 |
| 广播 | 身份验证通过等关键事件 |
| 委托 | 记忆专员 Agent 代管某命名空间 |
冲突解决优先级建议：来源权威 > 用户确认 > 置信度 > 时间戳。离线 Agent 上线做增量同步，拒绝静默覆盖 pinned 事实。
1.5 权限模型最小集
| 级别 | 可见范围 | 示例 |
|---|---|---|
| public_team | 全员 | 迭代目标 |
| restricted | 角色组 | 薪资相关讨论摘要禁止进入 |
| private_agent | 单 Agent | 推理草稿 |
| user_sensitive | 指定服务角色 | 身份证号哈希仅风控可读 |
测 试 Agent 必须使用独立 namespace，禁止指向生产集合。
2. L1–L4 分层存储（Day7）
| 层 | 介质 | 延迟 | 存什么 |
|---|---|---|---|
| L1 | 模型上下文 | 毫秒 | Working 拼装结果 |
| L2 | Redis 等 | 亚毫秒–毫秒 | 热会话、热偏好 |
| L3 | 向量库 / KG / SQL | 十毫秒级 | 温长期记忆 |
| L4 | 对象存储 / 湖 | 百毫秒+ | 冷归档、原始审计 |
Memory Service 化：独立进程提供 gRPC/HTTP，Agent 无状态水平扩展；记忆层单独扩容与备份。
3. 多租户与数据面隔离
| 手段 | 说明 |
|---|---|
| 强制过滤器 | 所有查询自动注入 tenant_id |
| 集合/分区 | 大租户独立 collection |
| 密钥分离 | 租户级加密密钥（企业场景） |
| 配额 | 写入 QPS、存储上限、检索 TopK 上限 |
| 导出/删除 | GDPR 式数据包与证明删除 |
红队必测：伪造 user_id 读邻租户，应 100% 失败。
4. 可观测性
最少指标：
| 指标 | 含义 | 告警思路 |
|---|---|---|
| write_accept_rate | 门禁通过率 | 突降至过严或攻击 |
| recall_hit_rate | 检索是否命中评测键 | 下滑查索引/模型 |
| inject_token_p95 | 注入 Working 的 token | 预算失控 |
| end_to_end_p95 | 检索+重排延迟 | 升 ef 或扩容 |
| conflict_rate | 矛盾事实比例 | 巩固质量差 |
| forget_lag | 删除到不可检索延迟 | 合规风险 |
追踪字段：trace_id、tenant_id、memory_ids[]、rerank_model、embedding_version。
5. 评测指标
| 指标 | 测什么 |
|---|---|
| Recall@K / MRR | 该找回的记忆是否进 TopK |
| Faithfulness | 回答是否有记忆证据支持 |
| Timeliness | 过期偏好是否仍被注入 |
| Personalization | 偏好是否改变行为 |
| Harmful retention | 敏感内容是否被错误保存 |
| Isolation | 跨用户泄漏率（目标 0） |
维护 50–200 条黄金场景，CI 中跑；模型升级必须对比报告。
6. 安全与隐私
| 主题 | 实践 |
|---|---|
| 提示注入 | 用户内容与系统指令分通道；写入分类器 |
| 最小化 | 能存哈希不存明文；能存摘要不存全量录音 |
| 访问控制 | 服务账号最小权限；人管记忆需审批 |
| 保留期 | 默认 TTL；法律保留单独标记 |
| 供应商 | 第三方 Memory SaaS 签 DPA，明确训练禁用 |
7. Oncall Runbook（提纲）
- 检索全空：查 embedding 版本是否漂移、过滤条件是否过紧、集合是否指错环境。
- 串租户嫌疑：立刻切只读、导出审计、比对过滤中间件版本。
- 延迟飙升：降
efSearch、关重排实验开关、扩副本。 - 写入风暴：启配额、检查是否被工具循环写入。
- 错误偏好扩散：按
memory_id批量吊销，重建画像快照。 - 回滚：记忆 schema 与索引版本绑定发布，支持一键指回上版 collection。
8. 反模式
| 反模式 | 后果 | 纠正 |
|---|---|---|
| 全员共享一个向量集合 | 串数据、谣言放大 | 分层 + 过滤 |
| 反思原文直接当真理 | 策略漂移 | 打分与人工抽检 |
| 无限重试写入 | 放大故 障 | 熔断与幂等键 |
| 只监控 LLM 延迟不监控检索 | 误判根因 | 记忆黄金指标 |
| 生产直接调参无评测 | 不可逆体验回退 | 门禁实验平台 |
9. 上线检查表
- 租户过滤集成测试通过
- forget 在约定 SLA 内不可检索
- L1–L4 容量与备份演练完成
- 评测集基线入库
- Oncall 手册与值班表就绪
- 多 Agent 写入协议有 ADR
- 红队：注入、越权、矛盾记忆
10. 前沿如何克制采用
HippoRAG、神经符号、可微分记忆等值得跟踪，但生产采纳标准是：可观测、可回滚、可评测、有租户隔离。先在影子流量验证，再小流量。
11. 成本治理（生产必谈）
| 成本项 | 驱动因素 | 治理手段 |
|---|---|---|
| Embedding | 每条写入/重嵌 | 批量、去重后再嵌；换模型慎重建 |
| LLM 摘要/巩固 | 每日全量回顾 | 只巩固高 importance；限额条数 |
| 重排 | Cross-Encoder 对候选打分 | 初筛 Top50→精排 Top8 |
| 存储 | 无限情景原文 | TTL + 冷归档；画像替代重复句 |
| 人工审核 | 冲突与隔离区 | 抽检比例随风险调节 |
设立月度预算看板：按租户拆分写入量与检索 QPS，超额降 TopK 而非静默欠费宕机。
12. Schema 演进与版本
记忆字段会变（新增 locale、拆分 affective）。规则：
- 只增不改语义：旧字段废弃用
deprecated_at，读取兼容两版。 - 索引版本：
schema_version与embedding_version一起发布。 - 双写窗口：迁移期写新读旧+新，验证后切读。
- 禁止在线改边类型含义而不跑回填。
把重大变更写成 ADR：背景、选项、回滚、对评测集的影响。
13. 跨团队 RACI（简表）
| 活动 | 产品 | 应用研发 | 平台/记忆组 | 安全合规 | Oncall |
|---|---|---|---|---|---|
| 定义记什么 | A | C | C | C | I |
| 写路径门禁 | C | A | R | C | I |
| 索引与容量 | I | C | A | I | C |
| 评测集维护 | C | A | R | I | I |
| 事件响应 | I | C | C | C | A |
R=执行，A=问责，C=协商，I=知会。避免「人人都能改生产集合、出了事无人认领」。