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
• 1 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 array shortly after the dream starts running, once the workflow has cloned the input store; a running dream can briefly report an empty outputs array.

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-5-5",
    instructions="Focus on coding-style preferences; ignore one-off debugging notes.",
)
print(dream.id)  # drm_01...

Dreaming inputs include the pre-existing memory store and an array of sessions. The model you choose runs the dreaming pipeline. Only select models are supported. You can optionally pass instructions to steer the dreaming process. See Steer with 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-5-5" },
  "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
}

Steer with instructions

The optional instructions field steers what the dreaming pipeline synthesizes. It is applied throughout the pipeline: what to read closely, what to merge or drop, and how to structure the output store.

Use instructions for high-level synthesis guidance such as focus areas (“focus on coding-style preferences”), content to preserve unchanged, or output conventions you want applied across the store. The pipeline is a synthesis pass over the inputs, not an editor applied to the text of the store, so imperative directives that target specific lines (“change sentence X to Y,” “fix the count in section Z”) generally produce no change. To make targeted edits to individual memories, use the Memory Stores API on the output store directly.

Track progress

Dreams run asynchronously and typically take minutes to a few hours, driven by the number of input transcripts. 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 running 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 Claude Console, then either:

• Use it: attach it to future sessions as a memory_store resource in place of (or alongside) the input memory store, or
• Discard it: delete the memory storePreview with links to the API reference available — press Tab until focus enters the card, Escape to return. or archive the memory storePreview with links to the API reference available — press Tab until focus enters the card, Escape to return..

# 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 through 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 through 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. Set include_archived to 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 follows.

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 research preview. Contact support if you need higher limits.

Availability

Dreams are in research preview on select models.

API support

Beta headers allow you to access experimental features and new model capabilities before they become part of the standard API.

Dream endpoints require the dreaming-2026-04-21 beta header. The managed-agents-2026-04-01 header on its own doesn’t grant access to dreams. Session calls use managed-agents-2026-04-01, and memory store calls use agent-memory-2026-07-22. The SDK sets the right header on each call.