feat(memory): select versioned LIBERO corpora by model

docs/source-en/rst_source/development/memory.rst

@@ -1,6 +1,8 @@
 Memory Management
 =================
 
+.. _memory-management:
+
 RPent memory is maintained per robot and lets runs reuse already-validated
 task experience and operating strategy instead of rediscovering it from
 scratch each time.
@@ -34,8 +36,8 @@ use the same directory structure:
        |-- <cell>_recipe.jsonl
        `-- <task_key>.md
 
-The default local root is ``memory/<robot>/``; on the Hugging Face dataset
-the same content lives under the ``<robot>/`` subdirectory. A custom
+The default local root is ``memory/<robot>/``. On Hugging Face, LIBERO has
+model-specific roots, described below; other robots use ``<robot>/``. A custom
 ``--memory-dir`` may point at any directory laid out like the tree above.
 
 Every subtree is optional; a robot ships only the directories it uses:
@@ -53,12 +55,114 @@ Missing a layer does not stop a task from running.
 Using memory
 ------------
 
-By default RPent syncs the current robot's memory from the Hugging Face
-dataset ``RLinf/RPent-memory`` into ``memory/<robot>/``. The dataset is
-public, so a fresh clone downloads it without a token. Set
-``HF_HUB_OFFLINE=1`` to skip the sync and use the local copy only. Memory is
-optional: if a robot has none on the dataset, or the sync fails, the run
-continues with whatever is on disk.
+RPent downloads memory from the public ``RLinf/RPent-memory`` dataset.
+LIBERO selects one version with ``--memory-version auto`` (the default):
+
+.. list-table:: LIBERO memory versions
+   :header-rows: 1
+   :widths: 25 35 40
+
+   * - Running model
+     - Memory directory under ``libero/``
+     - Exploration configuration
+   * - ``gpt-5.5``
+     - ``GPT_5.5_xhigh``
+     - Codex, reasoning on, xhigh
+   * - ``gpt-6-astra``
+     - ``GPT_6_astra_low``
+     - Codex, reasoning on, low
+
+Provider prefixes such as ``openai:`` are recognized. Codex uses ``--model``
+first, then ``CODEX_MODEL``. Unknown models, Claude, or an unknown backend
+default fall back to ``GPT_5.5_xhigh`` with a warning. Flash replay defaults
+to GPT-5.5. An explicit version overrides model selection; it does not change
+the running model or reasoning effort. The effort in a directory name records
+how that memory was generated.
+
+.. code-block:: bash
+
+   # Choose Astra memory automatically.
+   rpent --robot libero --suite libero_goal_swap --task 1 --seed 1 \
+     --planner codex --model gpt-6-astra --reasoning-effort low
+
+   # Use the same model with the GPT-5.5 corpus.
+   rpent --robot libero --suite libero_goal_swap --task 1 --seed 1 \
+     --planner codex --model gpt-6-astra --reasoning-effort low \
+     --memory-version GPT_5.5_xhigh
+
+CLI and Dashboard resolve the root before each task. In Dashboard, **Next task
+model** changes the model for the next task and reselects auto memory then;
+the active task keeps its existing model and corpus. A manually selected
+memory version remains selected across model changes.
+
+Only the chosen version is downloaded. LIBERO caches are isolated by repository,
+commit and version under ``memory/libero/.versions/``. Every file is verified
+before cache reuse. ``HF_HUB_OFFLINE=1`` requires a complete, unchanged cache
+for the selected version and revision; failed downloads never substitute
+another model's corpus. Missing or incomplete caches fail explicitly.
+Caches created before versioned-source receipts require one successful online
+refresh; old unversioned caches are not reused.
+Other robots retain their existing optional-memory sync behavior.
+
+Standalone download and local evaluation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+   rpent-memory sync --robot libero --memory-version GPT_6_astra_low
+   rpent-memory sync --robot libero --model gpt-6-astra \
+     --revision <release-commit> --output-dir /path/to/new-astra-memory
+   rpent --robot libero --suite libero_goal_swap --task 1 --seed 1 \
+     --planner codex --model gpt-6-astra --reasoning-effort low \
+     --memory-profile local --memory-dir /path/to/new-astra-memory
+
+``sync`` prints the actual corpus root. ``--output-dir`` must not already
+exist. ``--planner`` defaults to ``api``, matching ``rpent``; pass
+``--planner codex`` to use ``CODEX_MODEL`` when ``--model`` is omitted. ``--memory-profile local`` never downloads memory; combining it or
+``--explore`` with an explicit remote ``--memory-version`` is an error.
+Exploration uses a local corpus; use a separate empty ``--memory-dir`` for
+each independent exploration.
+
+Release provenance and compatibility
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The dataset's ``libero/README.md`` and ``libero/manifest.json`` document the
+versions, original source snapshots and published files. Each version's
+``files`` mapping contains paths relative to that version's root and SHA-256
+hashes of the published bytes; the loader verifies this mapping. Source
+revisions and source hashes describe the original snapshots and remain separate
+from published hashes after directory, index and reference changes.
+
+Both version roots use ``MEMORY.md``, ``global/``, ``task-family/`` and
+``task-specific/``. GPT-5.5 additionally includes its ``task_card/`` replay
+assets. Flash reads generated ``flash/`` plans or published ``task_card/``
+assets within the selected corpus. Astra has no replay assets; selecting it
+for Flash reports an error.
+
+The Astra release merges Long and Spatial/Object/Goal exploration memory,
+preserving both versions of three conflicting global notes with source
+suffixes. Its 79 task-specific audit/recipe pairs retain their original
+content; Long Swap task 6 has no task-specific pair. The historical **741/800**
+result used the two original frozen snapshots separately by suite. **The merged
+release has not been reevaluated.** Memory was generated at runtime commit
+``014a0fa``, before the scene-seed fix. Original snapshots are retained as the
+Hub tags ``libero-astra-long-frozen-20260917`` and
+``libero-astra-spatial-object-goal-frozen-20260917``.
+
+The current loader requires a versioned Hub layout and does not convert or
+fall back to the historical unversioned corpus. Update code and data together.
+Historical reproduction uses the matching historical client and dataset
+revision, archived at ``libero-gpt5.5-xhigh-before-versions-20260917``:
+
+.. code-block:: bash
+
+   hf download RLinf/RPent-memory --repo-type dataset \
+     --revision libero-gpt5.5-xhigh-before-versions-20260917 \
+     --include 'libero/*' --local-dir /path/to/legacy-download
+   # With an older RPent client:
+   rpent --robot libero --suite libero_goal_swap --task 1 --seed 1 \
+     --planner codex --model gpt-5.5 --memory-profile local \
+     --memory-dir /path/to/legacy-download/libero
 
 You can also prepare local memory yourself with the same directory structure
 and point the run at it through the environment's ``--memory-dir`` option or

docs/source-en/rst_source/usage/flash.rst

@@ -61,14 +61,18 @@ objects appear at different positions.
 Flash plan files
 ----------------
 
-Flash plans are distributed through the `RLinf/RPent-memory Flash directory
-<https://huggingface.co/datasets/RLinf/RPent-memory/tree/main/libero/flash>`_
-on Hugging Face rather than tracked in Git. RPent downloads them in HF memory
-mode and stores them locally under ``memory/libero/flash``. With
-``--memory-profile local --memory-dir /path/to/memory/libero``, it reads plans from
-``/path/to/memory/libero/flash`` without downloading data.
-There are 78 plans for 80 task identities; ``goal_swap_t0`` and ``10_swap_t9``
-have no plan. Missing plan or anchor files cause an error.
+Plans are distributed through the `GPT-5.5 memory directory
+<https://huggingface.co/datasets/RLinf/RPent-memory/tree/main/libero/GPT_5.5_xhigh>`_
+on Hugging Face rather than tracked in Git. Flash defaults to
+``--memory-version GPT_5.5_xhigh`` and uses that version's isolated cache.
+The published corpus includes 20 Object Task/Swap plans under ``task_card/``. This published coverage differs from the 78 plans used
+in the historical full-matrix evaluation above.
+
+With ``--memory-profile local --memory-dir /path/to/memory/libero``, replay
+reads generated ``flash/`` plans or published ``task_card/`` assets under that root
+without downloading.
+Missing plan or anchor files cause an error. Astra memory has no replay assets;
+it cannot be used for Flash. See :ref:`Memory Management <memory-management>`.
 
 .. code-block:: text
 
@@ -114,7 +118,10 @@ To download only the Flash plans manually, run:
 .. code-block:: bash
 
    hf download RLinf/RPent-memory --repo-type dataset \
-     --include "libero/flash/**" --local-dir memory
+     --include "libero/GPT_5.5_xhigh/task_card/**" --local-dir /path/to/download
+
+Use ``--memory-profile local --memory-dir /path/to/download/libero/GPT_5.5_xhigh``
+with the downloaded plans.
 
 Run Flash Mode
 --------------

docs/source-en/rst_source/usage/libero.rst

@@ -116,8 +116,10 @@ RPent supports two LIBERO run modes:
   audit, recipe, and lessons produced by exploration. The HarnessVLA success
   rate is reproduced in evaluation mode.
 
-Evaluation remains the default mode.  Omitting ``--memory-profile`` preserves
-the original Hugging Face resource sync and prompt:
+Evaluation remains the default mode. Omitting ``--memory-profile`` selects
+Hugging Face memory; ``--memory-version auto`` chooses its model-specific
+version. See :ref:`Memory Management <memory-management>` for overrides,
+offline downloads and release provenance.
 
 Both profiles run the same single-attempt evaluation workflow; they differ only
 in where the evaluation memory comes from and which memory prompt is used.

docs/source-zh/rst_source/development/memory.rst

@@ -1,6 +1,8 @@
 Memory 管理
 ===========
 
+.. _memory-management:
+
 RPent 的 memory 按机器人维护，用于复用已验证的任务经验和操作策略，避免每次运行
 都从头试错。
 
@@ -31,8 +33,8 @@ Exploration 和本地 memory Evaluation 的详细流程见
        |-- <cell>_recipe.jsonl
        `-- <task_key>.md
 
-默认本地目录为 ``memory/<robot>/``；Hugging Face 数据集中相同内容位于
-``<robot>/`` 子目录下。自定义 ``--memory-dir`` 可指向任意采用上述结构的目录。
+默认本地目录为 ``memory/<robot>/``。Hugging Face 中 LIBERO 按模型版本分目录，
+详见下文；其他机器人仍使用 ``<robot>/``。自定义 ``--memory-dir`` 可指向任意采用上述结构的目录。
 
 各目录均按需存在，机器人只需提供实际使用的目录：
 
@@ -47,10 +49,99 @@ Exploration 和本地 memory Evaluation 的详细流程见
 使用 memory
 -----------
 
-默认情况下，RPent 从 Hugging Face 数据集 ``RLinf/RPent-memory`` 把当前机器人的
-memory 同步到 ``memory/<robot>/``。数据集是公开的，无需 token 即可下载。设
-``HF_HUB_OFFLINE=1`` 可跳过同步，只用本地副本。memory 是可选的：如果某机器人在
-数据集上没有 memory，或同步失败，运行也会用本地已有的内容继续。
+RPent 从公开数据集 ``RLinf/RPent-memory`` 下载 memory。
+LIBERO 默认使用 ``--memory-version auto`` 按模型选择：
+
+.. list-table:: LIBERO memory 版本
+   :header-rows: 1
+   :widths: 25 35 40
+
+   * - 当前运行模型
+     - ``libero/`` 下的 memory 目录
+     - 探索生成配置
+   * - ``gpt-5.5``
+     - ``GPT_5.5_xhigh``
+     - Codex，Reasoning 开启，xhigh
+   * - ``gpt-6-astra``
+     - ``GPT_6_astra_low``
+     - Codex，Reasoning 开启，low
+
+支持 ``openai:`` 等提供方前缀。Codex 优先使用 ``--model``，其次使用 ``CODEX_MODEL``。
+其他模型、Claude 或无法确定的默认模型会回退到 ``GPT_5.5_xhigh``，并输出提示。
+Flash 重放默认选择 GPT-5.5。显式指定版本优先于自动选择，不改变当前模型或 reasoning
+effort；目录名中的 effort 只说明该 memory 的探索生成配置。
+
+.. code-block:: bash
+
+   # 自动选择 Astra memory。
+   rpent --robot libero --suite libero_goal_swap --task 1 --seed 1 \
+     --planner codex --model gpt-6-astra --reasoning-effort low
+
+   # 同一模型使用 GPT-5.5 memory。
+   rpent --robot libero --suite libero_goal_swap --task 1 --seed 1 \
+     --planner codex --model gpt-6-astra --reasoning-effort low \
+     --memory-version GPT_5.5_xhigh
+
+CLI 和 Dashboard 都在每个任务开始前解析 memory 根目录。在 Dashboard 的
+**下一任务的模型** 中修改模型后，下一任务会重新进行自动选择；正在运行的任务保留原模型
+和 memory。显式指定的 memory 版本不会随模型切换而改变。
+
+仅下载所选版本。LIBERO 缓存位于 ``memory/libero/.versions/``，按仓库、提交和版本隔离，
+每次复用前校验所有文件。``HF_HUB_OFFLINE=1`` 要求所选版本及 revision 已有完整、未改动的缓存。
+下载失败不会改用另一模型的 memory；缓存缺失或不完整会明确报错。
+旧缓存记录未标明版本来源时，需要联网成功刷新一次；不复用旧的无版本缓存。
+其他机器人保持原有的可选 memory 同步行为。
+
+独立下载与本地评测
+~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+   rpent-memory sync --robot libero --memory-version GPT_6_astra_low
+   rpent-memory sync --robot libero --model gpt-6-astra \
+     --revision <release-commit> --output-dir /path/to/new-astra-memory
+   rpent --robot libero --suite libero_goal_swap --task 1 --seed 1 \
+     --planner codex --model gpt-6-astra --reasoning-effort low \
+     --memory-profile local --memory-dir /path/to/new-astra-memory
+
+``sync`` 输出实际 memory 根目录，``--output-dir`` 必须是尚不存在的目录。
+``--planner`` 默认是 ``api``，与 ``rpent`` 一致；希望在省略 ``--model`` 时读取
+``CODEX_MODEL``，需指定 ``--planner codex``。
+``--memory-profile local`` 不下载 memory；本地模式或 ``--explore`` 与显式远程
+``--memory-version`` 同时使用会报参数冲突。探索使用本地 memory，每次独立探索应指定单独的空目录。
+
+发布来源与兼容性
+~~~~~~~~~~~~~~~~
+
+数据集中的 ``libero/README.md`` 和 ``libero/manifest.json`` 记录版本、原始来源快照和
+发布文件。各版本的 ``files`` 保存相对于该版本根目录的路径与发布文件的 SHA-256，
+加载器据此校验实际内容。来源 revision 和来源哈希描述原始快照；目录、索引及正文引用
+调整后，发布哈希另行更新，不改写原始来源哈希。
+
+两个版本根目录都使用 ``MEMORY.md``、``global/``、``task-family/`` 和 ``task-specific/``。
+GPT-5.5 还包含 ``task_card/`` 重放资产。Flash 在所选版本内读取生成的 ``flash/`` 计划或
+发布的 ``task_card/`` 资产。Astra 没有重放资产，显式选用它执行 Flash 时会报错。
+
+Astra 发布版合并了 Long 与 Spatial/Object/Goal 两批探索 memory；三个重名但内容不同的
+global 文件分别加来源后缀并保留两份。79 对任务 audit/recipe 保持原始内容，Long Swap task 6
+没有专属经验，不补造。历史 **741/800** 成绩使用原先两份冻结快照按套件分别评测，
+**合并发布版尚未重新评测**。生成环境为运行提交 ``014a0fa``，属于场景 seed 修复前版本。
+原始快照保留在 Hub tag ``libero-astra-long-frozen-20260917`` 和
+``libero-astra-spatial-object-goal-frozen-20260917``。
+
+当前加载器要求 Hub 数据按模型分版本存放，不转换旧布局，也不回退到旧的无版本语料。
+代码与数据需要配套更新。历史复现使用匹配的历史客户端与数据 revision；迁移前数据
+归档为 ``libero-gpt5.5-xhigh-before-versions-20260917``：
+
+.. code-block:: bash
+
+   hf download RLinf/RPent-memory --repo-type dataset \
+     --revision libero-gpt5.5-xhigh-before-versions-20260917 \
+     --include 'libero/*' --local-dir /path/to/legacy-download
+   # 旧 RPent 客户端使用：
+   rpent --robot libero --suite libero_goal_swap --task 1 --seed 1 \
+     --planner codex --model gpt-5.5 --memory-profile local \
+     --memory-dir /path/to/legacy-download/libero
 
 也可以按相同的目录结构自行准备本地 memory，通过对应环境的 ``--memory-dir`` 选项或
 本地 memory 配置使用。Hugging Face memory 和本地 memory 使用相同的目录规范，区别只

docs/source-zh/rst_source/usage/flash.rst

@@ -51,13 +51,16 @@ RPent 将实时锚点位置与计划保存的偏移组合成新的路点，再
 计划文件
 --------
 
-计划不随 Git 仓库提交，而是通过 Hugging Face 上的 `RLinf/RPent-memory 计划目录
-<https://huggingface.co/datasets/RLinf/RPent-memory/tree/main/libero/flash>`_
-分发。RPent 在 HF memory 模式下自动下载计划，默认保存到
-``memory/libero/flash``。使用 ``--memory-profile local --memory-dir /path/to/memory/libero``
-时，从 ``/path/to/memory/libero/flash`` 读取，不下载数据。
-80 个任务中有 78 份计划；``goal_swap_t0`` 和 ``10_swap_t9`` 暂无计划。
+计划不随 Git 仓库提交，而是通过 Hugging Face 上的 `GPT-5.5 memory 目录
+<https://huggingface.co/datasets/RLinf/RPent-memory/tree/main/libero/GPT_5.5_xhigh>`_
+分发。Flash 默认选择 ``--memory-version GPT_5.5_xhigh``，使用该版本的独立缓存。
+发布语料在 ``task_card/`` 中包含 20 份 Object Task/Swap 计划；发布覆盖范围
+与上文历史完整矩阵评测使用的 78 份计划不同。
+
+使用 ``--memory-profile local --memory-dir /path/to/memory/libero`` 时，从该根目录下的
+``flash/`` 读取生成的计划，或从 ``task_card/`` 读取发布资产，不下载数据。
 缺少计划或锚点文件时会报错。
+Astra memory 没有重放资产，不能用于 Flash。详见 :ref:`Memory 管理 <memory-management>`。
 
 .. code-block:: text
 
@@ -98,7 +101,9 @@ suite/task/seed 字段，必须指向同一个 episode。
 .. code-block:: bash
 
    hf download RLinf/RPent-memory --repo-type dataset \
-     --include "libero/flash/**" --local-dir memory
+     --include "libero/GPT_5.5_xhigh/task_card/**" --local-dir /path/to/download
+
+下载后指定 ``--memory-profile local --memory-dir /path/to/download/libero/GPT_5.5_xhigh``。
 
 运行计划
 --------

docs/source-zh/rst_source/usage/libero.rst

@@ -111,8 +111,9 @@ RPent 支持两种 LIBERO 运行模式：
   memory。使用本地 memory 的 evaluation 会读取 exploration 生成并通过校验的
   audit、recipe 和经验。HarnessVLA 的 success rate 在 evaluation mode 下复现。
 
-默认仍为原有单次评测模式。省略 ``--memory-profile`` 时，会继续同步并使用
-Hugging Face memory 和原有 prompt。两种 profile 都执行相同的单次评测流程；
+默认仍为单次评测模式。省略 ``--memory-profile`` 时使用 Hugging Face memory，
+``--memory-version auto`` 按模型选择版本。手动覆盖、离线下载和发布来源详见
+:ref:`Memory 管理 <memory-management>`。两种 profile 都执行相同的单次评测流程；
 区别仅在于评测 memory 的来源及所使用的 memory prompt。本地 memory 已准备好后
 （例如先执行下文的 exploration 流程），即可使用 ``local``。该选项不会开启 exploration，也不会从 Hugging Face 下载
 memory；它只会针对 ``--memory-dir`` 执行普通的单次评测，并避免同步覆盖本地