Managed Agentsのメモリストアの使い方 — 作成・アタッチ・監査ログの確認

Managed Agentsのメモリストアとは何か

Managed Agentsの各セッションはデフォルトで新規のコンテキストから始まり、終わるとエージェントが積み上げた状態は消えます。メモリストアは、ユーザーの好み・プロジェクトの慣習・過去の失敗・ドメイン知識をセッションをまたいで持ち越すための仕組みです。

実体は、ワークスペース単位のテキストドキュメント集合です。セッションにアタッチするとサンドボックス内のディレクトリとしてマウントされ、エージェントは他のファイルと同じファイルツールで読み書きします。このため、エージェント作成時にエージェントツールセットを有効にしておく必要があります。マウントの説明はシステムプロンプトに自動で追加されます。

ストア内の各メモリはpathでアドレスされ、API経由でもConsole経由でも直接読み書きできます。メモリへのすべての変更は、変更できないメモリバージョンを作ります。これがエージェントの書き込みの監査証跡とポイントインタイム復元になります。

全体の流れは次の4段階です。ベータヘッダがストア側とセッション側で違う点が、最初のつまずきどころです。

ストア系のリクエストにmanaged-agents-2026-04-01を併記すると400エラーになります。ヘッダを明示的に組み立てているコードでは、値を足さずに置き換えます。

メモリストアを作成してコンテンツを仕込む

ストアの作成にはnameとdescriptionを渡します。descriptionはエージェントに渡され、そのストアに何が入っているかを伝える役割を持ちます。

store=$(curl -s https://api.anthropic.com/v1/memory_stores \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: agent-memory-2026-07-22" \
  -H "content-type: application/json" \
  -d '{"name": "User Preferences", "description": "Per-user preferences and project context."}')
store_id=$(jq -r '.id' <<< "$store")

返ってくるIDはmemstore_で始まり、セッションへのアタッチでそのまま使います。

エージェントが動く前に、参照資料をストアへ事前投入できます。

curl -s "https://api.anthropic.com/v1/memory_stores/$store_id/memories" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: agent-memory-2026-07-22" \
  -H "content-type: application/json" \
  -d '{"path": "/formatting_standards.md", "content": "All reports use GAAP formatting. Dates are ISO-8601..."}'

少数の大きなファイルではなく、多数の小さく焦点を絞ったファイルに分けるのが公式の推奨です。上限は次の数字です。

セッションにアタッチする — read_writeとread_onlyの使い分け

メモリストアは、セッション作成時のresources[]配列でのみアタッチできます。ファイルリソースと異なり、稼働中のセッションへの後付けアタッチや取り外しはサポートされていません。

curl -s https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<EOF
{
  "agent": "$agent_id",
  "environment_id": "$environment_id",
  "resources": [
    {
      "type": "memory_store",
      "memory_store_id": "$store_id",
      "access": "read_write",
      "instructions": "User preferences and project context. Check before starting any task."
    }
  ]
}
EOF

instructionsは任意項目で、そのセッションでストアをどう使ってほしいかをエージェントに伝えます。ストアのname・descriptionと並べてエージェントに見せる文です。accessはread_write(既定)とread_onlyのどちらかです。

複数ストアを使い分けるのは、次のような場面です。

• 共有の参照資料は1つのread_onlyストアに置き、各セッション固有の内容は別のread_writeストアに分ける
• ユーザー・チーム・プロジェクトごとにストアを割り当て、エージェントの設定は1つのまま使い回す
• ライフサイクルが違うストアを、それぞれの都合でアーカイブする

エージェントからはどう見えるか

マウント先は/mnt/memory/配下で、ディレクトリ名はストアの表示名のスラッグです(小文字化し、英数字以外の連続を1つのハイフンに置換)。たとえば"Demo Memory"は/mnt/memory/demo-memory/になります。正確なパスはセッションのメモリストアリソースが返すmount_pathから取り、自前で組み立てません。

書き込みが永続化されるのは、このストアのディレクトリの下だけです。/mnt/memory/直下のそれ以外のパスへの書き込みは、親ディレクトリが読み取り専用でマウントされているため失敗します。

accessはファイルシステムのレベルで強制されます。read_onlyマウントへの書き込みは拒否され、read_writeマウントへの書き込みはセッションに紐づくメモリバージョンになります。エージェントの読み書きは、イベントストリーム上では通常のagent.tool_use / agent.tool_resultイベントとして見えます。

ストアが10,000件に達したとき

上限に達すると、新しいメモリの作成は失敗します。APIのPOSTも、エージェントが未登録のパスへ書くファイル書き込みも同じです。既存のメモリの読み取りと編集は続けられます。

公式が挙げる対処は3つです。

• 古い・重複したメモリをDELETEで削る
• ドリーミングセッションで断片化した内容を別の新しい出力ストアにまとめ、セッションをそちらへ切り替えてから元をアーカイブか削除する
• 新しいストアを書き込み先にして、元のストアをread_onlyで残す(エージェントは両方を読めて、書くのは新しい側だけ)

上限に届く前の整理方針は、メモリ管理のベストプラクティスで扱っています。

エージェントが書き込んだメモリを直接編集・削除する

メモリはAPIから直接管理できます。レビューワークフローの構築、誤ったメモリの修正、セッション実行前のストア準備に向きます。同じ操作はClaude Consoleからもできるので、コードを書かずに中身を見たいならConsole側のUIという選択肢もあります。

一覧では、path_prefixとdepthで対象を絞ります。path_prefixは/で終わる必要があり、パスセグメント単位で一致します。/notes/は/notes/todo.mdに当たり、/notes-archive/todo.mdには当たりません。depthは省略か0でサブツリー全体、1で直下だけです。それ以外の値は400になります。結果は安定したサーバー側の順序で返り、この挙動はどちらのベータヘッダでも変わりません。

作成と更新は対象が違います。

リネームだけなら、本文を送らずpathだけを渡します。公式の例は、古いメモリをアーカイブ用のパスへ移す使い方です。

curl -s -X POST "https://api.anthropic.com/v1/memory_stores/$store_id/memories/$mem_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: agent-memory-2026-07-22" \
  -H "content-type: application/json" \
  -d '{"path": "/archive/2026_q1_formatting.md"}'

同時編集を安全に行うには、content_sha256のプレコンディションを付けます。読み取り時のハッシュと保存済みコンテンツのハッシュが一致した場合だけ更新が適用されます。不一致なら適用されないので、メモリを読み直してから再試行します。

curl -s -X POST "https://api.anthropic.com/v1/memory_stores/$store_id/memories/$mem_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: agent-memory-2026-07-22" \
  -H "content-type: application/json" \
  --data @- <<EOF
{
  "content": "CORRECTED: Always use 2-space indentation.",
  "precondition": {"type": "content_sha256", "content_sha256": "$mem_sha"}
}
EOF

変更履歴を監査する — バージョンとredact

メモリへのすべての変更は、一度作られたら書き換わらないメモリバージョン(memver_...)を作ります。バージョンはメモリではなくストアに属するため、メモリが削除されても保持期間内なら監査証跡は残ります。

保持期間は書き込みから30日です。ただしライブなメモリの直近バージョンは古くなっても残るので、変更頻度の低いメモリは30日を超えて履歴が残ることがあります。それより長く残したい場合は、APIでエクスポートしておきます。ライブなメモリを取得すると常に最新バージョンが返り、履歴はバージョン用のエンドポイントで引きます。

バージョンの一覧は新しい順で、memory_idで1つのメモリに絞れます。

curl -s "https://api.anthropic.com/v1/memory_stores/$store_id/memory_versions?memory_id=$mem_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: agent-memory-2026-07-22"

個別のバージョンを取得すると、一覧と同じ項目に加えて本文(content)が返ります。

専用のロールバックエンドポイントはありません。戻したい場合は、目的のバージョンのcontentを取得し、memories.updateで書き戻します。親メモリがすでに削除されていても、そのバージョンが保持されている限りmemories.createで書き戻せます。

redactは、監査証跡(誰が・何を・いつ変更したか)を残したまま、過去バージョンの本文だけを消す操作です。漏洩したシークレットやPIIの除去、ユーザーの削除リクエストへの対応に使います。

curl -s -X POST "https://api.anthropic.com/v1/memory_stores/$store_id/memory_versions/$version_id/redact" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: agent-memory-2026-07-22" \
  -H "content-type: application/json" \
  -d '{}'

ライブメモリの現行ヘッドになっているバージョンはredactできません。先に新しいバージョンを書くか、メモリ自体を削除してから、古いバージョンをredactします。

ストア自体は、取得・更新・一覧・アーカイブ・削除ができます。一覧はデフォルトでアーカイブ済みを除外し、include_archived: trueで含めます。アーカイブはストアを読み取り専用にして新規セッションへのアタッチを禁じる一方向の操作で、取り消す方法はありません。ストアと全メモリ・全バージョンを完全に消すのはmemory_stores.deleteです。

セルフホストサンドボックスで使うとき

セルフホストでも、アタッチの書き方はクラウドと同じです。違うのは、ストアを実体化する主体が自社のworkerになる点です。そのため、症状は「ほかのセッションの変更が見えない」「セッションが動かない」の2系統に分かれます。セルフホスト環境が受け付けるリソースはmemory_storeだけです。

同期のタイミングと設定

同期はツール呼び出しのあとに、同期間隔につき最大1回走ります。セッション終了時にも、もう1回走ります。この最終同期は、未アップロードの分を最大30秒かけて送ってからディレクトリを削除します。既定の間隔は15秒で、最小は5秒です。別のセッションに変更が見えるのは、双方のworkerが同期を終えたあとです。公式は、既定の間隔なら通常1分に満たないと説明しています。

間隔を縮めると古いメモリを読む窓は狭まりますが、ストアへのリクエストは増えます。EnvironmentWorkerのオプションで変えられ、antのCLI版workerは常に既定値で動きます。memory_sync_intervalにNone・null・-1を渡すと、メモリ対応そのものが無効になります。ストアを付けたセッションは、ストア無しで動きます。システムプロンプトにはマウントの説明が残ったままです。

エージェントがローカルで消したファイルをストアからも消すかは、memory_sync_deletionsで決まります。

いきなりenabledで運用せず、log_onlyでworkerが何を消しそうかを見てから切り替えられます。

競合とread_onlyの注意点

同じメモリがストア側でも変わっていた場合、競合はストアが勝ちます。次の同期でworkerはストア側の版でローカルを上書きし、警告をログに出します。write・editツール自体は成功し、エージェントにエラーは返りません。変更がまだ必要なら、同期後に読み直してやり直させます。

read_onlyのストアでは、write・editツールが変更を拒否し、workerもアップロードしません。ただしbashや、サンドボックスから出す独自ツール・MCPサーバー経由の変更はローカルでは止まりません。それらは同期されず、次にストア側が変わった時点で上書きされます。ローカルコピーも変えたくないなら、そのエージェントのbashを無効にし、サンドボックスに書き込む独自ツールを持たせません。ストアのパスを読み取り専用でマウントするのは避けます。ディレクトリの作成とダウンロードをworker自身が行うためです。

起動できないときの切り分け

workerがストアをマウントできないと、そのワークアイテムは失敗します。セッションにエラーイベントは出ず、idleのまま止まります。ログに出る文言で原因を切り分けます。

原因を直したあとは、user.interruptイベントを送ると作業が再びキューに入り、次のworkerがマウントをやり直します。

事前に整えるものは次のとおりです。ant CLI 1.33.0以降、または各SDKのEnvironmentWorkerを使います。ホストはPOSIXファイルシステムが必要で、Windowsホストは未対応です。大文字小文字を区別するファイルシステムが推奨です。/mnt/memoryは書き込み可能にしておきます。

sudo mkdir -p /mnt/memory && sudo chown "$USER" /mnt/memory

ストアごとのディレクトリは自分で作りません。workerがセッション開始時に作り、終了時に消します。各ディレクトリの.anthropic-memory-storeというマーカーファイルは残しておく必要があり、無くなったり書き換わったりしたディレクトリは同期されません。同じストアを持つ2つのセッションを1台のホストで同時に動かすことはできないので、セッションごとにサンドボックスを分けます。Claude Platform on AWSのセルフホスト環境には、メモリストアをアタッチできません。

まとめ

アタッチはセッション作成時の1回きりで、既定がread_writeという2点を押さえれば、事故の大半は避けられます。セルフホストでは、変更が見えるのは双方のworkerが同期したあとです。参照するだけのセッションにはread_onlyを付けておくと、書き込みの出どころを追いやすくなります。

カスタムSkillと組み合わせてエージェントの専門性を作り込む場合はカスタムSkillの追加方法も参考にしてください。Managed Agents自体の全体設計はManaged Agentsの設計思想で扱っています。