セルフホスト型サンドボックスでのメモリストア
セルフホスト型サンドボックスで実行されるClaude Managed Agentsのセッションにメモリストアをアタッチします。ホストの準備、同期の設定、読み取り専用ストアと競合の処理について説明します。
セルフホスト環境上のセッションは、クラウド環境上のセッションとまったく同じ方法でメモリストアをアタッチします。セッションにメモリストアをアタッチするに示すように、セッションを作成する際にresourcesにそれらを列挙します。1つのセッションには最大8個のメモリストアをアタッチできます。
違いは、誰がストアを実体化するかです。セルフホスト環境では、Anthropicのインフラストラクチャではなくお使いのワーカーが、各ストアをサンドボックスにダウンロードし、エージェントによる変更を同期して戻します。
要件
- メモリストアをマウントするワーカー:
antCLI 1.33.0以降、またはPython、TypeScript、Go SDKのEnvironmentWorkerを使用してください。 - POSIXファイルシステム: ワーカーはメモリファイルを開く際に
O_NOFOLLOWを必要とするため、Windowsホストはサポートされていません。大文字と小文字の違いのみで異なるメモリパスが衝突しないように、Anthropicは大文字と小文字を区別するファイルシステムを推奨します。macOSのボリュームはデフォルトで大文字と小文字を区別しないため、そのようなパスはmacOS上では衝突します。 - 書き込み可能な
/mnt/memoryディレクトリ: ホストを準備するを参照してください。macOSの場合は、macOSホストを準備するを参照してください。 - ワークアイテムのシークレット: 独自のコードでワーカーを起動する場合は、ワークアイテムのシークレットを転送してください。
ホストを準備する
macOSでは、次のコマンドをスキップし、代わりにmacOSホストを準備するの手順に従ってください。
ワーカーを起動する前に、親ディレクトリを作成し、ワーカーを実行するユーザーが書き込めるようにします:
sudo mkdir -p /mnt/memory && sudo chown "$USER" /mnt/memoryストアのディレクトリは自分で作成しないでください。ワーカーは、セッションを取得した時点で各ストアのmount_pathディレクトリ(例:/mnt/memory/user-preferences)を作成し、そのセッションの処理を終えた時点で削除します。そのパスにすでに何かが存在する場合は、空のディレクトリであっても、ワーカーはワークアイテムを失敗させます。
セッションごとのサンドボックスパターンでは、サンドボックスイメージに書き込み可能な/mnt/memoryが必要です。ストアがすべてのメモリの永続的なコピーを保持するため、メモリディレクトリをホストにバインドマウントする必要はありません。
macOSホストを準備する
macOSではルートボリュームが読み取り専用であるため、mkdirで/mntを作成することはできません。代わりに、書き込み可能なデータボリューム上に/System/Volumes/Data/mnt/memoryを作成します。次に、/etc/synthetic.confに1行を追加して、macOSが/mntを/System/Volumes/Data/mntへのシンボリックリンクとして作成するようにします。これらの手順には管理者権限が必要です。
このセットアップを行わないと、ワーカーはストアのディレクトリを作成できないため、ワークアイテムを失敗させます。その場合、セッションはエラーイベントなしでアイドル状態のままになります。メモリストアのマウントまたは同期に失敗するを参照してください。
データボリューム上にディレクトリを作成する
memoryディレクトリを作成し、ワーカーのユーザーをその所有者にします。$USERはご自身のユーザー名です。ワーカーが別のユーザーとして実行される場合は、"$USER"をそのユーザーの名前に置き換えてください。sudo mkdir -p /System/Volumes/Data/mnt/memory && sudo chown "$USER" /System/Volumes/Data/mnt/memoryこの場所は選択肢の1つにすぎません。別の場所を使用する場合は、
synthetic.confの行のパスをそれに合わせて変更してください。Anthropicがテストしたのは/System/Volumes/Data/mntのみです。synthetic.confに1行を追加する
cat -et /etc/synthetic.confを実行します。これにより、各タブが^Iとして、各行末が$として表示されます。mnt^ISystem/Volumes/Data/mnt$という行がある場合、この手順はすでに完了しています。次の手順に進んでください。mntで始まる別の行がある場合は、中止してください。このMac上の別の何かがすでに/mntを定義しています。- 最後の行が
$で終わっていない場合は、echo | sudo tee -a /etc/synthetic.confを実行して行を終端させてください。その後、行を追加します。 - 何も出力されない場合、または
No such file or directoryと報告される場合は、行を追加します。次のコマンドは、ファイルが存在しない場合に作成します。 - それ以外の場合は、行を追加します。
行を追加するには、このコマンドを実行します。このコマンドは実行するたびに行が追加されるため、1回だけ実行してください。
printf 'mnt\tSystem/Volumes/Data/mnt\n' | sudo tee -a /etc/synthetic.confこのコマンドは追加した行を出力します。この行は、名前
mntをmemoryを含むディレクトリにマッピングします。ファイルには2つの列の間にタブが必要であり、それを\tが書き込みます。リンクを作成する
-tオプションを付けてapfs.utilを実行します。これにより、追加した行からリンクが再起動なしで作成されます。sudo /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -t結果を確認する
/mntと/mnt/memoryを一覧表示します。ls -ld /mnt /mnt/memory1行目は
/mnt -> System/Volumes/Data/mntで終わります。2行目には、ワーカーのユーザーが/mnt/memoryの所有者として表示されます。これでワーカーを起動できます。
Anthropicは、このセットアップをant CLIワーカーを使用してmacOS 26.7.1でテストしています。
ストアを共有するセッションを分離する
2つのセッションは同じパスを必要とするため、1つのファイルシステム上で同じストアを同時にマウントすることはできません。ストアを共有するセッションを並行して実行するには、各セッションに専用のファイルシステムを割り当ててください。セッションごとにサンドボックスを使用すると、各セッションに専用のファイルシステムが自動的に割り当てられます。セッションごとに1つのサンドボックスを実行するを参照してください。1つのホストでこのようなサンドボックスを多数実行できます。
ワーカーによるメモリの処理方法
メモリストアがアタッチされたセッションのワークアイテムを取得すると、ワーカーは次の処理を行います:
- 各ストアを
mount_pathにダウンロードします。 これはクラウドセッションが使用するのと同じ/mnt/memory/配下のディレクトリであり、セッションのシステムプロンプトがエージェントにそれを説明します。たとえば、「User Preferences」という名前のストアは/mnt/memory/user-preferences/に配置されます。 - それらのディレクトリをファイルツールに公開します。 エージェントは、作業ディレクトリで使用するのと同じファイルツールでメモリを操作します。
- ツール呼び出しの後に同期します。 前回の同期から同期間隔(デフォルトでは15秒)が経過している場合、ワーカーはツール呼び出しの後に同期します。各同期では、変更されたメモリをストアからディスクに書き込み、エージェントが変更したファイルをアップロードします。
- セッションが終了したとき、またはセッションがワーカーのアイドル制限の間アイドル状態のままだったときに、最終同期を実行します。 最終同期には最大60秒かかる場合があります。それまでにアップロードされなかった変更は失われます。その後、ワーカーは作成したディレクトリを削除します。
アイドル制限はデフォルトで60秒です。制限の対象と変更方法については、ワーカーがセッションの処理を終えるタイミングで説明しています。
エージェントのwriteツールとeditツールはローカルコピーのみを変更し、ワーカーはそれらの変更を次の同期時にアップロードします。/mnt/memory/配下のストアディレクトリ以外のパスは、「scratch space」(一時的な作業領域)ではありません。ワーカーのファイルツールはそれらへの書き込みを拒否し、シェルコマンドがそこに書き込んだものがストアに同期されることはありません。
メモリのバージョン、墨消し、Claude Console でのメモリの表示や編集は、クラウドセッションの場合と同じように機能します。エージェントによるメモリの読み書きは、通常のツールイベントとしてイベントストリームに表示されます。
各ストアディレクトリには、ディレクトリをそのストアに結び付ける.anthropic-memory-storeという名前のマーカーファイルが含まれています。これはそのままにしておいてください。マーカーが欠落しているか改変されており、かつディレクトリにまだファイルが残っている場合、ワーカーはそのディレクトリを同期しません。また、セッションの処理を終えたときにそのディレクトリを削除することもありません。
同期を設定する
2つのEnvironmentWorkerオプションがメモリの動作を制御します。Webhookハンドラー内を含め、ワーカーを構築する場所でこれらを設定してください。ant CLIワーカーは常にデフォルト値を使用します。
同期間隔
memory_sync_intervalは、セッションの実行中に2回の同期の間に置く最短の時間を設定します。
| 設定 | 値 |
|---|---|
| デフォルト | 15秒 |
| 最小値 | 5秒 |
| 例(10秒) | 10 |
| メモリサポートを無効化 | None |
ワーカーはタイマーで同期するわけではありません。bash、read、カスタムツールなど、サンドボックス内で実行されるツールが呼び出されるたびに、その後で間隔を確認します。その呼び出しがメモリに触れる必要はありません。ツール呼び出しがなければ、最終同期まで何も同期されません。あるセッションでの変更は、両方のセッションが同期した後にのみ実行中の別のセッションに反映されるため、待ち時間は一定ではありません。
間隔を短くすると、別のセッションが古いメモリを参照する時間枠が狭まりますが、その代わりにメモリストアへのリクエストが増えます。
メモリサポートを無効にするのは、セッションがメモリストアをアタッチしないワーカーに限ってください。無効化されたワーカーはストアのダウンロードも同期も行わないため、ストアがアタッチされたセッションは、システムプロンプトがそれらを説明しているにもかかわらず、ストアなしで実行されます。
メモリサポートが有効な間、ストアがアタッチされたセッションのワークアイテムがsecretなしで届いた場合、メモリなしで実行されるのではなく失敗します。メモリストアのマウントまたは同期に失敗するを参照してください。
削除
memory_sync_deletionsは、エージェントがローカルで削除したファイルをストアからも削除するかどうかを設定します。アップロードとダウンロードには影響しません。
| 値 | 動作 |
|---|---|
"enabled"(デフォルト) | 後続の同期でファイルが引き続き存在しないことが確認された時点で、ストアからメモリを削除します。 |
"log_only" | 同じチェックを実行しますが、削除したであろう内容をログに記録するだけです。有効モードを信頼する前に、ワーカーが何を削除するかを確認するために使用してください。 |
"disabled" | ストアから削除することはありません。 |
たとえば、最大でも10秒に1回同期し、ワーカーが行ったであろう削除をログに記録するだけにするには、次のサンプルを使用します。このサンプルでは作業ディレクトリとして/workspaceを使用しており、このディレクトリはワーカーの起動前に存在している必要があります。ディレクトリの作成方法とmacOSで使用するものについては、常時稼働ワーカーを実行するを参照してください。
import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker
async def main() -> None:
environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
async with AsyncAnthropic(auth_token=environment_key) as client:
worker = EnvironmentWorker(
client,
environment_id=environment_id,
environment_key=environment_key,
workdir="/workspace",
memory_sync_interval=10, # seconds
memory_sync_deletions="log_only",
)
task = asyncio.create_task(worker.run())
loop = asyncio.get_running_loop()
for signum in (signal.SIGINT, signal.SIGTERM):
loop.add_signal_handler(signum, task.cancel)
with contextlib.suppress(asyncio.CancelledError):
await task
asyncio.run(main())読み取り専用ストアと競合
読み取り専用ストア
access: "read_only"でアタッチされたストアの場合、writeツールとeditツールはそのディレクトリ内のファイルの変更を拒否します。ワーカーはそこから何もアップロードしません。
bash、またはサンドボックスから提供するカスタムツールやMCPサーバーを通じて行われた変更は、ローカルではブロックされません。それらがストアに届くことはありません。変更されたファイルは、次のいずれかが起こるまで変更されたままになります:
- そのメモリにストア内で新しいバージョンが作成される。 ワーカーの次の同期で、そのバージョンによってファイルが上書きされます。
- ワーカーがセッションの処理を終える。 ワーカーはディレクトリを削除します。
ローカルコピーも変更されないようにするには、そのエージェントのbashツールを無効にしてください。また、サンドボックスのファイルシステムに書き込むカスタムツールやMCPサーバーを与えないでください。ストアのパスに読み取り専用ボリュームをマウントしないでください。マウントによってそのパスにディレクトリが作成され、そこにすでに何かが存在するとワーカーはワークアイテムを失敗させます。
競合
競合とは、前回の同期以降にストアとサンドボックスの両方で変更されたメモリのことです。削除も変更として扱われます。access: "read_write"でアタッチされたストアの場合、ワーカーは次の同期時に競合を解決します:
| ストア側 | サンドボックス側 | 結果 |
|---|---|---|
| 変更 | 変更 | ストアのバージョンがファイルを上書きします。 |
| 変更 | 削除 | ワーカーはストアのバージョンをサンドボックスに書き戻します。 |
| 削除 | 変更 | ワーカーはファイルからメモリを再作成します。 |
最初の2行では、ツール呼び出しが成功したにもかかわらず、エージェントによる変更または削除は失われます。エージェントには何も通知されず、失われたことを示す唯一の手がかりはワーカーのログに記録される警告です。最後の行では、ストア内での削除が取り消されます。
トラブルシューティング
ワーカーのログメッセージとその修正方法については、メモリストアのマウントまたは同期に失敗するを参照してください。
利用可能状況
Claude API
- ステータス
- ベータ
- API
- Managed Agents
- ベータヘッダー
- が必要
- モデル
- すべてのモデル
データの取り扱い
データの取り扱いの概要対象エンドポイント
/v1/agents/v1/sessions/v1/environments
セルフホスト型Managed Agentsを除き、ZDRの適格対象ではありません。セッションはステートフルなリソースであり、トランスクリプトは削除するまで保持されます。 詳細はこちら
HIPAAの適格対象ではありません。すべてのManaged Agentsのサブ機能に適用されます。
このページは役に立ちましたか?