AIエージェントの記憶インデックスが「読み込み上限で黙って切り捨てられる」問題の検出と恒久対策

この指示書が解く問題

AIコーディングエージェント（Claude Code / Cursor / Codex など）に長期記憶を持たせるとき、 MEMORY.md のような索引ファイル1本に全項目を並べる設計をよく採る。 この設計は、索引がセッション開始時に自動ロードされる限り必ず破綻する。

• ロード対象のファイルにはサイズ上限があり、超えた分は黙って捨てられる
• エラーも警告も出ない。索引の後半に並んだ記憶はその日から存在しないのと同じになる
• 制約は行数ではなくバイト数。日本語・中国語など非ASCIIは1文字3バイトなので、 行数の感覚と実バイトが大きくずれる

まず自分の環境の上限を実測すること。 索引の末尾に一意な文字列（例 ZZZ-CANARY-<乱数>）を置き、 新しいセッションで「索引の最後の行は何か」と尋ねて答えられなくなるサイズを二分探索する。 上限は製品とバージョンで変わるので、他人の数字を信じない。

---

手順1: 現状をバイトで測る

# 索引の実バイト数（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。

// 直後のパスが同じ種別で始まる時だけ落とす。一致しない行は触らない。
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. 本文は追記のみで変更されている（既存内容の削除・書き換えが無い）

さらに、変換とは独立に自分でも突き合わせる:

# リンク先ファイル名の集合が前後で完全一致するか
grep -oE '\]\([^)]+\.md\)' <before> | sed 's/](//;s/)//' | sort -u > /tmp/before.txt
grep -oE '\]\([^)]+\.md\)' <after>  | 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週間しかない。夜間バッチ等で自動適用する。

# 冪等に。しきい値未満なら何もせず、追記0件なら1バイトも書かない
node tools/memory-index-compact.mjs --move-hooks --apply --all-projects --min-bytes 20000

🚨 最大の罠: 「共有リポジトリに入れた ＝ 恒久化」ではない

定期タスクが起動するのはそのマシンのローカルにあるコピーであって、 リポジトリのデフォルトブランチではない。実害の実例:

• 索引が上限を大きく超えて育っていた
• 原因は、定期タスクが起動するローカルの nightly-batch.ps1 に 該当ステップが1行も無かったこと（ローカルが別作業のブランチのまま数十コミット遅れていた）
• それでも定期タスクは LastTaskResult 0 で毎晩「成功」していた。 終了コード0は、その処理が実行された証拠にならない

恒久化を主張する前に、そのマシンが実際に読むファイルを grep して該当ステップの存在を確認する。

grep -n "memory-index" <定期タスクが起動する実ファイルのパス>   # 0件なら恒久化できていない

ローカルが別作業のブランチで dirty なときの安全な同期

他人／別セッションの作業を壊さずに、必要なファイルだけを更新する:

# 1. 対象ファイルが本当にクリーンか確認する（dirty なら触らない）
git status --porcelain -- <path1> <path2>

# 2. git checkout は index を汚す（＝相手のステージングに混ざる）。平打ちコピーで入れる
git show origin/<default-branch>:<path> > <path>

# 3. 改行コード属性を尊重する。.gitattributes が eol=crlf のファイルは blob(LF) を戻す
git show origin/<default-branch>:<path.ps1> | sed 's/$/\r/' > <path.ps1>

# 4. BOM を保っているか確認する（BOM が消えると非ASCIIのスクリプトが化ける）
head -c 3 <path> | xxd

同期したあと、相手の dirty 件数が増えた分を必ず申し送る。

---

完了条件（これを満たすまで「直った」と言わない）

1. 索引のバイト数が上限を下回る（実測値を数字で言う）
2. 記憶本体のファイル数が前後で不変（1つも消していない）
3. リンク先ファイル名の集合が前後で一致（増加のみ許容、減少はゼロ）
4. 定期実行が起動する実ファイルに該当ステップが存在し、同じコマンドの dry-run が 「変更なし（冪等）」を返す
5. 上限までの残りバイト数を報告する。数百バイトしか無ければ「直っていない」に等しい （1日100〜200Bで育つので数日で再発する）

---

再発防止として記憶に書くこと

• 新しい記憶を作るとき、索引の行は - [タイトル](file.md) だけにする。 一行要約は本体の ## 索引の要約 に書く。種別プレフィックスは最初から付けない
• 索引のバイト数を測る仕組みを持つ。切り捨ては無言なので、測らないと壊れていることに気付けない
• 「デフォルトブランチに入れた」は各マシンで動く保証にならない。 マシンごとに実ファイルを確認する