梦境

智能体在工作时会写入其 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 令牌费率计费；资源上的 usage 会报告精确的总量。成本大致随输入会话的数量和长度线性增长。请先从一小批会话开始，待您对整理质量满意后再扩大规模。

限制

在此功能处于研究预览阶段期间，梦境创建适用默认速率限制。如果您需要更高的限制，请联系支持团队。