record-episode

スキル：record-episode

overstack の エピソード記憶（4/4 の記憶層 — working／semantic／procedural／episodic）。 Wiki は蒸留された知識（semantic）を保持し、スキルは手順（procedural）を保持し、.claude/memory は 平坦な事実を保持します。欠けているのは、具体的なセッションの出来事です。「前のセッションで何をし、どのファイルに触れ、 結果はどうだったか」。このスキルは、その内容を mem-rank ストアに記録し、次のセッションで query によって意味に基づいて検索できるようにします（誰かが [[wikilink]] を設定する必要はありません）。

WHAT

目的とコンテキスト

• 目的： 構造化されたセッションエピソード（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 は出来事（episodic）であり、セッションを指します。wiki（semantic）は引き続き信頼できる情報源です。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-overlap 方式（決定論的）です。embedding は mem-rank.config.yaml のアダプターです（verified:false）。バックエンドが利用可能になったら有効にしますが、すぐに利用することを妨げません。
• 機能：ローカルメモリーストアへの追記と、ランキング付き検索。ネットワーク通信も hook もありません。

失敗の境界

• 内容が永続的な教訓／アーキテクチャ上の決定である場合 → /ingest または wiki ADR へ 確認／誘導し、episode は記録しません。
• 検証可能な結果がない場合 → did + files を記録し、--outcome は省略します（partial）。結果を捏造しません。
• retrieve で記録したばかりの episode が返されない場合 → failed。ユーザーに報告し、完了とはみなしません。

HOW

メインワークフロー

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	セッション	セッションを did の1文に要約します	did の文	内容が永続的な知識 → /ingest
W02	deterministic	git diff、テスト結果／issue	--files + --outcome を収集します	パラメーター	検証可能な outcome がない → 空欄のままにします
W03	effect	did + パラメーター	mem-rank.py episode ...	ストア内の episode 行	—
W04	effect	誤った古い episode	--id <ID> --supersedes <ID> で supersede します（B01）	新しい episode + リンク	—
W05	deterministic	質問	mem-rank.py retrieve "<質問>" --kind-filter episode	結果に episode が表示されます	見つからない → failed

各ステップの詳細（W01–W05 の信頼できる情報源）：

手順

1. セッションを did の1文に要約します — 主な行動（動詞＋対象）を、検索に十分な用語を含めて記述します。
2. ファイルと結果を収集します： --files = 変更したパス（必要に応じて git diff --name-only から取得します）； --outcome = 検証可能な結果（テスト成功／issue クローズ／PR 番号）。
3. エピソードを記録します：

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

4. 古いエピソードを修正します（時間的な置き換え）： --id <ID> --supersedes <ID> を使用します — 新しい版が古い版に置き換わり、「これはいつの時点で正しかったのか」に答えられるよう、supersedes リンクを保持します。
5. 簡単に確認します： python3 harness/scripts/mem-rank.py retrieve "<câu hỏi>" --kind-filter episode。

アンチパターン

• 日記のように長いエピソードを記録する — 検索には did の1文＋ファイル＋結果で十分です。長いとノイズになります。
• エピソードを、長期的に有効なアーキテクチャ上の決定を記録する場所として使う — それは wiki ADR の役割です。

分岐

ID	種類	条件	動作	スキップ／失敗	合流先
B01	user_optional	古いエピソードを修正する必要がある	--id <ID> --supersedes <ID> を使って新しい版を記録します（時間的な置き換え）	修正しない → スキップ	W05
B02	capability_optional	embedding バックエンドがあり、mem-rank.config.yaml が verified:true	ranker は token-overlap の代わりに embedding を使用します	まだない → token-overlap（デフォルト）	W05

検証と終了条件

W05 で記録したばかりのエピソードを検索できれば完了です。1つのエピソードは did の1文＋ファイル＋結果で構成します。それより長いとノイズになります（「アンチパターン」を参照）。

例

• 成功例： 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 を記録：store に JSONL ではなく SQLite を使う決定」と希望する → これは長期的に有効なアーキテクチャ上の決定です → エピソードには記録せず、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