Claude Media
Managed Agentsのメモリストアの使い方 — 作成・アタッチ・監査ログの確認
AnthropicAgent SDKチュートリアル

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

Managed Agentsのメモリストアをセッションにアタッチしてセッションをまたぐ記憶を持たせる手順と、変更履歴を監査するAPIの使い方をまとめます。

読了目安 約18分

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

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

メモリストアの実体は、ワークスペース単位のテキストドキュメント集合です。セッションにアタッチするとサンドボックス内にディレクトリとしてマウントされ、エージェントは他のファイルと同じファイルツールで読み書きします。マウントの説明はシステムプロンプトに自動的に追加されるため、エージェント側での特別な指示は不要です。ストア内の各メモリはpathでアドレスされ、API経由でもConsole経由でも直接読み書き・編集できます。そしてメモリへのすべての変更は、変更できないメモリバージョンを作ります。これがエージェントの書き込みに対する監査証跡とポイントインタイム復元を可能にします。

セルフホストサンドボックスでは、ディレクトリはライブマウントではありません。SDKのenvironment workerがエージェントのツール実行前に各ストアをダウンロードし、その後もストアと同期を取り続けます(既定の同期間隔は15秒、セッション終了時にも1回同期)。エージェントのwrite・editツールが変更するのはローカルコピーだけで、実際のアップロードは次の同期タイミングで行われます。そのため、同じストアを複数のセルフホストセッションで共有している場合、片方の変更がもう片方から見えるようになるのは双方のworkerが同期を終えたあとになります。read_onlyストアではworkerのwrite・editツール自体が変更を拒否し、ローカルコピーからストアへのアップロードも発生しません。

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

ストアの作成には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")

メモリストア系のエンドポイントは、他のManaged Agents API(managed-agents-2026-04-01)とは異なるベータヘッダagent-memory-2026-07-22を使います。両方を同時に送ると400エラーになるため、明示的にヘッダを組み立てているコードではこの点に注意します。

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

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..."}'

個々のメモリは100kB(おおよそ25,000トークン)が上限で、1ストアあたり最大10,000メモリまでです。少数の大きなファイルではなく、多数の小さく焦点を絞ったファイルとして構造化するのが公式の推奨です。

セッションにアタッチする — 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は任意項目で、そのセッションでストアをどう使ってほしいかをエージェントに伝える指示文です(4,096字上限)。accessはread_write(既定)とread_onlyのいずれかを指定します。

access向いている用途
read_write(既定)向いている用途エージェント自身がメモリを更新していく本流のストア
read_only向いている用途参照資料・共有ルックアップなど、エージェントに変更させたくないストア

1セッションにアタッチできるメモリストアは最大8個です。オーナーやアクセスルールが異なる部分を分けたいとき(共有参照資料は1つのread_onlyストア、各セッション固有の内容は別のread_writeストア)、ユーザー・チーム・プロジェクトの単位でストアを対応づけたいとき、ライフサイクルが異なるストアを個別にアーカイブしたいときなどに複数ストアを使い分けます。同じエージェントの設定を複数のエンドユーザーやプロジェクトで使い回しながら、記憶だけをアタッチ先のストアで切り替えるという構成も、この8個という枠の中で組み立てます。

マウント先は/mnt/memory/配下で、ディレクトリ名はストアの表示名を小文字化し非英数字の連続を1つのハイフンに置き換えたスラッグです。正確なパスはセッションのメモリストアリソースが返すmount_pathフィールドから取得すべきで、自前で組み立てるべきではありません。accessはファイルシステムレベルで強制され、read_onlyマウントへの書き込みは拒否され、read_writeマウントへの書き込みはセッションに紐づくメモリバージョンを生成します。エージェントの読み書きは、イベントストリーム上では通常のagent.tool_use / agent.tool_resultイベントとして観測できます。

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

メモリはAPIから直接管理できます。レビューワークフローの構築や、誤ったメモリの修正、セッション実行前のストア準備に使います。同じ操作はClaude Consoleからも行えるため、コードを書かずにメモリの中身を確認・修正したい場合はConsole側のUIを使う選択肢もあります。ストアの中身はテキストドキュメントに最適化されているので、バイナリファイルではなく文章として読み書きできる情報を蓄積する設計が前提です。

  • 一覧: path_prefix(/で終わる必要があり、パスセグメント単位で一致)で対象を絞り、depth(省略または0でサブツリー全体、1で直下のみ)で深さを制御します。結果は安定したサーバー側の順序で返り、この一覧の挙動はmanaged-agents-2026-04-01とagent-memory-2026-07-22のどちらのベータヘッダでも変わりません
  • 作成: memories.createは新規パスへの作成専用で、既存メモリを上書きしません。既存メモリの変更はmemories.updateを使います
  • 更新: content・path(リネーム)のいずれか、または両方を変更できます
  • 削除: memories.deleteでメモリ自体を削除します

同時編集を安全に行うには、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日を超えて履歴が残ることがあります。

専用のロールバックエンドポイントはありません。復元したい場合は、目的のバージョンのcontentを取得し、memories.updateで書き戻します(親メモリがすでに削除されている場合は、そのバージョンがまだ保持されている限りmemories.createで書き戻せます)。30日を過ぎたバージョンは削除される可能性があるため、より長い履歴が必要な場合はAPI経由でエクスポートしておく必要があります。

redactは、監査証跡(誰が・何を・いつ変更したか)を保持したまま、過去バージョンの本文だけを削除する操作です。漏洩したシークレットやPIIの除去、ユーザーの削除リクエストへの対応といったコンプライアンス用途に使います。ただし、ライブメモリの現行ヘッドになっているバージョンはredactできません。先に新しいバージョンを書くか、メモリ自体を削除してから、古いバージョンをredactします。

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

まとめ

メモリストアはセッション作成時にしかアタッチできず、既定はread_writeという2点をまず押さえておくと事故を避けやすくなります。参照資料はread_onlyで共有し、エージェントが実際に書き込んでいくストアだけをread_writeにする構成が基本形です。書き込まれた内容はメモリバージョンとして30日以上残る前提で運用でき、redactによって監査証跡を保ったまま機微情報だけを消せます。ストアが肥大化してきたときの整理方針や、そもそも何を書き込ませるべきかという設計判断はメモリ管理のベストプラクティスにまとめています。カスタムSkillと組み合わせてエージェントの専門性を作り込む場合はカスタムSkillの追加方法も参考にしてください。Managed Agents自体の全体設計はManaged Agentsの設計思想で扱っています。

この記事を共有:XはてブLinkedIn

関連する記事

Anthropic をもっと見る →