Dreams

Les agents écrivent dans leurs magasins de mémoire au fur et à mesure de leur travail, mais ces écritures sont locales et incrémentales : au fil de nombreuses sessions, un magasin de mémoire accumule des doublons, des contradictions et des entrées obsolètes.

Les « dreams » (rêves) permettent à Claude de nettoyer tout cela. Un dream lit un magasin de mémoire existant ainsi que les transcriptions des sessions passées, puis produit un nouveau magasin de mémoire réorganisé : les doublons sont fusionnés, les entrées obsolètes ou contredites sont remplacées par la valeur la plus récente, et de nouvelles informations sont mises en évidence.

Le magasin d'entrée n'est jamais modifié, vous pouvez donc examiner la sortie et la supprimer si le résultat ne vous convient pas.



Comment ça fonctionne

Un dream est une tâche asynchrone qui prend :

• un magasin de mémoire préexistant : le magasin que Claude vérifie, déduplique et réorganise, et
• 1 à 100 sessions : des transcriptions passées que Claude explore à la recherche de modèles et d'informations à intégrer dans la sortie.

Le dream produit un autre magasin de mémoire de sortie, distinct de l'entrée. L'ID du magasin de sortie apparaît dans outputs[] du dream peu après que le dream passe à l'état running, une fois que le flux de travail a cloné le magasin d'entrée ; un dream en état running peut brièvement signaler un outputs[] vide.



Créer 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...

Les entrées du dreaming comprennent le magasin de mémoire préexistant et un tableau de sessions. Le modèle sélectionné exécute le pipeline de dreaming ; pendant l'aperçu de recherche, claude-fable-5, claude-opus-4-8, claude-opus-4-7, claude-sonnet-5 et claude-sonnet-4-6 sont pris en charge. Vous pouvez éventuellement passer instructions pour orienter le processus de dreaming ; consultez Orienter avec des instructions.

La réponse est la ressource dream complète avec 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
}



Orienter avec des instructions

Le champ facultatif instructions oriente ce que le pipeline de dreaming synthétise. Il est appliqué tout au long du pipeline : ce qu'il faut lire attentivement, ce qu'il faut fusionner ou supprimer, et comment structurer le magasin de sortie.

Utilisez instructions pour des orientations de synthèse de haut niveau telles que des domaines d'intérêt (« se concentrer sur les préférences de style de codage »), du contenu à préserver sans modification, ou des conventions de sortie que vous souhaitez appliquer à l'ensemble du magasin. Le pipeline est une passe de synthèse sur les entrées, et non un éditeur appliqué au texte du magasin, donc les directives impératives qui ciblent des lignes spécifiques (« changer la phrase X en Y », « corriger le décompte dans la section Z ») ne produisent généralement aucun changement. Pour effectuer des modifications ciblées sur des mémoires individuelles, utilisez directement l'API Memory Stores sur le magasin de sortie.



Suivre la progression

Les dreams s'exécutent de manière asynchrone et prennent généralement de quelques minutes à quelques heures, selon le nombre de transcriptions en entrée. Interrogez le dream par ID pour vérifier son statut :

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}")



Cycle de vie



Observer l'exécution du pipeline

Une fois qu'un dream est en état running, son champ session_id pointe vers la session sous-jacente qui exécute le pipeline. Vous pouvez diffuser en streaming les événements de cette session pour observer en temps réel ce que le dream lit et écrit. La session est archivée (et non supprimée) lorsque le dream atteint un état terminal, de sorte que la transcription reste disponible par la suite.



Utiliser la sortie

Lorsque status atteint completed, l'entrée memory_store dans outputs[] référence un magasin entièrement rempli. C'est un magasin de mémoire ordinaire dans votre espace de travail. Examinez-le avec l'API Memory Stores ou dans la Console, puis soit :

• Exploitez-le : attachez-le aux sessions futures en tant que ressource memory_store à la place (ou en complément) du magasin de mémoire d'entrée, ou
• Supprimez-le : supprimez le magasin de mémoire ou archivez le magasin de mémoire.

# Une fois le rêve terminé, la sortie contient le magasin de mémoire reconstruit
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},
    ],
)

Le dream lui-même ne supprime ni ne modifie jamais ses entrées. En cas de failed ou canceled, le magasin de sortie persiste avec un contenu partiel afin que vous puissiez inspecter ce qui a été produit avant l'arrêt ; nettoyez-le via l'API Memory Stores si vous n'en avez pas besoin.



Annuler un dream

L'annulation fait passer immédiatement un dream pending ou running à l'état canceled. Annuler un dream déjà canceled est une opération idempotente sans effet ; annuler un dream completed ou failed renvoie 400.

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



Archiver un dream

L'archivage définit archived_at sur un dream qui a atteint un état terminal (completed, failed ou canceled) ; status reste inchangé. Les dreams archivés sont exclus des réponses de liste par défaut mais restent lisibles par ID. Archiver un dream déjà archivé est une opération idempotente sans effet. Archiver un dream pending ou running renvoie 400 ; annulez-le d'abord. Il n'y a pas de désarchivage.

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

L'archivage d'un dream ne touche pas son magasin de mémoire de sortie ; gérez-le séparément via l'API Memory Stores.



Lister les dreams

Renvoie tous les dreams non archivés de l'espace de travail, du plus récent au plus ancien. Utilisez limit (20 par défaut, 100 au maximum) et le curseur page pour paginer. Passez include_archived=true pour inclure les dreams archivés.

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



Erreurs

Voici une liste non exhaustive des erreurs de dreaming possibles.



Facturation

Les dreams sont facturés aux tarifs standard de jetons de l'API pour le modèle que vous sélectionnez ; usage sur la ressource indique les totaux exacts. Le coût évolue à peu près linéairement avec le nombre et la longueur des sessions d'entrée. Commencez avec un petit lot de sessions et augmentez une fois que vous êtes satisfait de la qualité de la curation.



Limites

Les limites de débit par défaut s'appliquent à la création de dreams tant que cette fonctionnalité est en aperçu de recherche. Contactez le support si vous avez besoin de limites plus élevées.