共享记忆（Shared Memory）

默认的智能体记忆模型是按用户的 — 每次对话构建一个限定到一个 (agent, user) 对的事实档案。这对于伴侣产品和一对一助手是正确的模型。但团队需要的恰恰相反：他们希望服务整个小组的一个智能体了解跨用户发生了什么。

共享记忆就是把单个智能体变成团队大脑的能力 — 它会用与用户 B 交谈时收集到的上下文回应用户 A，带归属、服务器端强制的隐私下限、完整的披露审计。再加上默认开启的 wisdom 层（不带归属的跨用户一般化），你就拥有两个互补层级的跨用户知识。

两个层级，一个能力面

两者可以同时在同一个智能体上运行。wisdom 是安全层（始终在 k-匿名化之后）；sharedMemory 是强大层（保留归属），需要谨慎地手动启用。

何时打开共享记忆

适合开启的场景：

• 团队协调员。「Alice 负责迁移；Bob 处理事故」 — 加入这个智能体的每位队友都能看到当前的责任分布。
• 小组／聚会规划。「Carol 带甜品；Dave 负责布置」 — 中途加入计划的人不必再问就能掌握当前状态。
• 共享业务工作区。 账户级智能体 — 账户上的每位用户都能受益于其他人提供的上下文。
• 多干系人支持。 客户成功智能体 — 一位干系人提供的续约上下文应该能影响与下一位的对话。

适合保持关闭的场景：

• 单用户伴侣产品（私密的一对一关系）
• 用户会因为智能体把自己的事讲给其他用户听而感到惊讶的场景
• 跨用户披露在法律上不被允许的合规敏感场景

启用共享记忆

wisdom 是先决条件（默认开启，所以通常不需要显式设置）。把 sharedMemory: true 翻开来让智能体加入。

// 新智能体的 wisdom 默认开启 — 只在你想覆盖默认值时
// 才显式设置。
await client.agents.updateCapabilities("agent_abc", {
wisdom:       true,
sharedMemory: true,
});

也可以在创建智能体时设定：

const agent = await client.agents.create({
name:       "Team Coordinator",
project_id: "proj_abc",
tool_capabilities: {
  wisdom:        true,
  shared_memory: true,
},
});

关闭共享记忆

传入 sharedMemory: false。已有的带归属事实保留在存储中（你可以稍后再开启），智能体会停止把它们暴露在上下文里，也不再获得写入工具。

await client.agents.updateCapabilities("agent_abc", { sharedMemory: false });

关闭 wisdom（少见 — 通常只在严格的单用户产品中考虑）：

await client.agents.updateCapabilities("agent_abc", { wisdom: false });

启用之后会变化什么

sharedMemory: true 一落地，三件事会同时切换：

1. 工具 — 智能体获得带归属的智慧 CRUD

LLM 多出四个新工具：

这些是延迟工具 — LLM 内联调用，平台在轮次之后异步处理写入，所以延迟保持干净。

2. 上下文 — 智能体的提示词长出"Shared facts"段落

从这一刻起智能体运行的每个系统提示词都会包含一个 Shared facts about people and entities 段落，列出已记录的带归属事实，再加上一段告诉 LLM 如何处理披露的审慎条款（"行使审慎；隐私优先于透明"）。智能体不会向每位用户倾倒所有信息 — 它会按轮次权衡披露决策。

3. 隐私下限 — 每次写入都在服务器端校验

带归属的事实在持久化之前，平台会运行一个语义校验器，拒绝有关薪酬、健康、政治以及其他配置好的隐私敏感类目的写入。这是在服务器端强制的，不在提示词里 — 哪怕用户明确请求智能体记录工资，写入也会被拦下。被拒绝的写入会以 decision = "redacted" 出现在披露审计里，所以你能看到尝试了什么、为什么被拦。

验证它在工作

三个可以对 staging 或生产端到端运行的检查。把 $AGENT_ID、$API_KEY 和平台 URL 替换成你自己的。

1. 列出智能体上的带归属事实

curl 'https://api.sonz.ai/api/v1/agents/$AGENT_ID/wisdom/attributed?limit=20' \
  -H "Authorization: Bearer $API_KEY"

期望：返回 200，body 是事实数组（entity_type、entity_id、category、value、confidence）。如果还没写入任何东西，返回空数组 — 这仍然是健康响应。

2. 直接通过 API 写入一条带归属事实

curl -X POST 'https://api.sonz.ai/api/v1/agents/$AGENT_ID/wisdom/attributed' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "person",
    "entity_id": "alice",
    "entity_display_name": "Alice",
    "category": "role",
    "value": "Lead Engineer",
    "confidence": 0.92
  }'

然后再跑一次上面的 list 端点。Alice 的角色应该出现在结果里。从此与这个智能体对话的任何用户都会在智能体的上下文里看到这条事实（受审慎条款约束）。

3. 读披露审计

curl 'https://api.sonz.ai/api/v1/agents/$AGENT_ID/wisdom/audit?limit=50' \
  -H "Authorization: Bearer $API_KEY"

每次有事实被加载到某轮次的上下文里，都会写一条 decision = "disclosed" 加 decision_why 的审计行。如果隐私下限拦下了什么东西，那一行会是 decision = "redacted"。这是你的实时可观测性 — 共享记忆开着、生产流量在跑的时候，这里就会有条目，你随时可以回查任何一次披露决策。

隐私与控制

共享记忆按设计就是敏感的。LLM 调用与一次持久化披露之间有四层控制：

1. 能力开关。 sharedMemory: false（默认）意味着什么都不会发生 — 不注册工具、不注入上下文、不写审计行。
2. 隐私下限。 语义校验器在数据落到存储之前拒绝薪酬、健康、政治等被配置为敏感的类目的写入。可按租户配置。
3. 提示词中的审慎条款。 即便事实已存在，智能体也被指示按轮次权衡披露而不是倾倒一切。
4. 披露审计。 每次披露决策都连同理由记入日志。智能体共享了什么、保留了什么、为什么 — 你随时可以通过审计端点查看。

硬删除仍然是管理员专属。智能体只能软删除（墓碑标记），所以一条被错误归属的事实在管理员永久清除之前都是可逆的。

与其他特性组合

与知识库自主编辑组合

knowledgeBaseWrite 和 sharedMemory 是独立的能力 — 任意组合都行：

• 只开 KB 写入： 智能体把关于世界的事实（产品、政策、价格、事故）写到项目知识图谱
• 只开共享记忆： 智能体记录这个团队里的人的事实（角色、专业、归属、关系）
• 两个都开： 完整的闭环组织记忆 + 团队大脑

与自我改进组合

自我改进 中按对学习的循环对那位用户越来越敏锐；共享记忆对整个团队越来越聪明。两者都在每次 sessions.End() 时自动运行。

完整 API 参考

每个共享记忆端点 — list、upsert、replace、delete、bulk import、relations CRUD、disclosure audit — 的请求／响应结构都在 Wisdom API 参考 中。

下一步

• 知识库 — 更广义的多人记忆故事
• 自我改进 — 共享记忆如何叠加在按对在线学习之上
• 组织知识库 — 位于项目之上的租户级知识
• Wisdom API — 完整端点参考