Claude Codeのサブエージェントが毎回忘れる問題を解決｜memory: projectの設定と注意点

Claude Codeで同じサブエージェントを使っているのに、毎回プロジェクト構成やテスト方法を調べ直していませんか。memory: projectを設定すると、そのサブエージェント専用の引き継ぎノートをプロジェクト内に保存できます。ただし、設定するだけで正しい知識が自動的に増えるわけではありません。この記事では、実際に保存・再読・修正まで確認した結果と、安全に使う手順を説明します。

この記事は、カスタムサブエージェントを作り始めたものの、「前回の学びを次回へ残したい」「何を記憶させればよいか分からない」と困っている方に向いています。

先に結論：専用の引き継ぎノートを作れる

サブエージェントの定義ファイルへmemory: projectを追加すると、次の場所が専用メモリになります。

.claude/agent-memory/エージェント名/

今回の検証では、次の動作を確認できました。

・初回の実行でMEMORY.mdと詳細メモが作成された

・独立した2回目の実行で、元ファイルを読まずに保存済みメモから回答できた

・3回目の実行で、保存内容を修正できた

memory: projectは、確認した情報を専用Markdownへ残し、次の同名サブエージェントが読み直す仕組みです。AI生成の図解。

一方、初回には禁止したはずのローカル絶対パスも保存されました。メモリは便利な保存場所ですが、正しさや安全性を保証する仕組みではありません。

なぜ毎回同じことを調べ直すのか

通常のサブエージェントは、新しい独立した作業領域で起動します。

親のClaude Codeが少し前に読んだファイルや、それまでの会話をすべて持って起動するわけではありません。親側のAuto Memoryも、通常のサブエージェントには読み込まれません。

この仕組みにより、長い検索結果やログを親の会話へ流し込まずに済みます。しかし、プロジェクト固有の知識を残していなければ、次回も同じ調査が必要になります。

そこで、次回も使える確認済み情報だけを専用メモリへ残します。

・テストで使うコマンド

・重要なファイルと役割

・繰り返し発生する問題

・確定した設計判断

・レビューで必ず確認する項目

設定する手順

安全に試すには、設定、保存条件、初回確認、別セッションでの再読を順番に進めます。

1. サブエージェントの定義ファイルを用意する

プロジェクト内の.claude/agents/へ、用途が分かる名前のMarkdownファイルを置きます。

必要な設定は、エージェント名、使う場面、利用する道具、モデル、メモリの保存範囲です。

2. memory: projectを追加する

設定部分へmemory: projectを追加します。

これにより、.claude/agent-memory/エージェント名/が保存先になります。プロジェクト内のため、内容を確認したうえでGitによる共有も選べます。

3. 何を保存するか本文で指定する

1行を追加するだけでは、保存内容の品質を管理できません。サブエージェントの指示本文に、次の条件も書きます。

・作業開始前に自分のメモリを確認する

・今後も使える確認済み情報だけを保存する

・根拠となるリポジトリ相対パスと確認日を残す

・推測、途中経過、秘密情報、個人情報を保存しない

・ローカル絶対パスを保存しない

4. 初回実行後に保存内容を確認する

最初の作業が終わったら、MEMORY.mdと詳細メモを人間が開きます。

確認するポイントは次の通りです。

・元ファイルと一致する事実か

・情報の根拠が書かれているか

・確認日があるか

・APIキーや個人情報がないか

・端末固有の絶対パスがないか

5. 別セッションで再読を試す

新しいClaude Codeセッションを起動し、元ファイルを読ませずに、メモリだけから回答させます。

回答内容だけでなく、実行記録や読み取ったファイルも確認できると、元ファイルを再調査したのか、保存済みメモを使ったのかを区別できます。

実際の検証結果

Windows、Claude Code 2.1.160、Claude Opus 4.8の環境で、検証専用のmemory-project-verifierを作りました。

確認させたのは、ブログ作成プロジェクトで有効な投稿先に関する公開可能な情報です。

初回の実行では、元のAGENTS.mdを読み、確認した事実を次の2ファイルへ保存しました。

・MEMORY.md：メモリ全体の短い索引

・project_active_platforms.md：事実、根拠、確認日を記録した詳細メモ

独立した2回目の実行では、元のAGENTS.mdを読まないよう指示しました。サブエージェントは上記2ファイルだけを読み、保存した内容を正しく回答しました。実行記録でも、読み取ったのがメモリ2ファイルだけであることを確認しています。

これにより、別セッションでもプロジェクト専用メモリを再利用できることを確認できました。

失敗例：禁止した絶対パスを覚えていた

保存と再読には成功しましたが、詳細メモにはローカル環境の絶対パスが残っていました。

サブエージェントの定義には「端末固有のパスを保存しない」と書いていました。しかし、初回タスク側で「絶対パスまたは相対パスを保存してよい」と許可していました。

つまり、指示同士がぶつかっていたのです。

「保存しない」だけでなく、「相対パスで保存する」と正しい形式まで指定します。AI生成の図解。

・エージェント定義では絶対パスを禁止

・今回の依頼では絶対パスも許可

そこで、「情報源は必ずAGENTS.mdのようなリポジトリ相対パスで記録する」と修正しました。3回目の実行で保存済みメモを点検させ、絶対パスを相対パスへ置き換えました。

この結果から、禁止事項だけでなく、別の指示に逃げ道がないか確認する必要があると分かります。

3種類のメモリをどう選ぶか

保存範囲は3種類あります。

・user：複数のプロジェクトで使う、個人のレビュー観点など

・project：チームで共有したい、プロジェクト固有の知識

・local：プロジェクト固有だが、Gitでは共有しないメモ

Anthropicはprojectを標準的な選択肢として案内しています。ただし、個人情報や認証情報を保存してよいという意味ではありません。

秘密情報はlocalへ移すのではなく、最初からメモリへ保存しない方が安全です。

導入前に知っておきたい注意点

・Auto Memoryを無効にすると、サブエージェントのmemoryも機能しない

・メモリを管理するため、Read、Write、Editが自動的に有効になる

・MEMORY.mdは先頭200行または25KBまでが起動時に読み込まれる

・メモリは人間が読めるMarkdownなので、秘密情報も書けばファイルに残る

・メモリあり・なしを同じ条件で比較しない限り、速度やトークン削減効果は断定できない

読み取り専用のレビュー担当として作った場合でも、メモリを有効にするとメモリファイルへの書き込み能力が加わる点には注意してください。

まず試すなら、この一歩から

最初から多くの情報を覚えさせる必要はありません。

1. 何度も使うサブエージェントを1つ選ぶ

2. memory: projectと保存禁止ルールを追加する

3. 公開可能で、元ファイルから確認できる事実を1件だけ保存させる

4. 作成されたMarkdownを人間が確認する

5. 新しいセッションで、その1件を再読できるか試す

大切なのは、記憶量を増やすことではありません。

根拠があり、次回も使え、人間が監査できる情報だけを引き継ぎノートとして残すことです。

公式仕様は、Claude Codeのサブエージェント、メモリ、.claudeディレクトリの各ドキュメントで確認できます。