# AIエージェントの「記憶インデックス」が本当に想起を助けているかをA/Bで実測する ## 何のための指示書か 多くのコーディングエージェントは、永続メモリの**索引ファイル**（例: `MEMORY.md`）を **セッション開始時に自動ロード**する。索引は放っておくと育ち、毎セッションの入力トークンを食う。 そこで「索引を薄くするか、ドメイン別サブ索引に分割するか」という設計判断が発生する。 この判断を**感覚で決めない**ための実測手順。実際にやると、多くの人の直感と逆の結果が出ることがある。 ## 前提となる用語 - **索引**: セッション開始時に自動で文脈に入るリンク一覧（`MEMORY.md`） - **本体**: 実際の知識が書かれた個別ファイル（`feedback_xxx.md` 等） - **サブ索引**: 索引を分割した第2階層（`index/<ドメイン>.md`）。読むには明示的な Read が要る ## 測定の設計 ### 比較する2案 - **v1（薄い単一索引）**: 全エントリをトップに載せる。分割なし。 - **v2（分割）**: トップは入口だけ。実体はサブ索引に置き、必要ならエージェントが読みに行く。 ### 質問を2群に分ける（ここが肝） 片方の設計に有利な質問だけを選ぶと結論が決め打ちになる。**双方の弱点を突く2群**を作る。 - **群A**: v1のトップ索引にあり、v2ではサブ索引にしかない知識 → v2の弱点（追加の Read が要る）を突く - **群B**: v1では索引から外れており、v2ではサブ索引にある知識 → v1の弱点（索引に載っていない）を突く 各群6問。質問は**その知識ファイルにしか書かれていない固有の事実**を問うものにし、 採点は「回答本文に期待キーワードのいずれかが含まれるか」の単純な部分文字列一致でよい。 ### 測る値 1. **想起成功率**（群別・全体） 2. **1セッションあたりの実入力トークン** 3. **サブ索引が実際に Read された回数** ← これが決定的 ## 実装上の4つの罠 ### 罠1: サブエージェントでは測れない 索引の自動ロードは**セッション開始時の機構**なので、サブエージェントを呼んでも経路を通らない。 **本物のエージェントCLIをヘッドレスで起動する**こと。 ``` <エージェントCLI> -p "<質問>" --model <モデル> --output-format json ``` ### 罠2: 共有環境の索引を差し替えない 実運用のメモリディレクトリを書き換えると、並行して動いている他セッションを巻き込む。 **一時ディレクトリに専用プロジェクトを2つ作って隔離**する。 多くのCLIは**プロジェクトIDを cwd の文字列から機械的に導出**する （よくある規則: 英数字以外をすべて `-` に置換）。この規則を使えば、 一時 cwd に対応するメモリディレクトリを自分で用意できる。 ``` <一時ルート>/ab-v1 → ~/.claude/projects/<導出したID>/memory/ <一時ルート>/ab-v2 → ~/.claude/projects/<導出したID>/memory/ ``` 本体ファイルは両方に同じものをコピーし、**索引だけを差し替える**。 測定後は一時ディレクトリとプロジェクトディレクトリを finally で必ず削除する。 信頼ダイアログで止まらないよう、設定ファイルの `projects[].hasTrustDialogAccepted` を 事前に立てておく。**設定ファイルが読めなかったら書き戻さずに中止する** （空オブジェクトを土台に書くと設定ごと消える）。 ### 罠3: 結論を出す前に「索引が本当にロードされたか」を検査する 最重要。実測値が理屈と合わないときは、**まず検査側を疑う**。 判定法（カナリア）: **実在しない固有語**を含む本体ファイルを1つ仕込み、 それを問う質問を投げる。逐語で返ってくれば索引・メモリの経路は生きている。 ``` 本体: 「ZQX-7731 は社内で『紫色のワニ手順』と呼ばれる復旧手順の型番」 質問: 「ZQX-7731 とは何ですか」 判定: 回答に「紫色のワニ」が含まれるか ``` これを踏まなかった場合、「差が出ない」を誤って「両案は同等」と読んでしまう （実際には何もロードされていなかった、という可能性を潰せない）。 ### 罠4: 総入力に対する索引の割合を見誤らない 索引が十数KBあっても、システムプロンプト・プロジェクト規約・ツール定義を含めた 総入力が100kトークン規模なら、**索引は数%にすぎない**。 セッションごとの作業量のばらつきが systematic な差を簡単に埋める。 差が理屈より小さく出ても、**方向が一致していれば矛盾ではない**。 ## 結果の読み方 次の3つが同時に成り立ったら、**索引の一覧は想起の経路ではない**と結論できる。 1. サブ索引の Read 回数が **0** 2. それでも想起成功率が両案で**同率** 3. **索引に載っていない群の方が、載っている群より成績が良い**（掲載と成功が逆相関） この場合、想起を担っているのは索引ではなく、**本体ファイルへの意味検索**である。 → **索引は薄いほどよい**。厚い索引は毎セッション数千トークンを払って便益ゼロ。 逆に、サブ索引が実際に読まれていて群Aで分割案が負けるなら、分割は追加Readのコストを 払っているだけなので、薄い単一索引を採る。 ## 必ず添える限界の明示 - 測っているのは**直接質問されたときの想起**であって、作業中に自発的に 「そういえばこの知識がある」と気づく**能動的な認識**ではない。索引が効くとすればそこ。 - 12問・各1回では統計的に強くない。結論を運用に反映する前に問題数を増やせる設計にしておく。 - タイムアウトは「失敗」として記録し、**成功率の分母から落とさない**。 ## 最小の実装骨子 ```js // 1) 一時cwdを2つ作る → プロジェクトID導出 → memory を用意（索引だけ差し替え） // 2) 各質問 × 各案 で独立セッションを起動（同時実行は4程度、1問180秒でタイムアウト） // 3) JSON から入力/出力トークンと本文を取る // 4) キーワード一致で採点し、群別・全体の成功率と平均入力トークンを出す // 5) finally で一時ディレクトリ・プロジェクト・設定の一時キーを削除 ``` タイムアウト時は**プロセスツリー全体を終了**する。子プロセスが一時 cwd を掴んだままだと ディレクトリを削除できない。 ## この手順で節約できること 索引設計は「厚くすべき/薄くすべき」の宗教論争になりやすい。24セッション程度の実測で 決着がつき、しかも**索引が想起に寄与していない**と分かれば、以後すべてのセッションの 入力トークンをそのぶん恒久的に削れる。 ---