Claude Code Auto Memory & Auto Dream実践ガイド — メモリ設計と運用でセッション間の学習を最大化する

「昨日説明したのに、今日また同じことを聞かれる」——Claude Codeとの作業で最も多い不満がセッション間のコンテキスト喪失だ。Auto Memory（v2.1.59〜）とAuto Dreamは、この問題に対するClaude Codeの回答である。AIが自律的に記憶を蓄積・整理し、次のセッションで「あなたのこと」を覚えている。本記事では、メモリがどう書かれ、どう整理され、どう活用されるかを時系列で追いながら、実プロジェクトで運用するための設計パターンと肥大化防止戦略を解説する。

Auto Memoryの仕組み — いつ・何が・どこに保存されるか

メモリが発火する4つのトリガー

Auto Memoryは常にバックグラウンドで動いているわけではない。以下の4つの場面でメモリ保存が発火する。

1. ユーザーの明示的な指示 — 「これを覚えて」「次回から〜して」と伝えた場合
2. ユーザーの修正 — 「そうじゃなくて」「〜はやめて」といったフィードバック
3. 非自明なアプローチの成功 — ユーザーが受け入れた提案のうち、コードから自明でないもの
4. プロジェクト文脈の学習 — 外部リソースの場所、進行中のイニシアティブ、期限などの情報

重要なのは、コードから導出可能な情報は保存しないという設計思想だ。アーキテクチャ、ファイルパス、git履歴、デバッグ手順などはメモリに書かず、毎回コードを直接読む。これにより、メモリの陳腐化リスクを最小限に抑えている。

メモリの4タイプ（user / feedback / project / reference）

保存されるメモリには4つのタイプがあり、それぞれ用途が異なる。

特に feedback タイプは、単なるルールではなく rule → Why → How to apply の3層構造で保存される。「なぜそうするのか」が含まれるため、エッジケースでも適切に判断できる。

MEMORY.mdインデックスと個別ファイルの2層構造

メモリの保存先は ~/.claude/projects/<project-path-hash>/memory/ ディレクトリだ。メモリは 個別ファイル + インデックス の2層構造で管理される。

個別メモリファイルの実例:

---
name: testing-approach
description: インテグレーションテストではDBモックを使わない方針
type: feedback
---

インテグレーションテストでは実DBを使い、モックは使わない。

**Why:** 前四半期にモックテストがパスしたが本番マイグレーションで障害が発生した。
**How to apply:** テストファイルでDB接続をモックしている箇所を見つけたら、
実DBに差し替えるよう提案する。

そして MEMORY.md はインデックスとしてのみ機能する:

- [testing-approach](memory/feedback_testing.md) - テストでDBモックを使わない方針
- [user-profile](memory/user_role.md) - Go熟練・React初心者の開発者
- [auth-rewrite](memory/project_auth_rewrite.md) - 認証ミドルウェア刷新の背景

MEMORY.md は会話コンテキストに常時ロードされるが、最初の200行または25KBのいずれか先に達した方が上限となり、超過分は切り捨てられる。メモリ本文を直接 MEMORY.md に書いてしまうと、すぐに上限に達する。必ずポインタだけを記述すること。

Auto Dreamの整理メカニズム — セッション間で記憶が洗練される過程

Auto Dreamは、セッション終了時にメモリの整理・統合を行う仕組みだ。なお、2026年4月時点ではAuto Dreamはまだ全ユーザーに正式リリースされておらず、サーバーサイドのフィーチャーフラグで段階的にロールアウトされている段階である。そのため、環境によってはこの機能が利用できない場合がある。人間が寝ている間に記憶が整理されるように、Claude Codeもセッション間でメモリを洗練させる。

相対日付→絶対日付変換と時間耐性の確保

ユーザーが「木曜日からマージフリーズ」と言った場合、そのまま保存すると翌週には意味不明になる。Auto Dreamはこれを 2026-03-05 のような絶対日付に変換して保存する。正直、この機能に気づいたときは「そこまでやるのか」と感心した。

とはいえ、変換が漏れるケースもゼロではない。メモリに日付情報を含める際は、最初から絶対日付で伝えるのが確実だ。

トピック別ファイル統合と重複排除

同じトピックについて複数回会話すると、メモリファイルが増殖する。Auto Dreamはこれを検知し、関連するメモリを1ファイルに統合する。

統合前（3ファイルに分散）:

memory/
├── project_auth_session_tokens.md   # セッショントークンの保存方式
├── project_auth_compliance.md       # コンプライアンス要件
└── project_auth_deadline.md         # 認証リライトの期限

統合後（1ファイルに集約）:

memory/
└── project_auth_rewrite.md          # 認証リライト: 背景・要件・期限を統合

これにより MEMORY.md のインデックス行数も3行から1行に削減される。

古いメモリの自動検証と削除判断

メモリが参照するファイルや関数が削除されている場合、そのメモリに基づく推奨は誤りになる。Auto Memoryの設計では、メモリを参照する際に現在のコード状態と照合し、存在を検証してから推奨する。

覚えておくべき原則がある:

「メモリにXがある」は「今もXが存在する」を意味しない。

メモリはあくまで「ある時点での事実」であり、推奨の前には必ず現状が確認される。完了したプロジェクトや、もう存在しないリソースへの参照は、Auto Dreamの整理サイクルで削除対象となる。

CLAUDE.mdとメモリの使い分け判断フロー

CLAUDE.mdに書くべきこと vs メモリに任せるべきこと

両者は明確に役割が異なる。

判断フローチャート

迷ったときは以下の順で判断する:

1. コードやgit履歴から読み取れるか？ → Yes: どちらにも書かない
2. チームの全員が従うべきルールか？ → Yes: CLAUDE.mdに書く
3. 個人の好み・作業文脈か？ → Yes: メモリに任せる
4. 外部リソースの場所か？ → メモリの reference タイプに保存

例えば「テストは vitest で書く」はCLAUDE.md、「自分はテストを先に書く派」はメモリだ。

実践：メモリディレクトリ設計とファイル命名規約

推奨ディレクトリ構造

メモリは ~/.claude/projects/<project-path-hash>/memory/ に保存される。ファイル名は <type>_<topic>.md の命名規約を推奨する。

~/.claude/projects/-Users-you-project/memory/
├── user_role.md                    # ユーザーの役割・スキルセット
├── user_preferences.md             # コードスタイルの好み
├── feedback_testing.md             # テスト方針のフィードバック
├── feedback_pr_style.md            # PRの粒度に関するフィードバック
├── project_auth_rewrite.md         # 認証リライトの背景と期限
├── reference_monitoring.md         # 監視ダッシュボードの場所
└── reference_ticket_tracking.md    # チケット管理ツールの情報

メモリの肥大化を防ぐ3つのルール

1. MEMORY.md の上限（200行/25KB）を常に意識する — description は1行に収め、統合できるメモリは積極的にまとめる
2. project タイプは完了したら削除する — マージフリーズの期限が過ぎた、リライトが完了した等のメモリは不要になる
3. 定期的に参照先の存在を確認する — メモリが指すファイルや関数が今も存在するか、月1回程度チェックする

メモリは意味（セマンティック）で整理し、時系列では整理しない。「3月の出来事」ではなく「認証に関する知見」でグルーピングすることで、検索性と統合しやすさを両立できる。

チーム開発でのメモリ共有パターン

メモリをCLAUDE.mdにPromoteするワークフロー

メモリは ~/.claude/ 配下に保存されるため、git管理外であり直接の共有はできない。これは意図的な設計だ。チームで共有すべき知見は、メモリからCLAUDE.mdへ「昇格（Promote）」させる運用が前提となる。

昇格を判断するチェックリスト:

新メンバーオンボーディングでのメモリ活用

新メンバーが初日から蓄積された文脈を得るには、CLAUDE.mdの充実が鍵になる。メモリは個人に閉じているため、チームの知見をCLAUDE.mdに昇格させておくことで、新メンバーのClaude Codeも初回セッションからプロジェクトの文脈を理解した状態で動作する。

個人的には、この「メモリで検証 → CLAUDE.mdに昇格」のサイクルが回り始めると、CLAUDE.mdの品質が目に見えて上がっていく実感がある。

よくあるハマりポイントと対策

メモリが古くなって誤った推奨をするケース

メモリが「src/auth/middleware.ts の validateSession 関数を修正する」と記録していても、リファクタリングでファイルが移動・削除されていれば、その推奨は誤りになる。

Auto Memoryの設計では、メモリ参照時にファイルパスや関数名の存在を検証してから推奨する仕組みになっている。ただし100%ではないため、メモリに基づく推奨を受けたときは、その対象が現在も存在するか意識しておくとよい。

MEMORY.mdが上限を超えて切り捨てられる問題

MEMORY.md が200行または25KBを超えると、後半のメモリはコンテキストに読み込まれない。つまり、せっかく保存したメモリが存在するのに参照されない状態になる。

対策:

• description を可能な限り短くする（1行30文字以内が目安）
• 同一トピックのメモリは統合してインデックス行数を減らす
• 完了した project タイプのメモリは定期的に削除する

「覚えて」と言っても保存されないケース

「このファイルの構造を覚えて」「アーキテクチャを記憶して」と伝えても、保存されないことがある。これはバグではなく、コードから導出可能な情報は意図的に保存しない設計だ。ファイル構造やアーキテクチャは、次のセッションでもコードを読めば分かる。メモリに保存すると陳腐化のリスクだけが増える。

保存してほしい場合は、コードからは読み取れない「なぜその構造にしたか」「どんな制約があったか」といった背景情報として伝えると、メモリに残りやすい。

Auto MemoryとAuto Dreamは、Claude Codeを「使い捨てのAIツール」から「プロジェクトを理解するパートナー」に変える仕組みだ。ただし、Auto Dreamは2026年4月時点でまだ段階的ロールアウト中であり、利用できない環境もある点に注意してほしい。メモリは万能ではない。コードから読み取れる情報はメモリに頼らず毎回読む設計であり、チーム共有が必要な知見はCLAUDE.mdに昇格させる運用が欠かせない。MEMORY.md の上限（200行/25KB）を意識したインデックス設計と、定期的な棚卸しによるメモリ品質の維持が、長期運用の鍵となる。まずは Auto Memory を有効化し、1週間の自然な蓄積から始めてみてほしい。