Dreams

Los agentes escriben en sus almacenes de memoria mientras trabajan, pero estas escrituras son locales e incrementales: a lo largo de muchas sesiones, un almacén de memoria acumula duplicados, contradicciones y entradas obsoletas.

Los dreams (sueños) permiten que Claude limpie todo eso. Un dream lee un almacén de memoria existente junto con transcripciones de sesiones pasadas y luego produce un nuevo almacén de memoria reorganizado: los duplicados se fusionan, las entradas obsoletas o contradichas se reemplazan con el valor más reciente y se revelan nuevos insights.

El almacén de entrada nunca se modifica, así que puedes revisar la salida y descartarla si no te gusta el resultado.

Cómo funciona

Un dream es un trabajo asíncrono que recibe:

• un almacén de memoria preexistente: el almacén que Claude verifica, deduplica y reorganiza, y
• de 1 a 100 sesiones: transcripciones pasadas que Claude analiza en busca de patrones e insights para incorporar en la salida.

El dream produce otro almacén de memoria de salida, separado del de entrada. El ID del almacén de salida aparece en outputs[] del dream una vez que comienza a estar en estado running.

Crear 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...

Las entradas de dreaming incluyen el almacén de memoria preexistente y un arreglo de sesiones. El modelo seleccionado ejecutará el pipeline de dreaming; durante la vista previa de investigación se admiten claude-opus-4-8, claude-opus-4-7 y claude-sonnet-4-6. Opcionalmente puedes pasar instructions para orientar el proceso de dreaming; consulta Orientar con instrucciones.

La respuesta es el recurso dream completo 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_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  },
  "error": null
}

Orientar con instrucciones

El campo opcional instructions orienta lo que sintetiza el pipeline de dreaming. Se aplica a lo largo de todo el pipeline: qué leer con atención, qué fusionar o descartar y cómo estructurar el almacén de salida.

Usa instructions para orientación de síntesis de alto nivel, como áreas de enfoque ("enfócate en preferencias de estilo de código"), contenido que debe preservarse sin cambios o convenciones de salida que quieres aplicar en todo el almacén. El pipeline es una pasada de síntesis sobre las entradas, no un editor aplicado al texto del almacén, por lo que las directivas imperativas que apuntan a líneas específicas ("cambia la oración X por Y", "corrige el conteo en la sección Z") generalmente no producen ningún cambio. Para hacer ediciones puntuales a memorias individuales, usa la API de Memory Stores directamente sobre el almacén de salida.

Seguir el progreso

Los dreams se ejecutan de forma asíncrona y normalmente tardan de minutos a decenas de minutos según el tamaño de la entrada. Consulta el dream por ID para verificar el estado:

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 de vida

Observar la ejecución del pipeline

Una vez que un dream está en estado running, su campo session_id apunta a la sesión subyacente que ejecuta el pipeline. Puedes hacer streaming de los eventos de esa sesión para observar en tiempo real qué está leyendo y escribiendo el dream. La sesión se archiva (no se elimina) cuando el dream alcanza un estado terminal, por lo que la transcripción permanece disponible después.

Usar la salida

Cuando status llega a completed, la entrada memory_store en outputs[] hace referencia a un almacén completamente poblado. Es un almacén de memoria ordinario en tu espacio de trabajo. Revísalo con la API de Memory Stores o en la Console, y luego:

• Aprovéchalo: adjúntalo a sesiones futuras como un recurso memory_store en lugar del almacén de memoria de entrada (o junto a él), o
• Descártalo: elimínalo o archívalo.

# After the dream ends, the output holds the rebuilt memory store
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},
    ],
)

El dream en sí nunca elimina ni modifica sus entradas. En caso de failed o canceled, el almacén de salida persiste con contenido parcial para que puedas inspeccionar lo que se produjo antes de detenerse; límpialo mediante la API de Memory Stores si no lo necesitas.

Cancelar un dream

Cancelar mueve un dream en estado pending o running a canceled de inmediato. Cancelar un dream que ya está en canceled es una operación idempotente sin efecto; cancelar un dream en estado completed o failed devuelve 400.

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

Archivar un dream

Archivar establece archived_at en un dream que ha alcanzado un estado terminal (completed, failed o canceled); status se deja sin cambios. Los dreams archivados se excluyen de las respuestas de listado predeterminadas, pero siguen siendo legibles por ID. Archivar un dream ya archivado es una operación idempotente sin efecto. Archivar un dream en estado pending o running devuelve 400; cancélalo primero. No existe la opción de desarchivar.

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

Archivar un dream no afecta a su almacén de memoria de salida; gestiónalo por separado mediante la API de Memory Stores.

Listar dreams

Devuelve todos los dreams no archivados del espacio de trabajo, del más reciente al más antiguo. Usa limit (predeterminado 20, máximo 100) y el cursor page para paginar. Pasa include_archived=true para incluir los dreams archivados.

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

Errores

A continuación se muestra una lista no exhaustiva de posibles errores de dreaming.

Facturación

Los dreams se facturan a las tarifas estándar de tokens de la API para el modelo que selecciones; usage en el recurso informa los totales exactos. El costo escala de forma aproximadamente lineal con el número y la longitud de las sesiones de entrada. Comienza con un lote pequeño de sesiones y aumenta la escala una vez que estés satisfecho con la calidad de la curación.

Límites

Se aplican límites de velocidad predeterminados a la creación de dreams mientras esta funcionalidad está en beta. Contacta con soporte si necesitas límites más altos.