Claude Code の開発効率を支える「MEMORY.md」の役割と活用方法

2026年5月30日 H.Ueda

今回は、Nick Babich 氏による記事 MEMORY.md for Claude Code projects を参考に、Claude Code におけるコンテキスト管理の肝となる MEMORY.md について自分なりに整理してみました。

ちゃんと理解しないとね。

Claude Code を使い込んでいる方の多くは、プロジェクトのルートに置く CLAUDE.md の重要性を既にご存知かと思います。AI に対して「どのように振る舞うべきか」「プロジェクトのコーディング規約は何か」を伝えるための、いわば「運用マニュアル」のようなファイルですね。

しかし、大規模なプロジェクトや長期的な開発において、もう一つの鍵となるのが MEMORY.md です。このファイルの役割を理解することで、Claude Code のパフォーマンスをより引き出せるようになるかと思います。

MEMORY.md とは何か

一言で言えば、MEMORY.md はプロジェクトに関する「動的な記憶のインデックス」です。

CLAUDE.md が「ルール（静的）」を定義するのに対し、MEMORY.md は開発の過程で蓄積される「知見やコンテキスト（動的）」を管理するために使われます。Claude Code はセッションを開始する際、このファイルを読み込むことで「以前どのような議論があったか」「特定のバグにどう対処したか」といった過去の経緯を把握します。

配置場所とディレクトリ構成

CLAUDE.md がプロジェクトのルート直下に置かれるのに対し、MEMORY.md は専用のディレクトリ内に配置されるのが一般的です。

~/.claude/projects/<project_name>/memory/
├── MEMORY.md             # 全セッションで読み込まれるメインのインデックス
├── debugging.md          # 特定のデバッグ手順や注意点
├── design-conventions.md  # UI/UX に関する決定事項のメモ
└── ...                   # その他、AIが自動生成するトピック別ファイル

このようにディレクトリを分ける理由は、プロジェクトが成長するにつれて、保持すべき情報量が増えていくからです。すべての情報を一つのファイルに詰め込むのではなく、トピックごとにファイルを切り出し、MEMORY.md をその「目次（インデックス）」として機能させる構成が推奨されています。

Claude Code が情報を読み込む仕組み

Claude Code がセッション開始時に MEMORY.md をどのように扱うか、その流れを図解すると以下のようになります。

graph TD
    A[Claude Code セッション開始] --> B{memory/MEMORY.md の確認}
    B -- 存在する場合 --> C[最初の200行 または 25KB を読み込む]
    C --> D[インデックス情報を元に必要に応じて別ファイルを参照]
    D --> E[コンテキストを保持した状態で作業開始]
    B -- 存在しない場合 --> F[最小限のコンテキストで開始]

重要なポイントは、「最初の 200 行、または 25 KB」 という読み込み制限がある点です。これを超える情報は無視されてしまう可能性があるため、MEMORY.md 自体は常に簡潔に保ち、詳細な内容は別ファイルにリンクさせるような書き方が理想的と言えます。

CLAUDE.md と MEMORY.md の使い分け

この 2 つのファイルは、役割が明確に異なります。実際の運用では、以下のような基準で使い分けるのがスムーズかと思います。

特徴	CLAUDE.md	MEMORY.md
役割	運用ルール・振る舞いの定義	知識の蓄積・過去の経緯の記録
主な内容	技術スタック、命名規則、出力スタイル	デバッグ記録、設計判断、進捗状況
管理主体	主に人間（開発者）	主に AI（自動更新）
性質	静的（一度決めたらあまり変えない）	動的（作業のたびに更新される）

たとえば、CLAUDE.md には「TypeScript を使い、サーバーコンポーネントを優先すること」といった普遍的なルールを記述します。一方で MEMORY.md には「〇〇モジュールのリファクタリング時に発生した型エラーの解決策」といった、その時々の知見を残していくイメージですね。

AI による自動記憶（autoMemoryEnabled）

多くの場合、MEMORY.md の更新を人間がいちいち手動で行うのは大変です。そこで活用したいのが autoMemoryEnabled 設定です。

Claude Code の設定でこれを有効にすると、AI エージェントが作業中に「これは将来のために覚えておくべき重要な情報だ」と判断した内容を、自動的に memory/ ディレクトリ配下に保存してくれるようになります。

{
  "autoMemoryEnabled": true
}

この機能をオンにしておくと、たとえば複雑なデバッグを終えた後に、その教訓を AI が自ら debugging.md に書き加え、次回のセッションで同じミスを繰り返さないよう備えてくれます。

まとめ

MEMORY.md を活用することで、Claude Code は単なる「コードを書くツール」から、プロジェクトの文脈を深く理解した「頼れるパートナー」へと進化します。

ルールは CLAUDE.md に。
経緯や知見は memory/MEMORY.md に。

この 2 つを適切に使い分けることで、長期間のプロジェクトでも AI のコンテキストが散逸せず、一貫性のある開発が続けられるようになるはずです。もし「AI がプロジェクトの詳細をすぐに忘れてしまう」と感じている方がいれば、まずは memory/ ディレクトリを作成して、オートメモリー機能を試してみるのが良いかもしれません。

MicroArchitectures

H.Ueda

Programmer

ブログ