「このプロジェクトはNext.jsで、FSDアーキテクチャで、パッケージマネージャーはBunで、Linterはbiomeで...」——セッションを起動するたびにこの説明から始めていないか。
それが不要になった。
Claude Codeはv2.1.59から、auto-memoryという仕組みを持つ。Claudeが自分でプロジェクトの学習内容を記録し、次のセッションで自動的に読み込む。「覚えておいて」と言う必要もなく、ClaudeがClaude自身で引き継ぎメモを残す。
この記事では、auto-memoryの実態と、それを支えるcontext compaction・ディスク永続化の仕組みを整理する。設定ファイルの詳しい書き方より、「何がどこで何をやっているか」の全体像を把握することが目的だ。
CLAUDE.mdだけでは足りなかった理由
まず、これまでの仕組みを整理する。
Claude CodeにはCLAUDE.mdというファイルがある。プロジェクトのルール・アーキテクチャ・コードスタイルをここに書いておくと、毎セッションの冒頭でClaudeが読み込む。チームで共有できるし、gitで管理できる。
ただし、CLAUDE.mdには構造的な限界があった。
長いセッションでCLAUDE.mdの効果が薄れる
Claude Codeを数時間使い続けると、会話の履歴がどんどん積み上がる。コマンドの出力、読み込んだファイルの内容、長いエラーログ。これらが「コンテキストウィンドウ」と呼ばれるAIの作業メモリを圧迫する。
問題は、会話中に「こういう方針で行こう」「このファイルはこういう役割だよ」と伝えた内容は、コンテキストが溢れると消えることだ。
対して、CLAUDE.mdはディスクから読み込むファイルなので、コンテキストが圧縮されても再注入される。つまり「ファイルに書いたこと」は生き残るが、「会話で伝えたこと」は消える。
CLAUDE.mdに書いていないプロジェクト固有の知見——たとえば「このバグは環境変数の順序に起因する」「このAPIは必ずキャッシュが必要」といった経験的な情報——は、会話の中で伝えるしかなかった。そしてそれは長いセッションの後、消えていた。
CLAUDE.mdは人間が書くもの
もう一つの限界は、CLAUDE.mdはあくまで人間が手動で書くものだという点だ。
Claudeがデバッグ中に「ああ、このプロジェクトはトランザクションをこう扱っているのか」と気づいたとしても、それをCLAUDE.mdに書いてくれるわけではない。次のセッションでは、また一から気づき直すことになる。
auto-memoryはこの問題を解決する。
auto-memoryとは何か
auto-memoryを一言で言えば、「ClaudeがClaude自身のために残す引き継ぎメモ」だ。
CLAUDE.mdが「就業規則」（チームが決めたルール）なら、auto-memoryは「先輩が新入りに渡す引き継ぎメモ」だ。就業規則には書かれていないが、仕事を円滑に進めるために知っておくべきこと——よく発生するバグのパターン、特定のライブラリの癖、暗黙のコード規約——をClaudeが自分で記録する。
保存される内容
公式ドキュメントによると、Claudeが自動保存するのは主に以下の内容だ：
- ビルドコマンドやテスト手順
- デバッグで判明した技術的な知見
- アーキテクチャの理解（どのファイルが何の役割か）
- コードスタイルや好みのパターン
- 繰り返し使うワークフローの習慣
ユーザーが「覚えておいて」と指示した場合も、この仕組みで保存される。ただし「CLAUDE.mdに追記して」と明示した場合はCLAUDE.mdに書かれるので、チーム共有したい情報はその書き方を使う。
ファイルの保存場所
auto-memoryのファイルは ~/.claude/projects/<プロジェクト名>/memory/ に保存される。<プロジェクト名> の部分はgitリポジトリのルートパスから自動的に決まる。
# CLAUDE.mdだけの時代
~/.claude/CLAUDE.md ← 自分で書いたユーザーレベルのルール
./CLAUDE.md ← プロジェクトのルール（git管理）
# auto-memory追加後
~/.claude/CLAUDE.md
./CLAUDE.md
~/.claude/projects/myapp/memory/
├── MEMORY.md ← Claudeが学んだこと（毎セッション先頭200行を自動ロード）
├── debugging.md ← デバッグパターン（必要時に読む）
└── build-notes.md ← ビルドの知見（必要時に読む）
200行制限の意味
MEMORY.mdは毎セッションの冒頭で自動的に読み込まれるが、読まれるのは先頭200行だけだ（それ以降は切り捨てられる）。これはシステムプロンプトを肥大化させないための制約だ。
debugging.md のようなトピックファイルは、Claudeが「必要だ」と判断したときだけ読みに行く。常に全部読むわけではない。このため、「重要度の高い学習内容」はMEMORY.mdの先頭に集約され、詳細情報は別ファイルに分散される構造になっている。
MEMORY.mdが200行を超えると、後半の内容は毎セッション読み込まれなくなる。Claudeが自動管理してくれるが、「覚えさせた内容が反映されない」と感じたら /memory コマンドで内容を確認するといい。
/memory コマンドで管理する
Claude Codeのターミナルで /memory とタイプすると、現在保存されているメモリの内容を確認・編集・削除できる。
# セッション内でauto-memoryの内容を確認・管理
> /memory
Claudeがメモリを読み書きするとき、「Writing memory」「Recalled memory」というメッセージが表示される。何が記録されているか分からなくなったり、誤った情報が保存されてしまったりした場合は、このコマンドで直接確認・修正できる。
auto-memoryを使いたくない場合の無効化方法は複数ある：
# セッション内でトグル
> /memory
# プロジェクト設定（.claude/settings.json）で無効化
{ "autoMemoryEnabled": false }
# 環境変数で無効化
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
context compactionの仕組み
auto-memoryとは別に、長いセッションを支えるもう一つの仕組みが「context compaction」だ。
先に「コンテキストウィンドウが圧迫される」と書いた。compactionはその問題への直接的な解決策だ。
「カバンの荷物を付箋1枚にまとめる」
長い開発セッションで会話履歴が溜まってくると、「実行済みのコマンド出力」「解決済みのバグのやりとり」「途中で読み込んだファイルの内容」がカバンを圧迫する。これらの多くは、今後の作業には直接関係ない「済んだこと」だ。
compactionは、これらを「今日はここまでやった、現在地はここ」という1枚の付箋にまとめる。古いメッセージを削除し、そのエッセンスだけを残す。
公式ドキュメントによると、具体的な流れはこうだ：
- Claudeが会話全体を分析する
- 過去のやりとり・決定事項・コード変更の簡潔なサマリーを作成する
- 古いメッセージをサマリーで置換する
- CLAUDE.mdをディスクから再読み込みして再注入する
自動トリガーと手動コンパクション
コンテキストウィンドウ容量の約95%に達したとき、compactionは自動で実行される。v2.0.64からは圧縮処理が即時完了するようになり、以前のような待機時間がなくなった。
手動でも実行できる：
# 手動でコンパクション実行
/compact
# 何を保持するかフォーカスを指定（例：APIの変更点に集中）
/compact APIの変更点に集中して
# 環境変数でトリガー閾値を変更（デフォルト95%）
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80
/compact focus on the... の形式でフォーカスを指定すると、「何を重点的に要約に残すか」をClaude に指示できる。長い作業の途中で「今日の前半の内容を圧縮して後半に集中したい」という場面で使う。
compactionとauto-memoryは別物
混同しやすいが、2つは全く別の仕組みだ。
auto-memoryは「セッションをまたいで記憶を持続させる仕組み」。compactionは「今のセッション内でコンテキストが溢れないようにする仕組み」。目的が違う。
ディスク永続化と50K閾値
コンテキスト管理のもう一つの改善が、ツール実行結果のディスク永続化だ。
Claudeがコマンドを実行したり、ファイルを読んだりすると、その出力がコンテキストウィンドウに積み上がる。大きなログファイルを読んだり、長いコマンド出力が出たりすると、それだけで相当なスペースを食う。
v2.1.51から、50,000文字（約50K文字）を超えるツール実行結果はディスクに書き出され、参照形式でコンテキストウィンドウに保持されるようになった（以前は100K文字が閾値だった）。
この変更の意味を日常的な比喩で言えば、「大きな資料を机の上に広げるか、棚に置いて必要なページだけ開くか」の違いだ。100ページの資料を全部机に広げると場所を取る。棚に置いて「棚の3番目の資料の42ページを参照」という形にすれば、机はすっきりする。
閾値を100K→50Kに引き下げたことで、「もっと早く棚に置く」ようになった。長い出力が出る作業でもコンテキストが圧迫されにくくなっている。
worktree間でのメモリ共有
git worktreeを使っている開発者にとって重要な変更が、v2.1.63で入った。
git worktreeとは、1つのリポジトリを複数のディレクトリとしてチェックアウトする機能だ。mainブランチとfeatureブランチを並行して作業するときなどに使う。以前は、worktreeごとに別々のメモリが作られていたため、あるworktreeで蓄積した学習が別のworktreeに引き継がれなかった。
v2.1.63からは、同じリポジトリの複数worktreeが1つの ~/.claude/projects/<プロジェクト>/memory/ を共有する。worktreeのパスではなく、gitリポジトリのルートから <プロジェクト> が決まるためだ。
並列開発をしている場合、mainブランチで学んだ「このプロジェクトのビルドはこういう癖がある」という知識が、featureブランチのworktreeでも使われる。
なお、auto-memoryはマシンローカルの仕組みだ。クラウドや他のマシンとは共有されない。チーム全体で知見を共有したい場合は、引き続きCLAUDE.mdをgitで管理するのが正しいアプローチだ。
使いこなしのTips
何を覚えさせるか
auto-memoryの自動判断に加え、意図的に記憶させた方がいい情報がある：
- 繰り返し発生するエラーとその解決パターン（「このエラーはnodeのバージョン違いが原因」など）
- プロジェクト固有のコマンドの使い方
- デプロイ前に必ず確認すること
「覚えておいて」と言えばauto-memoryに保存される。CLAUDE.mdに記録したい場合は「CLAUDE.mdに追加して」と明示する。
何を覚えさせないか
逆に、auto-memoryに記録させない方がいい情報もある：
- セッション固有の一時的な作業指示（「今日だけこのブランチで作業する」など）
- 実験的な試みで確定していない設計判断
- 大量のデバッグログや一時的なメモ
これらはMEMORY.mdを肥大化させ、重要な200行を圧迫する。/memory コマンドで定期的に内容を確認し、不要なものは削除する習慣が有効だ。
CLAUDE.mdとの使い分け
# ✅ CLAUDE.mdに書くもの（チームで共有、gitで管理）
- コーディング規約・アーキテクチャの方針
- 必須コマンド（bun run check-allなど）
- セキュリティルール・禁止事項
- 新メンバーへの説明
# ✅ auto-memoryに任せるもの（Claudeが自動記録）
- このプロジェクト特有のバグパターンと解決策
- ビルド・テストの癖
- よく参照するファイルの役割
- 蓄積されたデバッグの知見
サブエージェントとコンテキスト
Claude Codeはエージェントモードで複数の「サブエージェント」を並行して動かすことがある。公式ドキュメントによると、サブエージェントは独自のコンテキストウィンドウを持つ。サブエージェントの作業はメインセッションのコンテキストを消費しない。
長いエージェント作業でメインセッションのコンテキストが圧迫されにくいのは、この構造によるところも大きい。
まとめ
「毎回ゼロから説明」という地味な苦痛は、auto-memoryによって解消された。Claudeが自分でプロジェクトの学習を記録し、次のセッションで引き継ぐ仕組みが整った。
整理すると：
- auto-memory: Claudeがプロジェクトの知見をファイルに記録し、セッション間で引き継ぐ（
~/.claude/projects/<project>/memory/） - context compaction: 長いセッションでコンテキストが溢れないよう、古い履歴を自動的に要約する（セッション内限定）
- 50K永続化: 大きなツール実行結果をディスクに逃がしてコンテキストを節約する
- worktree共有: 同一リポジトリの複数worktreeが同じメモリを参照する
これらは全て、開発者が意識しなくても裏で動く仕組みだ。ただし /memory でその内容を確認し、定期的に整理する習慣があると、より精度が上がる。
AIに毎回「このプロジェクトは...」と説明し直すのではなく、Claudeが積み上げた文脈の上に乗って作業できる環境が、今はデフォルトになっている。
