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]]

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.

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 đè.

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

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.

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.

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):

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

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.

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

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).

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
```
.

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

record-episode

NPX Install

Tags

SKILL.md Content