Dreams

Les agents écrivent dans leurs memory stores (magasins de mémoire) pendant qu'ils travaillent, 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 rêve lit un magasin de mémoire existant ainsi que les transcriptions de 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.

Fonctionnement

Un dream (rêve) est une tâche asynchrone qui prend en entrée :

• un memory store (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 pour en extraire des motifs et des informations à intégrer dans la sortie.

Le rêve produit un autre magasin de mémoire de sortie, distinct de l'entrée. L'identifiant du magasin de sortie apparaît dans le champ outputs[] du rêve dès qu'il passe à l'état running.

Créer un rêve

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 rêve incluent le magasin de mémoire préexistant et un tableau de sessions. Le modèle sélectionné exécutera le pipeline de rêve ; pendant l'aperçu de recherche, claude-opus-4-8, claude-opus-4-7 et claude-sonnet-4-6 sont pris en charge. Vous pouvez éventuellement passer des instructions pour orienter le processus de rêve ; 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_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  },
  "error": null
}

Orienter avec des instructions

Le champ facultatif instructions oriente ce que le pipeline de rêve 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 directives de synthèse de haut niveau telles que des domaines d'intérêt (« concentre-toi sur les préférences de style de code »), du contenu à préserver tel quel, 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 ; les directives impératives ciblant des lignes spécifiques (« change la phrase X en Y », « corrige le décompte dans la section Z ») ne produisent donc 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 rêves s'exécutent de manière asynchrone et prennent généralement de quelques minutes à plusieurs dizaines de minutes selon la taille des entrées. Interrogez le rêve par son identifiant 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 rêve est 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 rêve lit et écrit. La session est archivée (et non supprimée) lorsque le rêve 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. Il s'agit d'un magasin de mémoire ordinaire dans votre espace de travail. Examinez-le avec l'API Memory Stores ou dans la Console, puis au choix :

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

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

Le rêve 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 rêve

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

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

Archiver un rêve

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

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

L'archivage d'un rêve n'affecte pas son magasin de mémoire de sortie ; gérez celui-ci séparément via l'API Memory Stores.

Lister les rêves

Renvoie tous les rêves 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 rêves archivés.

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

Erreurs

Une liste non exhaustive des erreurs possibles liées au rêve figure ci-dessous.

Facturation

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

Limites

Les limites de débit par défaut s'appliquent à la création de rêves tant que cette fonctionnalité est en bêta. Contactez le support si vous avez besoin de limites plus élevées.