TL;DR
Claude Codeのカスタムサブエージェントにmemory: projectを設定し、次の3点を実機で確認しました。
- 初回実行で
.claude/agent-memory/<agent-name>/へメモリを保存できた - 独立した2回目のセッションで、元ファイルを読まずにメモリだけから正しく回答できた
- 保存されたローカル絶対パスを、3回目のセッションでリポジトリ相対パスへ修正できた
一方、エージェント定義で絶対パスを禁止していても、タスク側の指示で絶対パスを許可すると保存されました。
memory: projectは永続化の仕組みであり、保存内容の正しさや安全性を強制する仕組みではありません。
対象読者
- Claude Codeのカスタムサブエージェントを使っている
- 同じプロジェクト情報を毎回調べ直す問題を減らしたい
-
CLAUDE.md、Auto Memory、サブエージェントのmemoryの違いを整理したい -
memory: projectが実際に別セッションで使われるか確認したい
検証環境
| 項目 | 値 |
|---|---|
| OS | Windows |
| Claude Code | 2.1.160 |
| モデル | Claude Opus 4.8 |
| 検証日 | 2026-08-18 |
| リポジトリ | Blog_Create |
| シェル | PowerShell |
memoryフロントマターはClaude Code 2.1.33で追加されています。使用中のバージョンは次のコマンドで確認できます。
claude --version
今回の出力は次の通りでした。
2.1.160 (Claude Code)
前提：サブエージェントのmemoryとは
通常の非forkサブエージェントは、独立した新しいコンテキストで起動します。親の会話履歴や、親のAuto Memoryをそのまま引き継ぐわけではありません。
サブエージェント自身にセッションをまたぐ知識を持たせる場合、定義ファイルのmemoryフィールドを使います。
利用できるスコープは3種類です。
| 設定 | 保存先 | 用途 |
|---|---|---|
memory: user |
~/.claude/agent-memory/<name>/ |
複数プロジェクトで使う個人の知識 |
memory: project |
.claude/agent-memory/<name>/ |
プロジェクト固有で共有可能な知識 |
memory: local |
.claude/agent-memory-local/<name>/ |
Gitで共有しないプロジェクト固有の知識 |
今回検証したのはprojectです。
検証用サブエージェント
既存の本番用サブエージェントを変更せず、検証専用の定義を作成しました。
---
name: memory-project-verifier
description: Use only when explicitly asked to verify project-scoped subagent memory.
tools: Read, Grep, Glob
model: inherit
memory: project
---
Before starting a task, consult your agent memory.
Save only durable, non-sensitive facts verified directly in a repository file.
For every fact, record the repository-relative source path and verification date.
Do not save guesses, temporary branch state, credentials, personal information,
customer information, machine-specific paths, or conversation history.
Never edit repository content outside your own agent-memory directory.
ポイントは次の通りです。
-
memory: projectで専用メモリを有効化 - 保存対象を「確認済みの永続的な事実」に限定
- 根拠となるリポジトリ相対パスと確認日を必須化
- 秘密情報、途中経過、端末固有情報を禁止
- 自分のメモリ以外を編集しないよう制限
定義上のtoolsはRead, Grep, Globだけですが、メモリ有効時はメモリ管理用のRead、Write、Editが自動的に有効になります。実際、今回の初回実行ではWriteでメモリファイルが作られました。
検証1：プロジェクト情報を保存する
検証対象には、リポジトリのAGENTS.mdで確認できる次の事実を使いました。
WordPressは停止中で、有効な投稿先はcoconala、libecity、note、qiita、zennの5媒体である。
非対話モードから、メインセッションに検証用サブエージェントを使うよう依頼しました。
claude -p `
--permission-mode acceptEdits `
--output-format json `
"Use the memory-project-verifier subagent. Read AGENTS.md, verify the active platforms, and save the fact with its source and verification date."
実行後、次のファイルが作成されました。
.claude/agent-memory/memory-project-verifier/
├── MEMORY.md
└── project_active_platforms.md
MEMORY.mdは短い索引です。
# Agent Memory Index
## Project
- [Active publishing platforms](project_active_platforms.md)
— WordPress inactive; five active platforms verified 2026-08-18
詳細メモには、確認した事実、AGENTS.mdの該当見出し、確認日が記録されました。
実行結果
- 終了コード：0
- 実行時間：約64.5秒
-
AGENTS.mdをRead - 詳細メモと
MEMORY.mdをWrite - 指定した事実は元ファイルと一致
検証2：別セッションでメモリだけを読む
次に、独立した新しいClaude Codeセッションを起動しました。
この実行では、AGENTS.mdや他のリポジトリファイルを読まず、専用メモリだけで回答するよう指定しました。
claude -p `
--permission-mode acceptEdits `
--output-format json `
"Use the memory-project-verifier subagent. Do not read AGENTS.md or files outside your agent-memory directory. Using only memory, report whether WordPress is active and list every active platform."
実際の回答
- WordPressは停止中
- coconala
- libecity
- note
- qiita
- zenn
回答内容だけでは、裏で元ファイルを読み直した可能性が残ります。そこで、Claude Codeが保存したサブエージェントのJSONL実行記録も確認しました。
2回目に記録されていたファイル読み取りは、次の2件だけでした。
.claude/agent-memory/memory-project-verifier/MEMORY.md
.claude/agent-memory/memory-project-verifier/project_active_platforms.md
AGENTS.md、CLAUDE.md、その他のリポジトリファイルに対するReadはありませんでした。
実行結果
- 終了コード：0
- 実行時間：約23.5秒
- メモリ2ファイルだけをRead
- 保存済みの5媒体を正しく回答
- ファイル変更なし
これにより、別セッションでプロジェクトスコープのメモリを再利用できたと判断しました。
失敗：絶対パス禁止が守られなかった
初回に作成された詳細メモを確認すると、情報源としてローカル環境の絶対パスが保存されていました。
エージェント定義では、machine-specific pathsを保存しないよう指定していました。しかし、初回タスクでは情報源を「absolute or repo-relative」で保存してよいと依頼していました。
つまり、次の指示が競合していました。
エージェント定義：端末固有パスを保存しない
初回タスク：絶対パスまたは相対パスを保存してよい
保存結果を見る限り、絶対パスを許可したタスク側の指示が採用されました。
この結果から、memoryはポリシーの強制機構ではなく、モデルが読み書きする永続ストレージとして扱う必要があります。
検証3：保存済みメモリを修正する
エージェント定義を次のように具体化しました。
Always record repository sources as relative paths such as AGENTS.md.
Never record an absolute local path.
その後、3回目の独立セッションで、メモリディレクトリ内だけを点検・修正させました。
実行結果
- 終了コード：0
- 実行時間：約50.5秒
- 詳細メモの絶対パスを
AGENTS.mdへ置換 -
MEMORY.mdは変更なし - 2ファイルを再走査し、ドライブ文字を含む絶対パスがないことを確認
保存後のメモリを別セッションから修正できることも確認できました。
CLAUDE.md、Auto Memory、resumeとの違い
| 仕組み | 役割 |
|---|---|
CLAUDE.md |
人間が作業規則やプロジェクト構成を渡す |
| メインのAuto Memory | メインセッションがプロジェクトの学びを保持する |
サブエージェントのmemory
|
同名サブエージェント専用の学習メモを保持する |
| resume | 同一サブエージェントの会話履歴を継続する |
memory: projectは、親の会話履歴を保存する機能ではありません。次回必要な情報がメモリファイルへ書かれている場合に、その情報を再利用できます。
運用上の注意
Auto Memoryを無効にすると機能しない
autoMemoryEnabled: falseまたはCLAUDE_CODE_DISABLE_AUTO_MEMORY=1が設定されている場合、サブエージェントのmemoryフィールドも無効になります。
MEMORY.mdの起動時読み込みには上限がある
起動時に含まれるのは、MEMORY.mdの先頭200行または25KBのうち小さい方までです。
詳細は別ファイルへ分け、MEMORY.mdを索引として保つ設計が必要です。
読み取り専用エージェントでも書き込み能力が加わる
メモリ管理用にRead、Write、Editが自動的に有効になります。ツール制限を設計する場合は、この挙動を考慮する必要があります。
メモリはプレーンなMarkdown
メモリは人間が読める反面、秘密情報を書けばファイルに残ります。projectスコープはGitで共有できるため、コミット前の差分確認が必要です。
制約と未検証事項
- 3回のタスク内容が異なるため、実行時間を性能比較には使えない
- メモリなし・ありでのトークン数比較は未実施
- 古いメモリと元ファイルが競合した場合の再確認動作は未検証
- メモリファイルの削除動作は未検証
- Claude Codeの将来バージョンで挙動が変わる可能性がある
まとめ
memory: projectにより、カスタムサブエージェントがプロジェクト固有の知識を保存し、別セッションで再利用できることを確認しました。
一方、相反する指示があると、禁止した情報も保存されます。
実運用では、次の条件を満たす情報だけを保存するのが安全です。
- 次回も利用する
- 元ファイルやコマンドで確認済み
- 根拠となるリポジトリ相対パスがある
- 確認日がある
- 秘密情報や個人情報を含まない
メモリ量を増やすことより、内容を監査・修正できる運用を先に設計する必要があります。