安全迁移 mem0：先验证契约，再切流量

记忆系统迁移不是修改一个 import。两个 API 都可能提供 add、search、update 和 delete，却对提取、身份、时间字段、过滤、分页、历史，以及何时算写入完成有不同理解。

安全路径从已经部署的真实契约开始，而不是从今天的 quickstart 开始；只有持久状态和下游答案都通过观察期，迁移才结束。

先说结论

• 盘点产品真正使用的 mem0 客户端、服务、配置和操作。
• 导出来源记录，并把导出独立保存在两个运行时之外。
• 显式映射所有权、推理、时间、元数据、历史和删除语义。
• 移动真实流量前，重放经过脱敏且具有生产形状的轨迹。
• 按用户群逐步切换，保留独立回滚和双读证据。
• 没有验证的操作和行为，不要声称兼容。

冻结来源系统的真实契约

记录 mem0 SDK 与服务版本、托管方式、向量后端、模型配置、自定义提示词、图或重排功能、默认限制，以及应用从响应中读取的每个字段。改变依赖前保存有代表性的请求与输出。

最低限度要盘点：

• 开启和关闭推理时的 add 行为；
• 搜索查询、过滤、排序和 top-k；
• 列表与分页语义；
• get、update、history 与 delete；
• user、agent、run、session、app 或 organization 作用域；
• 元数据和时间戳用法；
• 批量操作与速率限制；
• 导出格式和标识；
• 错误处理与重试行为。

生产契约可能比今天读到的文档更旧，也可能经过定制。当前文档可以参考，但不是产品曾经部署过什么的证据。

先映射语义，再映射字段

关注点	来源问题	FishMem 决策
外层租户	哪个账户或项目拥有数据？	绑定已认证项目命名空间，绝不信任正文传入值
用户与 agent 作用域	谁应该召回记录？	只有含义一致时才映射到 user_id、agent_id、run_id
推理	导出内容是持久事实还是原始对话？	已提炼记录使用 infer=false；推理另行评估
时间	时间戳代表写入、事件还是有效期？	保留已知含义，不制造精度
历史	更新是替换、追加还是替代？	明确选择当前状态和不可变历史行为
完成	来源调用何时报告成功？	确定写入同步完成；Cloud 推断写入返回持久事件

不要重新推理已经提炼好的记忆

mem0 导出通常包含记忆记录，而不是生成它们的原始对话。再经过另一个提取模型会改变措辞、丢失细节，也让团队无法区分迁移损失和新产品行为。

使用 infer=false 确定性导入记录内容，把来源标识保存在迁移 provenance 中，并在观察期结束前把原始导出独立保存。如果同时拥有原始对话并想比较新推理策略，那应该是一项单独实验。

建立迁移账本

每条来源记录都需要持久迁移状态。实用账本包括：

• 来源系统和版本；
• 来源记录 ID 与稳定导出 ID；
• 来源作用域及其 FishMem 命名空间、作用域映射；
• 内容哈希和元数据哈希；
• 事件、创建、更新时间，以及每个时间的已知含义；
• FishMem 幂等键和目标记录 ID；
• 状态、尝试次数、错误与验证结果；
• 迁移用户群和回滚负责人。

幂等键应来自稳定迁移身份，而不是循环计数器。导入程序重启后，应收敛到同一组目标记录。

重放具有生产形状的轨迹

创建隔离 FishMem 项目并重放脱敏用户旅程。比较的内容不能只限于搜索文字：

1. 持久记录与作用域；
2. 元数据和时间；
3. 更新或替代后的历史；
4. 搜索候选、排序与证据；
5. 组装后的上下文与下游答案；
6. 延迟、token 使用和失败率；
7. 重试、删除与导出行为。

案例要包括无相关记忆、冲突事实、变化偏好、重复请求、缺失元数据，以及具有相似历史的不同用户。只测试第一次成功 add，既没有测试检索，也没有测试隔离。

先做影子读取，再改变用户答案

影子阶段继续让来源系统保持权威。把同一查询发送给 FishMem，记录两组结果并比较下游决策，但不把 FishMem 输出呈现给用户。这样可以在影响生产前发现排序和格式差异。

不要要求上下文字节完全一致。两个系统可能以不同措辞和顺序支持同一个正确决策。应定义必须出现的证据、禁止出现的证据和预期答案行为。

按用户群逐步切换

1. 离线导入：迁移冻结导出，核对数量与哈希。
2. 影子读取：mem0 保持权威，同时比较检索与答案。
3. 双写：向两个系统写新命令并分别观测，不能让一方隐藏另一方失败。
4. 读取金丝雀：只为内部或少量用户启用 FishMem。
5. 扩大范围：在明确的错误和质量门槛下，逐个工作区或百分比扩大。
6. 退役：观察期、最终导出、删除计划与回滚决定完成后，才关闭来源系统。

回滚路径必须独立

依赖目标系统健康才能执行的回滚，不是独立回滚。保留来源导出、来源到目标账本、旧读取路径，以及对金丝雀期间新增写入进行对账的方法。

退役前先导出 FishMem，并验证该命名空间能够恢复到空目标。这不仅证明可以进入 FishMem，也证明可以离开。

常见迁移失败

字段同名被当成所有权相同

user_id 可能代表最终用户、账户或对话参与者。映射的是授权含义，不是字符串。

创建时间被提升为事件时间

导入时间可能只代表某行何时写入，并不代表事实何时成立。应该分开，或让事件时间保持未知。

所有来源记忆都被重新提取

迁移在声称保存内容时改变了内容。应按原文导入已提炼记录，再用原始证据单独评估新提取策略。

双写掩盖部分失败

如果任一后端成功就向应用报告成功，两边必然漂移。分别记录结果，并在每个阶段明确定义谁是权威。

验收标准

• 每条范围内来源记录只导入一次，或有一条经过审查的错误。
• 结构化作用域和授权测试覆盖对抗性用户、项目并通过。
• 当前事实与历史案例通过 holdout 集。
• 重试不制造重复，变化后的命令会明确冲突。
• 删除、导出与恢复旅程经过验证。
• 生产金丝雀的质量、错误率与延迟处于约定边界。
• 回滚负责人不需要写新代码就能执行文档化路径。

兼容性是一组证据，不是一句口号

FishMem 与 mem0 没有关联，也不声称在所有场景中无缝替代。迁移界面有意保持熟悉，但语义差异依然存在。只发布已经验证的版本和案例，其余一律标记为未测试。

延伸阅读

• FishMem mem0 迁移清单
• Mem0 记忆导出文档
• Mem0：当前记忆作用域与开放问题
• FishMem API 与命名空间不变量