自行託管沙箱中的記憶體儲存區
將記憶體儲存區附加到在自行託管沙箱中執行的 Claude Managed Agents 工作階段:準備主機、設定同步,以及處理唯讀儲存區與衝突。
在自行託管環境上的工作階段附加記憶體儲存區的方式,與雲端環境上的工作階段完全相同。建立工作階段時,請將它們列在 resources 中,如將記憶體儲存區附加到工作階段所示。一個工作階段最多可接受 8 個記憶體儲存區。
差別在於由誰將儲存區具體化。在自行託管環境上,是由您的 worker(而非 Anthropic 的基礎架構)將每個儲存區下載到沙箱中,並將代理的變更同步回去。
需求
- 可掛載記憶體儲存區的 worker: 使用
antCLI 1.33.0 或更新版本,或 Python、TypeScript 或 Go SDK 中的EnvironmentWorker。 - POSIX 檔案系統: 不支援 Windows 主機,因為 worker 在開啟記憶體檔案時需要
O_NOFOLLOW。Anthropic 建議使用區分大小寫的檔案系統,以免僅大小寫不同的記憶體路徑發生衝突。macOS 磁碟區預設不區分大小寫,因此這類路徑在該系統上會發生衝突。 - 可寫入的
/mnt/memory目錄: 請參閱準備主機。若使用 macOS,請參閱準備 macOS 主機。 - 工作項目的密鑰: 如果由您自己的程式碼啟動 worker,請轉送工作項目的密鑰給它。
準備主機
若使用 macOS,請跳過下一個命令,改為依照準備 macOS 主機操作。
在啟動 worker 之前,請建立父目錄,並讓執行 worker 的使用者可以寫入該目錄:
sudo mkdir -p /mnt/memory && sudo chown "$USER" /mnt/memory請勿自行建立任何儲存區的目錄。worker 會在認領工作階段時建立每個儲存區的 mount_path 目錄(例如 /mnt/memory/user-preferences),並在處理完該工作階段時將其移除。如果該路徑已存在任何內容,即使只是空目錄,worker 也會使工作項目失敗。
在每個工作階段一個沙箱的模式中,沙箱映像需要可寫入的 /mnt/memory。您不需要將記憶目錄 bind-mount 到主機,因為儲存區保有每個記憶的持久副本。
準備 macOS 主機
在 macOS 上,根磁碟區為唯讀,因此 mkdir 無法建立 /mnt。請改為在可寫入的資料磁碟區上建立 /System/Volumes/Data/mnt/memory。接著在 /etc/synthetic.conf 中新增一行,讓 macOS 將 /mnt 建立為指向 /System/Volumes/Data/mnt 的「symbolic link」(符號連結)。這些步驟需要管理員權限。
若未完成此設定,worker 將無法建立儲存區的目錄,因此會使工作項目失敗。工作階段接著會保持閒置,且不會產生任何錯誤事件。請參閱記憶體儲存區無法掛載或同步。
在資料磁碟區上建立目錄
建立
memory目錄,並將 worker 的使用者設為其擁有者。$USER是您自己的使用者名稱。如果 worker 以其他使用者身分執行,請將"$USER"替換為該使用者的名稱。sudo mkdir -p /System/Volumes/Data/mnt/memory && sudo chown "$USER" /System/Volumes/Data/mnt/memory此位置只是其中一個選項。如果您使用其他位置,請變更
synthetic.conf該行中的路徑以配合。Anthropic 僅測試過/System/Volumes/Data/mnt。在 synthetic.conf 中新增一行
執行
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,請新增該行。若檔案不存在,下列命令會建立該檔案。 - 否則,請新增該行。
若要新增該行,請執行此命令。此命令只需執行一次,因為每次執行都會再附加一行。
printf 'mnt\tSystem/Volumes/Data/mnt\n' | sudo tee -a /etc/synthetic.conf此命令會輸出它新增的行。該行將名稱
mnt對應到包含memory的目錄。檔案中兩個欄位之間需要一個定位字元,由\t寫入。- 如果有一行為
建立連結
使用
-t選項執行apfs.util。它會根據您新增的行建立連結,無需重新啟動。sudo /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -t檢查結果
列出
/mnt與/mnt/memory。ls -ld /mnt /mnt/memory第一行以
/mnt -> System/Volumes/Data/mnt結尾。第二行顯示 worker 的使用者為/mnt/memory的擁有者。您現在可以啟動 worker。
Anthropic 已在 macOS 26.7.1 上使用 ant CLI worker 測試過此設定。
隔離共用儲存區的工作階段
兩個工作階段無法在同一個檔案系統上同時掛載同一個儲存區,因為兩者都需要相同的路徑。若要並行執行共用同一儲存區的工作階段,請為每個工作階段提供各自的檔案系統。如果您為每個工作階段使用一個沙箱,每個工作階段就會自動擁有各自的檔案系統。請參閱每個工作階段執行一個沙箱。一台主機可以執行許多這類沙箱。
worker 如何處理記憶
當 worker 認領一個其工作階段附加了記憶體儲存區的工作項目時,它會:
- 將每個儲存區下載到其
mount_path。 這與雲端工作階段使用的/mnt/memory/下的目錄相同,且工作階段的系統提示會向代理描述該目錄。例如,名為「User Preferences」的儲存區會放在/mnt/memory/user-preferences/。 - 向檔案工具開放這些目錄。 代理使用與在工作目錄中相同的檔案工具來處理記憶。
- 在工具呼叫後進行同步。 如果自上次同步以來已經過同步間隔(預設為 15 秒),worker 會在工具呼叫後進行同步。每次同步都會將儲存區中已變更的記憶寫入磁碟,並上傳代理變更的檔案。
- 在工作階段結束或閒置達到 worker 的「idle limit」(閒置限制)時執行最後一次同步。 最後一次同步最多可能需要 60 秒。屆時仍未上傳的變更會遺失。接著 worker 會移除它所建立的目錄。
閒置限制預設為 60 秒。worker 何時處理完工作階段說明了此限制涵蓋的範圍以及如何變更。
代理的 write 和 edit 工具只會變更本機副本,而 worker 會在下一次同步時上傳這些變更。/mnt/memory/ 下、儲存區目錄之外的路徑並非「scratch space」(暫存空間)。worker 的檔案工具會拒絕寫入這些路徑,而 shell 命令寫入該處的任何內容永遠不會同步到儲存區。
記憶體版本、遮蔽處理,以及在 Claude Console 中檢視或編輯記憶體,其運作方式都與雲端工作階段相同。代理對記憶體的讀取與寫入會以一般工具事件的形式出現在事件串流中。
每個儲存區目錄都包含一個名為 .anthropic-memory-store 的標記檔案,用來將該目錄與其儲存區綁定。請保留此檔案。如果標記遺失或遭修改,且該目錄中仍有檔案,worker 不會同步該目錄。在處理完工作階段時,它也不會移除該目錄。
設定同步
有兩個 EnvironmentWorker 選項控制記憶行為。請在您建構 worker 的任何地方設定它們,包括在 webhook 處理常式中。ant CLI worker 一律使用預設值。
同步間隔
memory_sync_interval 設定工作階段執行期間,兩次同步之間的最短時間。
| 設定 | 值 |
|---|---|
| 預設 | 15 秒 |
| 最小值 | 5 秒 |
| 範例(10 秒) | 10 |
| 停用記憶支援 | None |
worker 不會依計時器進行同步。它會在每次呼叫在您沙箱中執行的工具(例如 bash、read 或自訂工具)之後檢查間隔。該呼叫不必涉及記憶。若沒有工具呼叫,在最後一次同步之前都不會進行任何同步。一個工作階段中的變更,只有在兩者都完成同步後才會傳達到另一個執行中的工作階段,因此等待時間沒有固定長度。
較短的間隔可縮小其他工作階段看到過時記憶的時間範圍,代價是更多的記憶體儲存區請求。
僅在其工作階段未附加任何記憶體儲存區的 worker 上停用記憶支援。已停用的 worker 既不會下載也不會同步儲存區,因此附加了儲存區的工作階段會在沒有這些儲存區的情況下執行,即使其系統提示仍會描述它們。
在啟用記憶支援時,若某個附加了儲存區的工作階段的工作項目送達時沒有 secret,該工作項目會失敗,而不會在沒有記憶的情況下執行。請參閱記憶體儲存區無法掛載或同步。
刪除
memory_sync_deletions 設定代理在本機刪除的檔案是否也會從儲存區中刪除。上傳與下載不受影響。
| 值 | 行為 |
|---|---|
"enabled"(預設) | 在後續同步確認檔案仍不存在後,從儲存區中刪除該記憶。 |
"log_only" | 執行相同的檢查,但只記錄原本會刪除的內容。在您信任啟用模式之前,可用它來觀察您的 worker 會刪除哪些內容。 |
"disabled" | 永不從儲存區中刪除。 |
例如,若要最多每 10 秒同步一次,且只記錄 worker 原本會執行的刪除,請使用下列範例。此範例使用 /workspace 作為工作目錄,該目錄必須在 worker 啟動前存在。執行常駐 worker 說明如何建立該目錄,以及在 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 工具會拒絕變更其目錄內的檔案。worker 永遠不會從中上傳任何內容。
透過 bash,或透過您從沙箱提供的自訂工具或 MCP 伺服器所做的變更,不會在本機被阻擋。這些變更永遠不會到達儲存區。已變更的檔案會維持變更後的狀態,直到發生下列其中一種情況:
- 該記憶在儲存區中有了新版本。 worker 的下一次同步會以該版本覆寫檔案。
- worker 處理完工作階段。 它會移除該目錄。
若也要讓本機副本保持不變,請為該代理停用 bash 工具。此外,不要提供任何會寫入沙箱檔案系統的自訂工具或 MCP 伺服器。不要在儲存區的路徑掛載唯讀磁碟區。掛載會在該路徑放置一個目錄,而如果該處已存在任何內容,worker 會使工作項目失敗。
衝突
「conflict」(衝突)是指自上一次同步以來,在儲存區與沙箱中都已變更的記憶。刪除也算是一種變更。對於以 access: "read_write" 附加的儲存區,worker 會在下一次同步時解決衝突:
| 在儲存區中 | 在沙箱中 | 結果 |
|---|---|---|
| 已變更 | 已變更 | 儲存區的版本會覆寫該檔案。 |
| 已變更 | 已刪除 | worker 會將儲存區的版本寫回沙箱。 |
| 已刪除 | 已變更 | worker 會根據該檔案重新建立記憶。 |
在前兩列中,代理的變更或刪除會遺失,即使工具呼叫已成功。不會有任何訊息告知代理,而遺失的唯一跡象是 worker 日誌中的一則警告。在最後一列中,儲存區中的刪除會被復原。
疑難排解
請參閱記憶體儲存區無法掛載或同步,以了解 worker 日誌訊息及其修正方式。
這個頁面有幫助嗎?