Claude Code memoryとは？CLAUDE.mdとの違いと運用設計の実例

2026年4月24日

結論から言うと、Claude Codeの「memory」は人が書くCLAUDE.mdとClaudeが自動で書くauto memoryの2層構造です。両者は名前が似ていて混同しがちですが、保存場所も目的も担当者も違います。先日チームで「CLAUDE.mdに毎回同じことを書き足すのが面倒」という話になり、調べてみたらauto memory（v2.1.59以降）で自動化できる範囲が思った以上に広いと気づきました。

本投稿は公式ドキュメントのHow Claude remembers your projectを読み直して、2層の使い分け、配置場所と優先順位、/memoryコマンド、@pathインポート、.claude/rules/のスコープ指定までを実例ベースで整理したものです。検証はClaude Code v2.2系で行っています。

CLAUDE.mdとauto memory—役割が違う2つの仕組み

まずは2つを並べて比較するのが一番わかりやすいです。公式ドキュメントの表を要約すると次のようになります。

	CLAUDE.md	auto memory（MEMORY.md）
書く人	あなた	Claude
中身	指示・ルール	学習した好み・パターン
スコープ	プロジェクト/ユーザー/組織	working tree単位
読み込み量	全文ロード	先頭200行（または25KB）まで
用途	コーディング規約・workflow・アーキテクチャ	ビルドコマンド・デバッグ知見・好みの学習

なぜ2つ用意されているのか

CLAUDE.mdは「毎回同じことを言うのが嫌だから書き留めておく」もの、auto memoryは「Claude自身が観察して書き溜める」ものです。前者は明示的な要件、後者は暗黙の学習と言い換えるとしっくりきます。

例えば「テストはvitestを使う」「APIハンドラはsrc/api/handlers/に置く」のような普遍的なルールはCLAUDE.mdに書く。一方で「このプロジェクトのE2Eテストは事前にRedisを起動しておかないと落ちる」のように触ってみて初めてわかった事実はauto memoryに任せる、という分担です。

判断に迷ったときの振り分け基準

「どっちに書けばいいか迷った時の判断基準」をフローチャート的にまとめると次の通りです。

毎セッション必ず必要 → CLAUDE.md（ルール、規約、アーキテクチャ）
触らないと気づけない → auto memory（環境固有の起動順、過去のハマりどころ）
個人の好み（チーム共有不要）→ CLAUDE.local.mdまたは~/.claude/CLAUDE.md
特定ファイルだけに効かせたい → .claude/rules/に分離

auto memoryの正体とMEMORY.mdの中身

auto memoryはClaude Code v2.1.59で追加された機能で、デフォルトで有効です。Claudeがセッション中の修正やフィードバックを観察し、「次の会話で役立ちそう」と判断したものを~/.claude/projects/<project>/memory/に書き出します。

保存先のディレクトリ構造

実際にauto memoryが動いているプロジェクトでディレクトリを覗くと、こんな構造になっています。

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 索引。毎セッションの先頭でロードされる
├── debugging.md       # デバッグ系の詳細メモ
├── api-conventions.md # API設計の決定事項
└── ...                # その他Claudeが必要と判断したトピック

実行例として、私のローカルではこんな出力になりました。

$ ls -la ~/.claude/projects/-Users-moha-workspace-private-wp-auto-poster/memory/

total 24
-rw-r--r--  1 moha  staff   612 Apr 24 10:14 MEMORY.md
-rw-r--r--  1 moha  staff  1284 Apr 22 18:33 wp_post_workflow.md
-rw-r--r--  1 moha  staff   893 Apr 19 12:08 article_style.md

プロジェクトのパスはgitリポジトリ単位で決まるので、同じリポジトリのworktreeはmemoryディレクトリを共有します。複数の作業ツリーで並列にClaude Codeを動かしても、auto memoryは1か所に集約されるという挙動です。worktreeで並列作業する設計を考えるならClaude Code worktreeの使い方—並列開発でセッション衝突を防ぐ設計と合わせて読むと整理しやすいと思います。

200行/25KBという読み込み上限

MEMORY.mdは先頭200行（または25KBの早い方）までしかセッション開始時にロードされません。それ以降はロードされない、という割り切った仕様です。

では超過分はどうなるのか？答えは個別のトピックファイル（debugging.md等）に分けて、必要時にClaudeが読みに行くです。MEMORY.mdは「索引」、トピックファイルは「本文」という役割分担になっています。

これはCLAUDE.mdとは挙動が違う点で、CLAUDE.mdは長さに関係なく全文ロードされます（ただし200行を超えると遵守率が下がるので非推奨）。memoryのほうが容量制限が明確です。

auto memoryをオフにする

「自動で書かれるのが気持ち悪い」という人は無効化できます。サジェストでもclaude code memory offがよく出てくる検索意図ですね。3つの方法があります。

// 方法1: /memoryコマンドからトグル
/memory

// 方法2: settings.jsonに書く
{
  "autoMemoryEnabled": false
}

// 方法3: 環境変数で一発
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

個人的にはオンのまま運用する派です。書かれた内容は~/.claude/projects/<project>/memory/を直接編集すればいいだけなので、不要なエントリは削除する運用で十分回ります。

CLAUDE.mdの配置と優先順位を整理する

CLAUDE.mdには複数の置き場所があり、より具体的な場所が優先されます。ここを混乱したまま運用すると「CLAUDE.mdに書いたのに守られない」現象が起きます。

4つの配置場所

スコープ	場所	用途
Managed policy	OS別の固定パス（例: `/etc/claude-code/CLAUDE.md`）	組織全体に強制配布
Project	`./CLAUDE.md` または `./.claude/CLAUDE.md`	チーム共有のルール
User	`~/.claude/CLAUDE.md`	自分の全プロジェクト共通
Local	`./CLAUDE.local.md`	個人のプロジェクト固有設定（`.gitignore`に追加推奨）

「上書きされる」という誤解を解く

優先順位という言葉から、「Project CLAUDE.mdがあればUser CLAUDE.mdは読まれない」と勘違いされがちですが、実際は全部concatenateされて読み込まれます。優先順位は競合した場合にどちらに従うかの問題で、ロード自体は両方されます。

さらに、Claude Codeはカレントディレクトリから親方向にツリーを遡って各階層のCLAUDE.mdを拾います。foo/bar/で起動すれば、foo/bar/CLAUDE.mdとfoo/CLAUDE.mdの両方が読まれます。モノレポではこれが地雷になりやすく、他チームのCLAUDE.mdまで読み込まれてcompact後に挙動がブレることがあります。

そんな時のためにclaudeMdExcludesという除外設定があります。

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

// 適用後、起動ログで該当ファイルがロード一覧から消える

.claude/settings.local.jsonに置けば自分のマシンだけに反映でき、チーム全体には影響しません。CLAUDE.mdの設計そのものはチームで揃えたい場合はClaude CodeのCLAUDE.md設計 — チーム開発ルールを統一する仕組みに書いてあります。

/memoryコマンドで実際にいじってみる

/memoryコマンドはClaude Codeの中で叩く管理画面で、ロードされている全ファイルの一覧表示と、auto memoryのオン/オフ切替、ファイルを開いて編集するためのリンクが揃っています。

ロード状況を確認する

「CLAUDE.mdに書いたのに守られない」と感じたら、まずこのコマンドでファイルが本当にロードされているか確認するのが定石です。

/memory

// 出力例
Loaded files:
  ✓ ~/.claude/CLAUDE.md (User)
  ✓ ./CLAUDE.md (Project)
  ✓ ./CLAUDE.local.md (Local)
  ✓ ./.claude/rules/testing.md
  ✓ ./.claude/rules/api-design.md (paths: src/api/**)
Auto memory: ON
  → ~/.claude/projects/wp-auto-poster/memory/MEMORY.md (612 bytes)
  [Open folder]

ここに表示されないファイルはClaudeから見えていません。階層を間違えて置いていたり、claudeMdExcludesに引っかかっていたりするケースが多いです。

#ショートカットでクイック追加

会話中に#から始めて文章を打つと、その内容をCLAUDE.mdまたはauto memoryに即座に保存できます。「これは毎回必要な情報だ」と思った瞬間に手を動かさずに記録できる地味に便利な機能です。

# テストはvitestを使う。jestと書いたらNG

// Claudeが「どのファイルに保存しますか？」と聞いてくれる
[1] ./CLAUDE.md
[2] ~/.claude/CLAUDE.md
[3] auto memory (MEMORY.md)
Select: 1

記録先を選べるので、プロジェクト固有か個人設定かを瞬時に振り分けられます。

インポート(@path)と.claude/rules/で肥大化を防ぐ

CLAUDE.mdに何でも書きたくなりますが、200行を超えると遵守率が落ちるという公式の警告があります。文字数を圧縮するのではなく、分割と遅延ロードで対応するのが正攻法です。

アンチパターン: 1ファイルに全部入り

まず避けたい書き方を見ておきます。

# CLAUDE.md（500行）

## コーディング規約
... 100行 ...

## API設計ルール
... 80行 ...

## テストの書き方
... 70行 ...

## デプロイ手順
... 50行 ...

## マイグレーション運用
... 80行 ...

## モノレポの各サービス概要
... 120行 ...

これだと毎セッション全部がコンテキストに乗り、Claudeが指示を取りこぼしやすくなります。

OKパターン: ルールを.claude/rules/に分割

スコープを切って必要な時だけロードさせるのが正解です。

your-project/
├── CLAUDE.md              # 50行程度のコア指示と索引
└── .claude/
    └── rules/
        ├── code-style.md  # 全体に適用
        ├── api-design.md  # paths: src/api/**
        ├── testing.md     # paths: tests/**, **/*.test.ts
        └── frontend/
            └── react.md   # paths: src/components/**/*.tsx

paths付きのルールはClaudeが該当ファイルを開いた時だけロードされるので、コンテキスト消費が激減します。frontmatterはこんな形です。

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

// 適用後の挙動
// src/api/users.ts を読むと → このルールがロードされる
// src/utils/format.ts を読むと → ロードされない

コンテキスト管理全般のテクニックはClaude Codeのコンテキスト管理術—トークン消費を抑える7つの工夫でも触れています。

@path構文で外部ファイルを取り込む

CLAUDE.mdの中で@path/to/fileと書くと、そのファイルが起動時に展開されてコンテキストに入ります。READMEや設計書、ワークフロー手順を再利用したい時に便利です。

See @README.md for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md
- 個人設定 @~/.claude/my-project-instructions.md

相対パスはCLAUDE.mdからの相対、絶対パスとホームディレクトリ展開（~/）も使えます。再帰的なインポートは最大5階層まで。

注意点として、importしてもコンテキスト消費は減りません。あくまで「CLAUDE.mdをファイル分割して整理する」ための機能で、.claude/rules/のpath-scopedルールとは目的が違います。

memoryとSkillsの使い分け

サジェストにclaude code memory skillがよく出るので補足しておくと、両者は完全に役割が違います。

	memory（CLAUDE.md / auto memory）	Skills
ロードタイミング	セッション開始時に常時	呼び出された時 or 関連時のみ
用途	常に守ってほしいルール・知識	特定タスクの手順
コスト	毎回トークン消費	必要時のみ消費

「常に必要 → memory」「タスク発火時だけ必要 → Skills」が判断基準です。Skillsの作り方はClaude Codeのカスタムスラッシュコマンド作り方—Skills統合と引数設計に書いてあります。

うまくいかないときの対処法

運用していてよく踏むトラブルと、公式が示している解決策をまとめます。

CLAUDE.mdの指示が守られないとき

CLAUDE.mdはシステムプロンプトではなくユーザーメッセージとして注入されます。Claudeは読んで従おうとしますが、強制力はありません。曖昧な指示や矛盾した指示があると無視されることがあります。

/memoryでファイルがロードされているか確認
指示が具体的か見直す（「コードを綺麗にして」ではなく「2スペースインデントを使う」）
複数のCLAUDE.md間で矛盾がないか確認
どうしても強制したい場合は--append-system-promptでシステムプロンプトに昇格

デバッグにはInstructionsLoadedフックが使えます。「いつ・どのファイルが・なぜロードされたか」をログに残せるので、path-scopedルールが意図通り発火しているか確認するのに重宝します。Hooksの組み合わせ方はClaude Codeで「イベント駆動型ワークフロー自動化」ー Hooks × Scheduler × Skills 3つの基本機能を組み合わせる実践ガイドでも整理しています。

/compact後に指示が消える問題

これも公式FAQに載っているハマりどころです。/compact後の挙動はファイルの種類で違います。

プロジェクトルートのCLAUDE.md: /compact後に再読み込みされ、再注入される。生き残る。
サブディレクトリのCLAUDE.md: 自動では再注入されない。Claudeがそのディレクトリ内のファイルを読んだ時に再ロードされる。
会話中で口頭で渡しただけの指示: 完全に消える。永続化したいならCLAUDE.mdに書く。

「auto memoryが消えた？」と思った時は、まず~/.claude/projects/<project>/memory/MEMORY.mdを直接開いて確認するのが早いです。auto memoryは/compactとは独立して、ファイルとして存在し続けます。

auto memoryに何が書かれているか把握できない

/memoryからフォルダを開いて中身を読むだけです。プレーンなmarkdownなので、不要なエントリは普通のエディタで削除すれば済みます。むしろ「何が学習されたかを覗ける」のがCLAUDE.mdとの大きな違いで、監査可能なメモリとして設計されているのがポイントです。

まとめ：CLAUDE.mdとauto memoryをこう使い分ける

長くなったので運用方針として要点だけ振り返ります。

CLAUDE.mdは「人が書く要件」、auto memoryは「Claudeが書く学習ノート」。役割が違うので両方使う。
CLAUDE.mdは200行以下を目安に。超えそうなら.claude/rules/にpath-scopedで分割する。
auto memoryは~/.claude/projects/<project>/memory/に置かれる。worktreeはmemoryを共有する。
MEMORY.mdは先頭200行/25KBまでしかロードされない。詳細は別トピックファイルに切り出す前提の設計。
配置場所には優先順位があるが、全階層がconcatenateされる。「上書き」ではなく「マージ」。
困ったら/memoryでロード状況を確認。ファイルが見えていなければ守られない。
Skillsとは住み分けが違う。常時必要ならmemory、発火時だけならSkills。

個人的にはauto memoryが入ってから「同じ修正を3回繰り返したら覚えてくれる」感覚で楽になりました。CLAUDE.mdに何でも書こうとしていた時期と比べると、コンテキスト消費もだいぶ減っています。まずは/memoryを叩いて、自分の手元で何がロードされているのかを見るところから始めるのがおすすめです。