Dreams

Agents write to their memory stores as they work, but these writes are local and incremental: over many sessions a memory store accumulates duplicates, contradictions, and stale entries.

Dreams let Claude clean that up. A dream reads an existing memory store alongside past session transcripts, then produces a new, reorganized memory store: duplicates merged, stale or contradicted entries replaced with the latest value, and new insights surfaced.

The input store is never modified, so you can review the output and discard it if you don't like the result.

How it works

A dream is an asynchronous job that takes:

• a pre-existing memory store: the store Claude verifies, deduplicates, and reorganizes, and
• optionally, up to 100 sessions: past transcripts Claude mines for patterns and insights to fold into the output.

The dream produces another output memory store, separate from the input. The output store ID appears in the dream's outputs[] once it starts running.

Create a 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-7",
    instructions="Write me a children's book abouta flying giraffe in space.",
)
print(dream.id)  # drm_01...

Dreaming inputs include the pre-existing memory store and an optional array of sessions. The model selected will run the dreaming pipeline; during the research preview claude-opus-4-7 and claude-sonnet-4-6 are supported. You can also provide additional guidance on dreaming run execution in instructions.

The response is the full dream resource with 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-7" },
  "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
}

Track progress

Dreams run asynchronously and typically take minutes to tens of minutes depending on input size. Poll the dream by ID to check status:

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

Lifecycle

Watch the pipeline run

Once a dream is running, its session_id field points at the underlying session executing the pipeline. You can stream that session's events to observe what the dream is reading and writing in real time. The session is archived (not deleted) when the dream reaches a terminal state, so the transcript remains available afterward.

Use the output

When status reaches completed, the memory_store entry in outputs[] references a fully populated store. It's an ordinary memory store in your workspace. Review it with the Memory Stores API or in the Console, then either:

• Leverage it: attach it to future sessions as a memory_store resource in place of (or alongside) the input memory store, or
• Discard it: delete or archive it.

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

The dream itself never deletes or modifies its inputs. On failed or canceled the output store persists with partial contents so you can inspect what was produced before stopping; clean it up via the Memory Stores API if you don't need it.

Cancel a dream

Cancel moves a pending or running dream to canceled immediately. Canceling an already-canceled dream is an idempotent no-op; canceling a completed or failed dream returns 400.

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

Archive a dream

Archive sets archived_at on a dream that has reached a terminal state (completed, failed, or canceled); status is left unchanged. Archived dreams are excluded from default list responses but remain readable by ID. Archiving an already-archived dream is an idempotent no-op. Archiving a pending or running dream returns 400; cancel it first. There is no unarchive.

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

Archiving a dream does not touch its output memory store; manage that separately via the Memory Stores API.

List dreams

Returns all non-archived dreams in the workspace, newest first. Use limit (default 20, max 100) and the page cursor to paginate. Pass include_archived=true to include archived dreams.

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

Errors

A non-exhaustive list of possible dreaming errors is below.

Billing

Dreams are billed at standard API token rates for the model you select; usage on the resource reports the exact totals. Cost scales roughly linearly with the number and length of input sessions. Start with a small batch of sessions and scale up once you're satisfied with the curation quality.

Limits

Default rate limits apply to dream creation while this feature is in beta. Contact support if you need higher limits.