Managed Agentsのメモリ管理ベストプラクティス — 何を憶えさせ、何を憶えさせないか

なぜメモリストアの設計判断が必要になるのか

Managed Agentsのメモリストアは1ストアあたり最大10,000メモリという上限を持ちます。この上限に達すると、新しいメモリへの書き込みは失敗します。memories.createを直接呼ぶ場合も、エージェントがマウントパス配下の未使用パスにファイルを書き込む場合も同様です。既存のメモリは上限に達したあとも引き続き読み書きできますが、新規追加だけが止まります。

メモリストアの作成・アタッチ・監査の具体的な手順を実際の運用に乗せると、遅かれ早かれこの上限とストアの信頼境界という2つの制約に向き合うことになります。以下は、この2つの制約から逆算して公式が示す設計判断です。

上限に達したあとの挙動は「エラーで止まる」ではなく「新規追加だけが静かに失敗する」という点に注意が必要です。既存メモリは読み書きできるままなので、エージェントが新しいメモリを書き込もうとして失敗しても、セッション全体がすぐに落ちるわけではありません。監視の仕組みがなければ、ストアが上限に達したことに気づかないまま、エージェントが本来記録すべきだった新しい情報を取りこぼし続ける状態になりかねません。以下の設計判断は、この失敗モードを未然に避ける予防策です。

ストアを絞って上限に強くする

1つの大きな汎用ストアにあらゆる情報を集めるのではなく、ユーザーごと・共有ドメイン知識用・プロジェクト固有コンテキスト用といった小さく目的特化したストアに分けるのが基本方針です。ストアはそれぞれ独立した10,000メモリの上限を持つため、スコープを絞るほど単一のストアが埋まるリスクは下がります。

書き込み権限を絞ることも、この設計の一部です。共有参照資料を読むだけのセッションにread_writeを与える必要はありません。書き込み権限を実際に新しいメモリを追加するセッションだけに限定しておくと、ストアがどこから成長しているかを追跡しやすくなります。

溜まったメモリをどう整理するか

ストアが上限に近づいたら、memories.deleteで陳腐化した重複メモリや矛盾したメモリを削除します。手作業での棚卸しに加えて、dreaming sessionという手段もあります。これは既存のメモリストアと過去のセッション記録を読み込み、断片化した内容を統合した新しい出力ストアを生成する仕組みです。入力側のストアは変更されないため、出力結果を確認してから気に入らなければ破棄できます。統合が済んだら、以降のセッションをその出力ストアに切り替え、元のストアはアーカイブまたは削除します。

dreamingはリサーチプレビュー機能であり、利用には別途アクセス申請と専用のベータヘッダ(dreaming-2026-04-21)が必要です。恒常的な自動整理の仕組みとしてではなく、ストアが手に負えなくなったときの棚卸し手段として使うのが現実的です。

ストアが本来の役割を超えて肥大化した場合は、新しいストアを新規コンテンツ用にアタッチし、元のストアはread_onlyでアタッチし直すという選択肢もあります。エージェントは両方から読み取れますが、書き込み先は新しい方だけに限定されます。

8ストアという枠をどう配分するか

1セッションにアタッチできるメモリストアは最大8個です。この枠をどう配分するかは、「1つの大きなストアを分割する」判断とは別の観点で考える必要があります。公式が挙げる複数ストアの使いどころは3系統に整理できます。

3系統とも共通しているのは、「このストアは誰が書き込み、誰が読むだけなのか」を先に決めてからaccessを割り当てている点です。8個という枠は多くはないため、目的が重なるストアを無計画に増やすより、この3系統のどれに当てはまるかで統合・分割を判断するほうが枠を使い切りにくくなります。

古いストアを片付ける段階では、アーカイブと削除のどちらを選ぶかも設計判断です。アーカイブはストアを読み取り専用にして新規セッションへのアタッチを禁止しますが、中身とバージョン履歴はそのまま残り、一方向の操作で取り消せません。削除はストアと全メモリ・全バージョンを完全に消します。統合後もしばらく参照する可能性がある移行期のストアはアーカイブに、監査上も残す理由がないストアだけを削除に回すという線引きにしておくと、「消してよかったのか」を後から悩む場面を減らせます。

何を書き込ませて、何を書き込ませないか

メモリストアはデフォルトでread_writeアタッチされます。ここが「何を憶えさせないか」の判断を最も左右する仕様です。エージェントがユーザー入力・Web取得コンテンツ・サードパーティツールの出力といった未信頼な入力を処理する構成では、プロンプトインジェクションが成功すると、その未信頼な内容がそのままメモリストアに書き込まれます。書き込まれた内容は次のセッション以降、信頼済みメモリとして読み込まれます。

read_writeを既定のまま使い続ける設計は、書き込み元を制御できないエージェントでは監査可能な負債を生みます。参照用のストアは最初からread_onlyで固定し、エージェント自身が学習して積み上げていくストアだけをread_writeにするという線引きが、事後の調査コストを最小化します。

監査とredactでコンプライアンスに応える

メモリへのすべての変更はimmutableなメモリバージョンとして記録され、書き込みから30日間保持されます(ライブなメモリの直近バージョンは、それより古くても保持され続けます)。この保持期間そのものが、「何を書かせてよいか」の設計にも影響します。一度書き込まれた内容は最低でも一定期間、監査可能な形で残る前提に立つほうが、事後のredact頼みで運用するより安全です。

とはいえ、漏洩したシークレットやPII、ユーザーからの削除リクエストのように、書き込まれてしまった後に対応が必要になる場面は避けられません。redactは、誰が・何を・いつ変更したかという監査証跡自体は保持したまま、過去バージョンの本文だけを消す操作です。ただし、ライブメモリの現行ヘッドになっているバージョンは直接redactできず、先に新しいバージョンを書くかメモリを削除してからでないと対象にできません。この制約を踏まえると、機微情報が疑われるメモリは検知した時点で速やかに上書きし、その上で古いバージョンをredactするという順序を運用手順に組み込んでおく必要があります。

復元専用のエンドポイントが無いことも設計に影響します。ロールバックは目的のバージョンの内容を取得してmemories.updateで書き戻す形でしか行えないため、「誤って書き込まれた内容をすぐに元に戻せる」という前提を運用手順に組み込むなら、対象メモリのバージョン一覧を先に確認できる体制をあらかじめ作っておく必要があります。redactと同様、事後対応の速さはストア設計そのものではなく、この確認フローの整備で決まります。

人間のレビューを運用フローに組み込む

メモリストアはエージェント専用のブラックボックスではなく、API経由で一覧・取得・作成・更新・削除ができる普通のドキュメント集合です。この性質は、エージェントが書いたメモリを人間が定期的にレビューする運用を組み込みやすくします。具体的には、path_prefixで対象範囲を絞ってストアの中身を一覧し、気になるメモリだけを取得して内容を確認し、誤りがあればmemories.updateで修正するという流れです。セッションが動く前にストアへ参照資料を事前投入しておく使い方も同じAPIの延長線上にあり、エージェントの初回実行前に「何を前提知識として持たせるか」を人間側でコントロールできます。

この仕組みを設計に組み込むなら、レビューの単位をストアの分割方針と揃えておくと運用が崩れにくくなります。ユーザーごと・プロジェクトごとにストアを分けているなら、レビューもその単位で回せます。逆に汎用ストア1つに全ユーザーの情報を混在させると、レビュー対象を絞り込むために毎回path_prefixの設計を工夫する必要が生じ、監査のたびに手間が増えます。ストアを目的別に絞っておく判断は、上限対策だけでなく、この後工程のレビューしやすさにも直結します。

レビューの頻度も、ストアのaccessに合わせて変えられます。read_writeストアはエージェントが継続的に書き込むため、新規メモリを対象に定期的なレビューが必要になりますが、read_onlyに固定した参照ストアは人間側の更新時にだけ確認すればよく、レビューコストは書き込み頻度にほぼ比例します。この対応関係を先に決めておくと、どのストアにどれだけレビューの手間をかけるべきかが自明になり、監査の優先順位付けに迷わなくなります。

まとめ

Managed Agentsのメモリ管理は、10,000メモリという上限と、read_write既定という信頼境界の2つから逆算して設計します。ストアは目的別に小さく分割し、書き込み権限は実際に書く必要があるセッションだけに絞ります。肥大化したらmemories.deleteかdreaming sessionで整理し、参照専用の内容は最初からread_onlyに固定します。そして、書き込まれた内容は最低30日は監査可能な形で残るという前提のもとで、機微情報をそもそも憶えさせない設計を優先し、redactは事後の是正手段として使います。具体的なAPIの呼び方はメモリストアの使い方、Managed Agents全体の設計はManaged Agentsの設計思想、エージェントに専門知識を持たせるもう一つの手段はカスタムSkillの追加方法を参照してください。