record-episode

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: record-episode

Tầng nhớ episodic cho overstack (4/4 tầng nhớ — working/semantic/procedural/episodic). Wiki giữ tri thức chưng cất (semantic); skill giữ quy trình (procedural);

.claude/memory

giữ sự thật phẳng. Còn thiếu: sự kiện phiên cụ thể — "phiên trước đã làm gì, đụng file nào, kết quả ra sao". Skill này ghi đúng thứ đó vào

mem-rank

store để phiên sau

query

truy hồi được theo NGHĨA (không cần ai đặt

[[wikilink]]

overstack 的 episodic 记忆层（4/4 记忆层——working/semantic/procedural/episodic）。 Wiki 保存已沉淀的知识（semantic）；skill 保存流程（procedural）；

.claude/memory

保存扁平事实。尚缺少：具体会话事件——“上一会话做了什么、涉及哪些文件、结果如何”。此 skill 将这些内容写入

mem-rank

store，使后续会话能够通过

query

按语义检索（无需任何

[[wikilink]]

）。

WHAT

Purpose và context

目的与上下文

Purpose: ghi một session episode có cấu trúc (did · files · outcome · session) vào memory store để phiên sau truy hồi "phiên trước làm gì" theo NGỮ NGHĨA, không cần
```
[[wikilink]]
```
.
Trigger (when to use):
- Cuối một phiên/mốc có ý nghĩa (đóng issue, xong một tính năng, một quyết định) — chốt lại làm gì.
- Khi muốn phiên sau tự nhớ được "việc X đã làm ở đâu, kết quả gì" mà không phải đọc lại git log.
- User nói "ghi episode", "record episode", "chốt phiên này vào nhớ", "lưu lại phiên trước làm gì", "session episode",
```
/record-episode
```
  .
Non-goals: KHÔNG dùng cho tri thức bền (→ đó là wiki
```
/ingest
```
) hay sự thật phẳng người dùng (→
```
.claude/memory
```
). Không tự chạy qua hook.

目的： 将结构化的 session episode（did · files · outcome · session）写入 memory store，使后续会话能够按语义检索“上一会话做了什么”，无需
```
[[wikilink]]
```
。
触发条件（何时使用）：
- 在会话结束或有意义的里程碑时（关闭 issue、完成 feature、做出 decision）——记录做了什么。
- 希望后续会话自动记住“任务 X 在哪里完成、结果如何”，而不必重读 git log。
- User 表示“记录 episode”、“record episode”、“将当前会话存档到记忆”、“保存上一会话做了什么”、“session episode”、“/record-episode”。
非目标： 不用于持久知识（→ 使用 wiki
```
/ingest
```
）或用户的扁平事实（→ 使用
```
.claude/memory
```
）。不通过 hook 自动运行。

Mental model

心智模型

phiên làm việc → did (1 câu) + files + outcome + session → mem-rank.py episode → harness/metrics/memory.jsonl → retrieve --kind-filter episode

. Episode là SỰ KIỆN (episodic), trỏ về phiên; wiki (semantic) vẫn là nguồn chân lý. Sửa episode = supersede có link thời gian, không ghi đè.

工作会话 → did（1 句话）+ files + outcome + session → mem-rank.py episode → harness/metrics/memory.jsonl → retrieve --kind-filter episode

。Episode 是一种事件（episodic），指向某个会话；wiki（semantic）仍是事实来源。修改 episode = 使用带时间链接的 supersede，不直接覆盖。

Input và output contract

输入输出约定

	Field	Required?	Ý nghĩa
In	`"<did>"`	có	hành động chính (động từ + đối tượng), đủ term để truy hồi
In	`--files`	không	path đụng tới, ngăn cách phẩy (lấy từ `git diff --name-only` nếu cần)
In	`--outcome`	không	kết quả kiểm chứng được (test xanh / issue đóng / PR số mấy)
In	`--session`	không	tên phiên / issue
In	`--id <ID> --supersedes <ID>`	chỉ khi sửa	thay bản cũ, giữ link `supersedes`
Out	episode trong `harness/metrics/memory.jsonl`	có	"xong" = `retrieve ... --kind-filter episode` trả lại được episode vừa ghi

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

Rules và capabilities

规则与能力

RULE-01 (MUST): On-demand, KHÔNG auto-hook — không đăng ký Stop-hook tự ghi (ADR-004: /fdk on-demand only).
RULE-02 (MUST): Episode là sự kiện, không phải tri thức — nếu nội dung là bài học bền, chưng cất vào wiki qua
```
/ingest
```
; episode chỉ trỏ "làm ở phiên nào", không thay wiki (wiki vẫn là nguồn chân lý).
RULE-03 (MUST): Store là local/travel-được —
```
harness/metrics/memory.jsonl
```
(đã gitignore); không kéo cloud.
RULE-04 (SHOULD): Ranker hiện là token-overlap (tất định); embedding là adapter
```
mem-rank.config.yaml
```
(
```
verified:false
```
) — bật khi có backend, không chặn việc dùng ngay.
Capabilities: ghi append vào memory store local + truy hồi xếp hạng; không mạng, không hook.

RULE-01 (MUST)：按需执行，绝不 auto-hook——不注册 Stop-hook 自动写入（ADR-004：/fdk 仅按需执行）。
RULE-02 (MUST)：Episode 是事件，不是知识——如果内容是持久经验，应通过
```
/ingest
```
沉淀到 wiki；episode 只指向“在哪个会话中做了什么”，不替代 wiki（wiki 仍是事实来源）。
RULE-03 (MUST)：Store 为本地且可携带——
```
harness/metrics/memory.jsonl
```
（已加入 gitignore）；不接入 cloud。
RULE-04 (SHOULD)：当前 ranker 使用 token-overlap（确定性）；embedding 是
```
mem-rank.config.yaml
```
中的 adapter（
```
verified:false
```
）——有 backend 后再启用，不阻塞立即使用。
能力：将内容 append 到本地 memory store，并进行排序检索；不访问网络，不使用 hook。

Failure boundaries

失败边界

Nội dung là bài học bền / quyết định kiến trúc → clarify/redirect sang
```
/ingest
```
hoặc wiki ADR, không ghi episode.
Không có kết quả kiểm chứng được → ghi
```
did
```
+ files, bỏ
```
--outcome
```
(partial), không bịa outcome.
```
retrieve
```
không trả lại episode vừa ghi → failed, báo user, không coi là xong.

内容是持久经验或架构决策 → clarify/redirect 到
```
/ingest
```
或 wiki ADR，不写入 episode。
没有可验证的结果 → 写入
```
did
```
+ files，省略
```
--outcome
```
（partial），不虚构 outcome。
```
retrieve
```
未返回刚写入的 episode → failed，告知 user，不视为完成。

HOW

Main workflow

主工作流

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	phiên	Tóm tắt phiên thành 1 câu `did`	câu did	nội dung là tri thức bền → `/ingest`
W02	deterministic	git diff, kết quả test/issue	Thu `--files` + `--outcome`	tham số	không có outcome kiểm được → bỏ trống
W03	effect	did + tham số	`mem-rank.py episode ...`	dòng episode trong store	—
W04	effect	episode cũ sai	Supersede bằng `--id <ID> --supersedes <ID>` (B01)	episode mới + link	—
W05	deterministic	câu hỏi	`mem-rank.py retrieve "<câu hỏi>" --kind-filter episode`	episode hiện trong kết quả	không thấy → failed

Chi tiết từng bước (nguồn chân lý cho W01–W05):

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	session	将 session 总结为 1 句 `did`	did 句子	内容是持久知识 → `/ingest`
W02	deterministic	git diff、test/issue 结果	收集 `--files` + `--outcome`	参数	没有可验证的 outcome → 留空
W03	effect	did + 参数	`mem-rank.py episode ...`	store 中的 episode 行	—
W04	effect	旧 episode 有误	使用 `--id <ID> --supersedes <ID>` 进行 Supersede（B01）	新 episode + 链接	—
W05	deterministic	问题	`mem-rank.py retrieve "<问题>" --kind-filter episode`	episode 出现在结果中	未找到 → failed

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

Steps

步骤

Tóm tắt phiên thành 1 câu
did
— hành động chính (động từ + đối tượng), đủ term để truy hồi.
Thu file + kết quả:
```
--files
```
= các path đụng tới (lấy từ
```
git diff --name-only
```
nếu cần);
```
--outcome
```
= kết quả kiểm chứng được (test xanh / issue đóng / PR số mấy).

Ghi episode:

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

Sửa lại một episode cũ (temporal supersede): dùng
```
--id <ID> --supersedes <ID>
```
— bản mới thay bản cũ và giữ link
```
supersedes
```
để trả lời "điều này đúng ở thời điểm nào".

Kiểm nhanh:

python3 harness/scripts/mem-rank.py retrieve "<câu hỏi>" --kind-filter episode

将 session 总结为 1 句
did
——主要动作（动词 + 对象），包含足够的 term 以供检索。
收集文件 + 结果：
```
--files
```
= 涉及的 path（如有需要，从
```
git diff --name-only
```
获取）；
```
--outcome
```
= 可验证的结果（test 通过 / issue 已关闭 / PR 编号）。

写入 episode：

python3 harness/scripts/mem-rank.py episode "<did>" \
  --files "path1,path2" --outcome "<结果>" --session "<会话/issue>"

修正旧 episode（temporal supersede）： 使用
```
--id <ID> --supersedes <ID>
```
——新版本替换旧版本，同时保留
```
supersedes
```
链接，以回答“此信息在何时成立”。

快速检查：

python3 harness/scripts/mem-rank.py retrieve "<问题>" --kind-filter episode

。

Anti-patterns

反模式

Ghi episode dài như nhật ký — 1 câu
```
did
```
+ file + outcome là đủ để truy hồi; dài = nhiễu.
Dùng episode làm nơi lưu quyết định kiến trúc bền — đó là việc của wiki ADR.

像日志一样写长 episode——1 句
```
did
```
+ file + outcome 足以检索；过长 = 噪声。
将 episode 用作持久架构决策的存储位置——这应由 wiki ADR 负责。

Branches

分支

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	user_optional	cần sửa một episode cũ	ghi bản mới với `--id <ID> --supersedes <ID>` (temporal supersede)	không sửa → skip	W05
B02	capability_optional	có backend embedding, `mem-rank.config.yaml` `verified:true`	ranker dùng embedding thay token-overlap	chưa có → token-overlap (mặc định)	W05

ID	Kind	Guard	行为	Skip / failure	Rejoin
B01	user_optional	需要修正旧 episode	使用 `--id <ID> --supersedes <ID>` 写入新版本（temporal supersede）	不修正 → skip	W05
B02	capability_optional	有 embedding backend，且 `mem-rank.config.yaml` 中为 `verified:true`	ranker 使用 embedding 替代 token-overlap	尚无 → token-overlap（默认）	W05

Validation và stopping

验证与停止条件

Xong khi W05 truy hồi được episode vừa ghi. Một episode = 1 câu

did

+ file + outcome; dài hơn là nhiễu (xem Anti-patterns).

当 W05 检索到刚写入的 episode 时即完成。一个 episode = 1 句

did

+ file + outcome；更长则是噪声（参见反模式）。

Examples

示例

Positive: vừa đóng 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

trả episode đó.

Boundary/failure: user muốn "ghi episode: quyết định dùng SQLite thay JSONL cho store" → đây là quyết định kiến trúc bền → không ghi episode, chuyển sang wiki ADR /
```
/ingest
```
.

正向示例： 刚关闭 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 在哪里实现" --kind-filter episode

返回该 episode。

边界/失败： user 想“记录 episode：决定用 SQLite 代替 JSONL 作为 store” → 这是持久的架构决策 → 不写入 episode，转交 wiki ADR /
```
/ingest
```
。

Origin

来源

Source: issue GH#9 (frontier-gap memory, 4/4 tầng nhớ); ledger
```
030726-memory-episodic-vector.md
```
. Engine:
```
harness/scripts/mem-rank.py
```
(episode/retrieve/temporal). Eval:
```
harness/scripts/mem-proxy.py
```
.
Date: 2026-07-04

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