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 dall'input. L'ID dello store di output compare in outputs[] del dream poco dopo che il dream passa a running, una volta che il workflow ha clonato lo store di input; un dream in stato running può riportare brevemente un 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-4-8",
    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, claude-fable-5, claude-opus-4-8, claude-opus-4-7, claude-sonnet-5 e claude-sonnet-4-6. Puoi facoltativamente 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-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
}

Orienta con le istruzioni

Il campo facoltativo instructions orienta ciò che la pipeline di dreaming sintetizza. Viene applicato lungo 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 puntano 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 la Memory Stores API direttamente 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

Una volta che un dream è 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. È 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 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. Passa include_archived=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 dei token 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 lotto 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.