# AIエージェントの記憶インデックスが「読み込み上限で黙って切り捨てられる」問題の検出と恒久対策 ## この指示書が解く問題 AIコーディングエージェント（Claude Code / Cursor / Codex など）に長期記憶を持たせるとき、 `MEMORY.md` のような**索引ファイル1本に全項目を並べる**設計をよく採る。 この設計は、索引がセッション開始時に自動ロードされる限り**必ず破綻する**。 - ロード対象のファイルには**サイズ上限**があり、超えた分は**黙って捨てられる** - エラーも警告も出ない。索引の後半に並んだ記憶は**その日から存在しないのと同じ**になる - 制約は**行数ではなくバイト数**。日本語・中国語など非ASCIIは1文字3バイトなので、 行数の感覚と実バイトが大きくずれる **まず自分の環境の上限を実測すること。** 索引の末尾に一意な文字列（例 `ZZZ-CANARY-<乱数>`）を置き、 新しいセッションで「索引の最後の行は何か」と尋ねて答えられなくなるサイズを二分探索する。 上限は製品とバージョンで変わるので、他人の数字を信じない。 --- ## 手順1: 現状をバイトで測る ```bash # 索引の実バイト数（wc -c はバイト、wc -m は文字。バイトで測る） wc -c <索引ファイル> # 内訳を出す（タイトル / パス / 一行要約 / wikilink のどれが太いか） node -e " const fs=require('fs');const s=fs.readFileSync(process.argv[1],'utf8'); let t=0,p=0,n=0; for(const m of s.matchAll(/\[([^\]]+)\]\(([^)]+)\)/g)){ t+=Buffer.byteLength(m[1],'utf8'); p+=Buffer.byteLength(m[2],'utf8'); n++; } console.log('エントリ',n,'/ タイトル',t,'B / パス',p,'B / 総計',Buffer.byteLength(s,'utf8'),'B'); " <索引ファイル> ``` 内訳を出さずに削り始めない。**どこが太いかを知らずに削ると、情報を失う側から削ってしまう。** --- ## 手順2: レバーを「情報を失わない順」に適用する ### レバーA: 一行要約（hook）を索引から本体へ移す ← 最大かつ最優先 索引の行を `- [タイトル](file.md) — 一行要約` の形で書いていると、この要約が索引の **25〜30%** を占める。要約は**リンク先の本文**に `## 索引の要約` セクションとして置けばよい。 索引は**リンクの一覧に徹する**。実測で -25〜35%。 移送は必ず**追記のみ**で行い、本文の既存内容を書き換えない。 ### レバーB: 種別プレフィックスの二重持ちを外す 索引が `- [Feedback: 〇〇](feedback_xxx.md)` の形なら、**種別をタイトルとパスで二重に持っている**。 直後のパスが同じ種別（`feedback_` / `project_` など）で始まる場合に限りタイトル側を落とす。 パスから完全に復元できるので**情報量は変わらない**。実測で239エントリ、-2,310 B。 ```javascript // 直後のパスが同じ種別で始まる時だけ落とす。一致しない行は触らない。 const out = src.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (all, title, p) => { const m = title.match(/^(Feedback|Project|Reference|User)[:：]\s*/); if (!m) return all; if (!p.startsWith(m[1].toLowerCase() + '_')) return all; // 種別不一致は保守的に見送る const rest = title.slice(m[0].length); return rest.trim() ? `[${rest}](${p})` : all; }); ``` **実行前に、その種別プレフィックスを前提にパースしているツールが無いか必ず grep する。** ### レバーC: これ以上はやらない タイトルの短縮、パスの拡張子省略は「情報」か「リンク解決性」を失う。 そこまで必要なら、削るのではなく**索引を2階層にする**（滅多に使わない記憶を `INDEX-archive.md` に逃がし、索引からはそこへ1行だけリンクする）。 2階層化は読むとき1回余分に開くだけで、**黙って消えることは無い**。 --- ## 手順3: 検証は「変換ツール自身の assert」で済ませない 変換ツールの自己検証は**生産側と同じモデル**で測るので、壊れ方が同じなら両方すり抜ける。 **別実装の検証スクリプト**を用意し、素で読み直して照合する。 検証すべき不変条件: 1. before のエントリ（タイトル＋リンク先）が**1つも消えていない** 2. before の一行要約の**全文**が、リンク先本文に存在する 3. before の `[[wikilink]]` が、リンク先本文に存在する 4. after の索引に一行要約 / wikilink が**1つも残っていない** 5. 本文は**追記のみ**で変更されている（既存内容の削除・書き換えが無い） さらに、変換とは独立に自分でも突き合わせる: ```bash # リンク先ファイル名の集合が前後で完全一致するか grep -oE '\]\([^)]+\.md\)' | sed 's/](//;s/)//' | sort -u > /tmp/before.txt grep -oE '\]\([^)]+\.md\)' | sed 's/](//;s/)//' | sort -u > /tmp/after.txt diff /tmp/before.txt /tmp/after.txt && echo "リンク先集合 一致" # 記憶本体のファイル数が減っていないか ls <記憶ディレクトリ>/*.md | wc -l ``` **並行して別のセッションが動いていると、この最中に索引へ1行増えることがある。** 差分が「増加のみ・減少ゼロ」なら正常。減少が1件でもあれば止めて復元する。 --- ## 手順4: 恒久化 — ここが一番よく失敗する 索引は**1日あたり 100〜200 B のペースで育つ**（複数セッションが並行で追記するため）。 上限まで数KBしか無ければ猶予は3〜4週間しかない。夜間バッチ等で自動適用する。 ```bash # 冪等に。しきい値未満なら何もせず、追記0件なら1バイトも書かない node tools/memory-index-compact.mjs --move-hooks --apply --all-projects --min-bytes 20000 ``` ### 🚨 最大の罠: 「共有リポジトリに入れた ＝ 恒久化」ではない 定期タスクが起動するのは**そのマシンのローカルにあるコピー**であって、 リポジトリのデフォルトブランチではない。実害の実例: - 索引が上限を大きく超えて育っていた - 原因は、定期タスクが起動するローカルの `nightly-batch.ps1` に **該当ステップが1行も無かった**こと（ローカルが別作業のブランチのまま数十コミット遅れていた） - それでも定期タスクは `LastTaskResult 0` で毎晩「成功」していた。 **終了コード0は、その処理が実行された証拠にならない** **恒久化を主張する前に、そのマシンが実際に読むファイルを grep して該当ステップの存在を確認する。** ```bash grep -n "memory-index" <定期タスクが起動する実ファイルのパス> # 0件なら恒久化できていない ``` ### ローカルが別作業のブランチで dirty なときの安全な同期 他人／別セッションの作業を壊さずに、必要なファイルだけを更新する: ```bash # 1. 対象ファイルが本当にクリーンか確認する（dirty なら触らない） git status --porcelain -- # 2. git checkout は index を汚す（＝相手のステージングに混ざる）。平打ちコピーで入れる git show origin/: > # 3. 改行コード属性を尊重する。.gitattributes が eol=crlf のファイルは blob(LF) を戻す git show origin/: | sed 's/$/\r/' > # 4. BOM を保っているか確認する（BOM が消えると非ASCIIのスクリプトが化ける） head -c 3 | xxd ``` 同期したあと、**相手の dirty 件数が増えた分を必ず申し送る**。 --- ## 完了条件（これを満たすまで「直った」と言わない） 1. 索引のバイト数が上限を**下回る**（実測値を数字で言う） 2. 記憶本体のファイル数が**前後で不変**（1つも消していない） 3. リンク先ファイル名の集合が前後で**一致**（増加のみ許容、減少はゼロ） 4. 定期実行が起動する**実ファイル**に該当ステップが存在し、同じコマンドの dry-run が 「変更なし（冪等）」を返す 5. 上限までの**残りバイト数**を報告する。数百バイトしか無ければ「直っていない」に等しい （1日100〜200Bで育つので数日で再発する） --- ## 再発防止として記憶に書くこと - 新しい記憶を作るとき、索引の行は `- [タイトル](file.md)` **だけ**にする。 一行要約は本体の `## 索引の要約` に書く。種別プレフィックスは最初から付けない - 索引のバイト数を測る仕組みを持つ。**切り捨ては無言なので、測らないと壊れていることに気付けない** - 「デフォルトブランチに入れた」は各マシンで動く保証にならない。 マシンごとに実ファイルを確認する ---