record-episode

技能：record-episode

为 overstack 提供情景记忆层（4/4 个记忆层——工作记忆/语义记忆/程序记忆/情景记忆）。 Wiki 保存提炼后的知识（语义记忆）；技能保存流程（程序记忆）；.claude/memory 保存 平铺事实。还缺少：具体的会话事件——“上一会话做了什么、涉及哪些文件、结果如何”。此技能会将这些内容 准确写入 mem-rank 存储，让后续会话可以按语义检索（无需任何人添加 [[wikilink]]）。

内容

用途和上下文

• **用途：**将结构化的会话事件（did · files · outcome · session）写入记忆存储，让后续会话可以按语义检索“上一会话做了什么”，无需 [[wikilink]]。
• 触发条件（何时使用）：
  • 在有意义的会话/里程碑结束时（关闭 issue、完成一项功能、做出一项决定）——总结做了什么。
  • 希望后续会话能自行记住“X 任务在哪里做了、结果如何”，而无需重新阅读 git log。
  • 用户说“记录 episode”、“record episode”、“把这一会话总结存入记忆”、“保存上一会话做了什么”、“session episode”、“/record-episode”。
• **非目标：**不要用于持久知识（→ 应使用 wiki /ingest），也不要用于用户的平铺事实（→ .claude/memory）。不要通过 hook 自动运行。

心智模型

工作会话 → did（1 句话）+ files + outcome + session → mem-rank.py episode → harness/metrics/memory.jsonl → retrieve --kind-filter episode。Episode 是事件（情景记忆），指向会话；wiki（语义记忆）仍是事实来源。修正 episode = 通过时间链接进行 supersede，而非覆盖。

输入和输出约定

	字段	必填？	含义
In	"<did>"	是	主要操作（动词 + 对象），包含足够的检索词
In	--files	否	涉及的路径，以逗号分隔（如有需要，从 git diff --name-only 获取）
In	--outcome	否	可验证的结果（测试通过 / issue 已关闭 / PR 编号）
In	--session	否	会话名称 / issue
In	--id <ID> --supersedes <ID>	仅修正时	替换旧版本，保留 supersedes 链接
Out	harness/metrics/memory.jsonl 中的 episode	是	“完成” = retrieve ... --kind-filter episode 能返回刚记录的 episode

规则和能力

• RULE-01 (MUST)：按需使用，不要使用自动 hook——不要注册自动写入的 Stop-hook（ADR-004：/fdk 仅按需使用）。
• RULE-02 (MUST)：Episode 是事件，不是知识——如果内容是持久经验，应通过 /ingest 提炼到 wiki；episode 只指明“在哪个会话中完成”，不替代 wiki（wiki 仍是事实来源）。
• RULE-03 (MUST)：存储是本地且可迁移的——harness/metrics/memory.jsonl（已加入 gitignore）；不接入云端。
• RULE-04 (SHOULD)：当前排序器基于 token 重叠（确定性）；embedding 是 mem-rank.config.yaml 中的适配器（verified:false）——有后端时再启用，不妨碍立即使用。
• 能力：向本地记忆存储追加写入 + 排序检索；不联网，不使用 hook。

失败边界

• 内容是持久经验 / 架构决策 → 澄清/引导至 /ingest 或 wiki ADR，不记录为 episode。
• 没有可验证的结果 → 记录 did + files，省略 --outcome（部分完成），不要编造结果。
• retrieve 未返回刚记录的 episode → 失败，告知用户，不要视为完成。

使用方法

主要工作流

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	判断	会话	将会话总结为 1 句 did	did 句子	内容是持久知识 → /ingest
W02	确定性	git diff、测试/issue 结果	收集 --files + --outcome	参数	没有可验证的结果 → 留空
W03	执行	did + 参数	mem-rank.py episode ...	存储中的 episode 行	—
W04	执行	有误的旧 episode	使用 --id <ID> --supersedes <ID> 进行 supersede（B01）	新 episode + 链接	—
W05	确定性	问题	mem-rank.py retrieve "<问题>" --kind-filter episode	episode 出现在结果中	未找到 → 失败

各步骤详情（W01–W05 的事实来源）：

步骤

1. 将会话总结为一句 did——概括主要行动（动词 + 对象），包含足够的术语以便检索。
2. 收集文件和结果：--files = 涉及的路径（如有需要，从 git diff --name-only 获取）； --outcome = 可验证的结果（测试通过 / issue 已关闭 / PR 编号）。
3. 记录 episode：

   python3 harness/scripts/mem-rank.py episode "<did>" \
     --files "path1,path2" --outcome "<kết quả>" --session "<tên/issue>"
   

4. **修订旧 episode（时间性取代）：**使用 --id <ID> --supersedes <ID>——新版本 取代旧版本，并保留 supersedes 链接，以便回答“这在什么时候是正确的”。
5. 快速检查：python3 harness/scripts/mem-rank.py retrieve "<câu hỏi>" --kind-filter episode。

反模式

• 将 episode 写成冗长的日志——一句 did + 文件 + 结果就足以用于检索；内容太长 = 噪声。
• 将 episode 用作存储长期架构决策的地方——这属于 wiki ADR 的职责。

分支

ID	Kind	Guard	行为	Skip / failure	Rejoin
B01	user_optional	需要修订旧 episode	使用 --id <ID> --supersedes <ID> 记录新版本（时间性取代）	不修订 → 跳过	W05
B02	capability_optional	有 embedding 后端，mem-rank.config.yaml 中 verified:true	ranker 使用 embedding 替代 token-overlap	尚未具备 → 使用 token-overlap（默认）	W05

验证与停止条件

当 W05 能检索到刚记录的 episode 时即完成。一个 episode = 一句 did + 文件 + 结果；更长就是噪声（见“反模式”）。

示例

• **正例：**刚关闭 GH#9 → python3 harness/scripts/mem-rank.py episode "add episodic memory layer to mem-rank" --files "harness/scripts/mem-rank.py" --outcome "GH#9 closed, mem-proxy eval pass" --session "GH#9" → retrieve "episodic memory làm ở đâu" --kind-filter episode 返回该 episode。
• **边界情况 / 失败：**用户想要“记录 episode：决定使用 SQLite 替代 JSONL 作为存储” → 这是长期架构决策 → 不记录 episode，转到 wiki ADR / /ingest。

来源

• **来源：**issue GH#9（frontier-gap memory，4/4 层记忆）；ledger 030726-memory-episodic-vector.md。 引擎：harness/scripts/mem-rank.py（episode/retrieve/temporal）。评测：harness/scripts/mem-proxy.py。
• **日期：**2026-07-04