メインコンテンツへスキップ
BayashiLab LogoBayashiLab(バヤシラボ)
ブログ一覧

Claude Code Auto Memory完全ガイド — MEMORY.mdの仕組みから200行制限の管理戦略、PreCompact Hooksとの連携まで

Claude CodeAuto MemoryAI開発ツール開発効率化

「毎回同じことをClaude Codeに説明していませんか？」——プロジェクト固有の命名規則、テストの流儀、デプロイ手順。CLAUDE.mdに書けばいい？ 半分正解です。しかし2026年2月、Claude Codeに「自分で学び、自分で記録する」メモリが実装されました。Auto Memoryです。本記事では、CLAUDE.md・.claude/rules/・Auto Memory・PreCompact Hooksという4層メモリアーキテクチャを体系的に解説し、実プロジェクトでの運用ノウハウをお届けします。

Claude Codeの4層メモリアーキテクチャ全体像

各層の役割と情報の流れ

Claude Codeのメモリは以下の4層で構成されています。

code
セッション開始時のロード順序:

  ┌─────────────────────────────────────────────────┐
  │  第1層: CLAUDE.md（指示層）                       │
  │  人間が書く永続的な指示。全文ロード               │
  ├─────────────────────────────────────────────────┤
  │  第2層: .claude/rules/（コンテキスト別ルール）     │
  │  globパターンで条件付きロード                     │
  ├─────────────────────────────────────────────────┤
  │  第3層: Auto Memory MEMORY.md（学習層）           │
  │  Claudeが自発的に記録。先頭200行のみロード        │
  ├─────────────────────────────────────────────────┤
  │  第4層: PreCompact Hooks（作業状態保存）           │
  │  コンテキスト圧縮時のみ発火                      │
  └─────────────────────────────────────────────────┘
層 ファイル 書き手 ロードタイミング 行数制限
第1層 CLAUDE.md 人間 セッション開始時に全文 なし（ただし200行以下推奨）
第2層 .claude/rules/*.md 人間 該当ファイル編集時 なし
第3層 ~/.claude/projects/<project>/memory/MEMORY.md Claude セッション開始時に先頭200行 200行（超過分は無視）
第4層 PreCompact Hooks — コンテキスト圧縮直前 —

「人間が書く指示」と「Claudeが学ぶ記録」の境界線

第1層・第2層は人間が意図的に書くもの。第3層はClaudeが作業を通じて自発的に記録するものです。この境界を意識することが、メモリを効果的に運用する第一歩になります。

Auto Memory MEMORY.mdの仕組みを深掘りする

保存場所とプロジェクト解決ルール

Auto Memoryの保存先は ~/.claude/projects/<project>/memory/ です。<project> はgitリポジトリのルートパスから導出されるため、同一リポジトリ内の全worktreeとサブディレクトリが同じメモリディレクトリを共有します。gitリポジトリ外ではプロジェクトルートがそのまま使われます。

Claudeは何を・いつ・どう記録するのか

Claudeは作業中に「今後のセッションでも有用」と判断した情報を、Write/Editツールで MEMORY.md に自主的に書き込みます。ユーザーが「これを覚えて」と明示的に伝えた場合も即座に記録されます。

記録すべきもの:

  • 複数セッションで確認された安定パターンや規約
  • アーキテクチャ上の重要な意思決定やファイルパス
  • ユーザーのワークフロー嗜好（「常にbunを使う」等）
  • 繰り返し発生する問題の解決策

記録すべきでないもの:

  • セッション固有の一時的な作業状態
  • 単一ファイルを読んだだけの未検証の推測
  • CLAUDE.mdと重複する内容

トピックファイルによる分割パターン

200行制限の本質は、MEMORY.md の先頭200行のみがセッション開始時に自動ロードされる点にあります。201行目以降はサイレントに無視されます。CLAUDE.mdにはこの制限がないことが重要な差異です。

この制限への対策が、トピックファイルへの分割です。

code
~/.claude/projects/<project>/memory/
├── MEMORY.md              # インデックス（200行以内に収める）
├── debugging.md           # デバッグパターン
├── api-conventions.md     # API設計の決定事項
└── patterns.md            # コード規約の詳細

トピックファイルはセッション開始時にはロードされません。Claudeが必要に応じて標準のファイルツールでオンデマンドに読み取ります。

MEMORY.md の構成例を示します。

markdown
# Project Memory Index

## Architecture
- Next.js App Router + SQLite (better-sqlite3)
- 詳細: ./architecture.md

## Conventions
- テスト: vitest + testing-library、カバレッジ80%以上
- import順序: node組み込み → 外部パッケージ → 内部モジュール
- 詳細: ./patterns.md

## Debugging Notes
- PostCSS競合: autoprefixerを除外して解決
- 詳細: ./debugging.md

## User Preferences
- パッケージマネージャ: bun（npmではない）
- commit前に必ずビルド確認
- 日本語でコミュニケーション

このように MEMORY.md 自体は目次とサマリに徹し、詳細はリンク先のトピックファイルに委ねます。

200行制限を攻略する実践的管理戦略

MEMORY.mdをインデックスとして使う設計

戦略1: 目次+最重要事項に徹する。 MEMORY.md には各トピックの1行サマリとトピックファイルへのパスだけを記載し、200行で収まる密度を維持します。

戦略2: セマンティックに構造化する。 時系列（「3月2日に発見」）ではなく、カテゴリ別（## Architecture, ## Conventions, ## Debugging）で整理します。

戦略3: 定期的にクリーンアップする。 Claudeに「MEMORY.mdを確認して、古い情報や誤った記録を整理して」と依頼するだけで、不要なエントリを削除・統合してくれます。

アンチパターン:

  • セッションログのような時系列の記録
  • 「○○かもしれない」という未検証の仮説
  • CLAUDE.mdに既に書いてある内容の二重管理

SFEIR Instituteの分析によると、CLAUDE.mdが200行以下の場合はルール適用率が92%以上であるのに対し、400行を超えると71%まで低下します。これはAuto Memoryの MEMORY.md にも同様に当てはまる原則で、簡潔さが品質に直結します。

PreCompact Hooksで作業状態を保存する

PreCompact Hooksの基本設定

PreCompact Hooksは、コンテキストウィンドウが満杯になった際の圧縮（compact）直前に発火するフックです。

matcherには manual（/compact コマンド実行時）と auto（自動圧縮時）を指定できます。両方に対応するにはmatcherを省略するか "*" を指定します。

json
// .claude/settings.json
{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/save-work-state.sh"
          }
        ]
      }
    ]
  }
}

フックスクリプトの実装例です。圧縮前に作業状態をファイルに書き出します。

bash
#!/bin/bash
# .claude/hooks/save-work-state.sh
INPUT=$(cat)
CWD=$(echo "$INPUT" | jq -r '.cwd')
STATE_FILE="$CWD/.claude/work-state.json"

jq -n \
  --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --arg trigger "$(echo "$INPUT" | jq -r '.trigger')" \
  --arg git_branch "$(cd "$CWD" && git branch --show-current 2>/dev/null)" \
  --arg git_diff_stat "$(cd "$CWD" && git diff --stat 2>/dev/null)" \
  '{timestamp: $timestamp, trigger: $trigger,
    git_branch: $git_branch, git_diff_stat: $git_diff_stat}' \
  > "$STATE_FILE"

Auto Memoryとの連携パターン

正直、最初はPreCompact HooksとAuto Memoryの違いが分かりにくかったのですが、使い分けは明快です。

  • PreCompact Hooks: 「今このセッションの作業状態」を保存する。圧縮後にClaudeが .claude/work-state.json を読み取って文脈を復元
  • Auto Memory: 「セッションをまたぐ永続知識」を蓄積する。次回以降のセッションで自動ロード

両者は補完関係にあり、PreCompact Hooksが短期記憶、Auto Memoryが長期記憶と捉えると分かりやすいです。

CLAUDE.mdとAuto Memoryの使い分け判断フロー

どちらに書くべきか？ 3つの判断基準

判断基準 CLAUDE.md Auto Memory
誰が書くか 人間が意図的に記述 Claudeが学習・発見して記録
共有範囲 gitコミット対象（チーム全員） ローカルのみ（個人の環境固有）
安定性 変更頻度の低い恒久ルール 試行錯誤中の知見、発展的なパターン

Auto Memoryはリポジトリにコミットしない設計です（~/.claude/ 配下に保存されるため、そもそもリポジトリ外）。

チーム開発での運用ルール

CLAUDE.mdでAuto Memoryの記録方針を指示するテクニックが地味に便利です。

markdown
# CLAUDE.md

## Auto Memory記録方針
- テスト戦略に関する発見は memory/testing.md に記録すること
- パフォーマンス改善のパターンは memory/performance.md に記録すること
- セッション固有の一時情報はメモリに記録しないこと

こうすることで、Claudeの学習内容をプロジェクトのニーズに合わせて誘導できます。

よくあるトラブルと解決策

Q: MEMORY.mdが肥大化して200行を超えた Claudeに「MEMORY.mdを整理して、詳細はトピックファイルに移動して」と依頼してください。手動で編集することも可能です。/memory コマンドからメモリフォルダを直接開けます。

Q: Auto Memoryが意図しない情報を記録する CLAUDE.mdで記録ルールを明示するのが効果的です。それでも問題がある場合は /memory でAuto Memoryを無効化できます。設定ファイルで "autoMemoryEnabled": false を指定するか、環境変数 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 でも無効化可能です。

Q: worktree間でメモリが共有されて困る gitリポジトリパスが同一であれば共有は仕様です。ブランチ固有の情報はトピックファイル内でセクションを分けて管理してください。

Q: PreCompact Hooksが発火しない matcherが manual のみになっていないか確認してください。自動圧縮にも対応するには auto を追加するか、"*" を指定します。

Claude Codeのメモリは「人間が教えるCLAUDE.md」と「Claudeが自ら学ぶAuto Memory」の二本柱で成り立っています。この2つを混同せず、それぞれの特性に合わせて使い分けることが、セッションをまたいだ生産性向上の鍵です。まずは MEMORY.md の200行をインデックスとして設計し、詳細はトピックファイルへ。PreCompact Hooksで長時間セッションの文脈も守る。この4層構造を意識するだけで、Claude Codeは「毎回ゼロから説明するツール」から「プロジェクトを理解したパートナー」へと変わります。

もっと読む他の技術記事も読む