Claude Code auto-memory完全ガイド｜MEMORY.mdでセッションをまたいだ記憶を自動管理する方法

Claude Codeに「このプロジェクトではpnpmを使う」「テストにはRedisが必要」と伝えても、次のセッションでは覚えていない——こんな経験はありませんか。auto-memoryは、Claude Codeがセッション間にわたってプロジェクト固有の情報を自律的に記憶・管理する機能です。

開発中に得た知識（コマンド・アーキテクチャの決定・デバッグ手順）をClaudeがメモリファイルに書き残し、次のセッションで活用します。設定不要で動作しますが、仕組みを理解して活用することでより効果的に使えます。

Claude Code全般の概要はClaude Code完全ガイドを、CLAUDE.mdとの違いについてはCLAUDE.md完全ガイドを参照してください。

auto-memoryの仕組み：MEMORY.mdインデックスとトピックファイル

auto-memoryは2層構造で動作します。

保存場所

# プロジェクト固有のメモリ
~/.claude/projects/<project>/memory/
├── MEMORY.md              # インデックス（先頭200行が毎セッション自動ロード）
├── build-commands.md      # ビルド・テストコマンドの詳細
├── architecture.md        # アーキテクチャの決定事項
├── debugging.md           # デバッグで発見した知見
└── code-style.md          # コードスタイルの好み

# <project> はgitリポジトリのルートから導出される
# 同一リポジトリ内のworktreeやサブディレクトリはすべて同じディレクトリを共有

メモリはすべてマシンローカルのプロジェクト固有の情報です。クラウドや別のマシンとは共有されません。gitにコミットされることもないため、チームメンバーのマシンには引き継がれません。

MEMORY.mdの先頭200行制限

MEMORY.mdは毎セッション先頭200行までが自動的にコンテキストにロードされます。200行を超えた部分はセッション開始時には読み込まれません。インデックスを肥大化させないよう、詳細はトピックファイルに分割し、MEMORY.mdにはファイル名と概要だけを残す構成が推奨されます。

Claudeが自動的に記憶する内容

auto-memoryが有効な状態で作業していると、Claudeは「次のセッションで役に立つ情報」を自律的に判断してメモリに書き残します。以下のような情報が記憶されます。

Claudeが「これは覚えておくべき情報だ」と判断したタイミングでメモリが更新されます。明示的に「覚えておいて」と伝えることもできますが、通常の作業会話の中でも自動的に記憶されていきます。

/memoryコマンドでメモリを管理する

セッション内で/memoryを実行すると、メモリ管理のUIが開きます。

# セッション内で実行
/memory

# /memory で表示される内容:
# - 現在のセッションにロードされているCLAUDE.mdとメモリファイルの一覧
# - auto-memoryのオン/オフのトグル
# - メモリフォルダを開くリンク
# - 個別ファイルを選択してエディタで開ける

メモリファイルの構造と推奨フォーマット

メモリファイルはプレーンMarkdownです。Claudeが自動で書き残す場合も、手動で整理する場合も、以下の構造でまとめておくと、関連するセッションで効率よく活用できます。

# プロジェクトメモリ

## 開発環境
- ビルド・テストコマンド → [build-commands.md](build-commands.md)
- ローカル環境の要件 → [dev-environment.md](dev-environment.md)

## アーキテクチャ
- ディレクトリ構成と各モジュールの役割 → [architecture.md](architecture.md)

## コーディングルール
- 命名規則・コードスタイル → [code-style.md](code-style.md)

## 既知の問題・デバッグ
- 遭遇したエラーとその解決策 → [debugging.md](debugging.md)

# ビルド・テストコマンド

パッケージマネージャー: pnpm（npmは使わない）

## よく使うコマンド
- ビルド: `pnpm build`
- テスト: `pnpm test`（ローカルのRedisが必要 → localhost:6379）
- 型チェック: `pnpm typecheck`
- 開発サーバー: `pnpm dev`（ポート3000）

## デプロイ
- ステージング: `pnpm deploy:staging`
- 本番: `pnpm deploy:prod`（要MFA確認）

auto-memoryの設定と無効化

有効/無効の切り替え

{
  "autoMemoryEnabled": false
}

# 環境変数で無効化
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

# headlessモードで無効化（--bareフラグ）
claude --bare -p "query"
# --bareは auto-memory を含む複数の機能を無効化する

--bareフラグはauto-memory・Hooks・プラグイン同期・自動CLAUDE.md探索など複数の機能をまとめて無効化します。CI/CDや軽量実行に向いていますが、auto-memoryだけを無効にしたい場合はautoMemoryEnabled: falseを使ってください。

メモリ保存ディレクトリのカスタマイズ

autoMemoryDirectory設定で、メモリファイルの保存先を変更できます。デフォルトは~/.claude/projects/<project>/memory/ですが、任意のディレクトリに変更可能です。

{
  "autoMemoryDirectory": "~/my-memories/project-x"
}

CLAUDE.mdとauto-memoryの使い分け

チームで共有すべきルール（コードスタイル・禁止ツール・ブランチ戦略等）はCLAUDE.mdに書きます。そのプロジェクトを作業する中で積み上がる知識（コマンド・エラー解決・設計メモ等）はauto-memoryに任せます。両者を組み合わせることで、個人の学習とチーム共有のルールを分けて管理できます。

サブエージェントとauto-memoryの関係

通常、auto-memoryへの書き込みはメインのClaudeセッションが行います。サブエージェントを使う場合も、サブエージェントが実行された結果はメインセッションのコンテキストに戻ってくるため、メインセッションが判断してメモリに記録します。

そのため、サブエージェントに調査・分析を委任した内容も最終的にはauto-memoryに蓄積されます。「この調査結果をメモリに保存してください」とメインセッションで指示すれば、サブエージェントの成果物をメモリに記録できます。

まとめ

auto-memoryを活用すると、Claude Codeが作業のたびにプロジェクト固有の知識を蓄積し、次のセッションで文脈を引き継いでくれるようになります。設定は不要でv2.1.59以降では自動的に有効です。

• 保存場所は~/.claude/projects/<project>/memory/（マシンローカル）
• MEMORY.mdは先頭200行が毎セッション自動ロード。詳細はトピックファイルに分割
• /memoryコマンドでメモリの状態確認・編集・オン/オフの切り替えが可能
• autoMemoryEnabled: falseまたはCLAUDE_CODE_DISABLE_AUTO_MEMORY=1で無効化
• CLAUDE.md（チーム共有ルール）との違いを理解して使い分けることが重要

よくある質問