1. これは何の話？

Claude Codeの公式ドキュメントが、エージェントのメモリ管理機能を体系的に整理したページを公開している。コーディングエージェントを日常的に活用する開発者に向け、セッションをまたいで知識を引き継ぐ仕組みを理解するための参照先となる。

Claude Codeのメモリ階層と各管理ファイルの役割

Claude Codeのメモリは大きく2種類に分類される。Claudeが自動的に情報を保存・管理する「オートメモリ」と、開発者が手で書いて管理する「CLAUDE.mdファイル」だ。この2つはどちらか一方ではなく、用途に応じて組み合わせて使うことが推奨されている。

2. 何がわかったか

オートメモリとは、Claude Codeがセッション中に有益なコンテキストを自動で保存する機能だ。保存される情報には、ビルドコマンドやテスト規約などのプロジェクトパターン、デバッグで得た知見、アーキテクチャ上の重要なファイルや関係性、コミュニケーションスタイルや使用ツールなどのユーザー設定が含まれる。

保存先は~/.claude/projects/<project>/memory/以下のディレクトリで、概要を示すMEMORY.mdと、debuggingやapi-conventionsなどのトピック別ファイルで構成される。MEMORY.mdに記載された一定のコンテキストが毎セッション開始時のシステムプロンプトに展開される仕様だ。トピック別ファイルは起動時には読み込まれず、Claude Codeが必要に応じてオンデマンドで参照する。

/memoryコマンドで直接編集できるほか、autoMemoryEnabled: falseを~/.claude/settings.jsonに設定すれば無効化もできる。

3. 他とどう違うのか

従来のペルソナ記憶（チャットツール的なアプローチ）は、会話ログを積み上げて文脈を保つものだった。Claude Codeのオートメモリは、その情報を構造化されたファイルとして明示的に管理する点が異なる。開発者はMEMORY.mdを自分で確認・編集でき、不要な情報を削除したり優先順位を変えたりできる透明性がある。

CLAUDE.mdをチームで共有し、CLAUDE.local.mdを個人設定に使う分離も用意されている。チームの規約とエンジニア個人の嗜好を別管理できる設計だ。

4. なぜこれが重要か

エージェントの最大の課題の一つが「毎回同じ説明から始める」コンテキストロスだ。ビルドコマンドやコードスタイル、過去のデバッグで得た知見を毎セッション再入力することなく引き継げるなら、開発サイクルの効率は実質的に上がる。

.claude/rules/によるモジュール化は、大規模なプロジェクトや複数人開発での問題—CLAUDE.mdが肥大化してメンテしにくくなる問題—を事前に回避する設計だ。

5. 未来の展開・戦略性

pathsフィールドを使ったパス限定ルールは、フロントエンドとバックエンドで異なるコーディング規約を持つプロジェクトや、APIファイルだけに特別なルールを適用したいケースにとって実用的な機能だ。今後、組織レベルのメモリ管理（Organization-level memory management）として記述されているように、チーム・組織単位でのルール共有の仕組みも設計に組み込まれている。

~/shared-claude-rulesをシムリンクで参照できるシンボリックリンク対応も、複数リポジトリ・複数チームへ共通ルールを配布する運用を可能にする。

6. どう考え、どう動くか

Claude Codeを使い始めたばかりの段階では、まず/initコマンドでプロジェクト向けのCLAUDE.mdを生成し、よく使うコマンドと命名規則を記録することが出発点になる。オートメモリは黙って動いているので、定期的にMEMORY.mdを覗いてClaudeが何を学んでいるか把握するとよい。

指針：

  • プロジェクトルートで/initを実行し、ビルド・テスト・lintコマンドをCLAUDE.mdに記録する。
  • コード規約が複数のディレクトリに分かれるなら、.claude/rules/にトピック別ファイルを作ってモジュール化する。
  • ~/.claude/projects/<project>/memory/MEMORY.mdを週1回確認し、古い情報や誤った学習を手動で整理する。

次の一歩：

  • 今日やること：現在のプロジェクトでCLAUDE.mdとオートメモリフォルダの存在を確認し、ないなら/initで初期化する。
  • 今週やること：.claude/rules/にtest.mdとcode-style.mdを作り、チームのルールを分離して管理する仕組みを導入する。

7. 限界と未確定

  • MEMORY.mdの読み込み量には上限があるため、情報が増えると重要な記録が自動的に読まれなくなる可能性がある。
  • 組織レベルのメモリ管理の詳細（管理者による中央集権的な配布方法など）はドキュメント上では記述が薄い。
  • オートメモリが何をどのタイミングで書き込むかの詳細なアルゴリズムは非公開だ。

8. 用語ミニ解説

  • ファイルやディレクトリに別名でアクセスするための参照ファイル。（シムリンク / Symbolic Link）

9. 出典と日付

Claude Code Docs（最終確認日：2026-02-28）：https://code.claude.com/docs/en/memory