メモリの使用

Agent Memoryはリサーチプレビュー機能です。アクセスをリクエストして試してください。

Agent APIセッションはデフォルトではエフェメラルです。セッションが終了すると、エージェントが学習したことはすべて失われます。メモリストアを使用すると、エージェントはセッション間で学習を持ち越すことができます。ユーザーの好み、プロジェクト規約、過去の失敗、ドメインコンテキストなどです。

すべてのManaged Agents APIリクエストには、managed-agents-2026-04-01ベータヘッダーが必要です。リサーチプレビュー機能には追加のベータヘッダーが必要です。SDKはこれらのベータヘッダーを自動的に設定します。

概要

メモリストアは、Claudeに最適化されたワークスペーススコープのテキストドキュメント集です。1つ以上のメモリストアがセッションに接続されると、エージェントはタスクを開始する前に自動的にストアをチェックし、完了時に永続的な学習を書き込みます。追加のプロンプトや設定は必要ありません。

ストア内の各メモリは、APIまたはConsoleを通じて直接アクセスおよび編集でき、メモリの調整、インポート、エクスポートが可能です。

メモリへのすべての変更は、不変のmemory_versionを作成し、メモリ変更の監査とロールバックをサポートします。

メモリストアを作成する

ストアにnameとdescriptionを指定します。説明はエージェントに渡され、ストアに何が含まれているかを伝えます。

store=$(curl -fsS https://api.anthropic.com/v1/memory_stores \
  -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
{
  "name": "User Preferences",
  "description": "Per-user preferences and project context."
}
EOF
)
store_id=$(jq -r '.id' <<< "$store")
echo "$store_id"  # memstore_01Hx...

メモリストアid（memstore_...）は、ストアをセッションに接続するときに渡すものです。

コンテンツでシードする（オプション）

エージェント実行前にストアに参考資料を事前ロードします。

ストア内の個々のメモリは100KB（約25Kトークン）に制限されています。メモリを少数の大きなファイルではなく、多くの小さな焦点を絞ったファイルとして構造化してください。

セッションにメモリを接続する

メモリストアはセッションのresources[]配列に接続されます。

このメモリストアの使用方法についてClaudeに提供するセッション固有の指示を提供したい場合は、オプションでpromptを含めてください。これはメモリストアのnameとdescriptionに加えてClaudeに提供され、4,096文字に制限されています。

accessも設定できます。デフォルトはread_writeですが、read_onlyもサポートされています（以下の例で明示的に示されています）。

セッションあたり最大8つのメモリストアがサポートされています。メモリの異なる部分が異なる所有者またはアクセスルールを持つ場合は、複数のストアを接続します。一般的な理由：

共有参考資料 - 多くのセッションに接続された1つの読み取り専用ストア（標準、規約、ドメイン知識）、各セッション独自の読み取り/書き込み学習から分離。
製品の構造へのマッピング - エンドユーザーごと、チームごと、またはプロジェクトごとに1つのストア、単一のエージェント設定を共有。
異なるライフサイクル - 単一のセッションより長く存在するストア、または独自のスケジュールでアーカイブしたいストア。

メモリツール

メモリストアがセッションに接続されると、エージェントは自動的にメモリツールにアクセスできるようになります。メモリストアとのエージェントの相互作用は、イベントストリームでagent.tool_useイベントとして登録されます。

ツール	説明
`memory_list`	ストア内のドキュメントをリストアップし、オプションでパスプレフィックスでフィルタリング。
`memory_search`	ドキュメントコンテンツ全体にわたるフルテキスト検索。
`memory_read`	ドキュメントのコンテンツを読み取る。
`memory_write`	パスにドキュメントを作成または上書き。
`memory_edit`	既存のドキュメントを変更。
`memory_delete`	ドキュメントを削除。

メモリを検査および修正する

メモリストアはAPIを通じて直接管理できます。これを使用して、レビューワークフローを構築したり、悪いメモリを修正したり、セッション実行前にストアをシードしたりします。

メモリをリストアップする

リストはメモリコンテンツを返さず、オブジェクトメタデータのみを返します。path_prefixをディレクトリスコープのリストに使用します（末尾のスラッシュを含めます：/notes/は/notes/a.mdにマッチしますが、/notes_backup/old.mdにはマッチしません）。

メモリを読み取る

個々のメモリを取得すると、完全なドキュメントコンテンツが返されます。

ドキュメントを書き込む

memories.writeを使用して、パスでドキュメントをアップサート（作成または更新）します。パスに何も存在しない場合は作成されます。ドキュメントが既にそこに存在する場合は、そのコンテンツが置き換えられます。既存のドキュメントを**mem_... ID で**変更する場合（例えば、パスの名前を変更したり、コンテンツ編集を安全に適用したりする場合）は、代わりにmemories.updateを使用します（以下の更新を参照）。

パスが空いている場合のみ作成する

precondition={"type": "not_exists"}をmemories.writeに渡して、作成のみガードを作成します。ドキュメントがパスに既に存在する場合、書き込みは置き換える代わりに409 memory_precondition_failedを返します。ストアをシードするときに既存のコンテンツを上書きしたくない場合に使用します。

既存のドキュメントを安全に編集するには（読み取り、変更、書き込み戻す際に同時実行変更を上書きしない）、代わりにcontent_sha256前提条件でmemories.updateを使用します。以下の更新を参照してください。

更新

memories.update()は、そのmem_... IDで既存のドキュメントを変更します。content、path（名前変更）、またはその両方を1回の呼び出しで変更できます。

占有されたパスへの名前変更は409 conflictを返します。呼び出し元は最初にブロッカーを削除または名前変更するか、precondition={"type": "not_exists"}を渡して、ターゲットに既に何かが存在する場合は名前変更をノーオプにする必要があります。

以下の例は、ドキュメントをアーカイブパスに名前変更します。

安全なコンテンツ編集（楽観的同時実行制御）

ドキュメントのコンテンツを同時実行書き込みを上書きせずに編集するには、content_sha256前提条件を渡します。更新は、保存されたハッシュが読み取ったものと一致する場合にのみ適用されます。不一致の場合は409 memory_precondition_failedを返し、その時点でドキュメントを再読み込みして新しい状態に対して再試行します。

ドキュメントを削除する

オプションで条件付き削除のためにexpected_content_sha256を渡します。

メモリバージョン

メモリへのすべての変更は、不変のメモリバージョン（memver_...）を作成します。バージョンは親メモリの存続期間中に蓄積され、その下の監査とロールバック表面を形成します。ライブmemories.retrieve呼び出しは常に現在のヘッドを返します。バージョンエンドポイントは完全な履歴を提供します。

すべての変更で新しいバージョンが書き込まれます。

パスへの最初のmemories.writeは、operation: "created"でバージョンを作成します。
content、path、またはその両方を変更するmemories.updateは、operation: "modified"でバージョンを作成します。
memories.deleteは、operation: "deleted"でバージョンを作成します。

バージョンエンドポイントを使用して、どのユーザーまたはエージェントが何をいつ変更したかを監査し、以前のスナップショットを検査または復元し、redactで履歴から機密コンテンツをスクラブします。

バージョンをリスト表示

ストアのバージョンメタデータをページネーション付きでリスト表示します（最新順）。memory_id、operation（created、modified、またはdeleted）、session_id、api_key_id、またはcreated_at_gte/created_at_lteの時間範囲でフィルタリングできます。リスト応答にはcontent本体は含まれません。完全なコンテンツが必要な場合は、retrieveで個別のバージョンを取得してください。

バージョンを取得

個別のバージョンを取得すると、リスト応答と同じフィールドに加えて、完全なcontent本体が返されます。

バージョンを編集

バージョンを編集すると、履歴バージョンのコンテンツをスクラブしながら、監査証跡（誰が何をいつしたか）を保持します。漏洩したシークレット、個人識別情報、またはユーザー削除リクエストの削除など、コンプライアンスワークフローに使用します。編集はcontent、content_sha256、content_size_bytes、およびpathをハード削除します。アクターとタイムスタンプを含むその他すべてのフィールドは保持されます。

curl -fsS "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: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- > /dev/null <<EOF
{
  "path": "/formatting_standards.md",
  "content": "All reports use GAAP formatting. Dates are ISO-8601..."
}
EOF

session=$(curl -fsS 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",
      "prompt": "User preferences and project context. Check before starting any task."
    }
  ]
}
EOF
)

page=$(curl -fsS "https://api.anthropic.com/v1/memory_stores/$store_id/memories?path_prefix=/" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")
jq -r '.data[] | "\(.path)  (\(.size_bytes) bytes, sha=\(.content_sha256[0:8]))"' <<< "$page"

mem=$(curl -fsS "https://api.anthropic.com/v1/memory_stores/$store_id/memories/$memory_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")
jq -r '.content' <<< "$mem"

mem=$(curl -fsS "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: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<EOF
{
  "path": "/preferences/formatting.md",
  "content": "Always use tabs, not spaces."
}
EOF
)

curl -fsS "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: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- > /dev/null <<EOF
{
  "path": "/preferences/formatting.md",
  "content": "Always use 2-space indentation.",
  "precondition": {"type": "not_exists"}
}
EOF

curl -fsS -X PATCH "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: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{"path": "/archive/2026_q1_formatting.md"}' > /dev/null

curl -fsS -X PATCH "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: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- > /dev/null <<EOF
{
  "content": "CORRECTED: Always use 2-space indentation.",
  "precondition": {"type": "content_sha256", "content_sha256": "$mem_sha"}
}
EOF

curl -fsS -X DELETE "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: managed-agents-2026-04-01" > /dev/null

curl -fsS "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: managed-agents-2026-04-01" \
  | jq -r '.data[] | "\(.id): \(.operation)"'

curl -fsS "https://api.anthropic.com/v1/memory_stores/$store_id/memory_versions/$version_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

curl -fsS -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: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{}'