# Memory、Skills 与 Session history：讨论纪要

> 状态：设计讨论记录，尚未实现。本文区分已确认的策略与待定的实现方案。
>
> 参考：[Hermes 源码研究](../research/hermes-memory-skills.md)。本项目借鉴其经验积累机制，但不要求逐项复制其默认触发条件和本地存储方式。

## 1. 概念与关系

三者按用途区分，不按保存时长区分：

| 概念 | 作用 | 示例 |
| --- | --- | --- |
| **Memory** | 记住长期成立的事实 | 产品约定、环境信息、明确的长期用户偏好。 |
| **Skills** | 记住完成某类任务的方法，也称程序性记忆 | 需求澄清步骤、编码流程、CI 故障处理方法、E2E 测试流程及坑点。 |
| **Session history** | 记录任务中发生过什么，是追溯和复盘的原始材料 | 用户与 Agent 对话、工具调用及结果、执行证据、任务检查点。 |

**Skills 不是短期记忆，也不应为每次任务生成一个新 Skill。** 当前任务上下文、临时工作状态和检查点才承担短期记忆的作用；检查点也可以持久化，供恢复任务使用。

Agent 开始执行时，获取必要的 Memory、当前任务状态和可用 Skill 索引，加载相关 Skills 后开展工作，过程中仍可继续召回信息。这里不要求先加载全部长期记忆，也不要求预读所有 Skill 正文。

需求卡片内的需求描述与程序需求澄清、卡片状态，以及 GitHub Issue 中的可编码设计、PR 和代码仍以 Meegle / GitHub 为权威来源，记忆摘要不能替代或覆盖这些正式产物。当前交付流程以报告中的 14 步为准：CI 修复在同一 PR 内进行，含首次累计第 3 次失败转人工；成功仍由人合并，之后 CD 部署、E2E 回写执行状态、结论和报告，由人最终判断并手动流转需求卡片，不自动完成需求。这里的业务 Agent loop 不是下文的 RSI 学习活动。

## 2. 已确认的机制

### 2.1 调度中心触发 Agent 学习与更新

本文中的“Agent 调度中心”现统一称为“调度中心”，同时承担 Agent 调度与环境调度；环境管理是内部模块，不再设独立环境调度中心。

- 调度中心分配 Agent 时启动定时器，定期扫描 Agent 当前状态；当 Agent 满足空闲条件、进入回收流程时，按会话回收顺序加入统一队列，逐个触发对应 Agent 的 RSI 学习与直接写回，从 Session history 中提取值得保留的事实和可复用方法。
- 复盘结果分别用于新增、修正 Memory，以及改进已有或必要时新增 Skills。
- 执行类 Agent 负责执行任务、产出结果及记录过程，空闲超时后进入学习与输出阶段；活动结束后退出 Agent，再由调度中心内部环境管理模块回收环境。历史和知识不随环境回收删除。
- 复盘不是强制产生新条目；没有可靠的新事实或有效方法时，可以不更新。

本文中的 RSI 指上述知识和方法层面的持续改进，不指训练模型权重，也不授权修改权限或绕过人工审批。

### 2.2 Session history 全量保存为 JSONL

- Session history 采用 **JSONL** 保存，作为调度中心定时触发复盘的输入。
- 全量保存指保留可记录的会话与执行事件，而不是只保留压缩摘要或最终回复；不要求获取模型服务未提供的内部推理。
- JSONL 实时追加并持久化保存，不依赖 `/new`、Agent 空闲或沙盒退出时再收集、补存；复盘直接读取已持久化的历史记录。
- 执行环境挂载外部持久卷，将 JSONL 实时写到独立于 MicroVM / Container 生命周期的存储；回收环境不删除持久历史。Agent 的 RSI 学习从持久历史读取材料，历史本身不依赖原环境继续存活。
- 持久卷选型与 Agent 运行环境选型相关，不在初稿讨论范围；网络文件存储或持久磁盘只是可能的实现。挂载路径、字段规范、并发写入、耐久保障、检索索引及保留期限留待实现设计。

### 2.3 空闲学习与环境回收时序

**定时触发的是状态扫描，不是每次扫描都强制复盘。** 初稿确定的正常收尾路径为：

1. **分配并启动定时器**：调度中心分配 Agent，同时启动定时器，定期扫描该 Agent 当前状态。
2. **按回收顺序排队**：Agent 满足空闲条件、进入回收流程时，调度中心按会话回收顺序排队，逐个触发对应 Agent 的 RSI，读取对应 JSONL 范围及已有知识。
3. **直接更新持久知识**：提取有效事实和方法，经调度中心控制的唯一入口直接更新共享 Memory / Skills，不要求分支、PR 或人工合并；记录完成状态和写回结果，没有有效经验、无需更新也可正常完成。
4. **退出并回收**：学习与输出活动结束后退出 Agent，再由环境管理模块回收环境。

此时序替代此前“复盘与回收不串联、复盘只观察资源已回收状态”的讨论结论。正常空闲路径必须先完成学习与输出，再退出和回收；不将资源已回收或 `/new` 列为本次初稿的学习触发条件。

历史仍在执行时实时持久化，不放在 Pod 退出钩子中补存。复盘须依据事实和执行证据，不能把未验证的失败尝试总结成成功方法。学习 / 写回失败，或因崩溃、强制回收而未完成的 RSI 任务，已确认由定时扫描发现后进入同一队列补跑；具体扫描频率、空闲阈值、去重、超时、重试上限、持续失败处置及部分写入恢复留待实现设计，不默认无限重试。

Hermes 默认的“10 个用户轮次 / 10 次执行循环迭代”是参考机制，**尚未被选定为本项目的触发参数**。

### 2.4 学习产出归属与后续使用

- 被触发的 Agent 在 RSI 活动中读取对应历史以及已有 Memory / Skills，提取事实和方法，新增或修正记忆、改进已有或必要时新增 Skills；不是每个会话都生成新 Skill。
- 产出归属对应产品及 Agent 身份 / 角色；用户私有信息另行隔离，不默认将某个 Agent 的经验广播给所有 Agent。具体身份键、角色级共享与跨 Agent 授权规则待定。
- 记忆与知识库（含 Skills）面向 Agent，存储形式不作约束，不以原沙盒中的本地副本为唯一来源。后续任务由调度中心按产品、Agent 与权限加载必要记忆和 Skill 索引，再按需获取内容。
- 这一机制属于执行旁路，不增加主流程审批节点，不改变 Vault 授权、业务系统权威来源或已有人工把关点。共享库直接写回不要求 Git workflow；校验、读取一致性及回滚实现仍待细化，串行写入不保证内容一定正确。

### 2.5 按迭代复用会话（暂定，待研发总监确认）

需求设计报告本轮补充的暂定方向：**一个产品对应一个 Lark 机器人，一个机器人服务多个迭代，一个迭代包含多个需求，以迭代为维度复用会话。** 这不是已确定的研发流程，需与研发总监确认。

迭代会话用于延续讨论上下文，不能代替需求卡片的关联：同一迭代中的不同需求仍各自关联对应 Meegle 卡片，不能因为复用会话而混写状态或产物。会话复用也不表示执行环境必须一直保留，不改变正常空闲路径中「RSI 学习与输出 → 退出 Agent → 回收环境」的顺序。

跨角色如何衔接迭代上下文、GitHub Issue / CD / E2E 任务如何映射迭代会话、退出后如何恢复，以及迭代结束时如何归档，均留待确认；不预设五类角色必须共用同一条原始模型对话。当前流程要求需求讨论复用 Worker、Issue / PR 留言及批准回调复用对应 Coding；已退出时从持久记录和任务状态恢复，不能因重启 Agent 或环境重置同一 PR 的 CI 失败次数。

### 2.6 唯一写入入口与定时补跑（第 10 点已确认）

共享库写回统一由调度中心按会话进入回收流程的顺序排队，逐个安排对应 Agent 执行 RSI 并直接更新。唯一入口须通过实际写权限保证，其他 Agent 不能绕过队列直接修改共享内容；不要求分支、PR 或人工合并，也不强制某种存储形式。正常路径仍先学习、写回，再退出和回收。

调度中心设置定时器扫描 RSI 任务完成情况，针对失败及异常中断未完成的任务，依据持久化历史和任务记录进入同一个串行队列补跑，不要求原进程或沙盒存活。记录任务状态、处理范围和写回结果，重复扫描不重复派工，补跑不重复写入已完成内容；无需更新的正常完成任务不应被误判成失败。

本条补跑仅限 RSI / 共享库更新任务，不据此自动重跑 CI、部署等业务任务，也不重置 CI 失败计数或恢复过期权限。扫描间隔、超时、重试上限、持续失败处置、任务记录和部分写入恢复待细化，不默认无限重试。详见[报告第 10 点](../../requirements/index.html#review-10)。

## 3. 存储与分发：形式不作约束，运行环境与持久卷选型后置

### 3.1 Memory

记忆与知识库的存储形式不作为本条约束，按产品和 Agent 归属组织 Memory 与 Skills；目录结构和读写接口留待实现设计。产品公共事实、用户偏好和任务私有信息保持隔离，避免不同产品或用户互相污染。

Git 仍可作为存储实现选项，但不要求分支 / PR / 人工合并的 Git workflow，也不表示将所有原始 JSONL 历史提交到 Git；不要求第一版使用向量数据库或独立记忆中心。

### 3.2 Skills

已经讨论的两个选项是：将 Skills 固化在沙盒镜像中，或在中心保存、启动时分发。

**共享库更新已确认由调度中心串行安排直接写回，不要求独立的版本发布或人工审批流程。** 下列按任务分发、本地执行的方式仍是候选，不因此成为写回前置条件：

- 沙盒镜像主要包含 Agent 运行时、稳定工具和运行依赖。
- 共享知识库保存 `SKILL.md`、引用文件、模板和脚本等能力包，存储形式不作约束。
- 调度中心按产品及 Agent 角色确定可用 Skills，并固定本次任务使用的版本。
- 沙盒启动时获取相应版本的能力包，在容器中通过任务卷挂载，或通过适配 MicroVM 的注入/下载机制提供给客户机。
- Agent 按需读取；高频包可以缓存，但缓存和镜像内副本不是权威版本。
- Skill 包及其运行依赖必须兼容；不能仅复制文件而忽略运行环境。

若执行或复盘工具需要更新共享 Skill，必须进入调度中心控制的统一队列；轮到该会话时直接更新共享库，不要求先提交分支 / PR 或人工合并，其他 Agent 不得绕过队列并行修改。读取中的任务如何使用缓存或固定版本、写回结果如何校验与恢复，仍待设计。

本轮补充的另一种分发方式：提示词提供名称、适用描述与读取位置，Agent 通过受控远程工具按需获取 Skill 正文及关联资源，不要求源文件预置在沙盒本地。原生只支持本地文件发现的 harness 需适配远程加载工具或启动分发机制；仅提供 URL 而没有可访问的工具并不足够。远程读取与本地能力包分发是可选方案，尚未选定唯一实现。

### 3.3 Session history

已确认格式为 JSONL，并通过挂载到执行环境的外部持久卷保存；具体选型与运行环境相关，初稿不展开。按产品、Agent 和会话隔离，不让多个沙盒进程无协调地追加同一个文件。复盘应选取明确的已持久化记录范围，并处理异常中断留下的不完整尾部；写入失败与耐久提交保障需在实现时明确。

对象存储可以承载归档或日志分片，但不直接等同于可追加写入的 POSIX 持久卷；若采用对象存储，需要适配写入与读取机制。

全量记录不意味着保存明文凭证：建议在写入前脱敏，对敏感内容设置权限；大型附件可以保存受控引用和校验信息，避免把所有二进制内容塞进 JSONL。相关安全和附件规则需另行细化。

## 4. 机制概览

1. 调度中心匹配产品，准备必要 Memory、Skills 和 MCP，分配 Agent 并启动定时器。
2. 执行环境挂载外部持久卷，执行过程形成 Session history，实时追加到 JSONL；定时器持续扫描 Agent 状态。
3. Agent 满足空闲条件、进入回收流程时，调度中心按会话回收顺序排队，逐个安排对应 Agent 的 RSI，基于历史、执行证据和已有知识评估更新 Memory / Skills。
4. 有效知识经唯一入口直接写回共享库，不要求 Git workflow；记录完成状态和写回结果，活动完成后退出 Agent，再回收环境，不删除持久历史与知识。
5. 定时器扫描 RSI 任务完成情况，失败或中断未完成的任务依据持久历史进入同一队列补跑，防止重复派工和重复写入。
6. 后续任务按产品、Agent 与权限获得必要记忆及可用 Skill 索引；Skills 可远程按需读取或分发为本地能力包，具体分发方式待定。

其中，唯一入口串行直接写回与定时扫描补跑是已确认设计，尚未实现；Skills 的读取分发方式仍是建议方案。

## 5. 后续待讨论

以下为初稿完成后的实现细化，不作为本次流程设计的前置条件：

- Agent 运行环境及配套持久卷选型、挂载路径、JSONL 事件字段、会话和任务关联、工具调用配对、耐久提交与失败恢复规则。
- 定时检查频率、Agent 空闲判定阈值、复盘范围、任务去重、超时、重试上限及持续失败处置；定时扫描补跑方向已确认。
- 调度中心内部如何共享环境管理模块的资源状态及 Agent 最近工作时间。
- 共享库目录组织、唯一写入口与权限控制、读写接口、任务记录及写回幂等；Skill 的启动分发、缓存及依赖声明方案。不再把分支 / PR / 人工合并作为更新前置条件。
- Memory / Skill 更新的验证、部分写入恢复及回滚实现；串行写回不保证知识内容一定正确。
- 不同产品、用户及 Agent 角色之间的隔离和共享边界。
- 历史记录的脱敏、附件管理、检索与保留期限。
