Dreams

Gli agenti scrivono nei loro memory store (archivi di memoria) mentre lavorano, ma queste scritture sono locali e incrementali: nel corso di molte sessioni un memory store accumula duplicati, contraddizioni e voci obsolete.

I Dreams (sogni) permettono a Claude di fare pulizia. Un dream legge un memory store esistente insieme alle trascrizioni delle sessioni passate, quindi produce un nuovo memory store riorganizzato: duplicati uniti, voci obsolete o contraddette sostituite con il valore più recente e nuove intuizioni fatte emergere.

Lo store di input non viene mai modificato, quindi puoi esaminare l'output e scartarlo se il risultato non ti soddisfa.

Come funziona

Un dream è un job asincrono che riceve:

• un memory store preesistente: lo store che Claude verifica, deduplica e riorganizza, e
• da 1 a 100 sessioni: trascrizioni passate che Claude analizza alla ricerca di pattern e intuizioni da incorporare nell'output.

Il dream produce un altro memory store di output, separato da quello di input. L'ID dello store di output compare nell'array outputs del dream poco dopo che il dream passa allo stato running, una volta che il workflow ha clonato lo store di input; un dream in stato running può riportare brevemente un array outputs vuoto.

Crea un 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...

Gli input del dreaming includono il memory store preesistente e un array di sessioni. Il modello selezionato esegue la pipeline di dreaming. Durante l'anteprima di ricerca sono supportati claude-opus-5-5, claude-fable-5-1, claude-opus-5, claude-fable-5, claude-opus-4-8, claude-opus-4-7, claude-sonnet-5-5, claude-sonnet-5 e claude-sonnet-4-6. Facoltativamente puoi passare instructions per orientare il processo di dreaming. Consulta Orienta con le istruzioni.

La risposta è la risorsa dream completa con 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
}

Orienta con le istruzioni

Il campo facoltativo instructions orienta ciò che la pipeline di dreaming sintetizza. Viene applicato in tutta la pipeline: cosa leggere con attenzione, cosa unire o scartare e come strutturare lo store di output.

Usa instructions per indicazioni di sintesi di alto livello, come aree di interesse ("concentrati sulle preferenze di stile di programmazione"), contenuti da preservare invariati o convenzioni di output che vuoi applicare all'intero store. La pipeline è un passaggio di sintesi sugli input, non un editor applicato al testo dello store, quindi le direttive imperative che mirano a righe specifiche ("cambia la frase X in Y", "correggi il conteggio nella sezione Z") in genere non producono alcuna modifica. Per apportare modifiche mirate a singole memorie, usa direttamente la Memory Stores API sullo store di output.

Monitora l'avanzamento

I dream vengono eseguiti in modo asincrono e richiedono in genere da alcuni minuti a qualche ora, a seconda del numero di trascrizioni di input. Interroga il dream tramite ID per verificarne lo stato:

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

Ciclo di vita

Osserva l'esecuzione della pipeline

Quando un dream è in stato running, il suo campo session_id punta alla sessione sottostante che esegue la pipeline. Puoi ricevere in streaming gli eventi di quella sessione per osservare in tempo reale cosa il dream sta leggendo e scrivendo. La sessione viene archiviata (non eliminata) quando il dream raggiunge uno stato terminale, quindi la trascrizione rimane disponibile anche in seguito.

Usa l'output

Quando status raggiunge completed, la voce memory_store in outputs fa riferimento a uno store completamente popolato. Si tratta di un normale memory store nel tuo workspace. Esaminalo con la Memory Stores API o nella Console, quindi:

• Sfruttalo: collegalo alle sessioni future come risorsa memory_store al posto del (o insieme al) memory store di input, oppure
• Scartalo: elimina il memory store o archivia il memory store.

# Al termine del dream, l'output contiene l'archivio di memoria ricostruito
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},
    ],
)

Il dream in sé non elimina né modifica mai i propri input. In caso di failed o canceled lo store di output persiste con contenuti parziali, così puoi ispezionare ciò che è stato prodotto prima dell'interruzione; ripuliscilo tramite la Memory Stores API se non ti serve.

Annulla un dream

L'annullamento porta immediatamente un dream pending o running allo stato canceled. Annullare un dream già canceled è un'operazione idempotente senza effetti; annullare un dream completed o failed restituisce 400.

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

Archivia un dream

L'archiviazione imposta archived_at su un dream che ha raggiunto uno stato terminale (completed, failed o canceled); status rimane invariato. I dream archiviati sono esclusi dalle risposte di elenco predefinite, ma restano leggibili tramite ID. Archiviare un dream già archiviato è un'operazione idempotente senza effetti. Archiviare un dream in stato pending o running restituisce 400; annullalo prima. Non è possibile annullare l'archiviazione.

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

L'archiviazione di un dream non tocca il suo memory store di output; gestiscilo separatamente tramite la Memory Stores API.

Elenca i dream

Restituisce tutti i dream non archiviati nel workspace, dal più recente. Usa limit (predefinito 20, massimo 100) e il cursore page per la paginazione. Imposta include_archived su true per includere i dream archiviati.

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

Errori

Segue un elenco non esaustivo dei possibili errori del dreaming.

Fatturazione

I dream vengono fatturati alle tariffe standard per token dell'API per il modello selezionato; usage sulla risorsa riporta i totali esatti. Il costo cresce in modo approssimativamente lineare con il numero e la lunghezza delle sessioni di input. Inizia con un piccolo gruppo di sessioni e aumenta una volta soddisfatto della qualità della curatela.

Limiti

Alla creazione dei dream si applicano i limiti di velocità predefiniti mentre questa funzionalità è in anteprima di ricerca. Contatta il supporto se hai bisogno di limiti più elevati.