docs(tickets): complete memory usage metrics
This commit is contained in:
parent
76f83a0894
commit
ac09bfcc21
1
TODO.md
1
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 ツールの注意機構（無アクティビティで `<system-reminder>` ナッジ） → [tickets/session-todo-reminder.md](tickets/session-todo-reminder.md)
|
||||
- ワークスペースのメモリーをLintするヘッドレスCLI
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
- `#<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
|
||||
|
||||
具体形式は実装で決定するが、最低限以下を保持する。
|
||||
|
||||
```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 判定
|
||||
|
||||
## 範囲外
|
||||
|
||||
- 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 側の事後評価）
|
||||
|
|
@ -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 として記録される。
|
||||
- `#<slug>` 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 の観測に留まっている。マージしてよい。
|
||||
Loading…
Reference in New Issue
Block a user