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 dream (sogni) consentono 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: i duplicati vengono uniti, le voci obsolete o contraddette vengono sostituite con il valore più recente e nuove intuizioni vengono 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 integrare nell'output.

Il dream produce un altro memory store di output, separato dall'input. L'ID dello store di output appare negli 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ò brevemente riportare un outputs[] vuoto.



Creare 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 opzionalmente passare instructions per guidare il processo di dreaming; consulta Guidare 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
}



Guidare con le istruzioni

Il campo opzionale instructions guida ciò che la pipeline di dreaming sintetizza. Viene applicato in tutta la pipeline: cosa leggere attentamente, cosa unire o eliminare 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 codifica"), 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 direttive imperative che mirano a righe specifiche ("cambia la frase X in Y", "correggi il conteggio nella sezione Z") generalmente non producono alcuna modifica. Per apportare modifiche mirate a singole memorie, usa la Memory Stores API direttamente sullo store di output.



Monitorare l'avanzamento

I dream vengono eseguiti in modo asincrono e richiedono in genere da alcuni minuti a qualche ora, in base al numero di trascrizioni di input. Esegui il polling del 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



Osservare 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 eseguire lo streaming degli 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.



Usare l'output

Quando status raggiunge completed, la voce memory_store in outputs[] fa riferimento a uno store completamente popolato. È un memory store ordinario 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 stesso non elimina né modifica mai i suoi input. In caso di failed o canceled, lo store di output persiste con contenuti parziali in modo che tu possa ispezionare cosa è stato prodotto prima dell'interruzione; ripuliscilo tramite la Memory Stores API se non ti serve.



Annullare un dream

L'annullamento sposta immediatamente un dream in stato pending o running a canceled. Annullare un dream già in stato canceled è un'operazione idempotente senza effetto; annullare un dream in stato completed o failed restituisce 400.

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



Archiviare 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 tramite ID. Archiviare un dream già archiviato è un'operazione idempotente senza effetto. Archiviare un dream in stato pending o running restituisce 400; annullalo prima. Non esiste un'operazione di ripristino dall'archivio.

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

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



Elencare 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 gradualmente una volta che sei soddisfatto della qualità della curazione.



Limiti

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