エージェントメモリの使用

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

概要

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

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

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

メモリストアを作成する

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

store = client.beta.memory_stores.create(
    name="User Preferences",
    description="Per-user preferences and project context.",
)
print(store.id)  # memstore_01Hx...

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

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

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

client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/formatting_standards.md",
    content="All reports use GAAP formatting. Dates are ISO-8601...",
)

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

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

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

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

session = client.beta.sessions.create(
    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.",
        }
    ],
)

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

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

メモリツール

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

メモリを表示および編集する

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

メモリをリストする

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

page = client.beta.memory_stores.memories.list(
    store.id,
    path_prefix="/",
)
for memory in page.data:
    print(
        f"{memory.path}  ({memory.size_bytes} bytes, sha={memory.content_sha256[:8]})"
    )

メモリを読み取る

個別メモリをフェッチすると、完全なコンテンツが返されます。

mem = client.beta.memory_stores.memories.retrieve(
    memory_id,
    memory_store_id=store.id,
)
print(mem.content)

メモリを作成する

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

mem = client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/preferences/formatting.md",
    content="Always use tabs, not spaces.",
)

安全な書き込み（楽観的同時実行制御）

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

client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/preferences/formatting.md",
    content="Always use 2-space indentation.",
    precondition={"type": "not_exists"},
)

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

メモリを更新する

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

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

以下の例は、メモリをアーカイブパスに名前変更します。

client.beta.memory_stores.memories.update(
    mem.id,
    memory_store_id=store.id,
    path="/archive/2026_q1_formatting.md",
)

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

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

client.beta.memory_stores.memories.update(
    memory_id=mem.id,
    memory_store_id=store.id,
    content="CORRECTED: Always use 2-space indentation.",
    precondition={"type": "content_sha256", "content_sha256": mem.content_sha256},
)

メモリを削除する

client.beta.memory_stores.memories.delete(
    mem.id,
    memory_store_id=store.id,
)

オプションで条件付き削除のために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で個別のバージョンを取得してください。

for v in client.beta.memory_stores.memory_versions.list(
    store.id,
    memory_id=mem.id,
):
    print(f"{v.id}: {v.operation}")

バージョンを取得

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

version = client.beta.memory_stores.memory_versions.retrieve(
    version_id,
    memory_store_id=store.id,
)
print(version.content)

バージョンを編集

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

client.beta.memory_stores.memory_versions.redact(
    version_id,
    memory_store_id=store.id,
)