Dreams

Agentes escrevem em seus memory stores (armazenamentos de memória) 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 o Claude limpe isso. Um dream lê um memory store existente junto com transcrições de sessões anteriores e, em seguida, produz um novo memory store reorganizado: duplicatas mescladas, entradas obsoletas ou contraditórias 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 o Claude verifica, deduplica e reorganiza, e
• de 1 a 100 sessões: transcrições anteriores que o 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 assim que ele começa a ficar running.

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 de dreaming incluem o memory store pré-existente e um array de sessões. O modelo selecionado executará o pipeline de dreaming; durante a prévia de pesquisa, claude-opus-4-8, claude-opus-4-7 e claude-sonnet-4-6 são suportados. Opcionalmente, você pode passar instructions para orientar o processo de dreaming; consulte Orientar 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_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  },
  "error": null
}

Orientar com instruções

O campo opcional instructions orienta 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, 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 alteração. Para fazer edições direcionadas em memórias individuais, use a Memory Stores API diretamente no store de saída.

Acompanhar o progresso

Dreams são executados de forma assíncrona e normalmente levam de minutos a dezenas de minutos, dependendo do tamanho da entrada. Consulte o dream pelo 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 o pipeline em execução

Assim que 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 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 preenchido. É um memory store comum no seu workspace. Revise-o com a Memory Stores API 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 ou arquive o store.

# 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},
    ],
)

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 via Memory Stores API se não precisar dele.

Cancelar um dream

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

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

Arquivar um dream

Arquivar 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 via Memory Stores API.

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

Uma lista não exaustiva de possíveis erros de dreaming está abaixo.

Cobrança

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

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