yoi/tickets/memory-file-format.md

メモリ機構: ファイル形式 + Linter 土台

背景

docs/plan/memory.md で決めたメモリ機構の永続化レイヤの土台。memory/* と knowledge/* の record を保存・編集する際の静的スキーマと、書き込み時の Linter を成立させる。Phase 1/2、検索ツール、常駐注入、GC はすべてこの層に乗る。

Workflow（docs/plan/workflow.md）も同じ frontmatter / Linter 経路で扱うため、memory/workflow/<slug>.md の frontmatter 検証と書き込み制限も本チケットに含める。実行経路（/<slug> dispatch）は別。

設計方針

memory クレートに集約

memory 関連は新規 crates/memory/ に全部閉じ込める。tools クレートや pod 層に memory 由来のコードを漏らさない。

• schema（frontmatter 型）、slug 文法、Linter ルール、Tool 実装、ワークスペース解決を全部 memory クレート内に置く
• tools::write_tool / edit_tool には一切手を入れない
• LLM への違反伝達は memory tool が ToolError::InvalidArgument を返すことで自然に成立。Interceptor 拡張・retry message 注入・違反カウンタは持たない
• 「N 回失敗で abort」は worker 層の max iteration に委ね、memory 固有のカウンタは設けない

memory 専用 Tool（汎用 CRUD ではない）

memory クレートが read_tool / write_tool / edit_tool の 3 種を提供する。これらは <workspace>/memory/、<workspace>/knowledge/ 配下のみを対象とし、write/edit は fs 書き込み前 に Linter を通して違反は ToolError::InvalidArgument で返す。

docs/plan/memory.md の「同じ汎用 CRUD」記述は本チケットで memory 専用 Tool 方式に書き換える（汎用 CRUD は memory ディレクトリには触らせない）。

Pod 側の責務（最小限）

memory を有効化する Pod は、generic tool に渡す Scope から memory/、knowledge/ を deny に落とす。これにより同じ workspace 内で、generic write/edit は memory 配下を触れず、memory tool だけが触れる構造になる。Pod 側でやることはこの Scope deny と memory tool の登録だけ。

「sub-Worker / 人間」の二系統

• sub-Worker: tool 層を経由するため Linter を必ず通る
• 人間: エディタ / git commit は tool 層を経由しないので Linter を通らない。memory::Linter を import して走らせる CLI / pre-commit hook を後で用意できる構造にしておく（本チケットでは実装しない）

要件

ディレクトリと record 種別

• memory/summary.md — Always-on サマリ（1 ファイル固定）
• memory/decisions/<slug>.md — Decisions
• memory/requests/<slug>.md — Requests
• memory/workflow/<slug>.md — Workflow（frontmatter 検証のみ対象）
• memory/_staging/<id>.json — Phase 1 中間（パス予約のみ。Linter 対象外）
• knowledge/<slug>.md — Knowledge（memory/ の兄弟）

slug 文法: ^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$（agent-skills 準拠、1-64 chars、先頭末尾 - 不可、-- 連続不可）。ファイル名がそのまま識別子で、frontmatter に id / name は持たない。

frontmatter スキーマ

• 共通: created_at, updated_at（RFC3339）
• Decisions: sources, status: open | resolved | replaced、置き換え時 replaced_by: <slug>
• Requests: sources
• Knowledge: kind, description, model_invokation, user_invocable, last_sources
• Summary: updated_at（optional: last_rewritten_from_range）
• Workflow: description, auto_invoke, user_invocable, requires

sources / last_sources の要素形式は { session_id: String, range: [u64, u64] }。range は session-store の entry index ペア。

Linter ルール

静的 error（memory tool が ToolError::InvalidArgument で返す。複数違反は集約して 1 回で返す）:

• frontmatter 必須 field 欠落・型違反
• memory/workflow/ への書き込み禁止（sub-Worker のみ。memory tool が拒否、人間編集は memory tool を通らないので素通り）
• 同 slug での新規作成禁止（既存があれば update を要求）
• replaced_by: <slug> / requires: [..] が実在 record を指す
• replaced_by の循環は error
• Decisions status の enum 違反
• slug 文法違反
• model_invokation: true な Knowledge の description 1024 chars 上限
• 種別ごとの char 硬上限（初期既定値、設定 key は別 PR）:
  • summary.md: 20000 chars
  • decisions / requests / knowledge 本文: 各 8000 chars

膨張抑制 Warn（error にせず、warn として返す。memory tool は受け取って summary に追記する程度）:

• 低重要度 × char の天秤（暫定: 1500 chars 超のレコードに対して sources 1 件のみなら warn）
• sources 配列長の累積（暫定: 10 件超で warn）
• 類似 slug 乱立（暫定: Levenshtein 距離 2 以下の slug が 3 件以上で warn）

具体閾値の調整は別 PR（設定 key 化）。

#<slug> 本文中検出はスコープ外

本文中の #<slug> 参照の検出 / 補完は submit-segment 系チケットの責務。本チケットの Linter は frontmatter 由来の参照（replaced_by / requires）のみを検証する。

参照整合チェックの実行方式

write/edit 毎に <workspace>/memory/、<workspace>/knowledge/ を毎回 walk して slug 集合を構築（キャッシュなし）。ファイル数は少ない想定。

適用経路

• memory tool の write/edit 内で pre-write 検証
• 人間編集 / pre-commit hook 経路は本チケットでは作らない。memory::Linter を pure 関数として export しておけば後で CLI 化できる

範囲外

• 検索ツール、常駐注入、Phase 1/2、GC の実装
• 意味破壊（rewrite で主張が落ちる等）の検出 — 監査 LLM 層は将来検討
• staging JSON の schema — Phase 1 チケット
• Workflow の /<slug> 実行経路
• 本文中 #<slug> 参照の検出 — submit-segment 系
• 設定 key（閾値 tune）— 別 PR
• 人間編集向け CLI / pre-commit hook — 別チケット
• Interceptor / Hook 系統への拡張 — 不要（tool error で完結）

完了条件

• crates/memory/ が新設され、workspace に登録されている
• memory tool 3 種（read / write / edit）が登録できる
• write/edit に違反 content を渡すと、複数違反を集約した ToolError::InvalidArgument が返り、fs に書き込まれない
• 正常 content は通常通り書き込まれる
• memory/workflow/<slug>.md への write/edit は error で止まる
• 同 slug で新規作成しようとすると error になる（existing → edit に倒すサイン）
• replaced_by / requires の参照切れと循環が error として検出される
• Pod が memory を有効化すると、generic tool の Scope から memory/knowledge が deny される
• 既存ビルド・テストを壊さない

実装順序

1. crates/memory/ 新設、workspace 登録、依存追加
2. schema/, slug.rs, error.rs（pure 関数 + 型）
3. linter/（frontmatter / size / 参照存在 / 循環 / workflow 拒否）
4. tool/（read / write / edit、pre-write で linter 通す）
5. Pod 側の Scope deny 配線
6. 単体テスト

各ステップ終了時点でビルド通過を維持する。

参照

• docs/plan/memory.md §ファイル形式 / §書き込み経路と Linter / §Knowledge の採択基準（本チケットで該当箇所を memory 専用 tool 方式に更新）
• docs/plan/workflow.md §格納先とファイル形式 / §生成・更新ポリシー
• crates/tools/src/{write,edit,read}.rs — Tool 実装の参考（依存はしない）
• crates/llm-worker/src/tool.rs — Tool trait / ToolError / ToolOutput

Review

• 状態: Approve with follow-up
• レビュー詳細: ./memory-file-format.review.md
• 日付: 2026-04-27