设计经得起重试的异步记忆写入
2026年8月5日指南
迁移图记忆时，别把事件与时间压平成字符串
2026年7月15日指南阅读约 13 分钟
一套保留来源导出、显式映射事实与时间状态，并用下游决策验收的迁移方法。
图记忆导出不是一张记忆列表。它可能包含原始 episode、实体、事实边、时间有效性、摘要、community、嵌入、命名空间，以及一段可以直接放进提示词的上下文。只复制渲染后的上下文，保存的是某次查询看到的结果，却丢掉以后纠正和重建所需的结构。
安全迁移需要确认来源系统里哪些产物是权威、哪些图产物是派生，以及目标系统必须为应用复现什么行为。
先说结论
- 冻结已部署的 Zep 或 Graphiti 契约，改变任何内容前先导出原始 episode。
- 分别映射 episode、事实、实体、时间与命名空间。
- 确定性导入已经派生的事实，不要压平成一个上下文字符串。
- 让每条目标记录都能追溯到全部来源 episode。
- 只从保留证据重建派生投影。
- 比较下游决策、历史、删除与故障行为，不比较提示词字节是否相同。
盘点你真正使用的图
记录服务与 SDK 版本、存储后端、group 或 user 标识、自定义实体与边类型、提取指令、搜索 recipe、重排器、上下文模板和删除行为。捕获的是应用实际发出的请求，不是来源产品提供的全部功能。
Graphiti 把接入事件建模为 episode，并把提取实体和事实边与 episode 关联。Zep 在此之上提供托管用户、thread、检索和治理能力。生产集成可能只使用消息接入与上下文块，也可能直接查询 node、edge、episode 和过滤器；这是两个不同规模的迁移项目。
分开来源产物与派生产物
| 来源产物 | 可能的权威 | 目标处理方式 |
|---|---|---|
| Episode 正文与 reference time | 原始接入证据 | 作为来源或重放输入保存，并带 provenance |
| 实体 node | 从 episode 解析出的身份 | 只有应用依赖稳定实体身份时才映射 |
| 事实 edge | 派生关系与时间状态 | 以带作用域事实导入，并保留全部支撑 episode |
| 摘要或 community | 可重建综合视图 | 保留为可选视图，绝不作为唯一证据 |
| 渲染后的 context block | 查询时展示 | 用于比较，不作为迁移权威 |
| 嵌入或排序分数 | 模型特定投影 | 在目标索引中重建 |
保存 episode 要先于保存事实
一条提取事实未必逐字出现在消息或业务记录中。它的可信度来自回到一个或多个 episode 的关联。需要保存 episode 内容、来源描述、reference time、group 或 user 身份、元数据，以及支撑每条事实的全部关联。
多个 episode 可能再次确认或让一条关系失效，应保留完整关联集。只复制第一个来源，会破坏后续删除、访问过滤，以及解释事实为何改变的能力。
按照时间字段的含义映射
Graphiti 事实边可能包含创建、有效、失效与过期信息；FishMem 记录包含事件时间、有效区间、系统历史与替代关系。字段名称不如它们回答的问题重要：
- 来源事件何时发生？
- 关系何时开始成立？
- 它何时停止成立？
- 来源系统何时知道或改变它？
- 哪一条新记录替代了旧记录？
未知值保持为空。不要用导出时间代替事件时间，也不要从模糊历史陈述中推断精确区间。
映射实体之前先映射命名空间
Graphiti group_id、Zep user graph，以及 FishMem 的 project、user、agent、run 都能分区数据，但它们的授权含义可能不同。先决定哪个目标命名空间拥有数据，再决定哪些结构化 ID 可以成为安全检索过滤。
需要用不同来源 group 中名字相似的实体执行对抗测试。实体去重绝不能因为语义匹配认为两个 node 很像，就跨越安全边界。
选择事实导入策略
重放 episode
重新接入 episode，让 FishMem 推理产生新记录。这能评估新的提取策略，但结果不是来源图的无损迁移。
保留事实
关闭推理，导入已导出的事实内容，保留时间字段与 episode provenance，再重建目标索引。这最能保留来源系统已经作出的结论。
混合迁移
确定性保存高价值事实，同时保留 episode 用于引用和未来受控重处理。在理解差异之前，把新推理运行在单独评估命名空间。
不能默默混用三种策略。迁移账本需要记录每条目标记录由哪条路径产生。
从证据重建投影
实体关联、语义索引、全文索引、画像和提示词摘要都很有用，但它们依赖具体模型与实现。应在目标系统中重建并比较行为，直到新投影通过观察期才删除原始导出。
应用依赖自定义 ontology 时，需要显式映射。把关系降成普通字符串可能保留人类语义，却丢失类型化查询；反过来，把来源里的每种 node 类型都复制进目标，又可能复刻产品从未使用的复杂性。
比较决策，不比较上下文字节
为下列情况建立轨迹案例：
- 矛盾之后的当前事实；
- 指定时点的历史问题；
- 多跳关系；
- 带来源作用域的检索；
- 实体别名与合并；
- 共享事实存在时删除某个 episode；
- 命名空间隔离；
- 没有证据时拒绝回答；
- 真实图规模下的延迟与 token 预算。
比较必需证据和下游答案。只要在预算内支持同一个有证据的决策，排序或格式不同是可以接受的。
删除是最难的完整性测试
删除一个 episode 时，要决定哪些事实、实体、摘要和索引随之变化。由两个 episode 支撑的事实应保留剩余关联；只由被删 episode 支撑的事实可能需要删除或失效。目标系统不能留下没有任何可检查来源的派生结论。
删除应在双读阶段测试，而不是切换完成后才测试。它能暴露迁移保存的是一条活的来源关系，还是仅仅把来源 ID 复制进了元数据。
分阶段迁移方案
- 冻结来源版本，导出 episode、图产物、schema 和配置。
- 建立来源到目标映射与迁移账本。
- 导入一张小型隔离图，核对数量、哈希、时间与关联。
- 重建检索投影并运行脱敏轨迹集。
- 影子运行生产查询并比较决策。
- 以一个来源 group 或用户群做金丝雀，并保留独立回滚。
- 测试更新、矛盾、episode 删除、导出和恢复。
- 只有质量、隔离、延迟与运营门槛都成立时才扩大。
这里的兼容是什么意思
FishMem 与 Zep、Graphiti 没有关联，也不声称 SDK 或 context block 兼容。成功迁移保留的是你选择的应用决策与证据，而不是来源图内部每项实现细节。
