Claude Code memoryの三層構造 — CLAUDE.md・自動メモリ・セッションの使い分け
Claude Codeのmemoryは、自分で書くCLAUDE.md、Claudeが自分で記録する自動メモリ、毎回リセットされるセッションの三層です。読み込まれ方・保存場所・使い分けの判断基準をまとめます。
Claude Codeのmemoryとは — 三層の全体像
Claude Codeのmemory(メモリ)とは、セッションをまたいで知識を引き継ぐ仕組みの総称です。Claude Codeの各セッションはまっさらなコンテキストウィンドウから始まるため、何もしなければ前回の会話で伝えた規約や知見はすべて消えます。これを補うのが、あなたが書く「CLAUDE.md」と、Claudeが自分で書き溜める「自動メモリ(auto memory)」という2つの永続化機構です。
本記事では、この2つに「セッション(コンテキストウィンドウそのもの)」を加えた三層モデルで、それぞれの読み込まれ方・保存場所・使い分けの判断基準を解説します。
| 層 | 誰が書くか | 永続性 | セッション開始時の読み込み |
|---|---|---|---|
| CLAUDE.md | 誰が書くかあなた(人間) | 永続性永続(gitでチーム共有可) | セッション開始時の読み込み全文が読み込まれる |
| 自動メモリ | 誰が書くかClaude自身 | 永続性永続(マシンローカル) | セッション開始時の読み込みMEMORY.md の先頭200行または25KBまで |
| セッション | 誰が書くか会話の流れ | 永続性揮発(終了・圧縮で消える) | セッション開始時の読み込みなし(毎回ゼロから) |
第1層: CLAUDE.md — 自分で書く永続的な指示
CLAUDE.mdは、プロジェクトの規約・ビルドコマンド・アーキテクチャ背景をClaudeに毎セッション伝えるためのMarkdownファイルです。配置場所によってスコープが変わり、組織全体・ユーザー・プロジェクト・ローカルの4段階が用意されています。
4つの配置場所とスコープ
CLAUDE.mdは複数の場所に置け、広いスコープから順に読み込まれて連結されます。後から読まれる(=作業ディレクトリに近い)指示ほどコンテキストの後方に置かれるため、プロジェクトの指示が個人の指示の後に来る構造です。
| スコープ | 場所 | 用途 | 共有範囲 |
|---|---|---|---|
| 管理ポリシー | 場所macOSは /Library/Application Support/ClaudeCode/CLAUDE.md、Linux/WSLは /etc/claude-code/CLAUDE.md | 用途組織全体のコーディング標準・セキュリティ方針 | 共有範囲組織内の全ユーザー |
| ユーザー | 場所~/.claude/CLAUDE.md | 用途全プロジェクト共通の個人の好み | 共有範囲自分のみ |
| プロジェクト | 場所./CLAUDE.md または ./.claude/CLAUDE.md | 用途チーム共有の規約・ワークフロー | 共有範囲gitを通じてチーム全員 |
| ローカル | 場所./CLAUDE.local.md | 用途個人のプロジェクト固有メモ(.gitignore 推奨) | 共有範囲自分のみ |
複数のファイルが見つかった場合は上書きではなく連結されます。同じ動作について矛盾する指示が複数ファイルにあると、Claudeはどちらかを任意に選ぶ可能性があるため、定期的な棚卸しが要ります。
ディレクトリ走査と遅延読み込み
Claude Codeは起動時に、作業ディレクトリからファイルシステムの上位へ向かって各ディレクトリの CLAUDE.md と CLAUDE.local.md を探します。foo/bar/ で起動すれば foo/bar/CLAUDE.md と foo/CLAUDE.md の両方が全文ロードされる仕組みです。
一方、作業ディレクトリより下のサブディレクトリにあるCLAUDE.mdは起動時には読み込まれません。Claudeがそのディレクトリ内のファイルを読んだときに初めてオンデマンドで読み込まれます。モノレポで他チームのCLAUDE.mdまで拾ってしまう場合は、settings.jsonの claudeMdExcludes にglobパターンを書いて除外できます。パッケージ単位での権限スコープの絞り方まで含めた設計はClaude Codeモノレポ設計 — CLAUDE.md階層とパッケージ単位の権限スコープで扱っています。
/initでの生成と「効く指示」の書き方
ゼロから書く必要はなく、/init コマンドでClaudeにコードベースを分析させて雛形を生成できます。既にCLAUDE.mdがある場合は上書きせず改善提案になります。
/init環境変数 CLAUDE_CODE_NEW_INIT=1 を設定すると対話型のセットアップフローに切り替わり、CLAUDE.mdに加えてSkillsやHooksの初期構成まで提案を受けられます。
書き方の要点は3つあります。第一に1ファイル200行以下が目安です。CLAUDE.mdは長さに関係なく全文が毎セッション読み込まれるため、長いほどコンテキストを消費し、指示の遵守率も下がります。第二に「コードをきれいに書く」ではなく「インデントは2スペース」のように検証可能な具体性で書くこと。第三にMarkdownの見出しと箇条書きで構造化することです。なお、ブロックレベルのHTMLコメント(<!-- ... -->)はコンテキスト注入前に除去されるので、人間向けのメンテナンスメモをトークン消費なしで残せます。実践的な記述パターンはCLAUDE.mdの実装パターン10選で扱っています。
@インポートとAGENTS.mdの取り込み
CLAUDE.mdは @path/to/file 構文で他のファイルをインポートできます。相対パスはインポート元ファイル基準で解決され、インポート先からさらに再帰的にインポートする場合の深さは最大4ホップまでです。インポートされたファイルも起動時に展開されてコンテキストに入るため、分割は整理には役立ちますがコンテキスト削減にはなりません。
他のコーディングエージェントと共通の AGENTS.md を使っているリポジトリでは注意が必要です。Claude CodeはAGENTS.mdを直接読まないため、@AGENTS.md と書いた1行のCLAUDE.mdを作るか、シンボリックリンクで橋渡しします。
.claude/rules/によるパス別ルール
指示が増えてきたら、.claude/rules/ ディレクトリにトピック別のMarkdownを置いて分割できます。frontmatterに paths を書いたルールは、パターンに一致するファイルをClaudeが読んだときだけ読み込まれるため、常時のコンテキスト消費を抑えられます。
---
paths:
- "src/api/**/*.ts"
---
# API開発ルール
- すべてのAPIエンドポイントに入力検証を入れる
- エラーレスポンスは標準形式に従うpaths のないルールは起動時に .claude/CLAUDE.md と同じ優先度で読み込まれます。~/.claude/rules/ に置けばユーザーレベルのルールとして全プロジェクトに適用され、プロジェクトルールより先に読み込まれる(=プロジェクト側が後勝ちで効きやすい)順序です。
第2層: 自動メモリ — Claudeが書き溜める学習ノート
自動メモリ(auto memory)は、Claudeが作業中に得た学び — ビルドコマンド、デバッグの知見、あなたの修正から読み取った好み — を自分でMarkdownに記録し、次のセッションへ持ち越す機能です。Claude Code v2.1.59以降で利用でき、既定で有効になっています。
CLAUDE.mdとの違いは「誰が書くか」です。CLAUDE.mdはあなたが意図を持って書く指示、自動メモリはClaudeが「将来の会話で役立つか」を自分で判断して書き残すノートで、毎セッション必ず何かを保存するわけではありません。
保存場所とファイル構成
自動メモリはプロジェクトごとに ~/.claude/projects/<project>/memory/ に保存されます。<project> はgitリポジトリから導出されるため、同じリポジトリ内のworktreeやサブディレクトリはすべて1つの自動メモリを共有します。
~/.claude/projects/<project>/memory/
├── MEMORY.md # 簡潔なインデックス。毎セッション読み込まれる
├── debugging.md # デバッグパターンの詳細メモ
├── api-conventions.md # API設計の決定事項
└── ... # Claudeが作るその他のトピックファイル自動メモリはマシンローカルで、別のマシンやクラウド環境とは共有されません。保存先を変えたい場合はsettings.jsonの autoMemoryDirectory に絶対パス(または ~/ 始まり)を指定します。
読み込みの仕組み — 先頭200行・25KBの上限
セッション開始時に読み込まれるのは MEMORY.md の先頭200行、または先頭25KBの早く達した方までです。それを超えた内容は起動時には読み込まれないため、Claudeは詳細を debugging.md のようなトピックファイルへ逃がし、MEMORY.md をインデックスとして簡潔に保ちます。トピックファイルは起動時には読まれず、必要になった時点で通常のファイルツールを使ってオンデマンドで参照されます。
この200行/25KB制限が適用されるのは MEMORY.md だけで、CLAUDE.mdは長さに関係なく全文読み込まれる、という非対称も覚えておく価値があります。セッション中に画面へ「Writing memory」「Recalled memory」と表示されたら、Claudeがこのディレクトリを読み書きしているサインです。
オン・オフの切り替えと中身の監査
自動メモリの状態確認と管理は /memory コマンドに集約されています。現在のセッションに読み込まれているCLAUDE.md・CLAUDE.local.md・rulesファイルの一覧表示、自動メモリのオン/オフ切り替え、メモリフォルダを開く導線がここにあります。
/memoryプロジェクト単位で無効化するならsettings.jsonに "autoMemoryEnabled": false を書きます。環境変数で切る方法もあります。
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1中身はすべてプレーンなMarkdownなので、いつでも自分で開いて編集・削除できます。会話中に「常にnpmではなくpnpmを使うことを覚えておいて」と頼むと自動メモリに保存され、「これをCLAUDE.mdに追記して」と頼めばCLAUDE.md側に書かれる、という振り分けです。なおサブエージェントにも、それぞれ独自の自動メモリを持たせる設定があります。
第3層: セッション — 圧縮と再起動で何が残るか
セッション(コンテキストウィンドウ)は、三層の中で唯一永続化されない層です。会話の中で口頭で伝えた指示はそのセッション限りで、新しいセッションを開けば消えます。
見落としやすいのがコンテキスト圧縮(/compact)との関係です。圧縮後の挙動はファイルの場所で異なります。
- プロジェクトルートのCLAUDE.mdは圧縮を生き残ります。/compact後にディスクから再読込され、セッションに再注入されます
- サブディレクトリのネストされたCLAUDE.mdは自動では再注入されません。次にそのディレクトリのファイルを読んだときに再ロードされます
- 会話の中だけで与えた指示は再注入されず、失われます
「圧縮したら指示を忘れた」と感じたら、その指示は会話にしか存在していなかった可能性が高いです。セッションをまたいで残したい指示はCLAUDE.mdへ、Claudeに学ばせたい知見は自動メモリへ昇格させる運用が解になります。
もう1つの仕様として、CLAUDE.mdの内容はシステムプロンプトの一部ではなく、その後に続くユーザーメッセージとして渡されます。つまり厳密な遵守は保証されません。コミット前のテスト実行のように特定のタイミングで必ず走らせたい処理はHooksに、システムプロンプトレベルの指示が必要な自動化には --append-system-prompt フラグに役割を分けるのが現行仕様に沿った設計です。
どの層・どの仕組みに置くか — 判断基準
置き場所は「誰が書くか」「いつ効いてほしいか」「強制力が要るか」の3つで決まります。memoryの三層に加えて、隣接する置き場所としてsettings.json(hooks・権限などの機械可読設定)とSkills(呼び出し時にだけ読まれる手順書)があるため、合わせて判断します。
- 機械的に必ず実行・ブロックしたい → settings.jsonのhooks / permissions(コンテキストでは強制できない)
- 全セッションで常に守ってほしい方針・規約 → CLAUDE.md
- 特定のファイル群でだけ効かせたいルール →
.claude/rules/のpathsスコープ - 手順型のノウハウ・テンプレート → Skills
- Claudeが作業から学んだ知見 → 自動メモリ(基本はClaudeに任せる)
- 今回だけの一時的な指示 → セッション(会話)で十分
| 情報の種類 | 置き場所 | 理由 |
|---|---|---|
| コミット規約・命名規則 | 置き場所プロジェクトのCLAUDE.md | 理由全セッション常時+チーム共有 |
| 個人のツールの好み | 置き場所~/.claude/CLAUDE.md | 理由全プロジェクトに効く個人設定 |
| 保存後のフォーマッタ自動実行 | 置き場所hooks(settings.json) | 理由強制力が必要 |
| API層だけのルール | 置き場所.claude/rules/ + paths | 理由該当ファイル使用時のみロード |
| 記事執筆・リリースの手順書 | 置き場所Skills | 理由常時は不要、呼び出し時のみ |
| 「このrepoはpnpm」等の学習事項 | 置き場所自動メモリ | 理由Claudeの自己学習に向く |
アンチパターン1: 全部CLAUDE.mdに詰め込む
「常時読まれる」便利さに頼って、手順書もパス別ルールも全部CLAUDE.mdに書く運用は破綻しやすいです。200行を超えるとコンテキスト消費が増えるだけでなく遵守率も下がります。手順はSkillsへ、特定パスにしか関係しないルールは .claude/rules/ へ振り分けるのが健全です。@ インポートでの分割は見通しの改善にはなりますが、起動時に全部展開されるためコンテキスト削減にはならない点に注意してください。
アンチパターン2: 自動メモリを放置する・頼りすぎる
自動メモリは便利な一方、放置すると古い知見が残って判断を誤らせることがあります。/memory から定期的に中身を確認し、不要なメモは削除する運用が安全です。逆に、チームで共有すべき規約を自動メモリ任せにするのも危険です。自動メモリはマシンローカルでチームに共有されず、MEMORY.md は200行/25KBで切り詰められるため、確実に効かせたい規約はCLAUDE.mdに書く方が適しています。
よくある質問
CLAUDE.mdと自動メモリはどちらが優先されますか?
機械的な優先順位はありません。どちらも毎セッション読み込まれる対等なコンテキストで、矛盾があるとClaudeがどちらかを任意に選ぶ可能性があります。規約はCLAUDE.mdに一本化し、自動メモリ側に古い矛盾したメモが残っていたら /memory から削除するのが安全です。
自動メモリはチームで共有できますか?
できません。自動メモリは ~/.claude/projects/ 配下に置かれるマシンローカルのデータで、他のマシンやクラウド環境とは共有されません(同一リポジトリのworktree間では共有されます)。チームに広げたい知見は、gitで共有されるプロジェクトのCLAUDE.mdへ転記する形になります。
CLAUDE.mdの指示をClaudeが守らないときはどうすればよいですか?
まず /memory で対象ファイルが読み込まれているかを確認します。一覧に出ていなければ配置場所の問題です。読み込まれているのに守られない場合は、指示を検証可能な具体性に書き直し、複数ファイル間の矛盾を消します。それでも必ず実行させたい処理は、コンテキストではなくHooksとして書くのが確実です。
コンテキスト圧縮(/compact)の後に指示が消えるのはなぜですか?
消えるのは「会話の中だけで与えた指示」と「再ロード前のネストされたCLAUDE.md」です。プロジェクトルートのCLAUDE.mdは圧縮後に自動で再注入されます。圧縮で消えて困る指示は、CLAUDE.mdに書いておけば毎回復元されます。
AGENTS.mdを使っているリポジトリではどうすればよいですか?
Claude CodeはAGENTS.mdを読まないため、@AGENTS.md と1行書いたCLAUDE.mdを作ってインポートするか、シンボリックリンクを張ります。/init を実行すれば、既存のAGENTS.mdや .cursorrules などの他ツール設定を読み取って、生成するCLAUDE.mdに取り込んでくれます。
まとめ
Claude Codeのmemoryは、あなたが書くCLAUDE.md、Claudeが書く自動メモリ、毎回消えるセッションの三層で動いています。CLAUDE.mdは全文・常時ロードされる指示、自動メモリは MEMORY.md の先頭200行/25KBだけが常時ロードされる学習ノート、セッションは/compactと再起動で揮発する作業領域、というのが現行仕様の骨格です。
迷ったら「誰が書くか」「いつ効いてほしいか」「強制力が要るか」の3つで振り分けてください。常時の規約はCLAUDE.mdへ、機械的な強制はhooksへ、手順はSkillsへ、学習はメモリの自動蓄積へ。この役割分担が崩れていないことが、長期で壊れにくいClaude Codeプロジェクトの土台になります。Claude Code全体の機能体系はClaude Code完全ガイドから辿れます。