「Memory index read limit」の対処 — Claude Code

Claude Codeがauto memoryの索引MEMORY.mdに書き込んだ直後に「Memory index is over its read limit」と出ることがあります。この場合、書き込みそのものは成功しています。問題は次回以降のセッション開始時です。MEMORY.mdは200行または25KBのどちらか先に達した時点までしか読み込まれず、そこから先の内容はセッションが始まるたびに黙って読み飛ばされます。

Memory index is over its read limitとは何のエラーか

表示される文言は次のとおりです。

Error: this write left the memory index at MEMORY.md at 214 lines, over its 200-line read limit.
The write succeeded, but everything past the limit is silently dropped each time the index is
loaded — entries at the end are already invisible to readers. Rewrite it to under 140 lines now:
keep one line per entry, move detail into topic files, and merge or drop stale entries.

Claude Codeはターミナルにバナーとしてこのエラーを出しません。書き込みが終わった後、Claudeへの応答として渡されるため、気づくとしたらトランスクリプト上だけになります。ユーザーが目にする前にClaude自身がこのエラーを受け取り、その場で索引を整理し直すことを前提にした設計です。

なぜ200行・25KBという上限があるのか

MEMORY.mdはauto memoryディレクトリ全体の索引です。ディレクトリの中にはMEMORY.md本体とトピックファイルが並びます。セッション開始時に自動で読み込まれるのは、そのうちMEMORY.mdの先頭200行、または先頭25KBのどちらか先に達した範囲だけです。詳細なメモをトピックファイルへ逃がし、MEMORY.md自体は「何がどこに保存されているか」の一覧に留めることで、コンテキストを圧迫せずに長期記憶を持たせる仕組みになっています。

上限を超えた状態で書き込みが行われると、その場では成功として扱われます。ただし次にセッションが始まったとき、200行目・25KBを超えた部分は読み込まれず、そこに書かれたエントリは実質的に存在しないのと同じ状態になります。特に末尾に追記され続けたエントリほど見えなくなりやすく、古いエントリを整理しないまま新しい学びを積み増していくと、直近に書いたはずの内容が次のセッションで参照されない事態につながります。

上限に近づいたとき・超えたときの違い

Claude Codeは、書き込み後にMEMORY.mdをこの2つの上限と照合し、状態に応じて反応を変えます。

エラーメッセージが指定する「140行未満」という目標値は、200行の上限そのものではなく、余裕を持たせた再発防止のためのラインです。ぎりぎり200行に収めても、次の書き込みで再びこのエラーが出るのを避けるための数値です。

何が測定対象で、何が対象外か

このエラーの計測対象は「実際にセッション開始時に読み込まれる内容」だけです。YAMLのfrontmatterやブロックレベルのHTMLコメントは、索引が読み込まれる前に取り除かれるため、行数・バイト数の計測には含まれません。以前のバージョンでは生のファイルをそのまま計測していたため、コメントやfrontmatterが多いだけで、実際に読み込まれる内容量は上限内に収まっているのにエラーになることがありました。

auto memoryディレクトリの中身

MEMORY.mdが肥大化する仕組みを理解するには、auto memoryディレクトリ全体の構造を押さえておくと近道です。ディレクトリには索引役のMEMORY.mdと、任意の数のトピックファイルが並びます。

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 簡潔な索引。毎セッション読み込まれる
├── project_aimedia.md # トピックファイル(必要時のみ読む)
├── feedback_xxx.md    # トピックファイル
└── ...

Claudeはセッション中、このMEMORY.mdを「どこに何が保存されているか」の道しるべとして使い、必要になったトピックファイルだけをその都度読みに行きます。上限エラーが起きるのは、この道しるべ自体に詳細を書き込みすぎて、索引としての役割を超えてしまったときです。

保存場所とスコープの注意点

auto memoryはマシンローカルな仕組みです。プロジェクトのパスはGitリポジトリから導出されるため、同じリポジトリ内であればworktreeやサブディレクトリをまたいでも1つのauto memoryディレクトリを共有します。逆に、別のマシンやクラウド環境とはファイルが共有されません。複数の環境で同じClaude Codeプロジェクトを行き来している場合、「あるマシンでは学習済みのはずなのに、別のマシンでは同じ説明を繰り返す」という体験はこのスコープの仕組みによるものです。保存場所自体はautoMemoryDirectory設定で変更できますが、これは置き場所の話であって、200行・25KBの上限とは別の設定です。

対処法

対処は基本的に、エラーメッセージが指示する内容とまったく同じです。

• Claudeに任せる: エラーを受け取ったClaude自身に、MEMORY.mdを1エントリ1行に圧縮させ、詳細はトピックファイルへ逃がし、古くなったエントリは統合または削除させる
• 自分で整理する: /memoryコマンドで自動memoryフォルダを開き、MEMORY.mdと各トピックファイルを直接編集する。中身はすべて素のMarkdownなので、エディタで自由に読み書きできる

MEMORY.md自体はautoMemoryDirectory設定で保存場所を変更できますが、200行・25KBの上限自体は変更できません。上限を回避する設定は存在せず、内容を圧縮する以外の解決策はない点に注意してください。

CLAUDE.mdとの違い

この上限が適用されるのはMEMORY.mdだけです。プロジェクトのCLAUDE.mdファイルは、行数に関わらず全文が読み込まれます。ただし、ファイルが長くなるほどコンテキストを消費し、指示への追従性が下がる点は共通の課題です。CLAUDE.md側は200行を目安に、パス限定ルールで必要なときだけ読み込ませる設計が推奨されています。auto memoryとCLAUDE.mdは「Claudeが自動で書くか、人間が書くか」の違いはあっても、長くなるほど扱いにくくなるという性質は同じです。

よくある質問

エラーが出た書き込みはやり直す必要がありますか

必要ありません。エラーメッセージにもあるとおり、書き込み自体はすでに成功しています。必要なのはMEMORY.mdを140行未満に圧縮する追加の編集だけです。

サブエージェントのauto memoryにも同じ上限が適用されますか

適用されます。メインの会話とは別に、サブエージェント自身がmemoryフィールドで持つauto memoryディレクトリにも同じMEMORY.mdの仕組みが使われ、同じ200行・25KBの上限が働きます。なお、メインの会話のauto memoryはサブエージェントには読み込まれません。例外は会話をフォークして起動するサブエージェントで、この場合は親の会話とシステムプロンプトをそのまま引き継ぎます。

auto memoryを無効化すればこのエラーは出なくなりますか

出なくなります。/memoryのトグル、またはCLAUDE_CODE_DISABLE_AUTO_MEMORY=1でauto memory自体を無効にできます。そうすればMEMORY.mdへの自動書き込みが発生しないため、本エラーも起きません。ただし、Claudeが学習した内容を次回セッションに引き継げなくなる点とのトレードオフです。

トピックファイルに分けた内容はセッション開始時に読み込まれますか

読み込まれません。200行・25KBの上限が適用されるのはMEMORY.mdだけで、トピックファイルはClaudeが会話の中で必要になったときに読みに行く対象です。CLAUDE.mdの@pathインポートは起動時に全文が読み込まれてコンテキストを消費しますが、auto memoryのトピックファイルはそれと違い、常時読み込まれるわけではありません。だからこそ「詳細はトピックファイルへ逃がす」がこのエラーの正しい対処になります。

何を書けと頼むとauto memoryに保存されますか

「pnpmを使う、npmは使わない」「APIのテストにはローカルのRedisが必要」のように、繰り返し使いたい判断や制約をClaudeに伝えると、Claudeがauto memoryへ保存します。プロジェクト全体のルールとして固定したい内容は、auto memoryではなくCLAUDE.mdに書くよう明示的に頼む使い分けが基本です。auto memoryは「Claudeが気づいたことを自動で書き留める」場所、CLAUDE.mdは「人間が意図して固定する」場所という役割の違いがあります。

実際にどこまで読み込まれたかを確認する方法はありますか

/contextコマンドで、そのセッションに実際に読み込まれたファイルを確認できます。MEMORY.mdが上限を超えた状態だと、超過分がこの一覧にも現れないため、「書いたはずのエントリが読み込まれていない」ことを/contextで直接確認できます。日頃から/memoryで中身を眺めるだけでなく、/contextで読み込み結果を照合しておくと、上限超過に早めに気づけます。

まとめ

「Memory index is over its read limit」は、MEMORY.mdが200行または25KBの読み込み上限を超えたときに出るエラーです。放置しても会話は止まりませんが、超過分は静かに見えなくなり続けるため、気づいた時点で整理しておくのが結局は近道です。書き込み自体は成功していますが、超過分は次回のセッション開始時に黙って読み飛ばされます。対処は1エントリ1行への圧縮、詳細のトピックファイルへの分離、古いエントリの統合・削除の3点に尽きます。v2.1.211より前のバージョンではfrontmatterやコメントまで計測に含まれていたため、意図せず上限に達しやすい状態でした。頻繁にこのエラーに当たる場合は、claude updateで最新のバージョンに更新してから整理に取りかかると無駄がありません。エラー全般の切り分けはClaude Codeでよくあるエラー10選も参考になります。