[RFC] 关于经验记忆on-policy更新与记忆文件的版本化方案

[chenjw]

Memory Data Versioning 方案

日期： 2026-05-28
状态： Draft

---

目标

为记忆文件（memory files）增加版本化能力，满足以下需求：

1. 记忆文件支持版本历史。
2. 检索时可基于 data_version 查看某个历史时刻的记忆状态。
3. 不同版本的 diff 保存在记忆文件内部。
4. 支持按版本读取和 materialize 记忆内容。
5. 向量索引仅维护最新版本，避免多版本向量存储成本。

---

背景与动机

引入 memory versioning 的核心原因，不只是为了“可回溯”或“可审计”，更重要的是为了支持 on-policy memory update。

关键术语

为避免歧义，本文统一使用以下术语：

• on-policy memory update
  • 指经验（experience / memory）的写入、消费、评估，都应基于同一历史策略视图（policy view）来分析。
• policy view
  • 指 Agent 在某个时刻真实可见的一组 memory / experience 状态。
• experience consumption
  • 指 Agent 在执行任务时，对 memory / experience 的实际读取和使用。
• historical memory state
  • 指 memory 在某个历史 data_version 下的状态，而不是当前 latest state。
• time travel (over memory)
  • 指通过 data_version 回到某个历史 policy view，对当时的 memory state 进行读取、检索与分析。

为什么需要 on-policy memory update

在 experience system 中，memory 不是静态知识，而是会随着任务反馈持续更新的策略对象（policy object）。

这意味着：

• Agent 在任务 T1 执行时，依赖的是当时的 policy view；
• 任务结束后，系统可能会把新的经验写入 memory；
• 到任务 T2 时，Agent 消费的 memory 已经发生变化；
• 因此，T1 和 T2 实际上处在不同的 historical memory state 下。

如果系统只保留 latest state，而不保留 historical memory state，那么 experience consumption 的分析就会被“事后知识”污染，导致经验更新无法做真正的 on-policy 归因。换句话说，系统失去了对 memory policy view 的 time travel 能力。

示例：为什么需要 on-policy 视角

假设有一个 game agent，在挑战同一个 Boss，目标是尽快学会稳定通关。

历史过程

• 在 data_version = v1 时，memory 中还没有这条经验：
  • E1：Boss 放红圈大招前，会先抬手 1 秒，这时要立刻闪避，不要贪输出。
• Task A：Agent 第一次打 Boss。
  • 当时的 policy view = v1
  • Agent 看到 Boss 抬手，但不知道这是大招前摇，于是继续输出
  • 结果被大招击杀
• 任务结束后，系统抽取并写入新经验 E1
• memory 更新到 data_version = v2
• Task B：Agent 第二次打 Boss
  • 当时的 policy view = v2
  • Agent 看到 Boss 抬手，识别为大招前摇，立即闪避
  • 结果成功存活，并完成通关

如果系统支持 on-policy memory update

系统可以明确区分：

• Task A 的 experience consumption 基于 policy view(v1)
• Task B 的 experience consumption 基于 policy view(v2)

这样在分析时就能得到正确结论：

• Task A 失败，是因为当时的 historical memory state 中还没有 E1；
• Task B 表现变好，很可能是因为 v2 中新增的经验 E1 已经进入了新的 policy view，并被实际消费了。

如果系统不支持 on-policy memory update

如果系统只保留 latest state（即只看到 v2），那么回看 Task A 时会产生错误理解：

• 当前 memory 明明已经写着“Boss 抬手后立刻闪避”；
• 系统会误以为 Task A 执行时也拥有这条经验；
• 从而错误地认为：
  • Task A 是“明知道该闪避却还在贪输出”；
  • 或者 Agent 执行不稳定；
  • 而不是“当时的 policy view 中根本没有这条经验”。

这就会带来几个典型问题：

1. 历史决策被未来知识污染

   • 过去对局中的行为，会被后续才学到的经验反向解释。

2. 经验效果归因错误

   • 无法判断 Task B 的改善究竟来自：
     • experience update
     • 随机发挥更好
     • Boss 行为恰好更容易处理

3. 经验生成与经验消费错位

   • 一条在 Task A 之后才生成的经验，会被错误地当成 Task A 执行时已存在的前提。

4. 评估结果失真

   • 系统无法准确回答：
     • 某条经验是否真的改变了后续对局行为；
     • 某次表现提升是否来自 memory update；
     • 某类经验是否值得保留或强化。

图示：遵守 on-policy 与不遵守 on-policy 的区别

下面用 Boss 战例子说明，为什么 experience system 需要遵守 on-policy memory update。

场景

Agent 学到一条新经验：

• E1：Boss 放红圈大招前，会先抬手 1 秒，这时要立刻闪避，不要贪输出。

情况 A：遵守 on-policy

sequenceDiagram
    participant TA as Task A (policy view = v1)
    participant M as Memory
    participant EU as Experience Update
    participant TB as Task B (policy view = v2)

    Note over M: v1: no E1
    TA->>M: consume policy view(v1)
    Note over TA: Boss 抬手<br/>继续输出<br/>被大招击杀

    TA->>EU: 从失败中抽取经验
    EU->>M: 写入 E1<br/>Boss 抬手 1 秒后会放红圈大招，应立即闪避
    Note over M: v2: with E1

    TB->>M: consume policy view(v2)
    Note over TB: Boss 抬手<br/>识别为大招前摇<br/>立刻闪避并通关

Loading

结论：

• Task A 基于 v1
• Task B 基于 v2
• 可以正确分析：Task B 的改善，很可能来自 E1 被写入并进入了新的 policy view

情况 B：不遵守 on-policy

也就是在事后分析时，只看 latest memory，而不回到当时的 historical memory state。

flowchart LR
    A[Task A 执行于 v1] --> U[写入经验 E1]
    U --> B[Task B 执行于 v2]

    A -. 事后统一拿 latest(v2) 回看 .-> X[Task A 被误判为
明明知道要闪避却还在贪输出]
    B -. 也统一拿 latest(v2) 回看 .-> Y[Task B 的改善
无法准确归因到 E1]

Loading

结果：

• Task A 被错误地当成“明明知道要闪避却还在贪输出”
• Task B 的改善也无法准确归因到 E1

---

本方案解决的问题

因此，memory versioning 的本质，不只是“保存历史”，而是为 memory / experience 提供一个时间维度上的 policy view。从能力定义上看，这本质上也是一种对 memory state 的 time travel capability。

这也是为什么本方案必须支持：

• 按版本 read
  • 用于恢复某次任务执行时的 historical memory state
  • 可视为对 memory 的 time-travel read
• 按版本 search
  • 用于近似重建某次任务当时的 experience consumption 视图
  • 可视为对 policy view 的 time-travel search
• 检索后 materialize 到目标版本
  • 用于把 latest recall 映射回目标 policy view

最终目标是让经验系统能够做到：

• 写入是增量演化的（memory update）
• 消费是版本感知的（experience consumption is version-aware）
• 分析是 on-policy 的（evaluation is based on the correct policy view）

---

已确认的设计约束

1. 版本参数

统一使用：

• data_version

2. 版本号形式

使用毫秒级时间戳。

约定：

• 一次 memory apply / extraction batch 开始时生成一个统一的 data_version
• 这一批里所有被修改或删除的文件共用同一个 data_version

因此，data_version 是一批 memory 变更的全局版本号，而不是单文件独立版本号。

3. 检索语义

当指定：

search(query, data_version=X)

语义为：

• 先按最新向量索引召回候选文件
• 对每个候选文件，取 <= X 的最近可用状态进行还原
• 如果某个候选文件不存在 <= X 的历史版本，则说明该文件在该版本视角下不存在可用状态，不应被召回

4. 向量策略

采用简化方案：

• 向量索引只保留最新版本
• 不为历史版本维护独立 embedding
• 历史检索通过“先召回最新，再按版本还原文件内容”实现

该方案的特点：

• 优点：实现简单、存储成本低
• 缺点：历史召回并非严格基于历史语义，只是基于最新语义的近似召回

5. 历史存储位置

• 版本 diff 保存在记忆文件内部

6. 正文与版本链关系

• 文件正文始终保存最新版本
• 历史版本通过 reverse diff 链从最新版本逐步回退得到

7. diff 粒度

• 采用整文件文本 diff
• diff 覆盖范围包括：
  • 正文内容
  • 普通 MEMORY_FIELDS

8. 删除策略

• 采用逻辑删除
• 默认检索不返回已删除文件
• 历史版本仍可恢复
• 删除时保留删除前最后正文，仅通过 VERSION_HISTORY.status = "deleted" 标记当前状态

9. checkpoint / compact

一期不做 checkpoint：

• 先使用“最新正文 + reverse diff 链”
• 后续通过 compact 机制压缩历史版本

10. diff 算法

本方案区分两类 diff，用于不同目的：

10.1 存储层 diff（用于 VERSION_HISTORY）

• 使用 diff-match-patch
• 用途：
  • 生成 reverse diff
  • 存入 VERSION_HISTORY
  • 用于历史版本回放（time travel）
• 设计目标：
  • 压缩率高
  • 程序可稳定 apply
  • 适合 machine-oriented 的版本链存储

10.2 合并层 diff（用于 LLM merge）

• 使用 unified diff
• 用途：
  • 在 head_version != src_version 时，向 LLM 展示 base / head / candidate 之间的差异
  • 辅助 LLM 做 merge decision
• 设计目标：
  • 易读
  • LLM 熟悉
  • 适合 model-oriented 的差异理解与冲突判断

10.3 双 diff 策略

因此本方案采用：

• 内部版本链存储：diff-match-patch
• LLM 合并分析：unified diff

也就是说：

• 存在 VERSION_HISTORY 里的 diff，不直接面向 LLM；
• 给 LLM 做 merge 判断的 diff，不进入版本链存储，而是在 merge path 中按需动态生成。

11. 历史读取范围

• 支持按版本 search 和按版本 read
• 历史版本用于恢复某个时刻的 memory 视图

12. 历史版本保留策略

• 每个记忆文件最多保留最近 100 个历史版本
• 超过 100 个版本时，直接丢弃最老版本
• 一期不做 checkpoint，不做 compact 合并

13. 并发与锁策略

• 写入 memory_file 时必须加锁
• 锁粒度为单文件级别（per-memory-file exclusive lock）
• 同一时刻只允许一个写入流程修改同一个 memory file
• 历史读取时不加读锁
• 读取正确性依赖写锁和原子落盘保证

14. 历史数据兼容性

• 需要兼容已存在但不包含 VERSION_HISTORY 的历史 memory file
• 对于这类文件，系统应将其视为仅包含当前 head 的单版本文件
• 读取当前版本时应正常工作，不要求强制迁移
• 当按 data_version 读取或检索时，当前文件版本的判断顺序为：
  1. 优先使用 VERSION_HISTORY.data_version
  2. 若缺失，则退化为 VERSION_HISTORY.updated_at
  3. 若两者都缺失，则视为版本未知的历史数据单版本文件
• 对于版本未知的历史数据单版本文件：
  • 不传 data_version 时可正常返回当前内容
  • 传入 data_version 时，不参与历史判断，直接视为不存在可用版本
• 若请求版本大于等于该文件当前可判定版本，则可直接返回当前内容
• 若请求版本早于该文件当前可判定版本，则视为不存在可用版本，不应返回该文件
• 历史文件在后续第一次被新版写入后，可自动补齐 VERSION_HISTORY

---

总体思路

Patch 定义

本文中的 patch，特指：

• 基于 diff-match-patch 生成的文本 patch
• 其 base 是 src_version 对应的 memory file 内容

语义上可表示为：

base_content_at_src_version + patch = candidate_updated_content

也就是说：

• patch 不是经验语义层的抽象描述；
• patch 是面向 memory file 文本内容的变更补丁；
• patch 的上下文依赖 src_version，不能脱离 base 单独解释。

Patch apply 规则

经验提炼完成后，系统会先基于 src_version 恢复出 base file，再生成 candidate updated content，随后通过 diff-match-patch 生成 patch。

apply 规则如下：

1. 如果 head_version == src_version

   • 说明 patch 的 base 与当前 latest head 一致；
   • 可以直接做确定性 apply。

2. 如果 head_version != src_version

   • 说明 patch 是针对旧 base 生成的；
   • latest head 已在 patch 生成后继续演化；
   • 此时不能直接 apply patch，而应进入 merge path。

从设计上看，这个规则可以概括为：

• same-base → deterministic apply
• diverged-base → merge path

---

核心原则

每个记忆文件只保留一份最新完整内容，历史通过文件内版本链回溯。

即：

• 当前态：文件正文
• 历史态：文件内部保存 reverse diff 列表
• 删除态：逻辑删除标记

当需要查看历史版本时：

1. 读取最新正文
2. 根据 data_version 找出目标版本
3. 逐条应用 reverse diff
4. 得到目标时刻的文件内容

---

文件结构设计

建议把记忆文件拆成三部分：

1. 正文（最新版本内容）
2. MEMORY_FIELDS（普通业务元数据）
3. VERSION_HISTORY（系统版本元数据 + 版本链）

其中：

• MEMORY_FIELDS 参与 diff
• VERSION_HISTORY 不参与 diff 基线

这样可以避免“历史记录本身不断进入下一次 diff”的套娃问题。

---

建议文件格式

用户偏好：
- 喜欢简洁回答
- 喜欢 TypeScript
- 不喜欢过度解释

<!-- MEMORY_FIELDS
{
  "memory_type": "preferences"
}
-->

<!-- VERSION_HISTORY
{
  "data_version": 1780000000123,
  "updated_at": "2026-05-27T15:10:23.456Z",
  "status": "active",
  "versions": [
    {
      "data_version": 1780000000123,
      "op": "update",
      "reverse_diff": "..."
    },
    {
      "data_version": 1779999999000,
      "op": "update",
      "reverse_diff": "..."
    },
    {
      "data_version": 1779999998000,
      "op": "create",
      "reverse_diff": null
    }
  ]
}
-->

---

版本语义

1. VERSION_HISTORY.data_version

表示当前文件正文对应的最新版本。

2. VERSION_HISTORY.status

表示当前正文在当前版本下的状态。

建议值：

• active
• deleted

3. versions

每个 version item 表示：

• 当前这版如何回退到上一版

例如：

• v3 version 保存 v3 -> v2 的 reverse diff
• v2 version 保存 v2 -> v1 的 reverse diff

因此，版本链方向是：

• 从新到旧逐步回退

---

写入流程设计

建议在现有 memory apply / updater 流程中改造。

Step 1：生成 batch 级 data_version

一次 memory apply 开始时生成统一版本号：

data_version = max(now_ms, last_data_version + 1)

目的：

• 保证单调递增
• 保证一次 batch 内所有文件共用同一个全局版本号

Step 2：处理单文件写入

场景 A：新建文件

• 写入最新正文
• 设置：
  • VERSION_HISTORY.data_version = 当前 batch data_version
  • VERSION_HISTORY.updated_at = 当前写入时间
  • VERSION_HISTORY.status = "active"
• VERSION_HISTORY.versions 追加：
  • op = create
  • reverse_diff = null

场景 B：更新文件

流程：

1. 读取旧完整文件文本（正文 + MEMORY_FIELDS，不含 VERSION_HISTORY）
2. 生成新完整文件文本（正文 + MEMORY_FIELDS，不含 VERSION_HISTORY）
3. 计算 reverse diff：

new_full_text -> old_full_text

4. 写入新正文与新 MEMORY_FIELDS
5. 更新 VERSION_HISTORY.data_version、VERSION_HISTORY.updated_at、VERSION_HISTORY.status
6. 在 VERSION_HISTORY.versions 追加：
   • data_version = 当前 batch data_version
   • op = update
   • reverse_diff = ...

场景 C：逻辑删除

流程：

1. 不删除正文
2. 写入：
   • VERSION_HISTORY.status = "deleted"
   • VERSION_HISTORY.updated_at = now
   • VERSION_HISTORY.data_version = 当前 batch data_version
3. 追加版本记录：
   • op = delete
   • reverse_diff = 当前 status=deleted 状态 -> 删除前状态

这样历史还原时即可恢复删除前内容。

---

还原流程设计

提供一个核心能力：

materialize_memory_at_version(file_uri, data_version)

还原逻辑

不传 data_version

• 直接返回当前 head 内容
• 若当前 VERSION_HISTORY.status = "deleted"，则默认视为不可见

传入 data_version = X

流程：

1. 读取最新文件正文、MEMORY_FIELDS 与 VERSION_HISTORY
2. 获取 VERSION_HISTORY.data_version（当前正文版本）
3. 若文件不存在任何 <= X 的历史版本：
   • 说明该文件在该版本视角下不存在可用状态，返回 not found / not visible
   • 对于不包含 VERSION_HISTORY 的历史文件，应按“仅存在当前 head 单版本”处理
4. 若 VERSION_HISTORY.data_version <= X：
   • 直接返回当前版本
5. 否则，从新到旧遍历 VERSION_HISTORY.versions
6. 对所有 entry.data_version > X 的记录依次应用 reverse_diff
7. 得到目标版本完整文本
8. 解析目标版本下的 MEMORY_FIELDS 与 VERSION_HISTORY
9. 若该版本 VERSION_HISTORY.status = "deleted"，则该版本不可见；否则返回

---

检索流程设计

接口形式

search(query, data_version=None)

流程

Step 1：最新向量召回

从当前向量索引召回候选 memory file URI。

Step 2：历史还原

对每个候选 URI 调用：

materialize_memory_at_version(uri, data_version)

Step 3：过滤删除态

• 当 data_version is None：
  • 过滤当前 VERSION_HISTORY.status = "deleted" 的文件
• 当指定 data_version：
  • 如果该历史版本的 status = "deleted"，则该文件不可见

Step 4：返回还原内容

将还原后的文本作为最终检索结果返回，或用于后续 prompt 注入。

---

删除可见性规则

默认检索

不传 data_version 时：

• 已逻辑删除文件不参与返回结果

历史检索

传 data_version 时：

• 如果目标版本当时未删除，则可见
• 如果目标版本当时已删除，则不可见

---

存储实现细节建议

1. VERSION_HISTORY 不参与 diff 基线

建议参与 diff 的“可还原业务文本”只包括：

• 正文
• MEMORY_FIELDS

不包括：

• VERSION_HISTORY

否则历史链本身会反复被写入 diff，导致版本膨胀。

2. diff 算法建议

推荐使用成熟文本 diff / patch 方案，例如：

• unified diff
• diff-match-patch

要求：

• 支持 reverse patch
• 支持稳定 apply
• 支持 patch 失败检测

3. 后续 compact 预留

虽然一期不做 compact，但建议版本历史结构预留压缩能力，例如未来支持：

• 历史条目合并
• 老版本快照化
• 版本链裁剪

4. 版本历史上限

一期直接限制：

• 每个文件最多保留最近 100 个历史版本
• 超过上限时，丢弃最老版本 item

这意味着非常老的历史版本可能不可恢复。

5. 单文件写锁

写入 memory file 时必须加单文件排他锁：

• 锁对象建议使用 memory file URI
• 锁覆盖范围包括：读取旧版本、生成 reverse diff、更新正文、更新 MEMORY_FIELDS、更新 VERSION_HISTORY
• 目的是保证版本链一致性，避免并发写入导致 diff 基线错误或历史链损坏

---

建议 metadata 字段

MEMORY_FIELDS

只保留业务元数据，例如：

{
  "memory_type": "preferences"
}

VERSION_HISTORY

建议结构：

{
  "data_version": 1780000000123,
  "updated_at": "2026-05-27T15:10:23.456Z",
  "status": "active",
  "versions": [
    {
      "data_version": 1780000000123,
      "op": "update",
      "reverse_diff": "..."
    },
    {
      "data_version": 1779999999000,
      "op": "delete",
      "reverse_diff": "..."
    },
    {
      "data_version": 1779999998000,
      "op": "create",
      "reverse_diff": null
    }
  ]
}

---

建议接口

1. 读取当前或历史版本

read_memory(uri, data_version=None)

2. 检索当前或历史版本

search(query, data_version=None)

3. 逻辑删除

delete_memory(uri, data_version=batch_data_version)

说明：

• 历史版本支持按版本读取与按版本检索

---

结论

本方案采用：

• data_version 作为 batch 级全局版本号
• 记忆文件正文保存最新版本
• 历史通过文件内 reverse diff 链保存
• 检索时先用最新向量召回，再按 data_version 还原目标状态
• 删除采用逻辑删除

这是一个偏工程实用的一期方案：

• 优先降低实现复杂度
• 保持与现有系统兼容
• 先完成可用版本化能力
• 后续再通过 compact / checkpoint 增强性能与健壮性

[huangruiteng]

【示例：为什么需要 on-policy 视角】这里，我觉得在不支持版本化方案时，系统是能 trace 并知道 E1 是否影响了 agent 的执行。这里真正需要版本化的原因是 E1 的更新，比如 E1 中增加了一行关键信息，这种感知不到。
但似乎可通过流式学习 E1 来辅助解决。

[chenjw]

【示例：为什么需要 on-policy 视角】这里，我觉得在不支持版本化方案时，系统是能 trace 并知道 E1 是否影响了 agent 的执行。这里真正需要版本化的原因是 E1 的更新，比如 E1 中增加了一行关键信息，这种感知不到。 但似乎可通过流式学习 E1 来辅助解决。

当更新记忆的时候LLM看到E1存在，但是用户的操作没有躲闪的时候，并不知道是因为没有使用E1才导致了问题。这个就算有trace也解决不了吧。