diff --git a/TODO.md b/TODO.md index 5b250c3e..594d0afd 100644 --- a/TODO.md +++ b/TODO.md @@ -25,8 +25,7 @@ - Manifest: Tool Output / File Upload 上限の分離とデフォルト緩和 → [tickets/manifest-output-upload-limits.md](tickets/manifest-output-upload-limits.md) - Prune: 保護境界を turn 数から末尾 token budget に置き換え → [tickets/prune-token-budget.md](tickets/prune-token-budget.md) - メモリ機構 - - 使用頻度メトリクス + Knowledge 化候補レポート → [tickets/memory-usage-metrics.md](tickets/memory-usage-metrics.md) - - Phase 1/2 呼称を extract/consolidation に統一 → [tickets/memory-phase-naming.md](tickets/memory-phase-naming.md) + - 明示使用回数ログ → [tickets/memory-usage-metrics.md](tickets/memory-usage-metrics.md) - extract / consolidation 監査ログ → [tickets/memory-audit-log.md](tickets/memory-audit-log.md) - セッション内 Task ツールの注意機構(無アクティビティで `` ナッジ) → [tickets/session-todo-reminder.md](tickets/session-todo-reminder.md) - ワークスペースのメモリーをLintするヘッドレスCLI diff --git a/tickets/memory-usage-metrics.md b/tickets/memory-usage-metrics.md index 37475eea..1ea2f722 100644 --- a/tickets/memory-usage-metrics.md +++ b/tickets/memory-usage-metrics.md @@ -1,60 +1,140 @@ -# メモリ機構: 使用頻度メトリクス + Knowledge 化候補レポート +# メモリ機構: 明示使用回数ログ ## 背景 -`docs/plan/memory.md` §使用頻度メトリクス の実装。memory 検索ツール / Knowledge 検索ツール内に invoke 計測フックを入れ、時間単位ではなく累積 input token で正規化した頻度を算出する。consolidation 統合 step の Knowledge 新規作成 gate と consolidation 整理 step の保護閾値の両方で使われる。 +memory / Knowledge の改善で必要なのは、「どの record が実際に context に読まれたか」を後から確認できる観測ログである。 -## 要件 +検索結果に出たことや session あたりの浮上率は、session の目的や query の広さに強く依存し、record が読まれたことも意味しない。`n/Mtoken` のような線形スコアも、Knowledge の価値や使用実態を表す軸としては不安定である。 -### 観測経路 +本チケットでは、判断ロジックではなく **明示使用回数の計測** を実装する。Knowledge 化、整理時の保護、`model_invokation` ON/OFF の判断は、このログを材料に consolidation / Doctor / prompt-eval 側で行う。 -- memory 検索ツール / Knowledge 検索ツール内に hook を挿入 -- `#`(slug 完全一致経路)、`/`(workflow 側、将来接続)、明示検索呼び出しをすべて同じ経路に集約 +## 方針 -### カウント対象 +- workspace 側に append-only な usage event log を残す +- staging や session-local state と独立させ、session データ喪失で統計が消えないようにする +- 主指標は record が明示的に context に読まれた回数に限定する +- 検索 hit / query result surface は主指標にしない。初期実装では記録しなくてよい +- session 浮上率や `n/Mtoken` は採用しない +- `model_invokation` 常駐注入は「使用回数」には含めず、resident exposure cost として別口で記録する -- **明示 invoke**: 検索ツール経由の読み取り / `#` / `/` を `n回 / Mtoken` でスコア化 -- **`model_invokation` 注入**: 明示 invoke の分子には含めない。**コスト側**(注入した record に対する消費 input tokens)として別途記録。使われ率 ratio や ON/OFF 判断材料として後段で参照 -- ファイル token 数 +## 使用回数として数える event -### 記録先 +### `use` -- staging と独立 -- workspace 側に記録(session データ喪失で統計が消えない) -- invoke event を UUID + Stats 形式 -- 具体 schema / フォーマットは実装で決定 +record が明示的に context に取り込まれたことを表す。 -### 集計 +対象: -- 累積方式: 最大 10 回前の invoke から現在までの時系列窓でフィルタして集計 -- **Knowledge 化候補レポート**: - - 対象は `memory/*` 配下の record(extract 成果物の decisions / requests + 既存 knowledge) - - 明示 invoke 頻度が閾値超過のものを列挙 - - 同一 session 内の連続参照は 1 count に丸める - - 複数 session での再参照を要件とする(spike 除外) - - 閾値は設定ファイルで tune +- `MemoryRead` +- `#` 完全一致参照 +- `/workflow` で workflow 自体が呼び出された場合の workflow record +- 将来追加される明示的な Knowledge / Workflow read 経路 -### 消費者 +補足: -- consolidation Worker の統合 step 入力として候補レポートを渡す -- consolidation Worker の整理 step で保護閾値判定(明示 invoke frequency >= 1.0 invokes/Mtoken)に使う +- `MemoryQuery` / `KnowledgeQuery` の検索結果に出ただけでは count しない +- LLM が検索後に自分で `MemoryRead` した場合は、その read を count する +- 同一 session 内での連続参照 coalescing は初期実装では必須にしない。必要になった時に report 側で補助的に扱う + +### `resident_exposure` + +`model_invokation: true` 等により常駐注入されたことを表す。これは使用回数ではなく cost 観測である。 + +対象: + +- resident knowledge injection + +用途: + +- record token size / injection count / 推定 total exposure cost の把握 +- 明示使用が少ない高コスト常駐 record の発見 +- usefulness の分子には含めない + +## event schema + +具体形式は実装で決定するが、最低限以下を保持する。 + +```text +id: uuid +occurred_at +session_id +event: use | resident_exposure +source: MemoryRead | KnowledgeRef | WorkflowInvoke | ResidentInjection +records[]: + kind + slug + file_bytes + file_tokens_estimate +``` + +`input_tokens` や prompt occupancy は、取得できるなら補助メタデータとして残してよい。ただし集計・判定の主軸にしない。 + +## report + +consolidation / Doctor / prompt-eval から読める集計 API を提供する。 + +record ごとに最低限以下を出す。 + +```text +kind +slug +use_count +last_used_at +source_breakdown +resident_exposure_count +estimated_tokens_per_injection +estimated_total_resident_exposure_tokens +``` + +この report は hard decision ではなく、判断材料である。 + +- Knowledge 化候補: `decision` / `request` のうち、明示使用回数が多いものを確認対象にする +- tidy protection: 明示使用された record は削除 / 大幅圧縮時に追加確認する +- resident 見直し: resident exposure cost が高く、明示使用が少ない record を確認対象にする + +## 現 worktree 実装の扱い + +`.worktree/memory-usage-metrics` の実装から残してよいもの: + +- workspace-local append-only JSONL event log +- `MemoryRead` hook +- `#` / `/workflow` 経路の hook +- resident injection を明示使用と別イベントにする配線 +- record snapshot に file bytes / token estimate を持つこと +- report API の土台 + +作り替えるもの: + +- `ExplicitInvoke` という単一分類 +- `MemoryQuery` / `KnowledgeQuery` hit を主指標として記録する設計 +- `frequency_per_mtoken` +- cumulative input token を前提にした window 集計 +- session 浮上率や複数 session 要件を hard metric にする設計 +- `usage_candidate_frequency_threshold` / `usage_protection_frequency_threshold` 系の設定 +- frequency threshold による Knowledge 化候補 / protection 判定 ## 範囲外 -- consolidation 整理 step の実装本体(`memory-consolidation` 側。本チケットは保護閾値判定に必要なメトリクスの提供まで) -- `model_invokation` ON/OFF の自動判定ロジック(将来検討) -- Shallow request の自動除外(将来検討) +- Doctor / prompt-eval の実装本体(`tickets/prompt-eval-metrics.md`) +- Knowledge の自動作成 +- `model_invokation` ON/OFF の完全自動切替 +- query hit の計測 +- session 浮上率の算出 +- record が model output に実際に使われたかの自動判定 ## 完了条件 -- 検索ツール呼び出しで invoke event が workspace 側に積まれる -- `model_invokation` 注入のコスト側集計が別口で積まれる -- 候補レポート API が consolidation Worker の起動時に呼べる -- 閾値未満の record は候補レポートに載らない -- 同一 session 内連続参照は 1 count に丸まる +- 明示使用 event が workspace 側に append-only に積まれる +- `MemoryRead` / `#` / `/workflow` 経路が使用回数として count される +- `MemoryQuery` / `KnowledgeQuery` の検索 hit が使用回数に含まれていない +- resident exposure が使用回数とは別口で記録される +- record ごとの `use_count` / `last_used_at` / `source_breakdown` / resident cost を集計できる +- consolidation / Doctor 側から report API を呼べる +- `n/Mtoken` や session 浮上率を Knowledge 化候補や tidy protection の主判断として使っていない ## 参照 - `docs/plan/memory.md` §使用頻度メトリクス / §判断ルール / §retrieval 経路 - `tickets/memory-search-tools.md`(hook 挿入点) - `tickets/memory-consolidation.md`(統合 / 整理 両 step の消費者) +- `tickets/prompt-eval-metrics.md`(Doctor / prompt-eval 側の事後評価) diff --git a/tickets/prompt-eval-metrics.md b/tickets/prompt-eval-metrics.md index a5ba97e8..5dda4258 100644 --- a/tickets/prompt-eval-metrics.md +++ b/tickets/prompt-eval-metrics.md @@ -9,8 +9,8 @@ mizchi の empirical-prompt-tuning は、agent-facing な指示(Skill / slash - evaluator Pod の session id / history - tool call / tool result - usage tokens -- workflow / knowledge の明示 invoke 頻度(`tickets/memory-usage-metrics.md`) -- `model_invokation` 常駐注入のコスト側指標 +- workflow / knowledge の明示使用ログ(use 回数、last used、source breakdown。`tickets/memory-usage-metrics.md`) +- `model_invokation` 常駐注入の exposure cost 指標 - extract / consolidation による recurring pattern 抽出 - Workflow 自動書き込み禁止に基づく improvement offer @@ -93,9 +93,9 @@ retries - evaluator self-report は consolidation extract の活動抽出対象になる - repeated `General Fix Rule` は consolidation が recurring failure pattern として統合できる -- recurring pattern は即 Knowledge 化せず、使用頻度メトリクス gate を通す +- recurring pattern は即 Knowledge 化せず、明示使用ログと Doctor / prompt-eval の事後評価を通す - Workflow 改善は `.insomnia/workflow/*.md` へ自動書き込みせず、Notification / report / ticket などの offer に留める -- `model_invokation` ON 判断では、明示 invoke 頻度と常駐コストに加えて、eval success rate / unclear point count / description-body consistency を判断材料にする +- `model_invokation` ON 判断では、明示使用ログと resident exposure cost に加えて、eval success rate / unclear point count / description-body consistency を判断材料にする ### 評価指標の解釈 @@ -140,7 +140,6 @@ Claude Code 版の `tool_uses` を、insomnia では tool 種別ごとの偏り ## 参照 -- `docs/external/zenn-mizchi-empirical-prompt-tuning.md` - `/home/hare/ghq/github.com/mizchi/skills/empirical-prompt-tuning/SKILL.md`(外部参照。取り込み時は必要最小限に一般化する) - `docs/plan/workflow.md` - `docs/plan/memory.md`