使用代理記憶
使用記憶儲存庫為您的代理提供可跨工作階段持續存在的持久記憶。
每個 Managed Agents 工作階段預設都以全新的上下文開始。當工作階段結束時,代理所建立的任何狀態都會消失。「Memory store」(記憶儲存庫)讓代理能夠跨工作階段攜帶資訊:使用者偏好、專案慣例、先前的錯誤以及領域上下文。
概覽
記憶儲存庫(memory store)是一個以工作區為範圍、針對 Claude 最佳化的文字文件集合。當您將儲存庫附加到工作階段時,它會以目錄的形式掛載在工作階段的沙箱中。代理使用與檔案系統其他部分相同的檔案工具來讀取和寫入它,並且描述每個掛載點的說明會自動新增到系統提示中,告訴代理該去哪裡查找。這些互動需要使用代理工具集;請務必在建立代理時啟用它。在自行託管的沙箱上,該目錄並非即時掛載。取而代之的是,您的環境 worker 會在代理的工具執行之前,將每個附加的儲存庫下載到您的沙箱中,並讓該副本與儲存庫保持同步。
儲存庫中的每個記憶都以路徑定址,並可透過 API 或 Claude Console 直接讀取和編輯,以便進行調整、匯入和匯出。
對記憶的每次變更都會建立一個不可變的記憶版本,為代理寫入的所有內容提供稽核軌跡和時間點復原。
建立記憶儲存庫
為儲存庫提供 name 和 description。描述會傳遞給代理,告訴它儲存庫包含哪些內容。
ant apply memory_store.yaml# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/memory_store.json
name: User Preferences
description: Per-user preferences and project context.記憶儲存庫的 id(memstore_...)就是您將儲存庫附加到工作階段時所傳遞的值。
預先填入內容(選用)
在任何代理執行之前,預先將參考資料載入儲存庫:
client.beta.memory_stores.memories.create(
store.id,
path="/formatting_standards.md",
content="All reports use GAAP formatting. Dates are ISO-8601...",
)將記憶儲存庫附加到工作階段
記憶儲存庫是在建立工作階段時,附加在工作階段的 resources 陣列中。與檔案資源不同,記憶儲存庫只能在建立工作階段時附加;不支援在執行中的工作階段新增或移除記憶儲存庫。無論是雲端環境還是自行託管環境上的工作階段,附加記憶儲存庫的方式都相同;自行託管環境僅接受 memory_store 資源。
您可以選擇性地加入 instructions,為代理應如何使用此儲存庫提供特定於工作階段的指引。它會與儲存庫的 name 和 description 一起顯示給代理,上限為 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",
"instructions": "User preferences and project context. Check before starting any task.",
}
],
)每個工作階段最多支援 8 個記憶儲存區。當記憶的不同部分有不同的擁有者或存取規則時,請附加多個儲存區。常見的原因包括:
- 共用參考資料:將一個唯讀儲存區附加到多個工作階段(標準、慣例、領域知識),並與每個工作階段自己的讀寫儲存區分開
- 對應您產品的結構:為每個終端使用者、團隊或專案各建立一個儲存區,同時共用單一代理設定
- 不同的生命週期:一個比任何單一工作階段存續更久的儲存區,或是您想依照其自身排程封存的儲存區
代理如何存取記憶
每個附加的儲存區都會以目錄的形式掛載在工作階段沙箱中的 /mnt/memory/ 之下。目錄名稱是將儲存區的顯示名稱轉換為檔案系統安全的 slug(轉為小寫,並將每一段連續的非英數字元替換為單一連字號),因此名為「Demo Memory」的儲存區會掛載在 /mnt/memory/demo-memory/。確切路徑會在工作階段記憶儲存區資源的 mount_path 欄位中傳回;請從該處讀取,而不要自行建構。代理會使用標準的代理工具集讀取和寫入儲存區。在掛載路徑下的寫入會持久化回儲存區,並在共用該儲存區的工作階段之間保持同步;寫入 /mnt/memory/ 下任何其他路徑則會失敗,因為沙箱以唯讀方式掛載該父目錄。每個掛載的簡短描述(顯示名稱、掛載路徑、存取模式、儲存區的 description,以及任何 instructions)會自動加入系統提示中。
access 在檔案系統層級強制執行:read_only 掛載會拒絕寫入,而對 read_write 掛載的寫入則會產生歸屬於該工作階段的記憶版本。
代理的讀取和寫入會以一般的 agent.tool_use 和 agent.tool_result 事件出現在事件串流中,對應於觸及該掛載的任何工具。
檢視和編輯記憶
記憶儲存庫可直接透過 API 管理。可用於建立審查工作流程、修正錯誤的記憶,或在任何工作階段執行之前預先填入儲存庫。
列出記憶
列出儲存庫中的記憶。結果以穩定的、由伺服器定義的順序回傳。
path_prefix將清單範圍限定於一個目錄。它必須以/結尾,並比對完整的路徑區段,因此path_prefix=/notes/會回傳/notes/todo.md,但不會回傳/notes-archive/todo.md。depth控制列表在path_prefix之下深入的程度:省略它(或傳入0)以列出整個子樹,或傳入1以僅列出直接子項目。其他值會傳回400錯誤。
page = client.beta.memory_stores.memories.list(
store.id,
path_prefix="/",
)
for item in page.data:
print(item.type, item.path)如需完整的參數和回應結構描述,請參閱列出記憶可檢視預覽,內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片,按 Escape 鍵返回。參考文件。
讀取記憶
擷取個別記憶會回傳完整內容。
retrieved = client.beta.memory_stores.memories.retrieve(
mem.id,
memory_store_id=store.id,
)
print(retrieved.content)如需完整的參數和回應結構描述,請參閱擷取記憶可檢視預覽,內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片,按 Escape 鍵返回。參考文件。
建立記憶
client.beta.memory_stores.memories.create() 會在指定的 path 建立記憶。建立操作不會覆寫;若要更新現有記憶,請使用 client.beta.memory_stores.memories.update()。
mem = client.beta.memory_stores.memories.create(
store.id,
path="/preferences/formatting.md",
content="Always use tabs, not spaces.",
)如需完整的參數和回應結構描述,請參閱建立記憶可檢視預覽,內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片,按 Escape 鍵返回。參考文件。
更新記憶
client.beta.memory_stores.memories.update() 會依 ID 修改現有記憶。您可以變更 content、path(重新命名),或兩者皆變更。以下範例將記憶重新命名為封存路徑:
client.beta.memory_stores.memories.update(
mem.id,
memory_store_id=store.id,
path="/archive/2026_q1_formatting.md",
)如需完整的參數和回應結構描述,請參閱更新記憶可檢視預覽,內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片,按 Escape 鍵返回。參考文件。
安全的內容編輯(樂觀並行控制)
為避免覆寫同時進行的寫入,請傳入 content_sha256 前置條件。只有在儲存內容的雜湊值仍與您讀取時的雜湊值相符時,更新才會套用;若不相符,請重新讀取記憶,並根據最新狀態重試。
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,
)如需完整的參數和回應結構描述,請參閱刪除記憶可檢視預覽,內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片,按 Escape 鍵返回。參考文件。
稽核記憶變更
對記憶的每次變動都會建立一個不可變的記憶版本(memver_...)。使用版本端點來稽核誰在何時變更了什麼、檢查或還原先前的快照,以及透過遮蔽(redact)將敏感內容從歷史記錄中清除。
版本隸屬於儲存區(而非個別記憶),且不會在記憶本身被刪除時一併刪除,因此稽核軌跡也涵蓋已刪除的記憶,但須遵守稍後描述的保留期限。版本在寫入後會保留 30 天;不過,現存記憶的近期版本無論存在多久都一律保留,因此不常變更的記憶可能會保留超過 30 天的歷史記錄。現存記憶的 client.beta.memory_stores.memories.retrieve() 呼叫一律傳回最新版本;版本端點則提供已保留的歷史記錄。
沒有專用的還原端點;若要回復,請擷取您想要的版本,並使用 client.beta.memory_stores.memories.update() 將其 content 寫回(如果父記憶已被刪除,則使用 client.beta.memory_stores.memories.create(),前提是您想要的版本仍被保留)。
過去的記憶版本可能會在 30 天後被刪除。若要將記憶歷史記錄保留更久,請透過 API 匯出版本。
列出版本
列出儲存庫的版本歷史記錄,最新的在前。此範例篩選為單一記憶的歷史記錄:
versions = client.beta.memory_stores.memory_versions.list(
store.id,
memory_id=mem.id,
)
for version in versions:
print(f"{version.id}: {version.operation}")
version_id = versions.data[1].id如需完整的參數和回應結構描述,請參閱列出記憶版本可檢視預覽,內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片,按 Escape 鍵返回。參考文件。
擷取版本
擷取個別版本會回傳與清單回應相同的欄位,外加完整的 content 內文。
version = client.beta.memory_stores.memory_versions.retrieve(
version_id,
memory_store_id=store.id,
)
print(version.content)如需完整的參數和回應結構描述,請參閱擷取記憶版本可檢視預覽,內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片,按 Escape 鍵返回。參考文件。
遮蔽版本
遮蔽(redact)會從歷史版本中清除內容,同時保留稽核軌跡(誰在何時做了什麼)。可將其用於合規工作流程,例如移除外洩的機密或「personally identifiable information」(個人識別資訊),即 PII,或履行使用者的刪除請求。
作為現存記憶目前最新版本(head)的版本無法被遮蔽。請先寫入新版本(或刪除該記憶),然後再遮蔽舊版本。
client.beta.memory_stores.memory_versions.redact(
version_id,
memory_store_id=store.id,
)如需完整的參數和回應結構描述,請參閱編修記憶版本可檢視預覽,內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片,按 Escape 鍵返回。參考文件。
管理記憶儲存庫
除了 create可檢視預覽,內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片,按 Escape 鍵返回。 之外,記憶儲存庫還支援 retrieve可檢視預覽,內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片,按 Escape 鍵返回。、update可檢視預覽,內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片,按 Escape 鍵返回。、list可檢視預覽,內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片,按 Escape 鍵返回。、archive可檢視預覽,內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片,按 Escape 鍵返回。 和 delete可檢視預覽,內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片,按 Escape 鍵返回。。
列出儲存庫
列出工作區中的儲存庫。預設會排除已封存的儲存庫;將 include_archived 設為 true 即可將其包含在內。
for memory_store in client.beta.memory_stores.list(include_archived=True):
print(memory_store.id, memory_store.name, memory_store.archived_at)如需完整的參數和回應結構描述,請參閱列出記憶儲存區可檢視預覽,內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片,按 Escape 鍵返回。參考文件。
封存儲存庫
封存會使儲存庫變為唯讀,並防止其被附加到新的工作階段。封存是單向的;沒有取消封存的功能。
client.beta.memory_stores.archive(store.id)如需完整的參數和回應結構描述,請參閱封存記憶儲存區可檢視預覽,內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片,按 Escape 鍵返回。參考文件。
若要永久刪除儲存區可檢視預覽,內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片,按 Escape 鍵返回。及其所有記憶和版本,請呼叫 client.beta.memory_stores.delete()。
記憶管理的最佳實務
當儲存庫達到 10,000 個記憶的上限時,寫入新記憶的操作會失敗:包括直接的 client.beta.memory_stores.memories.create() 呼叫,以及代理對未對應路徑的檔案寫入。現有記憶仍可讀取和編輯。以下實務可協助您保持遠低於上限,並在達到上限時順利復原。
-
使用專注的儲存區。與其使用一個大型的通用儲存區,不如使用較小的專用儲存區:每個使用者一個、共用領域知識一個,以及專案特定上下文一個。每個儲存區都有各自 10,000 個記憶的上限,因此限定儲存區的範圍可降低任何單一儲存區填滿的機會。
-
在儲存庫填滿之前進行精簡或修剪。使用
client.beta.memory_stores.memories.delete()刪除過時或重複的記憶。您也可以執行夢境工作階段,它會將零散的內容整合到另一個新的輸出儲存庫,而不是修改原始儲存庫。將您的工作階段切換到該輸出儲存庫,然後封存或刪除原始儲存庫。 -
在適當時機附加新的儲存庫。如果儲存庫已成長超出其有用範圍,請為新內容附加一個全新的儲存庫,並以
read_only存取權限附加原始儲存庫。代理可以從兩者讀取,同時只寫入新的儲存庫。 -
在適當情況下限制寫入權限。僅讀取共用參考資料的工作階段不需要
read_write。將寫入權限限定於實際新增記憶的工作階段,可更容易追蹤成長的來源。
可用性
Claude API
- 狀態
- Beta
- API
- Managed Agents
- Beta 標頭
- 需要
- 模型
- 所有模型
- 注意
在記憶儲存區呼叫中同時傳送
managed-agents-2026-04-01與agent-memory-2026-07-22會傳回 400 錯誤。
Claude Platform on AWS
- 狀態
- Beta
- API
- Managed Agents
- Beta 標頭
- 需要
- 模型
- 所有模型
- 注意
在 Claude Platform on AWS 上,自行託管環境中的工作階段無法附加記憶儲存區。在記憶儲存區呼叫中同時傳送
managed-agents-2026-04-01與agent-memory-2026-07-22會傳回 400 錯誤。
Claude Models on Google Cloud (Anthropic managed)
- 狀態
- Beta
- API
- Managed Agents
- Beta 標頭
- 需要
- 模型
- 所有模型
- 注意
在 Claude Models on Google Cloud (Anthropic managed) 上,自行託管環境中的工作階段不支援記憶儲存區。在記憶儲存區呼叫中同時傳送
managed-agents-2026-04-01與agent-memory-2026-07-22會傳回 400 錯誤。
資料處理
資料處理概覽適用端點
/v1/agents/v1/sessions/v1/environments
不具 ZDR 適用資格,自行託管的 Managed Agents 除外。工作階段是具狀態的資源;對話記錄會保留至您將其刪除為止。 深入了解
不具 HIPAA 適用資格。適用於所有 Managed Agents 子功能。
這個頁面有幫助嗎?