Dreams

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

I dream 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 portate in evidenza.

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 prende:

• 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 integrare nell'output.

Il dream produce un altro memory store di output, separato dall'input. L'ID dello store di output appare 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-fable-5, claude-opus-4-8, claude-opus-4-7, claude-sonnet-5 e claude-sonnet-4-6. Puoi opzionalmente passare instructions per guidare il processo di dreaming; consulta Guida 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
}



Guida con le istruzioni

Il campo opzionale instructions guida 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 ad alto livello come aree di interesse ("concentrati sulle preferenze di stile di codifica"), contenuti da preservare invariati, o convenzioni di output che vuoi applicare a tutto lo store. La pipeline è un passaggio di sintesi sugli input, non un editor applicato al testo dello store, quindi direttive imperative che mirano a righe specifiche ("cambia la frase X in Y", "correggi il conteggio nella sezione Z") generalmente non producono alcun cambiamento. 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 tipicamente richiedono da minuti a poche ore, in base al numero di trascrizioni di input. Interroga il dream per 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 è in stato running, il suo campo session_id punta alla sessione sottostante che esegue la pipeline. Puoi trasmettere 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 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 memory store di input (o insieme ad esso), 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 stesso non elimina né modifica mai i suoi input. In caso di failed o canceled lo store di output persiste con contenuti parziali così puoi ispezionare cosa è stato prodotto prima dell'interruzione; eliminalo 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à in stato canceled è un'operazione idempotente senza effetto; 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 rimangono leggibili per ID. Archiviare un dream già archiviato è un'operazione idempotente senza effetto. Archiviare un dream pending o running restituisce 400; annullalo prima. Non esiste la rimozione dall'archivio.

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 di 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 scala in modo approssimativamente lineare con il numero e la lunghezza delle sessioni di input. Inizia con un piccolo batch di sessioni e aumenta una volta soddisfatto della qualità della curatela.



Limiti

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