diff --git a/TODO.md b/TODO.md index 594d0afd..677a25fc 100644 --- a/TODO.md +++ b/TODO.md @@ -25,7 +25,6 @@ - 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) - メモリ機構 - - 明示使用回数ログ → [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 deleted file mode 100644 index 52f66ec9..00000000 --- a/tickets/memory-usage-metrics.md +++ /dev/null @@ -1,146 +0,0 @@ -# メモリ機構: 明示使用回数ログ - -## 背景 - -memory / Knowledge の改善で必要なのは、「どの record が実際に context に読まれたか」を後から確認できる観測ログである。 - -検索結果に出たことや session あたりの浮上率は、session の目的や query の広さに強く依存し、record が読まれたことも意味しない。`n/Mtoken` のような線形スコアも、Knowledge の価値や使用実態を表す軸としては不安定である。 - -本チケットでは、判断ロジックではなく **明示使用回数の計測** を実装する。Knowledge 化、整理時の保護、`model_invokation` ON/OFF の判断は、このログを材料に consolidation / Doctor / prompt-eval 側で行う。 - -## 方針 - -- 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 として別口で記録する - -## 使用回数として数える event - -### `use` - -record が明示的に context に取り込まれたことを表す。 - -対象: - -- `MemoryRead` -- `#` 完全一致参照 -- `/workflow` で workflow 自体が呼び出された場合の workflow record -- 将来追加される明示的な Knowledge / Workflow read 経路 - -補足: - -- `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 判定 - -## 範囲外 - -- Doctor / prompt-eval の実装本体（`tickets/prompt-eval-metrics.md`） -- Knowledge の自動作成 -- `model_invokation` ON/OFF の完全自動切替 -- query hit の計測 -- session 浮上率の算出 -- record が model output に実際に使われたかの自動判定 - -## 完了条件 - -- 明示使用 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 の主判断として使っていない - -## レビュー状態 - -- `d581a35 feat: add memory usage event metrics` を review 済み。結果は `tickets/memory-usage-metrics.review.md`。 -- 指摘 1 件（tidy hints の古い未接続文言）は amend 済み。 -- 判断: approve / merge 可。 - -## 参照 - -- `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/memory-usage-metrics.review.md b/tickets/memory-usage-metrics.review.md deleted file mode 100644 index 2a07db27..00000000 --- a/tickets/memory-usage-metrics.review.md +++ /dev/null @@ -1,36 +0,0 @@ -# Review: Memory usage metrics - -## 対象 - -- Ticket: `tickets/memory-usage-metrics.md` -- Branch: `memory-usage-metrics` -- Reviewed commit: `d581a35 feat: add memory usage event metrics` - -## 確認内容 - -- 明示使用回数ログは workspace-local append-only JSONL として `.insomnia/memory/_usage/events.jsonl` に保存される。 -- `MemoryRead` は `use` event として記録される。 -- `#` Knowledge ref は解決成功時に `KnowledgeRef` source の `use` event として記録される。 -- `/workflow` invocation は workflow record の `WorkflowInvoke` source の `use` event として記録される。 -- `MemoryQuery` / `KnowledgeQuery` は usage を記録せず、検索 hit を使用回数に含めていない。 -- resident injection は `resident_exposure` として `use_count` から分離されている。 -- report は record ごとの `use_count`, `last_used_at`, `source_breakdown`, `resident_exposure_count`, `estimated_tokens_per_injection`, `estimated_total_resident_exposure_tokens` を返す。 -- consolidation input は usage report を evidence として渡し、Knowledge 化や tidy protection の hard decision は実装していない。 -- 旧方針の `n/Mtoken`, cumulative-token window, session 浮上率, frequency threshold 判定は入っていない。 - -## 指摘と対応 - -- 指摘: tidy hints に「Explicit-invoke metrics が未接続」という古い文言が残っており、今回の evidence report 接続と矛盾していた。 -- 対応: 同 commit を amend し、usage evidence は soft context として扱う説明へ修正した。 - -## 検証 - -- `cargo test -p memory` passed -- `cargo test -p pod` passed -- `cargo fmt --check` は既存の unrelated rustfmt 差分により失敗するが、今回変更ファイルは対象 diff に含まれていない。 - -## 判断 - -Approve. - -チケットの簡略化後仕様に対して、実装は過剰な frequency / session-rate 判定を持ち込まず、明示使用回数と resident exposure cost の観測に留まっている。マージしてよい。