docs(tickets): simplify memory usage metrics

2026-05-11 16:54:23 +09:00 · 2026-05-11 16:54:23 +09:00 · 3d4d83db68
commit 3d4d83db68
parent 9abddb5a95
3 changed files with 119 additions and 41 deletions
--- 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 ツールの注意機構（無アクティビティで `<system-reminder>` ナッジ） → [tickets/session-todo-reminder.md](tickets/session-todo-reminder.md)
 - ワークスペースのメモリーをLintするヘッドレスCLI
--- 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>`（slug 完全一致経路）、`/<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**: 検索ツール経由の読み取り / `#<slug>` / `/<slug>` を `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`
+- `#<slug>` 完全一致参照
+- `/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
+- `#<slug>` / `/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` / `#<slug>` / `/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 側の事後評価）
--- 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`