夢境（Dreams）

代理在工作時會寫入其 memory stores（記憶儲存庫），但這些寫入是局部且漸進的：經過許多工作階段後，記憶儲存庫會累積重複、矛盾與過時的條目。

Dreams（夢境）讓 Claude 清理這些內容。一次夢境會讀取現有的記憶儲存庫以及過去的工作階段逐字稿，然後產生一個全新、重新組織過的記憶儲存庫：重複項目被合併、過時或相互矛盾的條目被替換為最新的值，並發掘出新的洞見。

輸入儲存庫永遠不會被修改，因此您可以檢視輸出結果，若不滿意即可將其捨棄。

運作方式

一個 dream（夢境）是一項非同步作業，其輸入包含：

• 一個既有的 memory store（記憶儲存庫）： Claude 會驗證、去除重複並重新組織的儲存庫，以及
• 1 到 100 個 sessions（工作階段）： Claude 從中挖掘模式與洞見、並將其整合進輸出的過去逐字稿。

夢境會產生另一個 output memory store（輸出記憶儲存庫），與輸入分開。在夢境開始 running 後不久、工作流程複製完輸入儲存庫之後，輸出儲存庫 ID 便會出現在夢境的 outputs[] 中；處於 running 狀態的夢境可能會短暫回報空的 outputs[]。

建立夢境

dream = client.beta.dreams.create(
    inputs=[
        {"type": "memory_store", "memory_store_id": store_id},
        {"type": "sessions", "session_ids": [session_a, session_b]},
    ],
    model="claude-opus-4-8",
    instructions="Focus on coding-style preferences; ignore one-off debugging notes.",
)
print(dream.id)  # drm_01...

夢境的輸入包含既有的記憶儲存庫與一個工作階段陣列。所選的模型會執行夢境管線。在研究預覽期間，支援 claude-opus-5、claude-fable-5、claude-opus-4-8、claude-opus-4-7、claude-sonnet-5 與 claude-sonnet-4-6。您可以選擇性地傳入 instructions 來引導夢境過程。請參閱使用指示進行引導。

回應為完整的 dream 資源，且 status: "pending"：

{
  "type": "dream",
  "id": "drm_01AbCDefGhIjKlMnOpQrStUv",
  "status": "pending",
  "inputs": [
    { "type": "memory_store", "memory_store_id": "memstore_01Hx..." },
    { "type": "sessions", "session_ids": ["sesn_01...", "sesn_02..."] }
  ],
  "outputs": [],
  "model": { "id": "claude-opus-4-8" },
  "instructions": "Focus on coding-style preferences; ignore one-off debugging notes.",
  "session_id": null,
  "created_at": "2026-04-29T17:04:10Z",
  "ended_at": null,
  "archived_at": null,
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  },
  "error": null
}

使用指示進行引導

選用的 instructions 欄位可引導夢境管線所綜合的內容。它會套用於整個管線：要仔細閱讀什麼、要合併或捨棄什麼，以及如何組織輸出儲存庫的結構。

請將 instructions 用於高層次的綜合指引，例如關注領域（「專注於程式碼風格偏好」）、要原封不動保留的內容，或您希望套用於整個儲存庫的輸出慣例。此管線是對輸入進行的一次綜合處理，而非套用於儲存庫文字的編輯器，因此針對特定行的命令式指令（「將句子 X 改為 Y」、「修正 Z 章節中的計數」）通常不會產生任何變更。若要對個別記憶進行針對性的編輯，請直接對輸出儲存庫使用 Memory Stores API。

追蹤進度

夢境以非同步方式執行，通常需要數分鐘到數小時，取決於輸入逐字稿的數量。透過 ID 輪詢夢境以檢查狀態：

while dream.status in ("pending", "running"):
    time.sleep(10)
    dream = client.beta.dreams.retrieve(dream.id)
    print(f"status={dream.status} input_tokens={dream.usage.input_tokens}")

生命週期

觀察管線執行

一旦夢境處於 running 狀態，其 session_id 欄位會指向執行該管線的底層 session（工作階段）。您可以串流該工作階段的 events（事件），即時觀察夢境正在讀取與寫入的內容。當夢境到達終止狀態時，該工作階段會被封存（而非刪除），因此逐字稿之後仍可取得。

使用輸出

當 status 到達 completed 時，outputs[] 中的 memory_store 條目會參照一個已完整填入內容的儲存庫。它是您工作區中的一個普通記憶儲存庫。請使用 Memory Stores API 或在 Console 中檢視它，然後選擇：

• 加以運用： 將其作為 memory_store 資源附加到未來的工作階段，以取代（或搭配）輸入記憶儲存庫，或
• 將其捨棄： 刪除該記憶儲存庫或封存該記憶儲存庫。

# 夢境結束後，輸出會保存重建的記憶儲存區
output_store_id = next(
    output.memory_store_id for output in dream.outputs if output.type == "memory_store"
)

session = client.beta.sessions.create(
    agent=agent_id,
    environment_id=environment_id,
    resources=[
        {"type": "memory_store", "memory_store_id": output_store_id},
    ],
)

夢境本身永遠不會刪除或修改其輸入。在 failed 或 canceled 時，輸出儲存庫會保留部分內容，讓您可以檢查停止前所產生的內容；若您不需要，請透過 Memory Stores API 將其清理。

取消夢境

取消會立即將 pending 或 running 的夢境移至 canceled。取消一個已經是 canceled 的夢境是冪等的無操作；取消 completed 或 failed 的夢境會回傳 400。

client.beta.dreams.cancel(dream.id)

封存夢境

封存會在已到達終止狀態（completed、failed 或 canceled）的夢境上設定 archived_at；status 保持不變。已封存的夢境會從預設的列表回應中排除，但仍可透過 ID 讀取。封存一個已封存的夢境是冪等的無操作。封存 pending 或 running 的夢境會回傳 400；請先將其取消。沒有取消封存的功能。

client.beta.dreams.archive(dream.id)

封存夢境不會影響其輸出記憶儲存庫；請透過 Memory Stores API 另行管理。

列出夢境

回傳工作區中所有未封存的夢境，最新的排在最前。使用 limit（預設 20，最大 100）與 page 游標進行分頁。傳入 include_archived=true 以包含已封存的夢境。

for listed_dream in client.beta.dreams.list(limit=20):
    print(listed_dream.id, listed_dream.status)

錯誤

以下為可能的夢境錯誤之非完整列表。

計費

夢境依您所選模型的標準 API token 費率計費；資源上的 usage 會回報確切的總量。成本大致隨輸入工作階段的數量與長度線性增長。請先從一小批工作階段開始，待您對整理品質感到滿意後再擴大規模。

限制

在此功能處於研究預覽期間，夢境建立適用預設的速率限制。如果您需要更高的限制，請聯絡支援團隊。