Claude Code の MEMORY.md とは何か？Auto-Memory の仕組みと使い方を完全解説

SHARE

Claude Code を使っていて、こんな経験はないでしょうか。

昨日まで続けていた作業を今日また始めようとしたら、Claude が何も覚えていない。プロジェクトの構成を説明し直して、コーディングの好みを伝え直して、「あの難しいバグ、結局どう直したんだっけ」という話を一から始める。毎回ゼロリセット。

Anthropic がリリースした Auto-Memory という機能は、まさにこの問題を解決するために作られました。Claude Code に自前のメモ帳を持たせる仕組みです。そのメモ帳が MEMORY.md というファイルです。

私はこの機能を実際のプロジェクトでテストしました。何を記録するのか、どこに保存されるのか、セッションをまたいで本当に機能するのかを確かめるために。この記事では、テスト結果を交えながら Auto-Memory の全貌を解説します。

目次

Auto-Memory の仕組み

Auto-Memory はデフォルトで有効になっています。Claude Code を最新版にアップデートすれば、設定不要でその日から動き始めます。

あなたが作業している間、Claude は静かに観察しています。どんな情報をメモするかを Claude 自身が判断し、次のカテゴリで記録します。

  • プロジェクトのパターン：ビルドコマンド、テストの流れ、コードベースの構造
  • デバッグの知見：難しいバグの解決策と根本原因
  • アーキテクチャのメモ：重要なファイル、モジュール間の関係、中核となる抽象化
  • あなたの好み：コミュニケーションスタイル、作業習慣、使うツール

これらは手動で入力する必要はありません。Claude が自分で判断して書き残します。

保存場所

Auto-Memory のファイルは以下の場所に保存されます。

~/.claude/projects/<project>/memory/

<project> の部分は Git リポジトリのルートパスに基づきます。同じリポジトリ内のサブディレクトリはすべて同じメモリディレクトリを共有します。

Git ワークツリーを使っている場合は、各ワークツリーごとに別々のメモリディレクトリが作られます。Git リポジトリの外では、カレントディレクトリがフォールバックとして使われます。

フォルダの中身は次のような構成になります。

~/.claude/projects/<project>/memory/
├── MEMORY.md # 毎セッション冒頭に読み込まれるメインインデックス
├── debugging.md # デバッグ履歴と繰り返し発生する問題のメモ
└── ... # Claude が必要に応じて作成するトピック別ファイル

MEMORY.md がメインのエントリポイントです。Claude が保存したすべての情報のインデックスとして機能し、新しいセッション開始時に自動的に読み込まれる唯一のファイルです。

200行制限について

Claude のシステムプロンプトに読み込まれるのは MEMORY.md の先頭 200 行だけです。これはとても重要な仕様です。

MEMORY.md が長くなってきたら、Claude は詳細なメモを debugging.md や api-conventions.md といった別のトピックファイルに移し、メインファイルを短くコンパクトに保つことが期待されています。トピックファイルは起動時には読み込まれず、Claude がセッション中に必要と判断したときだけ参照します。

実際の流れはこうなります。

  1. 新しいセッションが始まり、MEMORY.md の先頭 200 行が読み込まれる
  2. 特定のデバッグ履歴が必要になったら、Claude が debugging.md をその場で読む
  3. 新しい知見を得たら、MEMORY.md または関連するトピックファイルに書き込む

テストしていて気づいたのですが、これはバックグラウンドで動くプロセスではありません。セッション中に Claude がメモリディレクトリを読み書きする様子をリアルタイムで確認できます。

CLAUDE.md と MEMORY.md の違い

「CLAUDE.md があるのになぜ MEMORY.md が必要なのか」と思うのではないでしょうか。

CLAUDE.md は Claude Code の当初からある設定ファイルです。あなたが Claude に守ってほしいルール、好み、指示を書いておく場所です。

MEMORY.md はまったく別の役割を持ちます。

あなたが書くものではありません。Claude が自分で作成し、自分で更新するファイルです。

一番シンプルな説明はこうです。CLAUDE.md はあなたが Claude に渡す指示書、MEMORY.md は Claude 自身のメモ帳。MEMORY.md には Claude が作業を通じて学んだことが蓄積されます。あなたの好み、繰り返し現れるプロジェクトのパターン、うまくいったコマンド、失敗したコマンド、過去のセッションで役立ったメモなどです。

まとめると次の通りです。

ファイル誰が書くか役割
CLAUDE.mdあなたClaude への指示・ルール
MEMORY.mdClaude 自身作業を通じて学んだ知識のメモ

この 2 つが揃うと、セッション冒頭の Claude がかなり「知っている状態」で始まります。

Claude Code のメモリ階層

Claude Code は CLAUDE.md と MEMORY.md だけで動いているわけではありません。実際にはレイヤー構造になっています。

基本原則は「より具体的な指示が優先される」です。プロジェクトレベルの CLAUDE.md は、ユーザーのグローバルメモリより優先されます。Auto-Memory もプロジェクトレベルにスコープされているため、特定のプロジェクト内での作業にのみ適用されます。

もう一つ覚えておくと便利なのが CLAUDE.local.md です。このファイルは自動的に .gitignore に追加されるため、サンドボックス URL やローカルテストのメモなど、チームと共有したくないプライベートな設定を書く場所として使えます。

新しいセッション開始時、Claude は以下のレイヤーから文脈を読み込みます。

  1. 組織のポリシー（存在する場合）
  2. プロジェクトレベルの CLAUDE.md（チーム共有の指示）
  3. 個人の ~/.claude/CLAUDE.md（個人の好み）
  4. MEMORY.md の先頭 200 行（Claude が蓄積したメモ）

つまり最初のプロンプトを打つ前から、Claude はプロジェクトの慣習、あなたの好み、前回までのセッションで学んだ文脈をすでに持った状態で動いています。

実際に動かしてみる

実際のプロジェクトで試した手順を紹介します。

1. Claude Code をアップデートする

Auto-Memory を使うには最新版が必要です。

claude update

バージョンを確認します。2.1.76 以降であれば対応しています。

claude --version

2. テスト用プロジェクトを作成する

mkdir test-claude-memory && cd test-claude-memory
git init

ここで git init が重要です。Claude Code はメモリの保存場所を Git リポジトリのルートで決めています。Git リポジトリでないプロジェクトでは、プロジェクトレベルのメモリは期待通りに機能しません。

Claude Code を起動します。

claude

3. 実際に作業してみる

Auto-Memory はセッションを開いただけではファイルを作りません。何かを一緒に作業してから、Claude がメモを取り始めます。私は LangChain で RAG パイプラインを作るよう指示しました。

LangChain でシンプルな RAG パイプラインを作って

作業が進んだあと /memory コマンドを実行すると、Auto-Memory がオンになっていること、そして 3 つのオプションが表示されます。

Option 1: User Memory グローバルな ~/.claude/CLAUDE.md を開きます。すべてのプロジェクトをまたいで適用したい個人の好みや習慣を書いておく場所です。あなたが管理するファイルです。

Option 2: Project Memory 現在のプロジェクトの CLAUDE.md を開きます。コーディング規約やアーキテクチャの決定など、チーム全体で共有したいコンテキストが入ります。ソース管理にコミットできます。これもあなたが書き管理するファイルで、Claude は読むだけです。

Option 3: Open Auto-Memory Folder Claude が自分で管理するメモリディレクトリを開きます。MEMORY.md とトピック別ファイルがここにあります。

4. Auto-Memory のオン/オフを切り替える

/memory コマンドを実行すると Auto-memory: on という行が表示されます。その行を選択してエンターを押すだけで Auto-memory: off に切り替わります。

探索的な作業をしていて記録に残したくないとき、あるいは一度きりのセッションを実行するときに便利です。

新しいプロジェクトを始めたら /memory コマンドを最初に実行する習慣をつけておくと良いと思います。トグルの状態を確認しながら、メモリが積み上がる前にファイルの保存場所を把握できます。

5. セッションをまたいでテストする

本当に機能しているかを確かめるために、Claude Code を完全に閉じて新しいセッションを起動し、コンテキストを一切渡さずにこう聞きました。

このプロジェクトについて何を知っている？

Claude は前のセッションで MEMORY.md に書き込んだ内容をもとに、プロジェクトの詳細な概要を返してきました。これが Auto-Memory の設計通りの動作です。

Auto-Memory を制御する方法

Auto-Memory はデフォルトでオンですが、状況に応じてオフにしたいケースもあります。

特定のプロジェクトだけオフにする

プロジェクトの設定ファイルに以下を追加します。

// .claude/settings.json
{ "autoMemoryEnabled": false
}

このプロジェクトだけ Auto-Memory が無効になり、他のプロジェクトには影響しません。

すべてのプロジェクトでオフにする

ユーザーレベルの設定ファイルに同じ設定を書きます。

// ~/.claude/settings.json
{ "autoMemoryEnabled": false
}

グローバルに無効化されます。

CI 環境で強制オフにする

CI パイプラインや自動化環境で Claude Code を使う場合は、環境変数が最も確実です。

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 # 強制オフ
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 # 強制オン

この環境変数は /memory トグルや settings.json の設定よりも優先されます。CI セッションで意図せずメモが蓄積されるのを防ぐには、これが一番確実です。

メモリファイルを直接編集する

MEMORY.md はただのマークダウンファイルなので、いつでも開いて編集できます。

/memory コマンドから選択してシステムエディタで開くか、ターミナルから直接アクセスすることもできます。

open ~/.claude/projects/<your-project>/memory/MEMORY.md

古くなったメモを消したり、整理し直したりするのに使えます。プロジェクトが大きく変わったタイミングで見直すと、Claude の文脈理解がより正確になります。

TL;DR

  • Auto-Memory は Claude Code がセッションをまたいで文脈を保持するための仕組み。デフォルトオン、設定不要
  • MEMORY.md は Claude 自身が書き更新するメモ帳。あなたが書く CLAUDE.md とは別物
  • 新しいセッション開始時に読み込まれるのは MEMORY.md の 先頭 200 行のみ。詳細はトピック別ファイルに切り出される
  • メモリの保存場所は ~/.claude/projects/<project>/memory/。Git リポジトリである必要がある
  • /memory コマンドでトグル・確認・ファイルへのアクセスがすべてできる
  • プロジェクト単位・グローバル・CI 環境変数で細かく制御可能

前の記事

Claudeを使えば何でも100倍速く学べる。その6つのプロン…

次の記事

安いモデルがOpus級に賢くなるClaude Advisor …