docs: memory effectiveness plan

docs/plan/memory-effectiveness.md

@@ -0,0 +1,199 @@
+# Memory effectiveness improvement plan
+
+## Context
+
+`docs/plan/memory.md` で定義した永続化・検索・Phase 1 / Phase 2 の基盤は実装済みだが、現状の workspace memory を見る限り、実用上の効果はまだ弱い。
+
+現在の主要な症状:
+
+- `knowledge/*` が空で、通常 Pod が自発的に参照できる discovery 面がない
+- `memory/summary.md` は「Always-on サマリ」と設計されているが、通常 Pod の system prompt へ常駐注入されていない
+- Phase 2 は `KnowledgeCandidateReport::empty()` を受け取り、prompt 上も「候補レポートが空なら新規 Knowledge を作るな」としているため、Knowledge の cold-start が起きない
+- `decisions/*` と `requests/*` は記録としては残るが、description / resident injection を持たず、後続 turn で自然に読まれにくい
+- bundled prompt に INSOMNIA 開発固有の ticket / TODO 運用を前提にした shadow 禁止が入り、一般ユーザー workspace の管理文脈を過剰に落とす可能性がある
+
+この状態で usage metrics を先に実装しても、「使われていない / 発見されない memory」を測るだけになり、Knowledge 化候補や保護閾値の信号が十分に育たない。先に memory が読まれ、Knowledge が最低限生まれる経路を作る。
+
+## Proposal
+
+Usage metrics の前に、memory effectiveness の最小改善として以下を行う。
+
+1. `summary.md` を通常 Pod の resident context に入れる
+2. Knowledge の cold-start gate を緩める
+3. bundled memory prompts を project-management 手法に依存しない形へ汎用化する
+4. 明示参照 (`#<slug>`) の実用経路を整える
+5. 既存 decisions / requests から Knowledge へ昇格できる整理経路を用意する
+
+この順序により、metrics 実装時には「実際に読まれる対象」と「昇格候補になりうる Knowledge / memory record」が存在する状態になる。
+
+## 1. Summary resident injection
+
+### Problem
+
+`docs/plan/memory.md` では `memory/summary.md` を Always-on サマリとしている。しかし実装上、通常 Pod の system prompt に載るのは `model_invokation: true` の Knowledge description / Workflow description であり、summary は `MemoryRead(kind=summary)` しない限り読まれない。
+
+これは設計と実装のズレであり、memory の中心 record が通常 turn に効かない原因になっている。
+
+### Direction
+
+通常 Pod の system prompt trailing section に `summary.md` の本文または圧縮表示を載せる。
+
+- `[memory]` が有効で、`memory/summary.md` が存在する場合だけ注入する
+- Phase 2 / internal disposable Worker には注入しない
+- 既存の `Resident knowledge` とは別 section にする
+- summary の frontmatter は除外し、本文のみを載せる
+- summary 本文の linter 上限は 20,000 chars だが、resident 注入では別途 soft cap を持つか、当初は summary 自体を 1-5k tokens に保つ prompt 方針に依存する
+
+### Expected effect
+
+通常 Pod は少なくとも現在の project memory の要約を毎 turn 見られる。Knowledge が空でも memory subsystem の効果がゼロになりにくい。
+
+## 2. Knowledge cold-start gate
+
+### Problem
+
+現行 Phase 2 は `KnowledgeCandidateReport::empty()` を渡し、prompt も空レポート時の新規 Knowledge 作成を禁止している。これは usage metrics 完成後の gate としては妥当だが、cold-start では永久に Knowledge が生まれない。
+
+### Direction
+
+Knowledge 作成 gate と resident injection gate を分離する。
+
+- 新規 Knowledge 作成:
+  - Phase 2 が high-confidence に再利用価値を判断できる場合は許可する
+  - default は `model_invokation: false`
+  - `description` は「本文要約」ではなく「何の知識で、いつ読むべきか」を書かせる
+- `model_invokation: true` への昇格:
+  - usage metrics / 人間判断 / 将来の評価指標に基づく
+  - cold-start 自動作成時には原則 ON にしない
+- GC / drop 保護:
+  - 引き続き usage metrics の明示 invoke frequency を使う
+
+つまり、metrics が無い間も Knowledge は蓄積できるが、system prompt 常駐コストを増やす判断は保守的にする。
+
+### Expected effect
+
+Knowledge が空のまま固定される問題を避ける。metrics 実装前でも、検索可能な reusable knowledge が増える。
+
+## 3. Prompt generalization
+
+### Problem
+
+bundled memory prompts は、INSOMNIA 自身の ticket / TODO / worktree 運用を一般ユーザーへ押し付けている。ticket はこのプロジェクトの管理手法であり、ユーザー workspace の正本や作業管理の形は project ごとに異なる。
+
+### Direction
+
+Default prompt では特定の管理手法名を禁止対象として列挙しない。
+
+残すべき一般原則:
+
+- 既存の authoritative record を逐語的に mirror しない
+- ファイル操作ログや VCS 履歴そのものを memory に再保存しない
+- ただし、将来の作業判断に効く project-management 上の制約・優先順位理由・プロセス決定・ recurring pattern は抽象化して保存してよい
+- INSOMNIA 自身の ticket shadow 回避は bundled default ではなく workspace / user prompt override で表現する
+
+### Expected effect
+
+Memory extraction / consolidation が、ユーザー workspace の管理文脈を過剰に捨てなくなる。
+
+## 4. Explicit slug invocation path
+
+### Problem
+
+設計上は `#<slug>` で Knowledge を参照するが、現状は LLM が `KnowledgeQuery` / `MemoryRead` を自発的に呼ぶことに寄っている。ユーザーが明示的に `#slug` を書いても、専用の展開経路が弱い。
+
+### Direction
+
+段階的に実装する。
+
+1. user input から `#<slug>` を検出する
+2. exact slug で `knowledge/<slug>.md` を解決する
+3. 解決できた本文を user turn の context として history に append してから LLM に渡す
+4. 解決失敗は system-reminder / synthetic note ではなく、history に残る通常の input artifact として扱う
+
+この実装では、プロジェクト指示の「history に残らない context input 禁止」に従い、展開結果を必ず `worker.history` に commit する。context だけへの差し込みはしない。
+
+### Expected effect
+
+ユーザーが必要な Knowledge を明示参照でき、metrics 実装後の明示 invoke 計測点にもなる。
+
+## 5. Existing record promotion
+
+### Problem
+
+現状の memory には decisions と requests があるが、いくつかは reusable knowledge に近い。これらが decisions のままだと resident discovery や KnowledgeQuery の対象になりにくい。
+
+### Direction
+
+Phase 2 の tidy / consolidation に、既存 `decisions/*` / `requests/*` を Knowledge へ昇格する経路を追加する。
+
+- 同一内容を copy するのではなく、Knowledge として再利用可能な抽象に rewrite する
+- 元 decision は必要なら残す。Knowledge 側には `last_sources` として直近 source を持つ
+- 新規 Knowledge 作成は §2 の cold-start gate に従う
+- decision の「判断履歴」と Knowledge の「再利用可能な運用知識」を混同しない
+
+### Expected effect
+
+既存 memory の価値を引き出し、metrics 前に検索対象を増やせる。
+
+## Ordering
+
+推奨順序:
+
+1. Prompt generalization
+   - 既に `tickets/memory-prompts-remove-ticket-policy.md` として起票済み
+   - prompt が不要に情報を捨てる状態を先に止める
+2. Summary resident injection
+   - 既存 `summary.md` が即座に通常 Pod へ効く
+3. Knowledge cold-start gate
+   - Phase 2 が Knowledge を生めるようにする
+4. Existing record promotion
+   - 既存 decisions / requests から Knowledge を立ち上げる
+5. Explicit slug invocation path
+   - Knowledge が存在する状態で明示参照経路を整える
+6. Usage metrics
+   - 明示 invoke / resident cost / protection threshold / Knowledge candidate report を実装する
+
+## Interaction with usage metrics
+
+Usage metrics は不要ではない。役割を以下に限定すると妥当性が高い。
+
+- `model_invokation: true` へ昇格する判断材料
+- resident injection cost と使われ率の観測
+- tidy / GC での drop / 大幅圧縮保護
+- Knowledge candidate report の補助信号
+
+一方、metrics を Knowledge 作成そのものの唯一 gate にすると cold-start が壊れる。Knowledge 作成は high-confidence agent judgement、resident 化と保護は metrics、という分担にする。
+
+## Risks / open questions
+
+### Summary injection cost
+
+`summary.md` を常駐させると system prompt budget を消費する。summary が肥大化した場合に備え、以下のどちらかを選ぶ必要がある。
+
+- linter / Phase 2 prompt で summary を 1-5k tokens に保つ運用を先行する
+- resident injection 側に hard truncation / warning を入れる
+
+初期は前者でよいが、truncation されるなら LLM に明示した方がよい。
+
+### Knowledge noise
+
+cold-start gate を緩めると Knowledge が増えすぎる可能性がある。対策として、新規作成時の `model_invokation: false` default、update 優先、description 品質指示、tidy phase の noisy 分類を使う。
+
+### Prompt override boundary
+
+INSOMNIA 自身の ticket shadow 回避を完全に消すと、この repository の memory は作業ログ寄りに戻る可能性がある。これは bundled default ではなく workspace prompt override で解くべきで、default prompt の責務ではない。
+
+### `#<slug>` history representation
+
+明示参照展開をどの Item / Segment として history に残すかは別途詰める必要がある。原則は「LLM が見たものは history に残す」。context-only injection は使わない。
+
+## Validation criteria
+
+この計画が妥当かは、以下で判断する。
+
+- 新規 workspace で Knowledge が 0 件のまま固定されない
+- 通常 Pod が `summary.md` の内容を tool call なしで参照できる
+- bundled prompts が ticket / TODO / worktree 等の特定管理手法を前提にしない
+- Knowledge の `description` が discovery 面として機能する
+- `model_invokation: true` は uncontrolled に増えない
+- usage metrics 実装時に、計測対象となる明示参照 / resident cost / Knowledge records が存在する