AnthropicはClaude Managed AgentsのMemory Store一覧APIについて、agent-memory-2026-07-22 betaヘッダーを追加した。2026年7月22日には、従来のmanaged-agents-2026-04-01ヘッダーも同じ一覧挙動を採用する。
対象はGET /v1/memory_stores/{memory_store_id}/memoriesである。メモリの同期、管理画面、バックアップ、監査、差分取得を行う処理では、並び順やページカーソルの前提が崩れる可能性がある。
変更点
| 項目 | 新しい挙動 |
|---|---|
| 並び順 | 安定したサーバー定義順で返却 |
order_by / order | 指定しても無視される |
depth | 0、1、省略のみ許可 |
不正なdepth | 400エラー |
path_prefix | 末尾に/が必要 |
| prefix照合 | 部分文字列ではなくパスセグメント単位 |
| ページカーソル | 旧ヘッダーで発行したカーソルと互換性なし |
| betaヘッダー | Memory Storeでは新ヘッダーが旧ヘッダーを置換 |
新旧のbetaヘッダーを同時に送ると400エラーになる。追加ではなく置換として扱う必要がある。
SDK利用者も確認が必要
Anthropicは次のSDKバージョンから、Memory Store呼び出しに新しいヘッダーを送るよう変更した。
- Python
0.116.0 - TypeScript
0.110.0 - Go
1.56.0 - Java
2.48.0 - Ruby
1.55.0 - PHP
0.36.0 - C#
12.35.0 - CLI
1.16.0
SDKを更新しただけで、アプリケーション側の挙動が変わる可能性がある。特にコードがbetasを明示指定している場合は、旧ヘッダーを残したまま新ヘッダーを追加しないようにする。
壊れやすい実装
APIの返却順を業務上の順序として使う
order_byとorderが無視されるため、更新日時順や名称順を期待して画面表示、差分処理、先頭件取得を行う実装は結果が変わる。必要な順序はクライアント側で明示的に並べ替える。
ページカーソルを長期間保存する
旧ヘッダーで発行されたカーソルは新ヘッダーで利用できない。キューやデータベースへカーソルを保存し、翌日以降に続きから取得する処理は、切り替え時に先頭ページから再開する必要がある。
depthへ2以上を渡す
従来の実装が深い階層を一度に取得している場合、新仕様では400になる。depth: 1で段階的にたどるか、一覧設計を見直す。
曖昧なpath_prefixを使う
新仕様では末尾の/が必須で、パスセグメント全体で照合される。たとえばprojects/acmeではなくprojects/acme/を指定し、期待する階層だけが返るか確認する。
betaヘッダーを共通配列へ追記する
Memory Storeだけは新ヘッダーが旧ヘッダーを置き換える。共通HTTPクライアントが両方を送ると、正常なリクエストまで400になる。
必要な対応
1. 対象エンドポイントを特定する
ソースコード、APIゲートウェイ、SDKラッパー、運用スクリプトから、Memory Store一覧エンドポイントを呼ぶ箇所を検索する。
2. 新ヘッダーで先行試験する
本番と同じデータ量、階層、ページ数を持つ環境でagent-memory-2026-07-22を指定する。返却順、重複、欠落、ページ遷移、エラー処理を確認する。
3. カーソル移行を設計する
切り替え時には既存カーソルを破棄し、最初のページから取得する。重複登録を防ぐため、メモリIDによる冪等なupsertを使う。
4. ソートをアプリケーション責務にする
表示順や処理順が必要なら、取得後に安定ソートする。ページをまたぐ全体ソートが必要な場合は、全件取得後の処理または索引データベースを検討する。
5. depthとpath_prefixを検証する
固定値だけでなく、ユーザー入力、設定値、古いジョブ定義も確認する。入力不正は呼び出し前に検証し、400を監視対象へ加える。
切り替え時の試験項目
- 1ページだけのMemory Store
- 複数ページにまたがる大量データ
- 同名メモリが異なるパスに存在するケース
- 深い階層を持つパス
- ページ取得中にデータが追加・削除されるケース
- 旧カーソルを誤って送るケース
- 新旧ヘッダーを同時送信するケース
- SDK更新前後のHTTPヘッダー比較
推奨スケジュール
| 期限 | 実施内容 |
|---|---|
| 7月15日まで | 利用箇所、SDK、明示beta指定を棚卸し |
| 7月18日まで | 新ヘッダーで回帰試験 |
| 7月20日まで | カーソル破棄と再同期手順を準備 |
| 7月21日 | 本番設定と監視を最終確認 |
| 7月22日 | 400増加、欠落、重複を重点監視 |
編集部分析
今回の変更はモデル品質ではなく、状態管理APIの契約変更である。生成AIシステムではモデル更新が注目されやすいが、メモリ、セッション、ジョブ、ページングの変更も本番障害へ直結する。
特にカーソルは「不透明な値」であり、クライアントが意味を推測したり長期保存したりするべきではない。仕様変更に耐えるには、先頭から再同期できること、ID単位で冪等に処理できること、進捗より正確性を優先できることが重要である。
実務チェックリスト
- [ ] Memory Store一覧APIの利用箇所を特定した
- [ ] SDKバージョンと送信ヘッダーを確認した
- [ ] 新旧ヘッダーを同時送信していない
- [ ]
order_byとorderへの依存を除いた - [ ]
depthを0、1、省略へ限定した - [ ]
path_prefixの末尾/を確認した - [ ] 旧カーソルを破棄して再同期できる
- [ ] ID単位の冪等処理を実装した
- [ ] 7月22日の監視体制を準備した