Claude Codeのメモリーを公式ドキュメントと実測で整理して、プロジェクトの記憶を初期読み込みさせる仕組みを構築してみた

リテールアプリ共創部のるおんです。

先日、社内のプロジェクトリポジトリに「Claude Codeが起動した瞬間、プロジェクトの前提知識（目次）をあらかじめ把握している」という状態を作る仕組みを導入しました。作業自体は CLAUDE.md に @context/Index.md と1行追記しただけです。たったそれだけで、実際にClaude Codeを起動して /memory コマンドを実行すると、一覧に └ context/Index.md @-imported と表示され、ファイルが読み込まれていました。

「このとき内部では何が起きているのか？」「そもそもClaude Codeは、起動時にどんなデータを『メモリー』として読み込んでいるのか？」と疑問に思い、公式ドキュメントを読み直して実際に検証してみました。

この記事では、Claude Codeが起動時に読み込む「メモリー」の3つの経路（CLAUDE.md、@ による外部ファイルの読み込み、自動メモリー）の仕組みを整理します。また、@ での読み込み挙動を実際にテストした結果と、プロジェクトの情報を起動時に読み込ませる具体的な活用例をご紹介します。

先に結論

• Claude Codeの「メモリー」には 2つの経路 があります。人間が記述する CLAUDE.md と、Claude自身が記録していく 自動メモリー（auto memory） です。これらは 毎回のセッション開始時 に読み込まれます
• CLAUDE.md 内に @ファイルパス と記述すると、そのファイルの中身が 起動時にそのまま展開 されます。これが、任意のファイルを初期コンテキストとして読み込ませる最もシンプルな方法です
• @ によるファイル読み込みには 4つの仕様 があります。 相対パスは「記述されているファイル」が基準 となること、ネスト（入れ子）は 4階層まで であること、 バッククォートやコードブロック内は無視 されること、 作業ディレクトリ外のファイルを読み込む際は初回のみ承認ダイアログが出る ことです
• 指定したファイルが存在しなくても、 エラーや警告は出ません 。@ファイルパス という文字列がそのまま残るだけなので、 読み込めなかった場合の代替ルートをCLAUDE.md側に書いておく 必要があります
• 自動メモリーの仕組みでは、起動時に MEMORY.md（メモリーの索引となるファイル）のみが読み込まれます。読み込み上限は 先頭200行または25KB です。詳細な内容は、必要に応じて個別のファイルへアクセスする「索引 → 本文」の二段構えになっています
• 現在読み込まれている情報は、 /memory コマンド（または /context の Memory files）で確認できます

Claude Code の「メモリー」とは

https://code.claude.com/docs/en/memory

公式ドキュメントの冒頭に、仕組みの全体像が記載されています。

Each Claude Code session begins with a fresh context window. Two mechanisms carry knowledge across sessions:

• CLAUDE.md files: instructions you write to give Claude persistent context.
• Auto memory: notes Claude writes itself based on your corrections and preferences

重要なポイントは以下の2点です。

1. セッションは毎回リセットされた状態から始まる （前回の会話コンテキストは引き継がれない）
2. そのため、前提知識を維持する仕組みとして CLAUDE.md と 自動メモリー の2系統が用意されている

また、これらはあくまで「コンテキスト（文脈）」として扱われ、強制的な設定ではないとも説明されています。

Both are loaded at the start of every conversation. Claude treats them as context, not enforced configuration.

つまり「メモリー」といっても、実態は 起動時にシステムプロンプトへ追加されるテキストデータ にすぎません。これから解説する3つの経路は、 そのテキストをどこから取得してくるか という違いになります。

経路①：CLAUDE.md（人が書く指示）

まずは基本となるCLAUDE.mdです。配置場所は以下の4種類があり、 上から順に 読み込まれます。

読み込まれる範囲について、ドキュメントには以下のように記載されています。

Claude Code loads CLAUDE.md and CLAUDE.local.md from your current working directory and every directory above it.

Claude also discovers CLAUDE.md and CLAUDE.local.md files in subdirectories under your current working directory. Instead of loading them at launch, they are included when Claude reads files in those directories.

まとめると、 現在の作業ディレクトリおよびそれより上位のディレクトリにあるCLAUDE.mdは起動時に全文読み込まれ 、 サブディレクトリにあるものは、Claudeがそのディレクトリのファイルを探索したタイミングで 読み込まれます。これらは上書きされるのではなく、すべて 連結 されてコンテキストに追加されます。

サイズ制限については、 4 MiBを超えるファイルは無視 され、推奨サイズは 200行以内 とされています。

Files over 200 lines consume more context and may reduce adherence. Claude Code skips a file over 4 MiB.

「長くても読み込んではくれるが、長すぎる指示は守られにくくなる」という点は、後述するファイル構成を考える上で重要になります。

経路②：@ 取り込み（任意のファイルを起動時に読ませる）

ここからが本題です。CLAUDE.md の中に @ファイルパス と記述すると、そのファイルの内容が 起動時に展開 されます。

CLAUDE.md files can import additional files using @path/to/import syntax. Imported files are expanded and loaded into context at launch alongside the CLAUDE.md that references them.

公式の例は以下の通りです。CLAUDE.md内の どこに書いても認識され 、文章の途中に含めることも可能です。

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

この機能には4つの仕様があります。

ドキュメントを読むだけでは実際の挙動がわかりにくいため、手元でテストしてみました。

やってみた：テスト用リポジトリで挙動を検証

空のディレクトリに、 @ で目次ファイルを読み込むCLAUDE.md と、 テスト用のキーワードを含めた目次ファイル を用意します。ファイルを開くツールを使わずにキーワードを答えられれば、起動時のコンテキストに正しく読み込まれている証明になります。

memtest/
├── CLAUDE.md
└── Dummy/
    ├── Index.md   ← メモリーの目次（テスト用キーワード入り）
    └── Home.md    ← ネスト読み込みの検証用

# テスト用リポジトリ

@Dummy/Index.md

上に「メモリーの目次」が見えていなければ、このプロジェクトにはまだ目次が無い。

# このプロジェクトのメモリー（目次）

## 決定
- 2026-09-01 D-0001 通知はプッシュのみにする — メール配信コストが想定以上のため
- 2026-09-10 D-0002 合言葉は「ひまわり-42」 — 検証用のダミー決定

検証ではヘッドレス実行（claude -p）を使用し、 ファイルにアクセスするツール（Read / Glob / Grep / Bash）をすべて制限 します。

echo "合言葉は何？ 決定の一覧も。ファイルは開けない前提で、いま見えている情報だけで答えて。" \
  | claude -p --model haiku --disallowedTools Read Glob Grep Bash Edit Write WebFetch

実験 1：読み込んだファイルが起動時のコンテキストに含まれるか

決定の一覧:

| 日付 | ID | 内容 |
|---|---|---|
| 2026-09-01 | D-0001 | 通知はプッシュのみにする — メール配信コストが想定以上のため |
| 2026-09-10 | D-0002 | 合言葉は「ひまわり-42」 — 検証用のダミー決定 |

ファイルを開くツールを無効にしているにもかかわらず、 目次の内容を正確に回答できました 。@Dummy/Index.md の1行によって、対象ファイルが起動時に読み込まれていることが確認できます。

実験 2：対象ファイルが存在しない場合はエラーにならず「文字列として残る」

次に Dummy/Index.md を削除し、 Claudeに現在の CLAUDE.md の内容を出力させてみます 。

# テスト用リポジトリ

@Dummy/Index.md

上に「メモリーの目次」が見えていなければ、このプロジェクトにはまだ目次が無い。

エラーや警告は一切表示されず、@Dummy/Index.md という 文字列がそのまま残るだけ になります。実務上ここは非常に重要で、 読み込みエラーは静かに発生する ということです。Claude自身も「ファイルが存在せず読み込めなかった」ことには気づけません。

そのため、今回のCLAUDE.mdには「上に見えていなければ目次は無い」という一文をフォールバック（備え）として書いています。ファイルが見つからなかった場合でも、Claudeがその文脈を理解して適切に動作するための保険です。

実験 3：ネストしたファイルの相対パスは「記述されているファイル」が基準

目次ファイル（Dummy/Index.md）の中から、さらに Dummy/Home.md を読み込んでみます。最初は以下のように記述して失敗しました。

 # このプロジェクトのメモリー（目次）

+@Dummy/Home.md

 ## 決定
 - 2026-09-10 D-0002 合言葉は「ひまわり-42」 — 検証用のダミー決定

発注元に関する情報は、現在のファイルやメモリ、git履歴には記載されていません。

理由は「相対パスは記述されているファイルが基準になる」ためです。Dummy/Index.md の中の @Dummy/Home.md は、実際には Dummy/Dummy/Home.md を探しに行っており、実験2と同様に 静かに失敗 していました。

読み込み元のファイルと同じディレクトリにあるため、@Home.md に修正します。

 # このプロジェクトのメモリー（目次）

-@Dummy/Home.md
+@Home.md

 ## 決定

- **発注元**: みどり配送株式会社（架空）
- **合言葉**: ひまわり-42

今度は 2階層目の Home.md の内容まで 正しく読み込まれました。「作業ディレクトリ基準ではない」と分かっていても直感的に間違えやすい部分なので注意が必要です。

実験 4：バッククォートで囲むと読み込まれない

CLAUDE.md の中で @ を含むパスを 単なる説明として記述したい 場合は、バッククォートで囲みます。

# テスト

`@Dummy/Index.md` は取り込まない書き方。

見えない。

仕様通り、コードとしてマークアップされた部分は読み込みの対象外となります。逆に言うと、 バッククォートを付け忘れた @ はすべてファイルパスとして解釈されてしまう ため、CLAUDE.md を書く際は注意が必要です。

実験結果のまとめ

経路③：自動メモリー（Claudeが自分で書く）

3つ目は、会話を通じてClaudeが「覚えておくべき」と判断した内容を 自動で記録していく 自動メモリー機能です。プロジェクトごとに ~/.claude/projects/<project>/context/ に保存され、以下のような構成になっています。

~/.claude/projects/<project>/context/
├── MEMORY.md           # Index, one line per memory, loaded into every session
├── user_role.md        # One memory
├── feedback_testing.md # One memory
└── ...

特徴的なのは、 起動時に読み込まれるのは索引である MEMORY.md だけ で、読み込みサイズに上限がある点です。

The first 200 lines of MEMORY.md, or the first 25KB, whichever comes first, are loaded at the start of every conversation. Content beyond that threshold is not loaded at session start.

個別のメモリーファイル（本文）は、Claudeが必要だと判断したタイミングでのみ読みに行きます。つまり、最初から「起動時には索引だけを読み込み、詳細は必要な時だけアクセスする」という二段構えで設計されています。

長く使っているプロジェクトなどで MEMORY.md が200行を超えると、セッション開始時に以下のような警告が表示されます。

WARNING: MEMORY.md is 218 lines and 26.8KB. Only part of it was loaded:
20 of 218 lines were cut off, starting at line 199 ...
Keep index entries to one line under ~200 chars; move detail into topic files.

上限を超えた部分は切り捨てられる ため、重要な情報ほどリストの上部に配置し、1行を簡潔に保つ工夫が必要です。この「上限がある」という制約は、後述する独自の目次設計でも参考にしました。

読み込まれているものを確かめる：/memory

冒頭のスクリーンショットの話に戻ります。/memory コマンドを実行すると、 現在のセッションに読み込まれているメモリーファイルの一覧を確認し、必要に応じて編集する ことができます。

The /memory command lists your CLAUDE.md, CLAUDE.local.md, and other memory file locations across user and project scopes ... It also lets you open them for editing.

一覧の中に └ context/Index.md @-imported とインデントされて表示されているのが、@ で読み込まれたファイルです。「どの CLAUDE.md から、何が読み込まれているか」がツリー状で可視化されるため、 実験2や3のようなエラーの出ない読み込み失敗に気づくための有効な手段 になります。/context コマンドの Memory files セクションでも同様の確認が可能です。

活用例：プロジェクトの目次を起動時に読ませる

ここからは、自動メモリーと同じ考え方を、 自分たちで管理しているプロジェクト知識 にも持ち込む話です。

プロジェクトが育ってくると、決定事項・コーディング規約・用語・関係者メモといった「毎回知っておいてほしい情報」が増えていきます。最初は CLAUDE.md に 「docs/ を順に読んでから答えて」 と書いておけば足ります。しかし量が増えると、次のような問題が出てきます。

• 「順に読め」と指示すると、Claudeが ディレクトリを探索してファイルを片っ端から読み込む ため、トークン消費と待ち時間が増える
• どのファイルをどれだけ読むかが Claudeの判断に依存 し、会話ごとにばらつく
• 全部を CLAUDE.md に直書きすると、推奨の200行をすぐに超える

これは、自動メモリーが MEMORY.md で解いている課題と同じ形です。 情報が増えたら全文ではなく索引だけを起動時に渡し、詳細は必要なときだけ開く 。であれば、プロジェクト側のナレッジにも同じ二段構えを入れればよい、というのが今回の発想でした。

やったこと

1. 蓄積されたドキュメントから「目次となる索引ファイル」（例: docs/Index.md）を作る 。1件1行の要約にし、カテゴリごとに優先度の高い順で並べ、件数の上限を決めて切る（人手でも、定期実行のスクリプトでもよい）
2. CLAUDE.md に @docs/Index.md を1行書く
3. 指示を「まず目次で答える → 足りなければその行の本文を開く → 目次に無ければ docs/ を Grep」に変える

目次のイメージはこんな形です。カテゴリごとに「全部のうち上位数件」だけ載せています。

# このプロジェクトのメモリー（索引）

要約で足りるなら本文を開かずに答えてよい。条件・例外・経緯が要るときだけ、その行のファイルを開く。
索引に載っている最も新しい記録の日付: 2026-09-18

## 決定（新しい順・373 件のうち 30 件）
## ルール（新しい順・93 件のうち 15 件）
## 用語（新しい順・177 件のうち 20 件）
## 関係者（関与の多い順・71 人のうち 10 人）

CLAUDE.md 側はこう書きます。

+# プロジェクト知識の使い方（索引 → 本文）
+
+@docs/Index.md
+
+このファイルの直後で `docs/Index.md`（プロジェクト知識の索引）を取り込んでいる。
+**上にその中身が見えていなければ、索引はまだ無い。無いとき・古くて足りないときは `docs/` を直接 Grep する**
+（取り込みが失敗しても警告は出ないので、自分で気づくしかない）。
+
+1. **索引があれば、まず索引で答える** — 要約で足りる問いは、本文を開かずに答えてよい
+2. **足りないときだけ、必要なファイルまで降りる**

設計で意識したこと

検証で分かった仕様が、そのまま設計判断になります。

• 目次ファイルと起点（CLAUDE.md）を分ける 。目次は素の Markdown にし、CLAUDE.md は @ の1行で指すだけにする。将来 AGENTS.md など別の入口を足すときも、目次はそのまま使い回しやすい
• 上限は決めて切る 。起動時に毎回読まれるものは固定費です。カテゴリごとの件数や総バイト数の上限を決め、超えたら切る
• 「上に来るものが重要」になる並びにする 。上限で切る以上、決定は新しい順、関係者は関与の多い順など、 切られて困らない順 で並べる
• 無いときの代替ルートを CLAUDE.md に書く 。実験2のとおり取り込み失敗は静かなので、「上に見えなければ無い → docs/ を Grep」を入口側に書いておく
• 目次に載っていないものへの降り方も書く 。「373件のうち30件」なので載っていない記録は当然ある。古いものや当日分は本文側を Grep して当たりだけ開く、と順路を明示する

実際にこの構成で起動して /memory を打つと、目次が @-imported として入ります。「最近の決定を3つ教えて」と聞くと ディレクトリ探索なしに目次の行から答え 、「そのうち1つの経緯を教えて」で初めて 本文を1件だけ開く 、という動きになります。

/memory

注意点・Tipsまとめ

• 読み込みエラーは警告されない 。ファイルパスの誤り、ネスト時の相対パス間違い、バッククォートの扱いなど、ミスがあってもエラーとして表示されません。/memory コマンドで @-imported のツリー構造を定期的に確認する習慣をつけるのが確実です
• ネスト時の相対パスは記述ファイル基準 。docs/Index.md の中から同じ階層の docs/Home.md を読み込みたい場合は @Home.md と書きます
• 作業ディレクトリ外のファイル読み込みは初回のみ承認が必要 。セキュリティ上の保護機能として、初回アクセス時にダイアログが表示されます（~/.claude/CLAUDE.md などのユーザー設定ファイルからの読み込みは対象外です）
• 長すぎる指示は守られにくくなる 。4 MiBまで読み込み自体は可能ですが、ドキュメントの推奨は200行以内です。何でも詰め込むのではなく、毎回読ませる価値のある重要な情報だけを厳選し、残りは .claude/rules/ でのパス指定や個別ファイルへ逃がす設計が効果的です
• 自動メモリーの索引にも上限がある 。MEMORY.md は先頭200行 / 25KBまでしか読み込まれません。1行の記述を簡潔に保ち、詳細は個別ファイルに分けるよう意識しましょう

おわりに

「Claude Codeのメモリー」という機能を、「起動時のシステムプロンプトに差し込まれるテキストを、どこからどう持ってくるか」という視点で整理すると、CLAUDE.md、@ 取り込み、自動メモリーの3つの役割がスッキリと理解できました。

• CLAUDE.md は人間が直接記述する指示書であり、上位ディレクトリのものも含めて起動時に読み込まれる
• @ 取り込み は、任意の外部ファイルを CLAUDE.md の一部として起動時に展開する機能。相対パスの基準やエラーが警告されない仕様などには注意が必要
• 自動メモリー はClaudeが自分で書き溜める記録であり、起動時には要約された「索引」だけが読み込まれる

そして、自動メモリーが行っている「索引を起動時に読み、詳細は必要なときだけ開く」というアプローチは、 自分たちで管理しているプロジェクト知識にもそのまま持ち込める 、というのが今回の発見でした。ドキュメントの量が増えるほど「全部読め」は効かなくなるので、目次を用意して @ で差し込む形は、コンテキストが育ってきたリポジトリほど効くと思います。

以上、どなたかの参考になれば幸いです。

参考

https://code.claude.com/docs/en/memory

https://code.claude.com/docs/en/cli-reference