Page history
dreams
managed-agents/dreams
History
managed-agents/dreams First recorded · 667 lines, first recorded
## How it works ## Create a dream ### Steer with instructions ## Track progress ### Lifecycle ### Watch the pipeline run ## Use the output ## Cancel a dream ## Archive a dream ## List dreams ## Errors ## Billing ## Limits
The first capture of this source. The page was already there, and this is what it said.
---
title: Dreams
url: https://platform.claude.com/docs/en/managed-agents/dreams
description: Let Claude reflect on past sessions to curate an agent's memory and surface new insights.
---
<Tip>
Dreaming is a research preview feature. [Request access](https://claude.com/form/claude-managed-agents) to try it.
</Tip>
Agents write to their [memory stores](https://platform.claude.com/docs/en/managed-agents/memory) 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.
<Note>
Dream endpoints are gated by the `dreaming-2026-04-21` beta header; the `managed-agents-2026-04-01` header on its own doesn't grant access to dreams. The dream-endpoint examples on this page send both headers; session and memory-store calls need only `managed-agents-2026-04-01`. The SDK sets these automatically.
</Note>
## 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[]` shortly after the dream starts `running`, once the workflow has cloned the input store; a `running` dream can briefly report an empty `outputs[]`.
## Create a dream
<CodeGroup>
```bash cURL
dream=$(curl -s https://api.anthropic.com/v1/dreams \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01,dreaming-2026-04-21" \
-H "content-type: application/json" \
--data @- <<EOF
{
"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."
}
EOF
)
dream_id=$(jq -r '.id' <<< "$dream")
echo "$dream_id" # drm_01...
```
```bash CLI
dream_id=$(ant beta:dreams create --transform id --raw-output <<YAML
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.
YAML
)
```
```python Python
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...
```
```typescript TypeScript
let dream = await client.beta.dreams.create({
inputs: [
{ type: "memory_store", memory_store_id: storeId },
{ type: "sessions", session_ids: [sessionA, sessionB] },
],
model: "claude-opus-4-8",
instructions: "Focus on coding-style preferences; ignore one-off debugging notes.",
});
console.log(dream.id); // drm_01...
```
```csharp C#
var dream = await client.Beta.Dreams.Create(new()
{
Inputs =
[
new BetaDreamMemoryStoreInput
{
Type = BetaDreamMemoryStoreInputType.MemoryStore,
MemoryStoreID = storeID,
},
new BetaDreamSessionsInput
{
Type = BetaDreamSessionsInputType.Sessions,
SessionIds = [sessionA, sessionB],
},
],
Model = "claude-opus-4-8",
Instructions = "Focus on coding-style preferences; ignore one-off debugging notes.",
});
Console.WriteLine(dream.ID); // drm_01...
```
```go Go
dream, err := client.Beta.Dreams.New(ctx, anthropic.BetaDreamNewParams{
Inputs: []anthropic.BetaDreamInputUnionParam{
anthropic.BetaDreamInputParamOfMemoryStore(storeID),
anthropic.BetaDreamInputParamOfSessions([]string{sessionA, sessionB}),
},
Model: anthropic.BetaDreamModelParamsUnion{
OfString: anthropic.String("claude-opus-4-8"),
},
Instructions: anthropic.String("Focus on coding-style preferences; ignore one-off debugging notes."),
})
if err != nil {
panic(err)
}
fmt.Println(dream.ID) // drm_01...
```
```java Java
var dream = client.beta().dreams().create(
DreamCreateParams.builder()
.addMemoryStoreInput(storeId)
.addSessionsInput(List.of(sessionA, sessionB))
.model("claude-opus-4-8")
.instructions("Focus on coding-style preferences; ignore one-off debugging notes.")
.build()
);
IO.println(dream.id()); // drm_01...
```
```php PHP
$dream = $client->beta->dreams->create(
inputs: [
['type' => 'memory_store', 'memory_store_id' => $storeId],
['type' => 'sessions', 'session_ids' => [$sessionA, $sessionB]],
],
model: 'claude-opus-4-8',
instructions: 'Focus on coding-style preferences; ignore one-off debugging notes.',
);
echo "{$dream->id}\n"; // drm_01...
```
```ruby Ruby
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."
)
puts dream.id # drm_01...
```
</CodeGroup>
Dreaming inputs include the pre-existing memory store and an array of sessions. The selected model runs the dreaming pipeline; during the research preview `claude-opus-5`, `claude-fable-5`, `claude-opus-4-8`, `claude-opus-4-7`, `claude-sonnet-5`, and `claude-sonnet-4-6` are supported. You can optionally pass `instructions` to steer the dreaming process; see [Steer with instructions](https://platform.claude.com/docs/en/managed-agents/dreams#steer-with-instructions).
The response is the full `dream` resource with `status: "pending"`:
```json
{
"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
}
```
<Tip>
If you only have session transcripts and no existing store, [create an empty memory store](https://platform.claude.com/docs/en/managed-agents/memory#create-a-memory-store) first and pass it as the `memory_store` input.
</Tip>
### 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](https://platform.claude.com/docs/en/managed-agents/memory#view-and-edit-memories) 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:
<CodeGroup>
```bash cURL
while true; do
dream=$(curl -s "https://api.anthropic.com/v1/dreams/$dream_id" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01,dreaming-2026-04-21")
status=$(jq -r '.status' <<< "$dream")
echo "status=$status input_tokens=$(jq -r '.usage.input_tokens' <<< "$dream")"
[[ "$status" == "pending" || "$status" == "running" ]] || break
sleep 10
done
```
```bash CLI
ant beta:dreams retrieve --dream-id "$dream_id"
```
```python Python
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}")
```
```typescript TypeScript
while (dream.status === "pending" || dream.status === "running") {
await sleep(10_000);
dream = await client.beta.dreams.retrieve(dream.id);
console.log(`status=${dream.status} input_tokens=${dream.usage.input_tokens}`);
}
```
```csharp C#
while (dream.Status.Value() is BetaDreamStatus.Pending or BetaDreamStatus.Running)
{
await Task.Delay(TimeSpan.FromSeconds(10));
dream = await client.Beta.Dreams.Retrieve(dream.ID);
Console.WriteLine($"status={dream.Status.Raw()} input_tokens={dream.Usage.InputTokens}");
}
```
```go Go
for dream.Status == anthropic.BetaDreamStatusPending || dream.Status == anthropic.BetaDreamStatusRunning {
time.Sleep(10 * time.Second)
dream, err = client.Beta.Dreams.Get(ctx, dream.ID, anthropic.BetaDreamGetParams{})
if err != nil {
panic(err)
}
fmt.Printf("status=%s input_tokens=%d\n", dream.Status, dream.Usage.InputTokens)
}
```
```java Java
while (dream.status().equals(BetaDreamStatus.PENDING)
|| dream.status().equals(BetaDreamStatus.RUNNING)) {
Thread.sleep(10_000);
dream = client.beta().dreams().retrieve(dream.id());
IO.println("status=" + dream.status() + " input_tokens=" + dream.usage().inputTokens());
}
```
```php PHP
while (in_array($dream->status, [BetaDreamStatus::PENDING->value, BetaDreamStatus::RUNNING->value], true)) {
sleep(10);
$dream = $client->beta->dreams->retrieve($dream->id);
echo "status={$dream->status} input_tokens={$dream->usage->inputTokens}\n";
}
```
```ruby Ruby
while %i[pending running].include?(dream.status)
sleep 10
dream = client.beta.dreams.retrieve(dream.id)
puts "status=#{dream.status} input_tokens=#{dream.usage.input_tokens}"
end
```
</CodeGroup>
### Lifecycle
| `status` | Meaning |
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
| `pending` | Dream successfully created and queued. |
| `running` | The pipeline is processing. `usage` updates as work progresses. |
| `completed` | Finished successfully. The `outputs[]` value is the new memory store. |
| `failed` | Dreaming run ended with an error. The output memory store is left as-is with whatever was written before failure. |
| `canceled` | Dreaming run canceled. The output memory store is left as-is. |
### Watch the pipeline run
Cut at 300 lines.