Dreams

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

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

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

運作方式

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

• 一個既有的記憶儲存區：Claude 會驗證、去除重複並重新組織的儲存區，以及
• 1 到 100 個工作階段：Claude 會從這些過去的記錄中挖掘模式和洞察，並整合到輸出中。

Dream 會產生另一個輸出記憶儲存區，與輸入分開。一旦 dream 開始 running，輸出儲存區的 ID 就會出現在 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-opus-4-8、claude-opus-4-7 和 claude-sonnet-4-6。您可以選擇性地傳入 instructions 來引導 dreaming 流程；請參閱使用指令引導。

回應是完整的 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_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  },
  "error": null
}

使用指令引導

選用的 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 資源附加到未來的工作階段，以取代（或搭配）輸入的記憶儲存區，或
• 捨棄它：刪除或封存它。

# After the dream ends, the output holds the rebuilt 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 會回報確切的總計。成本大致與輸入工作階段的數量和長度呈線性關係。請先從少量工作階段開始，待您對整理品質滿意後再擴大規模。

限制

此功能處於 beta 階段時，dream 建立適用預設速率限制。如果您需要更高的限制，請聯絡支援團隊。