yoi/docs/plan/memory-effectiveness.md

Memory effectiveness improvement plan

Context

docs/plan/memory.md で定義した永続化・検索・extract / consolidation の基盤は実装済みだが、現状の workspace memory を見る限り、実用上の効果はまだ弱い。

現在の主要な症状:

• knowledge/* が空で、通常 Pod が自発的に参照できる discovery 面がない
• memory/summary.md は「Always-on サマリ」と設計されているが、通常 Pod の system prompt へ常駐注入されていない
• consolidation は KnowledgeCandidateReport::empty() を受け取り、prompt 上も「候補レポートが空なら新規 Knowledge を作るな」としているため、Knowledge の cold-start が起きない
• decisions/* と requests/* は記録としては残るが、description / resident injection を持たず、後続 turn で自然に読まれにくい
• bundled prompt に Yoi 開発固有の 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 が存在する場合だけ注入する
• consolidation / 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

現行 consolidation は KnowledgeCandidateReport::empty() を渡し、prompt も空レポート時の新規 Knowledge 作成を禁止している。これは usage metrics 完成後の gate としては妥当だが、cold-start では永久に Knowledge が生まれない。

Direction

Knowledge 作成 gate と resident injection gate を分離する。

• 新規 Knowledge 作成:
  • consolidation が 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 は、Yoi 自身の ticket / TODO / worktree 運用を一般ユーザーへ押し付けている。ticket はこのプロジェクトの管理手法であり、ユーザー workspace の正本や作業管理の形は project ごとに異なる。

Direction

Default prompt では特定の管理手法名を禁止対象として列挙しない。

残すべき一般原則:

• 既存の authoritative record を逐語的に mirror しない
• ファイル操作ログや VCS 履歴そのものを memory に再保存しない
• ただし、将来の作業判断に効く project-management 上の制約・優先順位理由・プロセス決定・ recurring pattern は抽象化して保存してよい
• Yoi 自身の 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

consolidation の 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
   • consolidation が 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 / consolidation 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 step の noisy 分類を使う。

Prompt override boundary

Yoi 自身の 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 が存在する