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

運用前に決めておく4つの上限と、満杯になったときの挙動

Managed Agentsのメモリストアは、セッションが終わっても残る文書の置き場です。作成・アタッチ・監査の具体的な手順を実際の運用に乗せると、設計を縛るのは次の4つの数字になります。

10,000件に達したときの挙動は限定的です。直接memories.createを呼ぶ場合も、エージェントがまだ存在しないパスへファイルを書く場合も、新しいメモリの作成が失敗します。既存のメモリは読み書きできるままです。ストア全体が止まるのではなく、新しい情報だけが入らなくなります。

数の上限とサイズの上限は逆向きに効きます。1ファイルを100 kB以内に保つには細かく分けるのが近道ですが、分けるほど10,000件には近づきます。1つのファイルに追記し続ける構成も、100 kBの壁に当たります。どちらも避けるには、ストアを目的別に切って1ファイルを短く保つことになります。

セッション作成後はストアを足せない

ストアはセッション作成時のresources[]でアタッチします。動いているセッションへの追加や取り外しはできません。ストアの分割方針は、最初のセッションを作る前に決めておく必要があります。あとから整理して切り替える場合も、反映されるのは新しく作るセッションからです。

アタッチしたストアはサンドボックスの/mnt/memory/の下にディレクトリとして現れます。ディレクトリ名はストアの表示名を小文字化し、英数字以外の連続を1つのハイフンにしたものです。「Demo Memory」なら/mnt/memory/demo-memory/になります。実際のパスはセッションのリソースにあるmount_pathから読み、自前で組み立てません。

ストアのnameとdescription、アタッチ時のinstructions(上限4,096文字)は、エージェントに渡る情報です。マウントごとの案内がシステムプロンプトに自動で加わるため、これらは人間向けのラベルではなく、エージェントへの指示文の一部として書くことになります。

誰が書き、誰が読むかでストアを切る

1つの大きな汎用ストアに集めず、ユーザーごと・共有ドメイン知識・プロジェクト固有といった目的特化の小さなストアに分けるのが基本です。ストアごとに10,000件の上限が独立しているため、単一のストアが埋まるリスクが下がります。8枠の配分は、次の3つの切り口で考えます。

3つに共通するのは、アタッチの前に「このストアに書くのは誰か、読むだけなのは誰か」を決めている点です。目的が重なるストアを足していくより、どの切り口に当たるかで統合・分割を判断するほうが、8枠を使い切りにくくなります。

たとえばサポート窓口のエージェントなら、社内規約を入れたread_onlyのストアと、顧客ごとのread_writeのストアを組み合わせる構成が考えられます。リクエストは次の形です。

{
  "agent": "$agent_id",
  "environment_id": "$environment_id",
  "resources": [
    {
      "type": "memory_store",
      "memory_store_id": "$policy_store_id",
      "access": "read_only",
      "instructions": "返金・エスカレーションの社内規約。参照のみ。"
    },
    {
      "type": "memory_store",
      "memory_store_id": "$customer_store_id",
      "access": "read_write",
      "instructions": "この顧客の過去の問い合わせと好み。対応後に更新する。"
    }
  ]
}

セルフホスト環境では、各ストアのディレクトリはワーカーが管理するローカルコピーになります。ワーカーはストアとの突き合わせを、既定15秒の同期間隔につき最大1回だけ行います。別のセッションに変更が見えるのは、両方のワーカーが同期したあとです。書き込み直後に別セッションから読む設計は、この遅れを織り込んでおきます。

read_writeを既定のまま使うと何が起きるか

メモリストアは何も指定しなければread_writeでアタッチされます。ユーザー入力、Webから取得した内容、サードパーティのツール出力といった未信頼の入力を扱う構成では、プロンプトインジェクションが成功すると、その内容がストアに書き込まれます。書き込まれた内容は次のセッション以降、信頼済みのメモリとして読み込まれます。

read_onlyの効き方は環境で少し違います。クラウドのサンドボックスでは、アクセス制御はファイルシステムの段階で強制されます。セルフホスト環境では、ワーカーのwriteとeditツールが変更を拒否し、そのディレクトリからは何もアップロードされません。

ただしbashや、サンドボックスから提供するカスタムツール・MCPサーバー経由の変更は、ローカルでは止まりません。ストアには同期されず、次にそのメモリへリモートの変更が入ると上書きされます。セルフホストでread_onlyに頼る構成では、この抜け道があることを前提にします。

書き込み元を制御できないエージェントで既定のまま使い続けると、事後の調査が重くなります。参照用は最初からread_onlyに固定し、エージェント自身が積み上げていくストアだけをread_writeにする線引きが、調査コストを抑えます。書き込み権限を、実際に新しいメモリを足すセッションだけに絞れば、ストアがどこから成長しているかも追いやすくなります。

満杯が近づいたときの整理手順

整理は、手作業の削除、ドリーム(dreaming)による統合、出力ストアへの付け替えという流れで考えられます。

ドリームは非同期のジョブで、入力するセッション記録の量しだいで数分から数時間かかります。料金は選んだモデルの標準のAPIトークン単価で、セッションの数と長さにほぼ比例します。最初は少ないセッション数で試し、整理の質に納得してから増やす進め方が示されています。

ドリームは入力のストアを変更しません。失敗した場合やキャンセルした場合も、出力ストアは途中までの内容のまま残ります。不要なら、メモリストアのAPIで自分で片付けます。

実行中のドリームに対して、入力のメモリストアをアーカイブしたり削除したりするとドリームが失敗します。入力のセッションを削除した場合も同様で、エラーの種類はinput_memory_store_unavailableとinput_session_unavailableです。統合の最中に元のストアを触らないよう、運用手順に入れておきます。

instructions(上限4,096文字)で整理の方針を指示することもできます。ただしこれは全体の統合に効く指示で、特定の行を直させるものではありません。「この文をこう直す」「この節の件数を直す」といった指示は、ほとんど変更を生みません。個別の修正は、出力ストアにメモリストアのAPIで直接かけます。

ドリームは満杯になってから使う救済には向かない可能性があります。入力のストアがパイプラインのサイズ上限を超えると、input_memory_store_too_largeで失敗するためです。ドリームのページのLimits表に、この上限の数値は載っていません。肥大化が見えてきた段階で早めに回すほうが、失敗しにくい使い方です。

実行中のドリームは、キャンセルするとpendingやrunningの状態から直ちにcanceledになります。方針の指示が外れていたと気づいたときは、最後まで待たずに止められます。

ドリームのエラーには、ほかにmemory_store_org_limit_exceededとtimeoutがあります。前者は、パイプラインが作業用ストレージを用意する間に、組織のメモリストア数の上限に達したときのエラーです。

ドリームはリサーチプレビュー機能で、利用にはアクセス申請が要ります。対応モデルはclaude-opus-5、claude-fable-5、claude-opus-4-8、claude-opus-4-7、claude-sonnet-5、claude-sonnet-4-6です。恒常的な自動整理というより、手に負えなくなる前の棚卸しの道具として位置づけると、前提のずれが小さくなります。

ストアが本来の役割を超えて大きくなったときは、新しいストアを新規の内容用にアタッチし、元のストアをread_onlyで付け直す方法もあります。エージェントは両方を読めて、書き込み先は新しいほうだけになります。

古いストアの最後の扱いは、アーカイブか削除かの判断です。アーカイブはストアを読み取り専用にして、新しいセッションへのアタッチを禁じます。アーカイブは一方向で、取り消せません。削除はストアと全メモリ・全バージョンを消します。統合後もしばらく参照する見込みがある移行期のストアはアーカイブ、残す理由がないストアだけを削除にする分け方が、後から迷わずに済みます。

メモリストアのAPIが400で落ちるとき — ベータヘッダの組み合わせ

メモリストアのAPIを呼ぶときのベータヘッダは、公式ページ同士で書き方が食い違っています。メモリのページは、メモリストアへのリクエストにagent-memory-2026-07-22を使い、managed-agents-2026-04-01と併用すると400になると書いています。セッションのエンドポイントは、ストアのアタッチを含めてmanaged-agents-2026-04-01のままです。

一方、ドリームのページには、セッションとメモリストアの呼び出しはmanaged-agents-2026-04-01だけで足りるという記述があります。ドリームのエンドポイント自体はdreaming-2026-04-21で保護され、ページの例は両方のヘッダを送っています。

# メモリストアの呼び出し(メモリのページの記述)
anthropic-beta: agent-memory-2026-07-22
 
# セッションの作成・ストアのアタッチ
anthropic-beta: managed-agents-2026-04-01
 
# ドリームのエンドポイント(ドリームのページの例)
anthropic-beta: managed-agents-2026-04-01, dreaming-2026-04-21

ヘッダを自前で組み立てているコードでは、メモリストアの呼び出しにmanaged-agents-2026-04-01を足していないかが、400の原因の候補になります。ドリームのページによれば、SDKはこれらのヘッダを自動で設定します。

削除してもバージョンに残る — 機微情報の消し方

メモリへの変更は、すべて不変のメモリバージョンとして記録されます。バージョンはメモリ個別ではなくストアに属し、メモリを削除しても消えません。削除済みのメモリの履歴も、保持期間の範囲で監査の対象に残ります。保持期間は書き込みから30日で、ライブなメモリの直近バージョンは日数に関係なく保たれます。

つまりmemories.deleteだけでは、本文を履歴から消したことにはなりません。本文まで消すのが、redactです。誰が・何を・いつ変えたかという監査証跡は残したまま、過去バージョンの本文だけを消します。

状況ごとの手順は次のとおりです。

現行のヘッドになっているバージョンは直接redactできません。機微情報が疑われるメモリは、検知した時点で先に上書きし、そのうえで古いバージョンをredactする順序を、運用手順に組み込みます。

復元専用のエンドポイントはありません。ロールバックは、目的のバージョンを取得して書き戻す形でしか行えません。親のメモリが削除済みなら、その版がまだ保持されている限り、memories.createで作り直します。「誤った書き込みをすぐ戻せる」前提で運用するなら、対象メモリのバージョン一覧をすぐ引ける体制が先に必要です。

保持期間があるので、書き込まれた内容は最低でも一定期間は履歴として残ります。機微情報はそもそも書かせない設計を優先し、redactは事後の是正手段にとどめるのが安全です。

人間のレビューを前提にしたパスの設計

メモリストアはAPIで一覧・取得・作成・更新・削除ができる文書の集合です。エージェントが書いたメモリを人間がレビューする運用を組み込めますし、セッションを動かす前に参照資料を入れておくこともできます。

一覧の絞り込みにはpath_prefixを使います。末尾を/にする必要があり、パスの区切り単位で一致します。/notes/を指定すると/notes/todo.mdは返りますが、/notes-archive/todo.mdは返りません。depthは省略(または0)で部分木の全体、1で直下の子だけが返ります。それ以外の値は400です。

この仕様から、パスの設計がそのままレビューの範囲になります。ユーザーごと・案件ごとのディレクトリで分けておけば、path_prefix1つで1人分、1案件分を一覧できます。ストアの分割方針とレビューの単位を揃えると、運用が崩れにくくなります。1つの汎用ストアに全員分を混在させると、レビューのたびにパス設計の工夫が必要になります。

人間が直すときは、エージェントの書き込みと衝突しない書き方があります。更新でcontent_sha256を前提条件として渡すと、保存されている内容のハッシュが、読んだときと同じ場合だけ書き換わります。不一致なら、読み直してやり直します。作成は上書きしないので、既存のメモリを変えるには更新を使います。名前の変更も更新で行え、contentとpathを同時に変えることもできます。

まとめ

各ストアについて、書き込むのは誰か、どこまで残すかを先に決めると、残りの判断が決まります。満杯への備えも、機微情報への備えも、この2点から導けます。具体的なAPIの呼び方はメモリストアの使い方、Managed Agents全体の設計はManaged Agentsの設計思想、エージェントに専門知識を持たせるもう一つの手段はカスタムSkillの追加方法にあります。