Spec: 自托管 Hindsight 个人记忆集成 #376

Problem Statement

用户希望 OpenBot 能跨会话记住已认可的偏好与事实，找回随时间变化的信息，并从多次经历形成可核查的判断。现有个人记忆在语义召回、时间变化与综合判断方面不足；现有本地召回还可能让未审核记录进入 Bot 上下文。OpenBot 正在建立公司与团队多租户边界，个人记忆不能因接入外部索引而跨公司、团队或来源泄露。用户还需要明确控制记忆的学习、使用、更正和遗忘，并知道删除何时真正清除了受控副本。

Solution

在自托管 OpenBot 内集成自托管 Hindsight，作为个人记忆的索引、语义检索、排序和待审核派生判断引擎。OpenBot 仍是候选、本人审核、原文、来源、权限、生效时间、遗忘和清理状态的唯一权威。Bot 只使用重新从 OpenBot 读取并再次授权的已确认个人记忆或派生记忆。完成公司与团队多租户全功能隔离验收、真实 Hindsight 部署验证及迁移对账后，对所有适用用户启用。

User Stories

1. 作为用户，我希望跨会话找回自己确认过的个人偏好，以便新会话延续我的工作方式。
2. 作为用户，我希望授权的同公司 Bot 使用我明确标为通用的个人偏好，以便不必逐个重复说明。
3. 作为用户，我希望团队业务事实仍受团队和来源权限限制，以便偏好共享不会扩大业务资料可见范围。
4. 作为同时属于多家公司的用户，我希望每家公司的个人记忆彻底隔离，以便不同公司 Bot 不会混用事实。
5. 作为团队成员，我希望其他团队无权使用本团队来源受限记忆，以便内容遵守原授权。
6. 作为用户，我希望普通对话能提出候选记忆，以便发现值得保留的信息。
7. 作为用户，我希望已启用的授权连接来源能提出候选记忆，以便整理工作中的相关事实。
8. 作为用户，我希望看到候选内容、来源、时间和证据，以便决定是否确认。
9. 作为用户，我希望能确认、编辑或拒绝候选记忆，以便控制 Bot 最终能使用的内容。
10. 作为用户，我希望未经审核的候选在任何跨会话召回路径中都不可见，以免 Bot 把建议当成已确认事实。
11. 作为用户，我希望 30 天未处理的候选过期清除，以免候选无限堆积。
12. 作为用户，我明确说“请记住”普通事实时，希望只保存我明确表述的内容，以免系统自行扩写。
13. 作为用户，即使要求保存密码或令牌，我也希望系统拒绝保存，以免凭据进入记忆。
14. 作为用户，要求保存医疗、财务或客户资料时，我希望再审核一次具体候选，以便看清实际保留内容。
15. 作为用户，我希望当前问题采用当前生效的事实、历史问题采用当时生效的事实，以免旧事实被错误覆盖。
16. 作为用户，我希望时间证据不足时 Bot 承认不确定，以免臆断变化日期。
17. 作为用户，我希望系统能从多次已确认经历提出派生判断，以便获得有用的长期认识。
18. 作为用户，我希望每条派生判断仍需本人确认，并看到全部依据，以便决定是否采纳。
19. 作为用户，我希望首版派生判断只在同一授权来源或通用个人记忆内形成，以免跨来源拼接出越权结论。
20. 作为用户，我希望回答中可展开来源、依据与有效时间，并从那里更正或遗忘，以便核查结果。
21. 作为用户，我希望单独暂停学习新记忆，以便暂时停止自动产生候选。
22. 作为用户，我希望单独暂停使用已有记忆，以便立即停止召回而不删除数据。
23. 作为用户，我希望网页聊天、频道和定时 Bot 使用相同记忆规则，以免入口改变权限或审核结果。
24. 作为用户，我希望遗忘或撤销来源后立即停止使用原始记忆和相关判断，以免等待远端清理时内容仍被召回。
25. 作为用户，我希望分别看到“已停止使用”和“受控副本清除完成”，以便理解删除进度。
26. 作为用户，我希望 Hindsight 故障时仍可从 OpenBot 找回已确认且有权的记忆，以免暂时故障抹去可用信息。
27. 作为用户，我希望后台预算耗尽时处理排队，而已有已确认记忆仍可按权限读取，以免系统错误声称新内容已学习。
28. 作为公司管理员，我希望看到服务健康、同步积压和预算用量，以便运营服务，同时看不到员工个人记忆内容。
29. 作为运营人员，我希望历史迁移仅接收公司归属可证的已确认 OpenBot 记录，以免旧数据被错归租户。
30. 作为用户，我接受放弃只存在于 CopilotKit Intelligence 而没有 OpenBot 记录的旧记忆，以便新系统只有一个可审核的事实来源。

Implementation Decisions

• 采用领域词汇：候选记忆、个人记忆、派生记忆、通用个人偏好和来源受限记忆；确认记忆不自动改变其来源授权。
• 个人记忆模块向调用方表达提出候选、审核、召回已确认内容、更正、遗忘及查看依据；bank、远端文档 ID、同步和降级留在模块内部。测试以这一现有业务边界为主要 seam。
• OpenBot 授权层从可信会话或后台任务取得公司、用户、团队、Bot 和来源资格。客户端不能选择 Hindsight bank；所有读取在返回 Bot 前重新核对当前权限、审核状态、生效时间及依据完整性。
• 共享自托管 Hindsight 服务使用隔离 bank：同公司同用户的通用个人偏好，以及按团队与来源或 Bot 限制的记忆分别划分。tag 只作分类，不作安全隔离。
• Hindsight 的自定义租户认证和操作校验只接受 OpenBot 签发的服务端身份，并限制可访问的 bank；API 和控制台不对终端用户或公司管理员开放。自托管版本、扩展接口和配置必须先经真实部署验证并固定。
• OpenBot 为已确认记忆保存稳定文档标识、同步状态和重试记录，幂等同步到 Hindsight。Hindsight 命中只提供检索排序线索；Bot 读取 OpenBot 已确认原文或已确认派生判断，不直接读取 Hindsight 提取事实、观察或 reflect 文本。
• 派生判断只依据同一授权来源或通用个人记忆中的已确认记录；保存完整依据关系。任一依据被遗忘、撤销或失权，相关判断立即停用。无法完整映射依据的 Hindsight 观察不可展示或使用。
• 已确认事实保留生效时间和更正历史。当前与历史查询分别选择对应时段的事实；时间不明不猜测。
• 普通候选必须审核，30 天未处理过期。明确“请记住”的普通事实可直接确认；密码和令牌拒收；医疗、财务和客户资料只在明确要求后提出候选并额外审核。
• 两个独立控制分别暂停自动学习与暂停使用。Hindsight 故障时，SQL 降级仅返回已确认、当前有权的记录；预算耗尽使新的后台工作进入待处理状态。
• 遗忘与来源撤销先在 OpenBot 阻断召回及依赖判断，再异步删除 Hindsight 文档与相关观察。持久遗忘记录用于重试和备份恢复后的重放。仅在活跃数据、已结束任务载荷和备份都具备实际清理证据时标记受控副本清除完成。
• Hindsight 关闭含内容模型追踪，已结束操作载荷保留 1 天，受控备份保留不超过 30 天；模型调用经 OpenBot 已批准网关。网关及外部供应商的日志留存单独核验。
• 已有 OpenBot 已确认记录只在公司归属可证时迁移；未审核记录继续待审；无 OpenBot 记录的 Intelligence 独有内容不迁移或导出。完成迁移数量和隔离对账后去除 Intelligence 的个人记忆权威路径。
• 平台承担后台处理费用，设置公司和个人预算上限。完成已批准的公司与团队多租户全功能隔离验收以及本功能安全与恢复验收后，统一向所有适用用户启用，不设按公司试点。

Testing Decisions

• 测试观察用户能否审核、召回、拒绝、更正和遗忘，以及 Bot 实际拿到的内容；不把 bank 命名、SQL 查询形状或私有实现步骤当成行为断言。以个人记忆模块的业务接口为主要 seam，辅以跨入口和真实 Hindsight 合约验证。
• 沿用现有个人记忆存储集成测试、连接来源测试与 Bot 运行中间件测试的做法；数据库测试使用专用测试 PostgreSQL，不在生产数据库运行。
• 用同一全局用户在两家公司、同公司两团队、不同成员与管理员身份，验证正向共享和越权拒绝；包括伪造身份、失权与召回后权限变化。
• 验证未审核候选在网页、频道、定时任务及 Hindsight 故障的 SQL 降级路径都不进入跨会话上下文；敏感候选需要额外审核，凭据不留存。
• 用“周五例会改为下周一、周报简短要点、两次风险优先依据”的场景验证语义召回、有效时间、派生判断审核、来源展示和删除依据后的判断失效。
• 在真实固定版本的自托管 Hindsight 上验证自定义认证、bank 隔离、共享或无 tag 观察、依据映射、文档删除、有效隐私配置、网关连接及故障降级。
• 注入同步失败、重复和乱序任务、预算耗尽、来源撤销、删除失败及备份恢复，验证状态可见、重试幂等且已遗忘内容不会复活。
• 上线验收同时包含正向功能、越权测试、迁移对账、保留与清理证据、恢复演练和适用的类型检查、静态检查及构建；任何隔离或清理证据缺失都阻断全员启用。

Out of Scope

• 公司或团队共享文档及知识库记忆。
• OpenMuse 的独立精确 ID 私有记忆。
• 首版跨不同授权来源综合派生判断。
• 迁移或导出仅存在于 CopilotKit Intelligence、没有 OpenBot 记录的旧记忆。
• 按公司试点上线；正式启用前仍需完成全功能隔离门槛。
• 以每公司单独 PostgreSQL schema 作为默认方案；若容量或隔离评估要求此方案，另作架构决策并验证维护成本。

Further Notes

• 此 Spec 依赖已批准的公司与团队多租户设计及其全功能隔离实现验收，尤其是个人记忆权限 Ticket 1123786563/OpenBot-archive#41（其父 Spec 为 1123786563/OpenBot-archive#2）；allowed_groups is documented as a channel access control but is never enforced CopilotKit/OpenBot#82 的范围是个人权限与来源选择，本 Spec 的范围是 Hindsight 集成及新增记忆行为，两者不重复交付。ready-for-agent 表示规格可供后续拆票与计划，不表示前置条件已满足、可立即派发生产实施或已经上线。
• 现状证据：个人记忆表尚缺公司归属字段；本地召回查询没有审核状态过滤。批准的需求设计和 ADR 已记录在仓库，实施时以这些事实源和后续实际代码状态核对。
• Hindsight 官方资料：项目、多租户指南、扩展、保留配置。