yoi/tickets/memory-usage-metrics.md

メモリ機構: 明示使用回数ログ

背景

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
• #<slug> 完全一致参照
• /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

具体形式は実装で決定するが、最低限以下を保持する。

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 ごとに最低限以下を出す。

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 判定

範囲外

• Doctor / prompt-eval の実装本体（tickets/prompt-eval-metrics.md）
• Knowledge の自動作成
• model_invokation ON/OFF の完全自動切替
• query hit の計測
• session 浮上率の算出
• record が model output に実際に使われたかの自動判定

完了条件

• 明示使用 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 の主判断として使っていない

レビュー状態

• 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 側の事後評価）