セルフホスト型サンドボックスでのメモリストア

セルフホスト環境上のセッションは、クラウド環境上のセッションとまったく同じ方法でメモリストアをアタッチします。セッションにメモリストアをアタッチするに示すように、セッションを作成する際にresourcesにそれらを列挙します。1つのセッションには最大8個のメモリストアをアタッチできます。

違いは、誰がストアを実体化するかです。セルフホスト環境では、Anthropicのインフラストラクチャではなくお使いのワーカーが、各ストアをサンドボックスにダウンロードし、エージェントによる変更を同期して戻します。

要件

• メモリストアをマウントするワーカー： ant CLI 1.33.0以降、またはPython、TypeScript、Go SDKのEnvironmentWorkerを使用してください。
• POSIXファイルシステム： ワーカーはメモリファイルを開く際にO_NOFOLLOWを必要とするため、Windowsホストはサポートされていません。大文字と小文字のみが異なるメモリパスが衝突しないよう、大文字と小文字を区別するファイルシステムを推奨します。
• 書き込み可能な/mnt/memoryディレクトリ： ホストを準備するを参照してください。
• ワークアイテムのシークレット： 独自のコードでワーカーを起動する場合は、ワークアイテムのシークレットを転送してください。

ホストを準備する

ワーカーを起動する前に、親ディレクトリを作成し、ワーカーを実行するユーザーが書き込めるようにします：

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

ストアごとのディレクトリは自分で作成しないでください。ワーカーは、セッションの開始時に各ストアのmount_pathディレクトリ（例：/mnt/memory/user-preferences）を作成し、セッションの終了時に削除します。そのパスにすでに何かが存在する場合、ワーカーはそのセッションの作業の開始を拒否します。

セッションごとのサンドボックスパターンでは、サンドボックスイメージに書き込み可能な/mnt/memoryが必要です。ワーカーはサンドボックスが終了する前にメモリディレクトリの内容をストアにアップロードするため、メモリディレクトリをホストにバインドマウントする必要はありません。

ストアを共有するセッションを分離する

2つのセッションは同じパスを必要とするため、1つのホスト上で同じストアを同時にマウントすることはできません。セッションが同じストアをアタッチする場合は、ファイルシステムごとに1つのセッションを実行してください。各セッションに専用のサンドボックスを与えることで、このルールを満たせます。

ワーカーによるメモリの処理方法

メモリストアがアタッチされたセッションのワークアイテムを取得すると、ワーカーは次の処理を行います：

1. 各ストアをmount_pathにダウンロードします。 これはクラウドセッションが使用するのと同じ/mnt/memory/配下のディレクトリであり、セッションのシステムプロンプトがエージェントにそれを説明します。たとえば、「User Preferences」という名前のストアは/mnt/memory/user-preferences/に配置されます。
2. それらのディレクトリをファイルツールに公開します。 エージェントは、作業ディレクトリで使用するのと同じファイルツールでメモリを操作します。
3. ツール呼び出しの後に変更を照合します。 これは同期間隔（デフォルトでは15秒）ごとに最大1回行われます。ストア内で変更されたメモリはディスクに書き込まれ、エージェントが変更したファイルはストアにアップロードされます。
4. セッション終了時に最終同期を実行します。 保留中のアップロードを最大30秒間フラッシュし、その後作成したディレクトリを削除します。

Anthropic側のメモリストアが引き続き信頼できる情報源となります。メモリバージョン、redact、Consoleでのメモリの表示や編集は、クラウドセッションの場合と同様に機能します。エージェントによるメモリの読み取りと書き込みは、通常のツールイベントとしてイベントストリームに表示されます。

各ワーカーは一定間隔で同期するため、あるセッションで書き込まれた変更は、両方のセッションが同期した後にのみ、実行中の別のセッションから見えるようになります。デフォルトの間隔では、通常1分を大きく下回ります。クラウドサンドボックス上のセッションは、互いの変更をほぼ即座に確認できます。

各ストアディレクトリには、ディレクトリをそのストアに結び付ける.anthropic-memory-storeという名前のマーカーファイルが含まれています。これはそのままにしておいてください。マーカーが欠落しているか改変されているディレクトリは、ワーカーによって同期されません。

同期を設定する

2つのEnvironmentWorkerオプションがメモリの動作を制御します。Webhookハンドラー内を含め、ワーカーを構築する場所でこれらを設定してください。ant CLIワーカーは常にデフォルト値を使用します。

同期間隔

memory_sync_intervalは、セッションの実行中にアタッチされたストアがサーバーと照合される頻度を設定します。

間隔を短くすると、別のセッションが古いメモリを参照する時間枠が狭まりますが、その代わりにメモリストアへのリクエストが増えます。

メモリサポートを無効にするのは、セッションがメモリストアをアタッチしないワーカーに限ってください。無効化されたワーカーはストアのダウンロードも同期も行わないため、ストアがアタッチされたセッションは、システムプロンプトがそれらを説明しているにもかかわらず、ストアなしで実行されます。

メモリサポートが有効な間、ストアがアタッチされたセッションのワークアイテムがsecretなしで届いた場合、メモリなしで実行されるのではなく失敗します。メモリストアのマウントに失敗するを参照してください。

削除

memory_sync_deletionsは、エージェントがローカルで削除したファイルをストアからも削除するかどうかを設定します。アップロードとダウンロードには影響しません。

たとえば、10秒ごとに同期し、ワーカーが行ったであろう削除をログに記録するだけにするには、次のようにします：

worker = EnvironmentWorker(
    client,
    environment_id=environment_id,
    environment_key=environment_key,
    workdir="/workspace",
    memory_sync_interval=10,  # seconds
    memory_sync_deletions="log_only",
)

読み取り専用ストアと競合

access: "read_only"でアタッチされたストアの場合、writeツールとeditツールはそのディレクトリ内のファイルの変更を拒否します。ワーカーはそこから何もアップロードしません。

bash、またはサンドボックスから提供するカスタムツールやMCPサーバーを通じて行われた変更は、ローカルではブロックされません。それらはストアに同期されることはなく、そのメモリに対する次のリモート変更によって上書きされます。セッション中にローカルコピー自体を変更されないままにする必要がある場合は、次のようにします：

• そのエージェントのbashツールを無効にし、サンドボックスのファイルシステムに書き込むカスタムツールを与えないでください。
• ストアパスを読み取り専用でマウントしないでください。ワーカー自身がディレクトリを作成し、ダウンロードしたメモリをそこに書き込む必要があります。

競合はストア側が優先されて解決されます。セッションが最後に同期して以降にストア内でも変更されたメモリファイルを、エージェントが変更したとします。次の同期時に、ワーカーはストアのバージョンを保持し、それでローカルファイルを上書きして、警告をログに記録します。writeツールとeditツール自体は成功し、エージェントにエラーは届きません。エージェントの変更がまだ有効な場合は、同期後にファイルを再度読み取り、変更をやり直すことができます。

トラブルシューティング

ワーカーのログメッセージとその修正方法については、メモリストアのマウントに失敗するを参照してください。