MEMORY.mdは管理が必要 AIエージェントの記憶を整理する方法

Claude Code や Codex を使っていると、頼んでいないのにこちらの好みを覚えていることがあります。前のセッションで「その言い回しはやめて」と伝えたことを、翌日には守っている。便利です。

ただ、その記憶に期限はありません。放っておけば、半年前の「次にやること」が、やり終えた後もそのまま残ります。そして古い記憶は、ある日から静かに邪魔を始めます。

以下はClaude Codeの自動メモリを軸に書きます。Codexのメモリは別の作りなので、違うところはそのつど分けて触れます。

記憶には、人が書くものとAIが書くものがある

Claude Code の公式ドキュメントは、セッションをまたいで知識を運ぶ仕組みを2つに分けています。

仕組み	誰が書くか	中身
CLAUDE.md	人	指示とルール
自動メモリ	AI	学びとパターン

前者は、人が書いて置いておく設定ファイルです。ビルドコマンド、命名規則、「必ずXする」の類。後者がこの記事の主題です。AIが自分で書き溜めるほう。

なお、この設定ファイルの名前はツールごとに違います。Claude Codeが読むのは CLAUDE.md、Codexが読むのは AGENTS.md です。Claude Codeは AGENTS.md を直接読みません。両方に同じルールを効かせる方法は後段で触れます。

Claude Codeの自動メモリは、記録するものを4種類に決めています。ファイル冒頭の type に入ります。

• user: 使う人の役割・専門・進め方の好み
• feedback: 受けた指摘と、確認が取れたやり方
• project: コードやgit履歴からは分からない、進行中の事情
• reference: 外部の資料の在りか

コードを読めば分かること、たとえば構成やファイルパスは書きません。CLAUDE.mdにすでに書いてあることも書きません。毎回何かを保存するわけでもなく、将来の会話で役に立つかどうかで決めているとされています。

Codexにも同じ発想の機能があります。公式ドキュメントによれば、置き場所は ~/.codex/memories/ で、既定ではオフです。設定から有効にします。

MEMORY.mdは索引。本体は読まれるまで開かない

ここが実務では大事なところです。メモリのディレクトリはこうなっています。

~/.claude/projects/<プロジェクト>/memory/
├── MEMORY.md           # 索引。1件1行
├── user_role.md        # メモリ1件
├── feedback_testing.md # メモリ1件
└── ...

MEMORY.mdは索引です。中身そのものではありません。1件につき1行の目次があるだけで、詳しい内容は個別のファイルに分かれています。

読み込まれ方に癖があります。セッション開始時に読まれるのはMEMORY.mdだけで、個別のファイルは読まれません。AIは索引を眺めて、いま必要そうなものだけを、そのつど開きに行きます。

図書館の目録と同じです。全部の本を抱えて歩くのではなく、背表紙の一覧だけ持って、必要な棚に取りに行く。

この設計のおかげで、メモリが何十件あっても、毎回のコンテキストを食うのは索引の分だけで済みます。

問題は、その索引に上限があることです。ただ、その前にひとつ。

索引は毎回コンテキストに乗る。古い行ごと

メモリと混同されやすいのがコンテキストです。別のものですが、つながっています。

コンテキストは一時記憶です。公式ドキュメントの言い方を借りると、Claude Codeのセッションは毎回まっさらなコンテキストウィンドウから始まります。会話が終われば消える。だから前回の続きは、そのままでは引き継がれません。

メモリは永続記憶です。ファイルとして残り、次のセッションでも生きています。

両者はここで出会います。セッションが始まると、MEMORY.mdの索引はコンテキストへ読み込まれます。人が書くCLAUDE.mdも同じで、公式ドキュメントは「セッション開始時にコンテキストウィンドウへ読み込まれ、会話とともにトークンを消費する」と書いています(訳です)。

つまりメモリは、毎回のコンテキストに種を撒く仕組みです。永続記憶が、一時記憶の初期値を決めている。

すると、古い記憶を放置したときに何が起きるかも決まります。索引に用済みの行が並んでいれば、それが毎回コンテキストに入ります。AIは前提として受け取るので、済んだ予定を未着手として扱ったり、別の場所へ移した情報を古いほうで探したりする。コンテキスト汚染と呼ばれるものは、こういう形で始まります。

量そのものも問題になります。公式ドキュメントは、指示を書くファイルを短く保つ理由をこう書いています。

長いファイルはより多くのコンテキストを消費し、指示への追従性を下げます。

行が増えるほど、一行あたりの重みは薄まる。 古い行は場所を取るだけでなく、生きている行の通りまで悪くします。捨てる作業に意味があるのは、ここです。

汚染は静かに進みます。エラーは出ません。返答が少しずつ的外れになるだけです。

記憶に期限はない。減らすのは人かAIの仕事

公式ドキュメントには、こう書かれています(英語なので訳しています)。

MEMORY.mdの先頭200行、または先頭25KBのうち、早く到達したほうが、すべての会話の開始時に読み込まれます。その閾値を超えた内容は、セッション開始時には読み込まれません。

上限より後ろに並んだ行は、そのセッションでは読み込まれません。ファイルからは消えないので、AIが必要に応じて開くことはできます。ただ、起動時に手渡される一覧からは外れる。

Claude Code自身も、この事態は避けようとします。MEMORY.mdへの書き込みのあとに大きさを測り、上限が近ければ短くするよう促す。超えていれば書き込みは通したうえでエラーを返し、索引の書き直しを求める。よくできた安全網です。そこまで手当てされている程度には、想定された事態だとも読めます。

もうひとつ、見落としやすい仕様があります。Claude Codeは古いセッションの記録を保持期間の設定に従って消しますが、メモリのファイルはその掃除の対象外です。AIの側が古い項目をまとめたり消したりすることはありますが、期限が来たら消える仕組みは無い。そこが履歴との違いです。

つまり、こういう構造になっています。

• 記憶は、役に立つと判断されたときに足される
• 古い記憶は期限では消えない
• 索引の上限より後ろは、起動時に読み込まれない

3つ目が問題になるのは、索引が育ってからです。どの行が境界の外に出るかは並び順で決まります。裏返せば、並び順は人が決められる。整理する側に主導権があるのは、ここです。

記憶は4通りに腐る

私たちもこのサイトの制作で、Claude CodeとCodexを併用しています。先日、メモリを一度棚卸ししました。15件を残し、4件を参照されない場所へ退避させています。

退避の理由が、4件とも違いました。腐り方には型があります。

1. 賞味期限切れ。 「次に書くブログのテーマ」というメモが2件。どちらも記事はとっくに公開済みでした。やり終えた瞬間に嘘になるタイプです。しかも書いた側は気づけません。

2. 二重管理。 メール送信の設定に関するメモが、リポジトリの docs/ にある文書と同じ内容でした。片方を直してもう片方を忘れると、どちらが正しいのか誰にも分からなくなります。

3. 粒度が粗い。 サイトの構成・技術選定・好みが1ファイルに全部入っていました。索引の1行では中身を言い表せず、結果として引くに引けない。分けるか、リポジトリへ移すかの二択でした。

4. 置き場所が違う。 これが一番やっかいでした。Codexにも守らせたいルールを、Claudeのメモリに書いていた。Codexは ~/.claude/ のメモリを自動では参照しません。別の製品なので当たり前なのですが、書いた側は伝えたつもりになっています。

並べてみると、性質が違います。1だけが時間で古くなったもので、書くときの注意では防げません。残る3つは置き方の問題です。2は正本がどちらか決まっていない状態、3と4は最初から置き場所と粒度を間違えていた。書いた時点で防げたはずのものが、動いているように見えて残っていました。

共通しているのは、書いた本人には見えないという点だけです。だから、あとから見返す機会を作るしかありません。

守らせたいルールは、記憶ではなくリポジトリに置く

では、どう整えるか。指針はOpenAI自身が書いています。Codexのドキュメントの一文です(こちらも訳です)。

チームに必要なガイダンスは、AGENTS.md か、リポジトリに入れた文書に置いてください。メモリは、思い出しを助ける層として扱い、必ず適用されるべきルールの唯一の出所にはしないでください。

メモリは補助であって、正本ではない。ここが軸になります。

同じドキュメントはさらに踏み込んで、メモリのファイルを「生成された状態」と呼び、手で編集することを主要な制御手段にするなと書いています。一方のClaude Codeは、人が読み書きできるマークダウンとして扱う前提です。同じ「メモリ」でも思想が分かれるので、混ぜて考えないほうが安全です。

私たちが採った切り分けはこうです。

置き場所	入れるもの
リポジトリの AGENTS.md / docs/	両方のツールに効かせたいルール・手順・事実
自動メモリ	判断の癖や好みなど、コードからは読み取れないもの
アーカイブ	役目は終えたが、経緯を追えるよう残すもの

1行目には前提があります。AGENTS.md に書いただけでは、Claude Codeには届きません。前述のとおり CLAUDE.md からの読み込みかシンボリックリンクが要ります。ここを繋がないまま「両方に書いたつもり」になるのが、さきほどの4番目です。

3つ目が、地味ですが続けるコツです。消すのではなく、参照されない場所へ動かす。捨てる決断のハードルが下がるので、整理が習慣になります。

月に一度、索引から棚卸しする

毎回すべてのメモリを読み返す必要はありません。まず索引を眺め、引っかかった行だけ本体を開く。二段階にすれば数分で終わります。

索引を見るときの目印は3つです。

1つ目。 「次に」「予定」「後で」が入っている行。もう済んでいないか確かめます。済んでいたら消すか、動かす。

2つ目。 リポジトリの文書と同じことを言っている行。正本はリポジトリ側なので、メモリからは消します。

3つ目。 索引そのものの大きさ。起動時に読まれるのは先頭200行か25KBまでで、先に来たほうで打ち切られます。行数だけ見ていると、1行が長い場合に容量のほうで先に頭打ちになります。両方見てください。

そのうえで、本体を開くのは次の場合です。索引の1行だけでは中身を言い表せていない行、書かれた時期が古そうな行、内容が他と重複していそうな行。3番目の「粒度が粗い」は、索引を眺めているだけでは見つかりません。

中身の確認はコマンドから入れます。Claude Codeなら /memory でメモリのフォルダを開けます。いま何が読み込まれているかは /context で見えます。Codexは /memories でそのチャットの扱いを切り替えられます。

このブログを作っているプロジェクトのMEMORY.mdは、いま19行、2.8KBです。まだ上限には遠いのですが、余裕があるうちに癖にしておくほうが楽だと考えています。

AIに何を覚えさせるかは、よく語られます。書き方の記事もたくさんあります。捨て方の話は、ほとんど見かけません。けれど記憶が増え続ける仕組みである以上、捨てる側の運用がなければ、古い情報を根拠に判断される場面も出てきます。

次にAIの返答が妙に的外れだと感じたら、プロンプトを疑う前に索引を開いてみてください。半年前に書かせた一行が、まだ効いているかもしれません。