概要
我正在推进 No.36：在 ReLax 中复现 MemAgent 的多轮记忆训练流程。目前本地已完成 GPU 验证前的实现、CPU 单测和 mock 集成验证。本 Issue 用于同步当前设计、实现过程中发现的框架接线问题、已有证据，以及仍待完成的 GPU 和效果验收。
关联的早期方案讨论：#196。本 Issue 以当前实际实现和已冻结的复现口径为准。
当前冻结的参考版本如下：
论文中的 Qwen2.5-7B/14B 指标仅作为 sanity reference。本任务的直接工程对照是固定版本的 VIME Qwen3-4B 配方，因为 VIME 没有公开该 example 的训练后 Qwen3-4B checkpoint 或完整指标表。
已实现的行为
当前 patch 主要新增 examples/mem_agent/，实现了以下完整链路：
- 将冻结版本的 HotpotQA 文件转换为包含
question/context/ground_truth 的 JSONL，并记录源文件和转换结果的 SHA-256；
- 按 token 将长文档连续切成 2048-token chunks；
- 每个 chunk 独立调用一次 SGLang，请求只包含
question + previous memory + current chunk；
- 每轮用本轮输出覆盖 memory，并重新 tokenize、硬截断到 1024 tokens；
- 最后一轮只基于
question + final memory 生成答案；
- 从最终
\boxed{} 答案计算一次 HotpotQA normalized exact-match reward；
- 保存所有 memory-update turn 和 final-answer turn，并严格对齐
tokens、response_length、loss_mask、rollout_log_probs；
- 先在 trajectory/GRPO group 维度完成 reward normalization，再无损展开所有 turns，不裁掉尾部样本；
- 默认采用与固定 VIME 代码一致的
split credit，同时保留并测试论文语义对应的 share 选项；
- 用一条 pipeline 串联数据准备、训练、逐 step reward 汇总、final checkpoint 转换和评测。
冻结配方使用 2048-token chunk、1024-token memory、256-token final answer、最多 64 chunks、GRPO group size 8、LR 1e-6 和 KL coefficient 0.001。
实现中发现的框架接线问题
现有 custom sample-converter 参数虽然会被 RolloutManager 加载，但 transfer 和 debug-replay 路径仍直接调用内置 converter。另外，一条 trajectory 会展开为数量不固定的 turn rows，而原 TransferQueue 容量、grouping 和 Actor 消费数量都按 trajectory 数量计算。
因此，除了 examples/mem_agent/，当前本地 patch 还包含以下受配置开关保护的小范围框架调整：
- transfer 和 debug replay 实际调用配置的 custom converter；
- 允许声明 TransferQueue storage capacity 使用的最大展开倍数；
- 对已经完成 GRPO normalization 的展开 rows 使用 group size 1；
- 由 producer 报告实际转换并写入的 row count；
- 按
rollout_id 协调 row count，并在生成/转换失败时唤醒等待方，避免 Actor hang；
- Actor 精确消费本轮已写入 rows，并校验其可被 DP size 整除；
- 未启用 expanded-batch 配置时，保留原有 converter、sampler、capacity 和 fixed-batch 行为。
这些调整涉及 Controller、TransferQueue 和 Actor 接线，但只在 MemAgent custom config 显式开启后生效；没有修改 SGLang core、Service lifecycle、Launcher、公开 Sample 字段或 checkpoint 格式。
评测与复现口径
评测脚本让冻结 base、VIME checkpoint 和 ReLax checkpoint 共用同一套 recurrent inference 代码。每次评测会保留逐样本 JSONL，并在 summary 中记录 data SHA-256、evaluator schema、tokenizer、采样参数、chunk/memory 上限、样本数和请求错误数。
当前建议的效果验收口径为：
- VIME 固定配方与 ReLax 配方使用相同模型、数据、seed、采样配置和硬件，各独立训练一次；
- 每个待比较 checkpoint 在预先选定的 RULER-HQA 长度上至少完成一次评测，默认长度为 50/200/800 documents；
- RULER-HQA 主指标使用
sub_EM；
- 每个选定长度都满足
abs(sub_EM_ReLax - sub_EM_VIME) <= 3 个百分点；
- ReLax 在每个选定 RULER-HQA 长度上都优于冻结 recurrent base，并在 HotpotQA boxed exact match 上优于 base；
- 保留并报告全部逐样本结果；评测不完整或存在请求错误时，不允许用于宣称验收通过。
固定 VIME 官方入口的有效上限是 64 chunks：run-eval.sh 会 source _common.sh，从而覆盖 Python evaluator 单独运行时的 fallback。ReLax 显式固定 64。最终报告必须披露超过 64 chunks 的截断情况，不能把发生截断的 800-document 评测描述成读取了完整上下文。
已完成的验证
当前本地证据如下：
- MemAgent/custom-converter/expanded-row 目标测试：
45 passed；
- 相邻默认路径回归：
14 passed, 4 skipped；
- Ray utility 子集：
3 passed, 33 skipped，平台相关用例在当前 CPU 环境按既有条件跳过；
- 所有 MemAgent shell 脚本通过
bash -n；
git diff --check 通过；- 全仓
pre-commit run --all-files --show-diff-on-failure 通过；
- 独立贡献 worktree clean，当前有 5 个本地 commit，尚未 push。
测试已覆盖 chunk 边界、memory 覆盖和硬上限、final prompt 隔离、多答案 boxed EM、每 turn 字段对齐、先归一化后展开、split/share credit、producer/consumer 精确 row-count 契约、异常唤醒、debug replay、冻结 prompt variant、评测控制变量校验和逐 step reward 完整汇总。
尚未完成的验收
CPU 和 mock 测试不能代替真实分布式 GPU 链路。以下项目尚未执行，也不声明已经通过：
- 连续 2 个真实 Ray/SGLang/Megatron GRPO step 无 error、OOM 或 hang；
- 在真实链路中核对 generated/transferred/Actor-consumed turn count 完全一致；
- final checkpoint 保存及 Hugging Face 转换；
- 通过真实推理 endpoint 完成 recurrent HotpotQA/RULER-HQA 评测；
- 100-step reward 趋势有明显提升；
- VIME/ReLax 成对训练与 3 个百分点
sub_EM 对比。
下一执行 gate 是 2-step GPU smoke。Qwen3-0.6B 单卡实验可以作为低成本控制流诊断，但不会替代冻结的 Qwen3-4B，也不能作为正式效果验收结果。
概要
我正在推进 No.36：在 ReLax 中复现 MemAgent 的多轮记忆训练流程。目前本地已完成 GPU 验证前的实现、CPU 单测和 mock 集成验证。本 Issue 用于同步当前设计、实现过程中发现的框架接线问题、已有证据，以及仍待完成的 GPU 和效果验收。
关联的早期方案讨论：#196。本 Issue 以当前实际实现和已冻结的复现口径为准。
当前冻结的参考版本如下：
8d8f25586da035661f95053d748421d33b8c9b68；8a54679e971087566bfda939a5f75649e07fb861；Qwen/Qwen3-4B@1cfa9a7208912126459214e8b04321603b3df60c；BytedTsinghua-SIA/hotpotqa@27275ff4fee67ac0acb6478e405e7ac07efbdc1a。论文中的 Qwen2.5-7B/14B 指标仅作为 sanity reference。本任务的直接工程对照是固定版本的 VIME Qwen3-4B 配方，因为 VIME 没有公开该 example 的训练后 Qwen3-4B checkpoint 或完整指标表。
已实现的行为
当前 patch 主要新增
examples/mem_agent/，实现了以下完整链路：question/context/ground_truth的 JSONL，并记录源文件和转换结果的 SHA-256；question + previous memory + current chunk；question + final memory生成答案；\boxed{}答案计算一次 HotpotQA normalized exact-match reward；tokens、response_length、loss_mask、rollout_log_probs；splitcredit，同时保留并测试论文语义对应的share选项；冻结配方使用 2048-token chunk、1024-token memory、256-token final answer、最多 64 chunks、GRPO group size 8、LR
1e-6和 KL coefficient0.001。实现中发现的框架接线问题
现有 custom sample-converter 参数虽然会被
RolloutManager加载，但 transfer 和 debug-replay 路径仍直接调用内置 converter。另外，一条 trajectory 会展开为数量不固定的 turn rows，而原 TransferQueue 容量、grouping 和 Actor 消费数量都按 trajectory 数量计算。因此，除了
examples/mem_agent/，当前本地 patch 还包含以下受配置开关保护的小范围框架调整：rollout_id协调 row count，并在生成/转换失败时唤醒等待方，避免 Actor hang；这些调整涉及 Controller、TransferQueue 和 Actor 接线，但只在 MemAgent custom config 显式开启后生效；没有修改 SGLang core、Service lifecycle、Launcher、公开
Sample字段或 checkpoint 格式。评测与复现口径
评测脚本让冻结 base、VIME checkpoint 和 ReLax checkpoint 共用同一套 recurrent inference 代码。每次评测会保留逐样本 JSONL，并在 summary 中记录 data SHA-256、evaluator schema、tokenizer、采样参数、chunk/memory 上限、样本数和请求错误数。
当前建议的效果验收口径为：
sub_EM；abs(sub_EM_ReLax - sub_EM_VIME) <= 3个百分点；固定 VIME 官方入口的有效上限是 64 chunks：
run-eval.sh会 source_common.sh，从而覆盖 Python evaluator 单独运行时的 fallback。ReLax 显式固定 64。最终报告必须披露超过 64 chunks 的截断情况，不能把发生截断的 800-document 评测描述成读取了完整上下文。已完成的验证
当前本地证据如下：
45 passed；14 passed, 4 skipped；3 passed, 33 skipped，平台相关用例在当前 CPU 环境按既有条件跳过；bash -n；git diff --check通过；pre-commit run --all-files --show-diff-on-failure通过；测试已覆盖 chunk 边界、memory 覆盖和硬上限、final prompt 隔离、多答案 boxed EM、每 turn 字段对齐、先归一化后展开、split/share credit、producer/consumer 精确 row-count 契约、异常唤醒、debug replay、冻结 prompt variant、评测控制变量校验和逐 step reward 完整汇总。
尚未完成的验收
CPU 和 mock 测试不能代替真实分布式 GPU 链路。以下项目尚未执行，也不声明已经通过：
sub_EM对比。下一执行 gate 是 2-step GPU smoke。Qwen3-0.6B 单卡实验可以作为低成本控制流诊断，但不会替代冻结的 Qwen3-4B，也不能作为正式效果验收结果。