Dreams

Agentes escrevem em seus memory stores enquanto trabalham, mas essas escritas são locais e incrementais: ao longo de muitas sessões, um memory store acumula duplicatas, contradições e entradas obsoletas.

Dreams 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 obsoletas ou contraditas substituídas pelo valor mais recente, e novos insights revelados.

O store de entrada nunca é modificado, então 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, desduplica e reorganiza, e
• de 1 a 100 sessões: transcrições passadas que Claude analisa 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 logo após o dream entrar em running, assim que o workflow tiver clonado o store de entrada; um dream em running pode brevemente reportar 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 a prévia de pesquisa, claude-fable-5, claude-opus-4-8, claude-opus-4-7, claude-sonnet-5 e claude-sonnet-4-6 são suportados. Você pode opcionalmente 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 preservar 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, então 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 mudança. Para fazer edições direcionadas em memórias individuais, use a API de Memory Stores diretamente no store de saída.



Acompanhar o progresso

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á em 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 escrevendo em tempo real. A sessão é arquivada (não excluída) quando o dream atinge um estado terminal, então a transcrição permanece disponível depois.



Usar a saída

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

• 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 ou modifica suas entradas. Em caso de 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 em pending ou running para canceled imediatamente. Cancelar um dream já em canceled é uma operação idempotente sem efeito; cancelar um dream em 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 em pending ou running retorna 400; cancele-o primeiro. Não há desarquivamento.

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

Dreams são cobrados nas taxas padrão de tokens da API para o modelo que você selecionar; usage no recurso reporta os totais exatos. O custo escala de forma aproximadamente linear com o número e o comprimento 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

Limites de taxa padrão se aplicam à criação de dreams enquanto este recurso está em prévia de pesquisa. Entre em contato com o suporte se precisar de limites mais altos.