Dreams

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

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

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



運作方式

一個 dream 是一個非同步作業，它接受：

• 一個預先存在的記憶儲存庫： Claude 驗證、去除重複並重新組織的儲存庫，以及
• 1 到 100 個工作階段： Claude 從中挖掘模式和洞察並融入輸出的過去記錄。

Dream 會產生另一個輸出記憶儲存庫，與輸入分開。輸出儲存庫 ID 會在 dream 開始 running 後不久出現在 dream 的 outputs[] 中，也就是工作流程複製輸入儲存庫之後；處於 running 狀態的 dream 可能會短暫地回報空的 outputs[]。



建立 dream

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...

Dreaming 的輸入包括預先存在的記憶儲存庫和一個工作階段陣列。所選的模型會執行 dreaming 管線；在研究預覽期間支援 claude-fable-5、claude-opus-4-8、claude-opus-4-7、claude-sonnet-5 和 claude-sonnet-4-6。您可以選擇性地傳入 instructions 來引導 dreaming 過程；請參閱使用 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 欄位可引導 dreaming 管線的合成內容。它會套用於整個管線：要仔細閱讀什麼、要合併或捨棄什麼，以及如何組織輸出儲存庫的結構。

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



追蹤進度

Dreams 以非同步方式執行，通常需要幾分鐘到幾小時，取決於輸入記錄的數量。透過 ID 輪詢 dream 以檢查狀態：

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}")



生命週期



觀察管線執行

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



使用輸出

當 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},
    ],
)

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



取消 dream

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

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



封存 dream

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

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

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



列出 dreams

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

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



錯誤

以下是可能的 dreaming 錯誤的非詳盡列表。



計費

Dreams 按照您所選模型的標準 API token 費率計費；資源上的 usage 會回報確切的總計。成本大致與輸入工作階段的數量和長度呈線性關係。建議先從少量工作階段開始，在您對整理品質滿意後再擴大規模。



限制

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