blog

Claude Codeのメモリ完全解説：3階層設計とAuto-Memory実装ガイド

監修

河合 継（クリスタルメソッド株式会社 代表取締役）

AI・ディープラーニングに関する特許16件の発明者。国立がん研究センターとの共同研究や、テレビ番組でのAI解説実績を持つAI研究者として、AIの研究開発を主導している。
運営会社について ｜ 編集方針

Claude Codeのメモリ完全解説：3階層設計とAuto-Memory実装ガイド

Claude Codeはセッションをまたいだ記憶をどのように実現しているのか。公式ドキュメント（code.claude.com）によれば、その答えは「開発者が書くCLAUDE.mdファイル」と「Claudeが自ら書き込むAuto-Memory」という2つの補完的な仕組みに集約される。本記事では両機構の設計原則・運用上の注意点・チーム導入のポイントを、一次情報に基づいて体系的に解説する。

Claude Codeのメモリとは何か：ステートレスLLMの制約を超える設計

LLMは本来ステートレスであり、セッションをまたいだ記憶を構造上持たない。Claude Codeの公式ドキュメント（code.claude.com/docs/en/memory.md）は冒頭でこの制約を明確に認めたうえで、「各セッションは新鮮なコンテキストウィンドウで始まる（Each Claude Code session begins with a fresh context window）」と述べ、それを補う2つの機構を定義している。

  • CLAUDE.mdファイル：開発者が記述する永続的な指示書。技術スタック・規約・アーキテクチャ方針を記録する
  • Auto-Memory：Claudeが修正や指摘をもとに自ら書き込むノート。ビルドコマンド・デバッグで得た知見・ユーザーの好みなどを蓄積する

公式ドキュメントは、両システムはすべての会話開始時にロードされると説明している。ただし重要な留保として、「Claudeはこれらをコンテキストとして扱うものであり、強制的な設定ではない（Claude treats them as context, not enforced configuration）」と明記されている。特定のアクションを問答無用でブロックしたい場合は、PreToolUseフックを使う必要がある。

インストールと初期設定については Claude Codeインストール完全ガイド を、ツール全体の概念整理には Claude Code概要ページ を参照されたい。

User メモリ ~/.claude/CLAUDE.md 全プロジェクト共通

Project メモリ {root}/CLAUDE.md チーム共有・git管理

Local メモリ {root}/CLAUDE.local.md 個人×プロジェクト固有

Auto-Memory（MEMORY.md） Claudeが自ら書き込む知見・パターン・コマンド 先頭200行または25KBをコンテキストにロード

CLAUDE.md vs Auto-Memory：両者は毎セッション冒頭でロードされる 指示が具体的・簡潔であるほど、Claudeはより一貫して従う

Claude Code メモリの構造とAuto-Memoryの関係。公式ドキュメント（code.claude.com/docs/en/memory.md）に基づく概念図

CLAUDE.mdファイルの2系統とAuto-Memoryの比較

公式ドキュメントは、CLAUDE.mdとAuto-Memoryを以下のように対比して説明している（code.claude.com/docs/en/memory.md）。

CLAUDE.mdファイル Auto-Memory
書き手 開発者（あなた） Claude自身
内容 指示とルール 発見した知見とパターン
スコープ プロジェクト・ユーザー・組織 リポジトリ単位（ワークツリー間で共有）
ロード方式 毎セッション 毎セッション（先頭200行または25KB）
用途 コーディング規約・ワークフロー・プロジェクト構造 ビルドコマンド・デバッグ知見・Claudeが発見した好み

Auto-Memoryのロード量が「先頭200行または25KB」に制限されている点は、コンテキスト管理の観点から重要である。コンテキストウィンドウの可視化シミュレーターでも、Auto-Memory（MEMORY.md）のロードトークンが示されており（code.claude.com/docs/en/context-window.md）、蓄積が進むほどこの上限が実質的な制約として機能し始める。

公式ドキュメントはさらに「指示が具体的・簡潔であるほど、Claudeはより一貫して従う（The more specific and concise your instructions, the more consistently Claude follows them）」と明言している。CLAUDE.mdを充実させれば回答品質が上がるという単純な話ではなく、記述の質と量のバランスが求められる。

CLAUDE.mdファイルの3つのスコープ：user / project / local

公式ドキュメントによれば、CLAUDE.mdファイルは配置場所によってスコープが異なる。コンテキストウィンドウのシミュレーターも~/.claude/CLAUDE.md（ユーザーグローバル設定）が起動時に自動ロードされることを示している（code.claude.com/docs/en/context-window.md）。実運用上の3つのスコープを以下に整理する。

スコープ ファイルパス 適用範囲 主な記述内容 gitコミット
User（ユーザー） ~/.claude/CLAUDE.md 全プロジェクト共通 個人の開発スタイル・言語設定・好みのコメント形式 しない（個人設定）
Project（プロジェクト） {root}/CLAUDE.md プロジェクト全体 技術スタック・コーディング規約・チームルール・アーキテクチャ方針 する（チーム共有推奨）
Local（ローカル） {root}/CLAUDE.local.md 個人×プロジェクト固有 ローカル環境固有の設定・一時的な作業メモ・個人的なオーバーライド しない（.gitignore推奨）

公式ドキュメントはさらに、.claude/rules/ディレクトリを使って特定のファイルタイプへのルール適用を細粒度で管理する方法も提供している（code.claude.com/docs/en/memory.md）。大規模プロジェクトでCLAUDE.mdが肥大化した場合は、このディレクトリ構造による分割が有効な選択肢となる。

CLAUDE.mdの実効的な記述パターン

CLAUDE.mdに記述すべき内容は「セッションをまたいでもClaudeに一貫して知っておいてほしい情報」に絞るのが原則である。以下は実際の運用で有効な構成例である。

# Project Memory: my-api-service

## 技術スタック
- Runtime: Node.js 22 / TypeScript 5.4
- DB: PostgreSQL 16（接続先は DATABASE_URL 環境変数）
- テストフレームワーク: Vitest 2.x

## コーディング規約
- 関数は純粋関数を優先し、副作用はモジュール境界に閉じ込める
- エラーハンドリングは Result 型で統一（throw は原則禁止）
- コミットメッセージ: Conventional Commits 形式

## アーキテクチャ制約
- src/domain/ 配下はフレームワーク非依存を維持すること
- 外部 API 呼び出しは src/infrastructure/ にのみ配置すること

## 既知の注意点
- PostgreSQL の接続プールは最大 20 を上限とすること（本番環境の制約）
- E2E テストは CI 環境でのみ実行すること（ローカルでは skip）

公式ドキュメントが強調する「具体的・簡潔な記述が一貫性を高める」という原則に従えば、上記のように箇条書きで要点を絞った記述が理想的である。冗長な説明文はCLAUDE.md自体がコンテキストウィンドウを圧迫するという逆効果を招く。

チームでのCLAUDE.md管理フロー

チーム開発においては、CLAUDE.mdをコードと同様にプルリクエストでレビューする運用が安定している。変更の意図が不明なまま蓄積すると、メモリの内容が実態と乖離し、Claudeの回答品質が逆に低下するリスクがある。CLAUDE.local.mdは初期設定時に.gitignoreへ追加し、個人設定の誤コミットを防ぐことが必須である。

Auto-Memoryの仕組みと制御

Auto-Memoryは、Claudeがユーザーの修正や指摘をもとに自動でノートを書き込み、次回以降のセッションで再利用する機能である。公式ドキュメントは「CLAUDE.mdファイルを使うのはClaudeの挙動を導きたいとき。Auto-Memoryはあなたの修正からClaudeが手動の手間なしに学ぶためのものだ（Auto memory lets Claude learn from your corrections without manual effort）」と説明している（code.claude.com/docs/en/memory.md）。

コンテキストウィンドウのシミュレーターによれば、Auto-Memory（MEMORY.md）には以下の特性がある（code.claude.com/docs/en/context-window.md）。

  • セッション開始時に自動ロードされる（hidden、つまりユーザーには直接見えない形で読み込まれる）
  • ロードされるのは先頭200行または25KBのいずれか先に達した方まで
  • 内容の例：Claudeが学習したビルドコマンド・気付いたパターン・避けるべきミスなど
  • スコープはリポジトリ単位で、ワークツリー間で共有される

また公式ドキュメントは、サブエージェントも独自のAuto-Memoryを維持できることに言及している（code.claude.com/docs/en/agent-sdk/subagents.md参照）。サブエージェントの詳細設定についてはサブエージェント設定ページを参照のこと。

Auto-Memoryの運用上のリスクと対処

Auto-Memoryには明確な利点がある一方、蓄積された情報が陳腐化するリスクを内包している。過去のアーキテクチャ決定や一時的な対処法が書き込まれ、その後もClaudeに参照され続ける状況は、回答品質の静かな劣化を招く。具体的なリスクを列挙する。

  • 廃止されたAPIエンドポイントや削除済みファイルへの参照が残存する
  • 一時的なワークアラウンドが恒久的な制約として記述される
  • 蓄積が進むとAuto-Memoryの先頭200行・25KBという上限が実質的な制約として機能し始め、後から追加された重要な知見がロードされなくなる

対処としては、スプリント単位などの定期的なメモリファイルのレビューサイクルを設けることが実運用上の要件となる。特定のセッションでAuto-Memoryの自動書き込みを抑制したい場合は、セッション開始時に明示的に指示することが現状では最も確実な制御手段である。

スラッシュコマンドを活用したセッション制御の詳細は Claude Codeスラッシュコマンド一覧 を参照されたい。

コンテキストウィンドウとメモリの関係：枯渇を防ぐ実装パターン

「Claude Codeのメモリ不足」として体感される現象の多くは、Claudeモデル自体のRAMの問題ではなく、コンテキストウィンドウの消費超過として発生する。公式のコンテキストウィンドウシミュレーター（code.claude.com/docs/en/context-window.md）は、セッション起動時に何がどれだけトークンを消費するかを明示している。起動時の主要ロード項目を以下に示す。

  • システムプロンプト：動作・ツール使用・応答フォーマットのコア指示。常に最初にロードされる
  • Auto-Memory（MEMORY.md）：前セッションからのノート。先頭200行または25KB
  • 環境情報：作業ディレクトリ・プラットフォーム・シェル・OSバージョン・gitの状態
  • MCPツール：デフォルトでは名前のみリスト化し、スキーマは遅延ロード（ENABLE_TOOL_SEARCH=autoでコンテキストの10%以内に収まる場合は起動時ロードに切り替え可能）
  • CLAUDE.md（ユーザーグローバル）：~/.claude/CLAUDE.mdの内容

これらの起動時コストに加え、ファイル読み込みやツール呼び出しのたびにトークンが積み上がっていく。長時間セッション・モノレポ規模のプロジェクト・複数ツールの並行呼び出しが重なると、利用可能なトークン残量が急速に減少する。コスト・利用量の管理については Claude Code料金・プラン比較 および Claude Code APIの料金体系 を参照されたい。

パターン1：CLAUDE.mdの分割管理（チャンク化）

大規模プロジェクトでは、単一のCLAUDE.mdにすべての情報を詰め込むと、ファイル自体がコンテキストを大量消費する。公式ドキュメントが提供する.claude/rules/ディレクトリ機能を活用して役割別にファイルを分割し、作業内容に応じて必要な文脈のみをロードする運用が有効である（code.claude.com/docs/en/memory.md）。

プロジェクトルート/
├── CLAUDE.md              # 全体方針・技術スタック・基本規約
├── .claude/
│   └── rules/
│       ├── api.md         # API設計・エンドポイント仕様・認証方式
│       ├── database.md    # DBスキーマ・マイグレーション方針
│       └── testing.md     # テスト戦略・カバレッジ要件・モック方針
└── CLAUDE.local.md        # 個人環境設定（.gitignore登録済み）

パターン2：セッション境界の意図的な設計

一つのセッションで複数のサブタスクをまたぐと、前半の作業コンテキストがトークンを占有し続ける。機能実装・テスト作成・コードレビューをセッション境界で区切り、各セッション冒頭でCLAUDE.mdから必要な文脈を注入する設計が安定した運用につながる。セッション設計の考え方については Claude Codeの使い方ガイド も参考になる。

パターン3：MCPツールの遅延ロードを活用する

公式シミュレーターによれば、MCPツールはデフォルトでスキーマを遅延ロードし、Claudeがタスクに必要と判断したときのみ個別スキーマをロードする（code.claude.com/docs/en/context-window.md）。多数のMCPツールを登録している場合、この挙動がコンテキスト節約に直結する。ENABLE_TOOL_SEARCH=falseに設定するとすべてのスキーマを起動時にロードするため、ツール数が多い環境では避けた方が無難である。

パターン4：Auto-Memoryの定期的な刈り込み

Auto-Memoryの先頭200行・25KBという上限を意識し、定期的に不要なエントリを削除することがコンテキスト管理の基本的な実践となる。スプリントのレトロスペクティブ等でメモリファイルの内容を確認するサイクルを組み込むことで、蓄積された情報の陳腐化を防げる。

メモリ設計の実践：チーム導入チェックリストと深掘り活用例

Claude Codeのメモリ機能をチームへ導入する際、設計段階で決定すべき事項を体系的に整理する。これらを事前に合意せずに導入すると、CLAUDE.mdの管理が属人化し、メモリの品質が急速に劣化する。

  1. CLAUDE.mdのオーナーシップ設計：誰がレビュー・マージ権限を持つかをコードのPR運用と同様に定める。変更の背景をコミットメッセージまたはPRの説明に記録する習慣を設ける
  2. CLAUDE.local.mdのgitignore登録：チーム全員の開発環境セットアップ手順に含め、初回セットアップ時に必ず実施する
  3. Auto-Memoryの運用方針の合意：自動書き込みを許可する範囲をチームとして決定し、方針をCLAUDE.md自体に記述しておく
  4. メモリファイルの定期棚卸し：スプリントのレトロスペクティブ等で内容の鮮度を確認するサイクルを組み込む。特にAuto-Memoryは200行・25KB上限を念頭に置いて優先度の低い項目を削除する
  5. セッション設計の標準化：タスク粒度とセッション境界のルールをチームドキュメントに記載する
  6. ルールファイルの分割基準策定：CLAUDE.mdが一定量を超えた時点で.claude/rules/への分割を検討するなど、具体的な閾値をチームとして設ける

AI開発プロジェクト特有のメモリ活用例

弊社が開発するDeepAIは、機械学習・深層学習（CNN）を用いた2D画像認識ソリューションである。ソファーなど形状が不定な対象の正常・異常分類において高精度な判定を実現しており、GANによるデータ拡張も活用している。このようなAI開発プロジェクトでClaude Codeをコーディング支援に用いる場合、CLAUDE.mdへの記述内容の選択がとりわけ重要になる。

具体的には、推論パイプラインのアーキテクチャ決定事項（モデルの入出力テンソル仕様・前処理のnormalization方針・GANで生成した拡張データのディレクトリ構造・バッチサイズとGPUメモリの制約関係）をProject層のCLAUDE.mdに記述しておくことで、セッションをまたいだ一貫したコーディング支援を受けられる。機械学習特有の「実験を重ねるうちに暗黙知になりがちな設計判断」をメモリとして明文化する場として、CLAUDE.mdは有効に機能する。これは弊社がAI開発の実務でClaude Codeを活用する中で確認している運用上のパターンである。

他ツールとのメモリ設計の比較視点

Cursorなど他のAIコーディングツールと比較した場合、Claude Codeのメモリ設計はファイルベースであることの透明性が高く、バージョン管理システムとの親和性において優位性がある。一方で、ファイルの維持・更新をチームが能動的に行わなければならないという管理コストは否定できない。他ツールとの詳細な機能比較は Claude Code vs Cursor比較 および Claude Code vs Codex比較 を参照されたい。

Claude Code全体の入門については Claude Code入門・はじめ方 を、SEOや実務活用の観点からは Claude CodeをSEOに活用する入門ガイド も参考になる。

まとめ：Claude Codeメモリ設計の要点と実装上の留意点

Claude Codeのメモリ機能は、LLMのステートレス性という根本的な制約を、ファイルベースの永続化とAuto-Memoryの自動化によって構造的に補う仕組みである。公式ドキュメント（code.claude.com/docs/en/memory.md）に基づいて本記事で論じた要点を以下に整理する。

  • メモリにはCLAUDE.mdファイル（開発者が記述）とAuto-Memory（Claudeが自動書き込み）の2系統がある。いずれも毎セッション冒頭でロードされるが、強制的な設定ではなくコンテキストとして扱われる
  • CLAUDE.mdはユーザーグローバル（~/.claude/CLAUDE.md）・プロジェクト（{root}/CLAUDE.md）・ローカル（{root}/CLAUDE.local.md）の3スコープで管理する。チームで共有すべきはプロジェクトスコープのファイルであり、ローカルスコープは.gitignoreで管理する
  • Auto-MemoryはリポジトリごとのMEMORY.mdとして管理され、先頭200行または25KBがコンテキストにロードされる。蓄積が進むとこの上限が実質的な制約になるため、定期的な刈り込みが必要である
  • 特定のアクションをCLAUDE.mdの記述で無条件にブロックすることはできない。アクションを強制的に制御したい場合はPreToolUseフックを使う
  • 「メモリ不足」として体感される問題の多くはコンテキストウィンドウの枯渇である。.claude/rules/によるルールファイルの分割、セッション境界の設計、MCPの遅延ロード活用によって緩和できる
  • CLAUDE.md自体がコンテキストを消費するという逆説を常に意識し、指示の簡潔さと情報の密度のバランスを取ることが大規模プロジェクトでの実用上の鍵となる

弊社が開発するDeepAIのようなAI開発プロジェクトにおいては、設計の暗黙知をCLAUDE.mdに明文化することで、Claude Codeによるコーディング支援の一貫性を長期にわたって維持できる。AIソリューションの活用にご興味のある方は、弊社サービスページもあわせてご確認いただきたい。

参考文献

関連記事

AIブログ購読

　
クリスタルメソッドがお届けする
AIブログの更新通知を受け取る

Study about AI

AIについて学ぶ

  • Claude Code 公式ドキュメント完全読解ガイド｜導入判断から運用まで

    Claude Code 公式ドキュメント完全読解ガイド｜導入判断から運用まで

    監修 河合 継（クリスタルメソッド株式会社 代表取締役） AI・ディープラーニングに関する特許16件の発明者。国立がん研究センターとの共同研究や、テレビ番組での...

  • Claude Code ベストプラクティス完全解説｜実装現場で使える設計指針2026

    Claude Code ベストプラクティス完全解説｜実装現場で使える設計指針2026

    監修 河合 継（クリスタルメソッド株式会社 代表取締役） AI・ディープラーニングに関する特許16件の発明者。国立がん研究センターとの共同研究や、テレビ番組での...

  • Claude Code 自動化の実装ガイド――設計・事例・セキュリティを徹底解説

    Claude Code 自動化の実装ガイド――設計・事例・セキュリティを徹底解説

    監修 河合 継（クリスタルメソッド株式会社 代表取締役） AI・ディープラーニングに関する特許16件の発明者。国立がん研究センターとの共同研究や、テレビ番組での...

View more

AIで、業務の生産性を変革しませんか？

無料デモ・資料請求は1分で完了。お気軽にお問い合わせください。

無料デモを試す お問い合わせ