自行託管沙箱中的記憶體儲存區

自行託管環境上的工作階段附加記憶體儲存區的方式，與雲端環境上的工作階段完全相同。在建立工作階段時將它們列在 resources 中，如將記憶體儲存區附加到工作階段所示。一個工作階段最多可接受 8 個記憶體儲存區。

差別在於由誰將儲存區具體化。在自行託管環境上，是由您的 worker（而非 Anthropic 的基礎架構）將每個儲存區下載到沙箱中，並將代理的變更同步回去。

需求

• 可掛載記憶體儲存區的 worker： 使用 ant CLI 1.33.0 或更新版本，或 Python、TypeScript 或 Go SDK 中的 EnvironmentWorker。
• POSIX 檔案系統： 不支援 Windows 主機，因為 worker 在開啟記憶檔案時需要 O_NOFOLLOW。建議使用區分大小寫的檔案系統，以免僅大小寫不同的記憶路徑發生衝突。
• 可寫入的 /mnt/memory 目錄： 請參閱準備主機。
• 工作項目的密鑰： 如果由您自己的程式碼啟動 worker，請轉送工作項目的密鑰給它。

準備主機

在啟動 worker 之前，請建立父目錄，並讓執行 worker 的使用者可以寫入該目錄：

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

請勿自行建立各儲存區的目錄。worker 會在工作階段開始時建立每個儲存區的 mount_path 目錄（例如 /mnt/memory/user-preferences），並在工作階段結束時將其移除。如果該路徑已存在任何內容，worker 會拒絕開始該工作階段的工作。

在每個工作階段一個沙箱的模式中，沙箱映像需要可寫入的 /mnt/memory。您不需要將記憶目錄 bind-mount 到主機，因為 worker 會在沙箱結束前將其內容上傳到儲存區。

隔離共用儲存區的工作階段

兩個工作階段無法同時在同一台主機上掛載同一個儲存區，因為兩者都需要相同的路徑。如果您的工作階段附加了相同的儲存區，請在每個檔案系統上只執行一個工作階段。為每個工作階段提供專屬的沙箱即可滿足此規則。

worker 如何處理記憶

當 worker 認領一個其工作階段附加了記憶體儲存區的工作項目時，它會：

1. 將每個儲存區下載到其 mount_path。 這與雲端工作階段使用的 /mnt/memory/ 下的目錄相同，且工作階段的系統提示會向代理描述該目錄。例如，名為「User Preferences」的儲存區會放在 /mnt/memory/user-preferences/。
2. 向檔案工具開放這些目錄。 代理使用與在工作目錄中相同的檔案工具來處理記憶。
3. 在工具呼叫後協調變更， 每個同步間隔最多一次（預設為 15 秒）。儲存區中已變更的記憶會寫入磁碟，而代理變更的檔案會上傳到儲存區。
4. 在工作階段結束時執行最後一次同步。 它會在最多 30 秒內清空所有仍待處理的上傳，然後移除它所建立的目錄。

Anthropic 端的記憶體儲存區仍是唯一的事實來源。記憶版本、遮蔽，以及在 Console 中檢視或編輯記憶，運作方式都與雲端工作階段相同。代理的記憶讀取與寫入會以一般工具事件的形式出現在事件串流中。

由於每個 worker 都是依間隔進行同步，在一個工作階段中寫入的變更，只有在兩者都完成同步後，才會對另一個執行中的工作階段可見。在預設間隔下，這通常遠少於一分鐘。雲端沙箱上的工作階段幾乎可以立即看到彼此的變更。

每個儲存區目錄都包含一個名為 .anthropic-memory-store 的標記檔案，用來將該目錄與其儲存區綁定。請保留此檔案：worker 不會同步標記遺失或遭修改的目錄。

設定同步

有兩個 EnvironmentWorker 選項控制記憶行為。請在您建構 worker 的任何地方設定它們，包括在 webhook 處理常式中。ant CLI worker 一律使用預設值。

同步間隔

memory_sync_interval 設定工作階段執行期間，已附加的儲存區與伺服器協調的頻率。

較短的間隔可縮小其他工作階段看到過時記憶的時間範圍，代價是更多的記憶體儲存區請求。

僅在其工作階段未附加任何記憶體儲存區的 worker 上停用記憶支援。已停用的 worker 既不會下載也不會同步儲存區，因此附加了儲存區的工作階段會在沒有這些儲存區的情況下執行，即使其系統提示仍會描述它們。

啟用記憶支援時，若附加了儲存區的工作階段的工作項目在抵達時沒有 secret，該工作項目會失敗，而不是在沒有記憶的情況下執行。請參閱記憶體儲存區無法掛載。

刪除

memory_sync_deletions 設定代理在本機刪除的檔案是否也會從儲存區中刪除。上傳與下載不受影響。

例如，若要每 10 秒同步一次，且只記錄 worker 原本會執行的刪除：

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 工具會拒絕變更其目錄內的檔案。worker 永遠不會從中上傳任何內容。

透過 bash，或透過您從沙箱提供的自訂工具或 MCP 伺服器所做的變更，不會在本機被阻擋。這些變更永遠不會同步到儲存區，且該記憶的下一次遠端變更會覆寫它們。如果本機副本本身在工作階段期間必須保持不變：

• 為該代理停用 bash 工具，且不要提供任何會寫入沙箱檔案系統的自訂工具。
• 不要以唯讀方式掛載儲存區路徑。worker 本身必須建立該目錄，並將下載的記憶寫入其中。

衝突會以儲存區為準來解決。假設代理變更了一個記憶檔案，而該檔案自工作階段上次同步以來在儲存區中也已變更。在下一次同步時，worker 會保留儲存區的版本，用它覆寫本機檔案，並記錄一則警告。write 和 edit 工具本身會成功，且不會有錯誤傳達給代理。如果代理的變更仍然適用，它可以在同步後重新讀取該檔案並再次進行變更。

疑難排解

請參閱記憶體儲存區無法掛載，以了解 worker 的記錄訊息及其修正方式。