Claude Code の agent で永続メモリを有効にすると、便利な一方で、何でも MEMORY.md に記録してしまうことがあります。これは回答時間の増大や、次回以降のシステムプロンプトの汚染につながります。
MEMORY.md にどの程度積極的に記録してもらうとよいかは、依頼する作業によります。そこでこの記事に、永続メモリの「記録の積極度」を分ける指示例を書き留めます。
関連記事
コード実装を担当する永続メモリ付きサブエージェント設定ファイルの例 (全部日本語) — エージェント定義ファイル全体の例です (この記事は関連箇所のみ書きます)。
困ったこと： エージェントが何でも記憶しようとする
最近、開発支援エージェントをベースに資料作成支援エージェントを定義したところ、資料作成中の細かな指摘まで永続メモリに残そうとするのが気になりました。
資料作成支援では、開発支援に対して作業の普遍性、つまり指摘の再利用性が異なり、開発支援と同じ積極度で永続メモリを記録されても役立たないどころか、無駄なトークン消費につながります。
方針： エージェントごとに記録の積極度を変える
エージェントごとに「どの程度積極的に永続メモリに記録するか」を分けました。
| 積極度 | 向くと思われる用途 | 記録すること |
|---|---|---|
| 1. 積極的に記録 | 開発支援 | 設計意図、依存関係、命名規則 |
| 2. 控えめに記録 | 資料作成支援 | 文書作成ルール、調査ルール |
| 3. 自発的には記録しない | 文献調査支援 一時作業支援 |
ユーザが明示した指摘のみ |
3. はもはや「エージェントによる自発的な学び」ではなく、ユーザが明示したルールを保存する運用です。定期的に MEMORY.md をエージェント定義に移すのがよいと思います。
1. や 2. についても、定期的に MEMORY.md を棚卸しして、ユーザから恒久的な方針として与えたいことはエージェント定義に移すのがよいと思います。
それらを実施するメタエージェントを設置してもよいかもしれません。
エージェント定義ファイル内の記述例
以下に、エージェント定義ファイル内の、永続的記憶に関わる記述のイメージを示します。
「常に守ってほしいルール」と「永続的記憶について」を、積極度で調整しています。
その他、
- 「永続的記憶の記録のプラクティス」に記録してほしいこと、記録してほしくないことを示しています (より具体的な記述が望ましいと思いますが、以下では抽象化しています)。
- 「永続的記憶の記録のルール」で「日本語で記録」を指示しています。英語だと記憶が適切か見直すハードルが上がってしまう (実際これまで見直していなかった) ためです。
1. 積極的に記録するエージェント
以下は手元の開発支援エージェントの定義です。以前からこのような定義ですが、今回改めて記録の言語だけ日本語に変更しました。
(前略)
## 作業時の共通ルール
- 作業後に、今後の作業時にも役立つ知見があったか確認し、もしあればワークルート以下の
**永続的記憶** `.claude/agent-memory/zundamon/MEMORY.md` (後述) に記録してください。
(中略)
---
## 永続的記憶について
あなたは `.claude/agent-memory/zundamon/MEMORY.md` に **永続的記憶** を持ちます。
作業後には、今後の作業時にも役立つ知見があれば、ここに記録してください。
ここに保存された内容は、次回のシステムプロンプトに反映されます。
また、作業中に問題に遭遇した場合、ここに手がかりがないか確認することもできます。
### 永続的記憶の記録のルール
- 日本語で記録してください。
- `MEMORY.md` は次回のシステムプロンプトに反映されますが、
このとき 200 行目以降は切り捨てられるため、簡潔に記述してください。
- 詳細なメモはトピック別ファイル (例: `write_unit_tests.md`) を作成し、
`MEMORY.md` からリンクを張ってください。
### 永続的記憶の記録のプラクティス
- 時系列ではなくトピックごとに整理してください。
- 誤った記録や陳腐化した記録があったら、修正または削除してください。
- 以下のような知見を書き留めることが推奨されます。
- ユーザに今後も守ってほしいと言われたこと
- モジュール間の依存関係とデータの流れ
- 主要クラス・関数の責務と設計意図
- コーディング規約・命名規則のパターン
- ただし、その時だけの指摘内容、ファイルを読めばわかる内容、
単なる作業履歴を記録するのは不適当です。
2. 控えめに記録するエージェント
以下は手元の資料作成支援エージェントの定義です。上記の開発支援エージェントのような定義で運用開始したところ、記録が多すぎたので、控えめに調整しました。LaTeX や文章の書き方の方針にある程度普遍性はあるので、その学びを禁止するほどではないです。
(前略)
## 作業時の共通ルール
- 作業後に、今後の作業時でも何度も使う可能性が高い知見があったか確認し、もしあれば
ワークルート以下の **永続的記憶** `.claude/agent-memory/yukari/MEMORY.md` (後述)
に記録してください (知見がなければ無理に記憶を追加する必要はありません)。
(中略)
---
## 永続的記憶について
あなたは `.claude/agent-memory/yukari/MEMORY.md` に**永続的記憶**を持ちます。
作業後に、今後も役立つ可能性が高い知見がもしあれば、ここに記録してください。
ここに保存された内容は、次回のシステムプロンプトに反映されます。
また、作業中に問題に遭遇した場合、ここに手がかりがないか確認することもできます。
### 永続的記憶の記録のルール
- 日本語で記録してください。
- `MEMORY.md` は次回のシステムプロンプトに反映されますが、
このとき 200 行目以降は切り捨てられるため、簡潔に記述してください。
- 詳細なメモはトピック別ファイル (例. `write_slides.md`) を作成し、
`MEMORY.md` からリンクを張ってください。
### 永続的記憶の記録のプラクティス
- 時系列ではなくトピックごとに整理してください。
- 誤った記録や陳腐化した記録があったら、修正または削除してください。
- 以下のような知見を書き留めることが推奨されます。
- ユーザに今後も守ってほしいと言われたこと
- スライド作成時のルール
- 文献調査時のルール
- ただし、その時だけの指摘内容、ファイルを読めばわかる内容、
単なる作業履歴を記録するのは不適当です。
3. ユーザが明示したときだけ記録するエージェント
以下は手元の文献調査支援エージェントの定義です。文献の収集方法・情報抽出方法は時と場合によることが多いので自動的に学んでほしくなく、最初から共通ルールを整備しづらいので、随時こちらで普遍的なルールを記録してもらうようにしました。
(前略)
## 作業時の共通ルール
- もしユーザに「これは記憶してください」「今後も守ってください」のように言われたら、
ワークルート以下の **永続的記憶** `.claude/agent-memory/akane/MEMORY.md` (後述)
に記録し、今後も守るようにしてください。
(中略)
---
## 永続的記憶について
あなたは `.claude/agent-memory/akane/MEMORY.md` に**永続的記憶**を持ちます。
ここに保存された内容は、次回のシステムプロンプトに反映されます。
また、作業中に問題に遭遇した場合、ここに手がかりがないか確認することもできます。
### 永続的記憶の記録のルール
- 日本語で記録してください。
- `MEMORY.md` は次回のシステムプロンプトに反映されますが、
このとき 200 行目以降は切り捨てられるため、簡潔に記述してください。
- 詳細なメモはトピック別ファイル (例. `describe_model_architecture.md`) を作成し、
`MEMORY.md` からリンクを張ってください。
### 永続的記憶の記録のプラクティス
- 時系列ではなくトピックごとに整理してください。
- 誤った記録や陳腐化した記録があったら、修正または削除してください。
- ユーザに今後も守ってほしいと言われたことは記録してください。
- その他、記録するとよいと思われることがあったら、ユーザに記録するか確認してください。
- その場限りの指摘内容かもしれないので、ユーザに確認の上で記録してください。
Tips
よくプラクティスが紹介されていますが、「永続メモリ」と「次回への引継ぎ内容」が混同されるときは、「永続的記憶は次回への引継ぎ内容と区別してください (次回への引継ぎ内容はこちらのファイルに書いてください)」のように記述したほうがよいと思います。
まとめ
Claude Code の agent で永続メモリを使うときは、エージェントごとに「どの程度自発的に記録してよいか」を分けると管理しやすくなると思います。
開発支援のように再利用性の高い知見が多いエージェントでは積極的に記録し、資料作成のようにその場限りの指摘が混ざりやすいエージェントでは控えめにするとよいと思います。
また、MEMORY.md は放置せず、定期的に見直して、恒久的なルールは agent 定義ファイルへ移すのがよさそうです。