Dreams

Os agentes gravam em seus memory stores (armazenamentos de memória) enquanto trabalham, mas essas gravações são locais e incrementais: ao longo de muitas sessões, um memory store acumula duplicatas, contradições e entradas desatualizadas.

Os Dreams (sonhos) permitem que Claude limpe isso. Um dream lê um memory store existente junto com transcrições de sessões passadas e, em seguida, produz um novo memory store reorganizado: duplicatas mescladas, entradas desatualizadas ou contraditas substituídas pelo valor mais recente e novos insights revelados.

O store de entrada nunca é modificado, portanto você pode revisar a saída e descartá-la se não gostar do resultado.

Como funciona

Um dream é um job assíncrono que recebe:

• um memory store pré-existente: o store que Claude verifica, deduplica e reorganiza, e
• de 1 a 100 sessões: transcrições passadas que Claude explora em busca de padrões e insights para incorporar à saída.

O dream produz outro memory store de saída, separado da entrada. O ID do store de saída aparece em outputs[] do dream pouco depois de o dream começar a ficar running, assim que o fluxo de trabalho tiver clonado o store de entrada; um dream running pode reportar brevemente um outputs[] vazio.

Criar um 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...

As entradas do dreaming incluem o memory store pré-existente e um array de sessões. O modelo selecionado executa o pipeline de dreaming. Durante o research preview, claude-opus-5, claude-fable-5, claude-opus-4-8, claude-opus-4-7, claude-sonnet-5 e claude-sonnet-4-6 são suportados. Opcionalmente, você pode passar instructions para direcionar o processo de dreaming. Consulte Direcionar com instruções.

A resposta é o recurso dream completo com 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
}

Direcionar com instruções

O campo opcional instructions direciona o que o pipeline de dreaming sintetiza. Ele é aplicado ao longo de todo o pipeline: o que ler com atenção, o que mesclar ou descartar e como estruturar o store de saída.

Use instructions para orientações de síntese de alto nível, como áreas de foco ("foque em preferências de estilo de código"), conteúdo a ser preservado sem alterações ou convenções de saída que você deseja aplicar em todo o store. O pipeline é uma passagem de síntese sobre as entradas, não um editor aplicado ao texto do store, portanto diretivas imperativas que visam linhas específicas ("mude a frase X para Y", "corrija a contagem na seção Z") geralmente não produzem nenhuma alteração. Para fazer edições direcionadas em memórias individuais, use a API de Memory Stores diretamente no store de saída.

Acompanhar o progresso

Os dreams são executados de forma assíncrona e normalmente levam de minutos a algumas horas, dependendo do número de transcrições de entrada. Consulte o dream por ID para verificar o status:

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 a execução do pipeline

Quando um dream está running, seu campo session_id aponta para a sessão subjacente que executa o pipeline. Você pode fazer streaming dos eventos dessa sessão para observar o que o dream está lendo e gravando em tempo real. A sessão é arquivada (não excluída) quando o dream atinge um estado terminal, portanto a transcrição permanece disponível posteriormente.

Usar a saída

Quando status atinge completed, a entrada memory_store em outputs[] referencia um store totalmente preenchido. É um memory store comum no seu workspace. Revise-o com a API de Memory Stores ou no Console e, em seguida:

• Aproveite-o: anexe-o a sessões futuras como um recurso memory_store no lugar do (ou junto com o) memory store de entrada, ou
• Descarte-o: exclua o memory store ou arquive o memory store.

# Após o dream terminar, a saída contém o armazenamento de memória reconstruído
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},
    ],
)

O dream em si nunca exclui nem modifica suas entradas. Em failed ou canceled, o store de saída persiste com conteúdo parcial para que você possa inspecionar o que foi produzido antes da interrupção; limpe-o por meio da API de Memory Stores se não precisar dele.

Cancelar um dream

O cancelamento move um dream pending ou running para canceled imediatamente. Cancelar um dream já canceled é uma operação idempotente sem efeito; cancelar um dream completed ou failed retorna 400.

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

Arquivar um dream

O arquivamento define archived_at em um dream que atingiu um estado terminal (completed, failed ou canceled); status permanece inalterado. Dreams arquivados são excluídos das respostas de listagem padrão, mas permanecem legíveis por ID. Arquivar um dream já arquivado é uma operação idempotente sem efeito. Arquivar um dream pending ou running retorna 400; cancele-o primeiro. Não há como desarquivar.

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

Arquivar um dream não afeta seu memory store de saída; gerencie-o separadamente por meio da API de Memory Stores.

Listar dreams

Retorna todos os dreams não arquivados no workspace, do mais recente para o mais antigo. Use limit (padrão 20, máximo 100) e o cursor page para paginar. Passe include_archived=true para incluir dreams arquivados.

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

Erros

Segue uma lista não exaustiva de possíveis erros de dreaming.

Cobrança

Os dreams são cobrados pelas tarifas padrão de tokens da API para o modelo que você selecionar; usage no recurso informa os totais exatos. O custo escala de forma aproximadamente linear com o número e o tamanho das sessões de entrada. Comece com um pequeno lote de sessões e aumente a escala quando estiver satisfeito com a qualidade da curadoria.

Limites

Os limites de taxa padrão se aplicam à criação de dreams enquanto este recurso estiver em research preview. Entre em contato com o suporte se precisar de limites mais altos.