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[<cwd>].hasTrustDialogAccepted を 事前に立てておく。設定ファイルが読めなかったら書き戻さずに中止する （空オブジェクトを土台に書くと設定ごと消える）。

罠3: 結論を出す前に「索引が本当にロードされたか」を検査する

最重要。実測値が理屈と合わないときは、まず検査側を疑う。

判定法（カナリア）: 実在しない固有語を含む本体ファイルを1つ仕込み、 それを問う質問を投げる。逐語で返ってくれば索引・メモリの経路は生きている。

本体: 「ZQX-7731 は社内で『紫色のワニ手順』と呼ばれる復旧手順の型番」
質問: 「ZQX-7731 とは何ですか」
判定: 回答に「紫色のワニ」が含まれるか

これを踏まなかった場合、「差が出ない」を誤って「両案は同等」と読んでしまう （実際には何もロードされていなかった、という可能性を潰せない）。

罠4: 総入力に対する索引の割合を見誤らない

索引が十数KBあっても、システムプロンプト・プロジェクト規約・ツール定義を含めた 総入力が100kトークン規模なら、索引は数%にすぎない。 セッションごとの作業量のばらつきが systematic な差を簡単に埋める。 差が理屈より小さく出ても、方向が一致していれば矛盾ではない。

結果の読み方

次の3つが同時に成り立ったら、索引の一覧は想起の経路ではないと結論できる。

1. サブ索引の Read 回数が 0
2. それでも想起成功率が両案で同率
3. 索引に載っていない群の方が、載っている群より成績が良い（掲載と成功が逆相関）

この場合、想起を担っているのは索引ではなく、本体ファイルへの意味検索である。 → 索引は薄いほどよい。厚い索引は毎セッション数千トークンを払って便益ゼロ。

逆に、サブ索引が実際に読まれていて群Aで分割案が負けるなら、分割は追加Readのコストを 払っているだけなので、薄い単一索引を採る。

必ず添える限界の明示

• 測っているのは直接質問されたときの想起であって、作業中に自発的に 「そういえばこの知識がある」と気づく能動的な認識ではない。索引が効くとすればそこ。
• 12問・各1回では統計的に強くない。結論を運用に反映する前に問題数を増やせる設計にしておく。
• タイムアウトは「失敗」として記録し、成功率の分母から落とさない。

最小の実装骨子

// 1) 一時cwdを2つ作る → プロジェクトID導出 → memory を用意（索引だけ差し替え）
// 2) 各質問 × 各案 で独立セッションを起動（同時実行は4程度、1問180秒でタイムアウト）
// 3) JSON から入力/出力トークンと本文を取る
// 4) キーワード一致で採点し、群別・全体の成功率と平均入力トークンを出す
// 5) finally で一時ディレクトリ・プロジェクト・設定の一時キーを削除

タイムアウト時はプロセスツリー全体を終了する。子プロセスが一時 cwd を掴んだままだと ディレクトリを削除できない。

この手順で節約できること

索引設計は「厚くすべき/薄くすべき」の宗教論争になりやすい。24セッション程度の実測で 決着がつき、しかも索引が想起に寄与していないと分かれば、以後すべてのセッションの 入力トークンをそのぶん恒久的に削れる。