diff --git a/docs/plan/memory-effectiveness.md b/docs/plan/memory-effectiveness.md new file mode 100644 index 00000000..5af11e58 --- /dev/null +++ b/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. 明示参照 (`#`) の実用経路を整える +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 + +設計上は `#` で Knowledge を参照するが、現状は LLM が `KnowledgeQuery` / `MemoryRead` を自発的に呼ぶことに寄っている。ユーザーが明示的に `#slug` を書いても、専用の展開経路が弱い。 + +### Direction + +段階的に実装する。 + +1. user input から `#` を検出する +2. exact slug で `knowledge/.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 の責務ではない。 + +### `#` 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 が存在する