> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt # Observational Memory **Ajouté dans :** `@mastra/memory@1.1.0` Observational Memory (OM) est le système de mémoire agentique à contexte long de Mastra. Un **Observer** surveille les conversations et crée des observations. Un **Reflector** restructure ces observations en combinant les éléments associés et en condensant les tendances générales. Ensemble, ils maintiennent un journal d’observations qui remplace progressivement l’historique brut des messages. ## Exemple d’utilisation ```typescript import { Memory } from '@mastra/memory' import { Agent } from '@mastra/core/agent' export const agent = new Agent({ id: 'my-agent', name: 'my-agent', instructions: 'You are a helpful assistant.', model: 'openai/gpt-5-mini', memory: new Memory({ options: { observationalMemory: true, }, }), }) ``` ## Configuration L’option `observationalMemory` accepte `true`, un objet de configuration ou `false`. La valeur `true` active OM avec `google/gemini-2.5-flash` comme modèle par défaut. Lorsque vous transmettez un objet de configuration, définissez `model` au premier niveau ou dans `observation.model` et/ou `reflection.model` ; si tous les champs de modèle sont omis, OM utilise `google/gemini-2.5-flash` comme solution de repli. L’entrée de l’Observer prend en charge le multimodal. OM conserve des espaces réservés textuels tels que `[Image #1: screenshot.png]` dans la transcription créée pour l’Observer et envoie également les parties d’image sous-jacentes lorsque cela est possible. Ce comportement s’applique à l’observation d’un seul thread comme à l’observation par lots de plusieurs threads. Les fichiers qui ne sont pas des images apparaissent uniquement sous forme d’espaces réservés. OM applique les seuils au moyen d’une estimation locale rapide des tokens. Le texte utilise `tokenx`, tandis que les entrées de type image utilisent des heuristiques adaptées au Provider et des solutions de repli déterministes lorsque les métadonnées sont incomplètes. **enabled** (`boolean`): Active ou désactive Observational Memory. Lorsque cette option est omise d’un objet de configuration, elle vaut par défaut true. Seul enabled: false la désactive explicitement. (Default: `true`) **model** (`string | LanguageModel | DynamicModel | ModelByInputTokens | ModelWithRetries[]`): Modèle des Agents Observer et Reflector. Définit simultanément le modèle des deux Agents. Ne peut pas être utilisé avec observation.model ou reflection.model ; une erreur est levée si les deux sont définis. Lorsque cette option et observation.model/reflection.model sont toutes omises, OM utilise google/gemini-2.5-flash comme solution de repli. Utilisez "default" pour employer explicitement le modèle par défaut (google/gemini-2.5-flash). (Default: `'google/gemini-2.5-flash'`) **scope** (`'resource' | 'thread'`): Portée mémoire des observations. 'thread' conserve les observations par thread. 'resource' (expérimental) partage les observations entre tous les threads d’une ressource, ce qui permet une mémoire interconversationnelle. (Default: `'thread'`) **activateAfterIdle** (`number | string | false | "auto"`): Durée d’inactivité après laquelle l’activation des observations mises en mémoire tampon est forcée, même avant d’atteindre observation.messageTokens. Accepte une valeur numérique en millisecondes telle que 300\_000, des chaînes de durée comme "5m" ou "1hr", "auto" pour une durée de vie du cache de prompts adaptée au Provider, ou false pour désactiver l’activation après inactivité héritée par les observations. Les réflexions n’héritent pas de ce paramètre. Utilisez reflection.activateAfterIdle pour activer ce comportement pour les réflexions. **activateOnProviderChange** (`boolean`): Force l’activation des observations mises en mémoire tampon lorsque le Provider ou le modèle de l’acteur change. Les réflexions n’héritent pas de ce paramètre. Utilisez reflection.activateOnProviderChange pour activer ce comportement pour les réflexions. (Default: `false`) **shareTokenBudget** (`boolean`): Partage le budget de tokens entre les messages et les observations. Lorsqu’elle est activée, le budget total est observation.messageTokens + reflection.observationTokens. Les messages peuvent occuper davantage d’espace lorsque les observations sont courtes, et inversement. Cette allocation flexible maximise l’utilisation du contexte. shareTokenBudget n’est pas encore compatible avec la mise en mémoire tampon asynchrone. Vous devez définir observation: { bufferTokens: false } lorsque vous utilisez cette option (limitation temporaire). (Default: `false`) **temporalMarkers** (`boolean`): Insère des marqueurs de rappel d’intervalle temporel avant les nouveaux messages utilisateur lorsque le message précédent du thread date d’au moins 10 minutes. Le marqueur est persisté en mémoire, émis comme événement de rappel en ligne afin que les clients puissent lui appliquer un rendu particulier, et présenté à l’Observer pour ancrer les observations dans le temps. (Default: `false`) **retrieval** (`boolean | { vector?: boolean; scope?: 'thread' | 'resource'; instructions?: string }`): Permet à l’Agent de consulter l’historique brut des messages à l’origine de ses observations. Les groupes d’observations conservent des pointeurs durables vers les messages d’origine, et un Tool recall est enregistré afin que l’Agent puisse les parcourir. true active par défaut la navigation entre les threads. { vector: true } active également la recherche sémantique au moyen du stockage vectoriel et de l’Embedder de Memory. { scope: 'thread' } limite le Tool de rappel au thread actuel. La portée par défaut est 'resource'. { instructions: '...' } ajoute des consignes de rappel propres à l’application après les instructions de récupération intégrées de Mastra. (Default: `false`) **hooks** (`ObserveHooks`): Hooks de cycle de vie déclenchés pour chaque cycle d’observation/réflexion : les API manuelles observe()/reflect(), l’observation synchrone pilotée par les tours et la mise en mémoire tampon asynchrone sans attente. Les callbacks reçoivent le contexte d’appel threadId/resourceId/trigger ('manual' | 'turn-sync' | 'async-buffer'), et les hooks de fin (onObservationEnd/onReflectionEnd) reçoivent en plus l’usage de tokens et les providerMetadata de l’appel au modèle OM, où des Providers tels que l’AI Gateway indiquent le coût de chaque appel. Les applications peuvent ainsi comptabiliser les dépenses du modèle OM sans encapsuler les modèles Observer/Reflector dans un middleware. Les cycles asynchrones mis en mémoire tampon qui échouent ne lèvent jamais d’erreur ; ils la signalent dans le champ error du hook de fin. Les erreurs levées par ces hooks sont interceptées et journalisées ; elles ne font jamais échouer le cycle. **observation** (`ObservationalMemoryObservationConfig`): Configuration de l’étape d’observation. Contrôle le moment où l’Agent Observer s’exécute et son comportement. **observation.model** (`string | LanguageModel | DynamicModel | ModelByInputTokens | ModelWithRetries[]`): Modèle de l’Agent Observer. Ne peut pas être défini si un model de premier niveau est également fourni. Si ni cette option ni le model de premier niveau ne sont définis, utilise reflection.model comme solution de repli. **observation.instruction** (`string`): Instruction personnalisée ajoutée au prompt système de l’Observer. Utilisez-la pour personnaliser les éléments sur lesquels l’Observer se concentre, tels que les préférences ou priorités propres au domaine. **observation.threadTitle** (`boolean`): Lorsque cette valeur vaut true, l’Observer suggère des titres de thread courts et met à jour le titre lorsque le sujet de la conversation change de manière significative. Cette fonctionnalité doit être activée explicitement et est désactivée par défaut. **observation.extract** (`Extractor[]`): Valeurs personnalisées à extraire après l’observation. Les extracteurs sans schéma sont demandés en ligne dans la sortie de l’Observer. Les extracteurs avec schéma s’exécutent dans un appel de sortie structurée ultérieur et sont stockés dans les métadonnées OM du thread. **observation.manageWorkingMemory** (`boolean`): Permet à l’Observer de gérer la mémoire de travail au moyen de l’extraction OM. Ajoute WorkingMemoryExtractor, définit par défaut workingMemory.agentManaged sur false et workingMemory.useStateSignals sur true. Consultez la section Mises à jour de la mémoire de travail. **observation.observeAttachments** (`'auto' | boolean | string[]`): Contrôle les pièces jointes image/fichier transmises au modèle Observer avec leurs lignes de texte d’espace réservé. true (valeur par défaut) transmet toutes les pièces jointes. false les retire toutes tout en conservant les espaces réservés visibles. 'auto' utilise le registre des fonctionnalités des Providers : les pièces jointes sont transmises lorsque le modèle Observer prend en charge les entrées multimodales, retirées dans le cas contraire, et transmises si aucune donnée de fonctionnalité n’est disponible. Un tableau constitue une liste d’autorisation mimeType insensible à la casse prenant en charge les correspondances exactes ('application/pdf'), les sous-types génériques ('image/\*') et '\*' seul pour tout autoriser. Cette option est utile lorsque le modèle Observer accepte uniquement du texte, par exemple certains endpoints DeepSeek, tandis que l’Agent principal utilise un modèle multimodal. Les pièces jointes issues des résultats de Tool sont filtrées selon la même règle. **observation.messageTokens** (`number`): Nombre de tokens des messages non observés qui déclenche l’observation. Lorsque les tokens de messages non observés dépassent ce seuil, l’Agent Observer est appelé. Le texte est estimé localement avec tokenx. Les parties d’image sont incluses au moyen d’heuristiques adaptées au modèle lorsque cela est possible, avec des solutions de repli déterministes si leurs métadonnées sont incomplètes. Les parties file de type image sont comptées de la même manière lorsque les téléversements sont normalisés comme fichiers. **observation.maxTokensPerBatch** (`number`): Nombre maximal de tokens par lot lors de l’observation de plusieurs threads dans la portée ressource. Les threads sont découpés en lots de cette taille et traités en parallèle. Des valeurs plus faibles augmentent le parallélisme, mais aussi le nombre d’appels d’API. **observation.modelSettings** (`ObservationalMemoryModelSettings`): Paramètres du modèle de l’Agent Observer. La valeur par défaut maxOutputTokens: 100\_000 ne s’applique qu’avec la sélection de modèle par défaut (aucun modèle défini, "default" ou un sélecteur ModelByInputTokens). Les modèles personnalisés ne reçoivent aucune valeur par défaut pour maxOutputTokens. **observation.modelSettings.temperature** (`number`): Température de génération. Des valeurs plus faibles produisent une sortie plus cohérente. **observation.modelSettings.maxOutputTokens** (`number`): Nombre maximal de tokens de sortie. Définissez une valeur élevée pour éviter la troncature des observations. La valeur par défaut 100000 ne s’applique qu’avec la sélection de modèle par défaut ; les modèles personnalisés ne reçoivent aucune valeur par défaut. **observation.providerOptions** (`ProviderOptions`): Options propres au Provider transmises à l’Agent Observer, telles que la configuration du raisonnement de Google. **observation.bufferTokens** (`number | false`): Fréquence d’exécution de la mise en mémoire tampon des observations en arrière-plan. Les valeurs comprises entre 0 et 1 sont des fractions de messageTokens : 0.25 met en mémoire tampon tous les 25 % du seuil (7,5 k tokens avec la valeur par défaut de 30 k). Les valeurs supérieures ou égales à 1 sont des nombres absolus de tokens : 5000 effectue une mise en mémoire tampon tous les 5 k tokens. Les observations sont stockées jusqu’à atteindre le seuil messageTokens, puis s’activent instantanément sans appel LLM bloquant. La valeur résolue doit être inférieure à messageTokens. Définissez false pour désactiver toute mise en mémoire tampon asynchrone (observation et réflexion). **observation.bufferOnIdle** (`boolean`): Exécute la mise en mémoire tampon des observations en arrière-plan à la fin d’un tour de l’Agent, lorsque celui-ci devient inactif. Ce mécanisme est distinct de bufferTokens, qui contrôle la mise en mémoire tampon asynchrone pendant les étapes. Définissez true pour mettre en mémoire tampon les tours inactifs courts sans attendre le tour suivant ni le seuil messageTokens. **observation.bufferActivation** (`number`): Part de la fenêtre de messages à effacer lors de l’activation des observations mises en mémoire tampon. Les valeurs comprises entre 0 et 1 représentent la fraction de messageTokens à supprimer : 0.8 retire environ 80 % de l’historique et en conserve environ 20 % (6 k tokens avec la valeur par défaut de 30 k). Les valeurs supérieures ou égales à 1000 indiquent le nombre de tokens à conserver : 4000 conserve environ 4 k tokens après l’activation. Le sens s’inverse : un ratio plus élevé supprime davantage d’historique, tandis qu’un nombre de tokens plus élevé en conserve davantage. **observation.activateAfterIdle** (`number | string | false | "auto"`): Durée d’inactivité avant l’activation forcée des observations mises en mémoire tampon. Accepte des millisecondes, une chaîne de durée, "auto" pour une durée de vie du cache de prompts adaptée au Provider, ou false. Si cette option n’est pas définie, les observations utilisent la valeur activateAfterIdle de premier niveau. Définissez false pour désactiver ce paramètre de premier niveau pour les observations. S’applique actuellement uniquement à la classe ObservationalMemory autonome ; new Memory(...) applique seulement la valeur activateAfterIdle de premier niveau. **observation.activateOnProviderChange** (`boolean`): Force l’activation des observations mises en mémoire tampon lorsque le Provider ou le modèle de l’acteur change. Si cette option n’est pas définie, les observations utilisent la valeur activateOnProviderChange de premier niveau. S’applique actuellement uniquement à la classe ObservationalMemory autonome ; new Memory(...) applique seulement la valeur activateOnProviderChange de premier niveau. **observation.blockAfter** (`number`): Filet de sécurité qui force une observation synchrone (bloquante) lorsque la mise en mémoire tampon en arrière-plan ne suit plus. Les valeurs de 1 à moins de 100 sont des multiplicateurs de messageTokens : 1.2 force une observation bloquante à 120 % du seuil (36 k tokens avec la valeur par défaut de 30 k). Les valeurs supérieures ou égales à 100 sont des nombres absolus de tokens et doivent dépasser messageTokens. Entre messageTokens et blockAfter, seules la mise en mémoire tampon asynchrone et l’activation s’exécutent ; l’activation conserve toujours un contexte minimal (la plus petite valeur entre 1 000 tokens et le plancher de rétention). Ne s’applique que lorsque bufferTokens est défini. Utilise par défaut 1.2 lorsque la mise en mémoire tampon asynchrone est activée. **observation.previousObserverTokens** (`number | false`): Budget de tokens facultatif du contexte des observations précédentes de l’Observer. Lorsqu’il s’agit d’un nombre, les observations transmises à l’Agent Observer sont tronquées en partant du début afin de respecter ce budget, tout en conservant les observations les plus récentes et, si possible, les éléments marqués 🔴. Lorsqu’une réflexion mise en mémoire tampon est en attente, les lignes d’observation déjà réfléchies sont automatiquement remplacées par le résumé de la réflexion avant la troncature. Définissez 0 pour omettre entièrement les observations précédentes, ou false pour désactiver explicitement la troncature. **reflection** (`ObservationalMemoryReflectionConfig`): Configuration de l’étape de réflexion. Contrôle le moment où l’Agent Reflector s’exécute et son comportement. **reflection.model** (`string | LanguageModel | DynamicModel | ModelByInputTokens | ModelWithRetries[]`): Modèle de l’Agent Reflector. Ne peut pas être défini si un model de premier niveau est également fourni. Si ni cette option ni le model de premier niveau ne sont définis, utilise observation.model comme solution de repli. **reflection.instruction** (`string`): Instruction personnalisée ajoutée au prompt système du Reflector. Utilisez-la pour personnaliser la consolidation des observations, par exemple en donnant la priorité à certains types d’informations. **reflection.extract** (`Extractor[]`): Valeurs personnalisées à extraire après la réflexion. Les extracteurs sans schéma sont demandés en ligne dans la sortie du Reflector. Les extracteurs avec schéma s’exécutent dans un appel de sortie structurée ultérieur et sont stockés dans les métadonnées OM du thread. **reflection.observationTokens** (`number`): Nombre de tokens d’observation qui déclenche la réflexion. Lorsque les tokens d’observation dépassent ce seuil, l’Agent Reflector est appelé pour les condenser. **reflection.modelSettings** (`ObservationalMemoryModelSettings`): Paramètres du modèle de l’Agent Reflector. La valeur par défaut maxOutputTokens: 100\_000 ne s’applique qu’avec la sélection de modèle par défaut (aucun modèle défini, "default" ou un sélecteur ModelByInputTokens). Les modèles personnalisés ne reçoivent aucune valeur par défaut pour maxOutputTokens. **reflection.modelSettings.temperature** (`number`): Température de génération. Des valeurs plus faibles produisent une sortie plus cohérente. **reflection.modelSettings.maxOutputTokens** (`number`): Nombre maximal de tokens de sortie. Définissez une valeur élevée pour éviter la troncature des observations. La valeur par défaut 100000 ne s’applique qu’avec la sélection de modèle par défaut ; les modèles personnalisés ne reçoivent aucune valeur par défaut. **reflection.providerOptions** (`ProviderOptions`): Options propres au Provider transmises à l’Agent Reflector, telles que la configuration du raisonnement de Google. **reflection.bufferActivation** (`number`): Moment où démarre la réflexion en arrière-plan, sous forme de ratio (0-1) de observationTokens : 0.5 lance la réflexion lorsque les observations atteignent 50 % du seuil (20 k tokens avec la valeur par défaut de 40 k). Lorsque le seuil complet est atteint, la réflexion mise en mémoire tampon remplace les observations qu’elle couvre tout en conservant les nouvelles observations ajoutées après cette plage. **reflection.activateAfterIdle** (`number | string | false | "auto"`): Durée d’inactivité avant l’activation forcée des réflexions mises en mémoire tampon. Accepte des millisecondes, une chaîne de durée, "auto" pour une durée de vie du cache de prompts adaptée au Provider, ou false. Les réflexions n’héritent pas de la valeur activateAfterIdle de premier niveau ; définissez explicitement cette option pour activer ce comportement. S’applique actuellement uniquement à la classe ObservationalMemory autonome ; ce paramètre est sans effet avec new Memory(...). **reflection.activateOnProviderChange** (`boolean`): Force l’activation des réflexions mises en mémoire tampon lorsque le Provider ou le modèle de l’acteur change. Les réflexions n’héritent pas de la valeur activateOnProviderChange de premier niveau ; définissez explicitement cette option pour activer ce comportement. S’applique actuellement uniquement à la classe ObservationalMemory autonome ; ce paramètre est sans effet avec new Memory(...). **reflection.blockAfter** (`number`): Filet de sécurité qui force une réflexion synchrone (bloquante) lorsque la réflexion en arrière-plan ne suit plus. Les valeurs de 1 à moins de 100 sont des multiplicateurs de observationTokens : 1.2 force une réflexion bloquante à 120 % du seuil (48 k tokens avec la valeur par défaut de 40 k). Les valeurs supérieures ou égales à 100 sont des nombres absolus de tokens et doivent dépasser observationTokens. Entre observationTokens et blockAfter, seules la mise en mémoire tampon asynchrone et l’activation s’exécutent. Ne s’applique que lorsque bufferActivation est défini. Utilise par défaut 1.2 lorsque la réflexion asynchrone est activée. ### Cache des métadonnées d’estimation des tokens OM persiste les estimations de tokens des charges utiles afin que les comptages répétés puissent réutiliser les estimations précédentes. - Cache au niveau des parties : `part.providerMetadata.mastra`. - Cache de repli pour le contenu textuel : métadonnées au niveau du message lorsqu’aucune partie n’existe. - Les entrées de cache sont ignorées et recalculées si la version du cache ou la source du tokenizer ne correspond pas. - Le surcoût propre à chaque message et à chaque conversation est toujours recalculé à l’exécution et n’est pas mis en cache. - Les parties `data-*` et `reasoning` sont ignorées et ne reçoivent aucune entrée de cache. ## API Extractor `Extractor` définit une valeur qu’OM doit extraire pendant l’observation ou la réflexion. Les valeurs OM intégrées telles que `current-task`, `suggested-response` et `thread-title` utilisent le même pipeline d’extraction que les valeurs personnalisées. ```typescript import { Memory, Extractor } from '@mastra/memory' import { z } from 'zod' const memory = new Memory({ options: { observationalMemory: { model: 'openai/gpt-5-mini', observation: { extract: [ new Extractor({ name: 'User profile', instructions: 'Extract stable user profile facts that should be remembered.', schema: z.object({ name: z.string().optional(), timezone: z.string().optional(), }), }), ], }, }, }, }) ``` **name** (`string`): Nom lisible de l’extracteur. OM transforme cette valeur en slug d’extracteur. Les noms doivent être uniques après la génération du slug. **slug** (`string`): Propriété en lecture seule dérivée de name ; il ne s’agit pas d’une option du constructeur. Identifiant stable généré pour les valeurs persistées et les tags XML. Les slugs utilisent des lettres minuscules, des chiffres et des traits d’union. Les extracteurs personnalisés ne peuvent pas utiliser les slugs intégrés ni les tags XML réservés. **instructions** (`string | (context) => string`): Instructions indiquant les données à extraire et le moment où mettre la valeur à jour. Utilisez une fonction pour dériver les instructions du contexte d’exécution. **schema** (`ZodType | (context) => ZodType | undefined`): Schéma Zod facultatif pour l’extraction structurée. Lorsqu’il est fourni, OM exécute un appel de sortie structurée ultérieur après l’opération OM principale. Lorsqu’il est omis, l’extracteur est un extracteur de chaîne en ligne émis dans la réponse de l’Observer ou du Reflector. Utilisez une fonction pour dériver le schéma du contexte d’exécution. **includePreviousExtraction** (`boolean`): Indique si l’extraction précédente est présentée à l’extracteur lors des prochaines exécutions OM. Définissez false pour les valeurs qui doivent provenir uniquement de l’exécution OM actuelle. (Default: `true`) **metadataKeyPath** (`string | false`): Chemin des métadonnées OM séparé par des points, utilisé pour persister la valeur extraite. Définissez false pour ignorer entièrement la persistance des métadonnées OM. (Default: `'extracted.'`) **onExtracted** (`(context) => T | void | Promise`): Hook facultatif appelé après qu’un extracteur personnalisé a renvoyé une valeur et avant la persistance des métadonnées. Le renvoi d’une valeur remplace la valeur extraite. Une erreur levée enregistre un échec d’extraction. ### Comportement de l’extraction - Les valeurs extraites sont stockées dans les métadonnées OM du thread sous `om.extracted`. - Les valeurs des extracteurs intégrés sont également reproduites dans les champs de métadonnées de compatibilité `currentTask`, `suggestedResponse` et `threadTitle`. - `thread-title` met à jour le titre du thread uniquement lorsque `observation.threadTitle` est activé. - `observation.extract` s’exécute pendant l’observation. `reflection.extract` s’exécute pendant la réflexion. - Les extracteurs avec schéma ajoutent une requête de sortie structurée ultérieure. - Les extracteurs sans schéma sont des extracteurs de chaîne en ligne émis directement dans la sortie de l’Observer ou du Reflector. - Les fonctions d’extraction dynamiques reçoivent le contexte d’exécution, notamment `source`, `threadId`, `resourceId`, `mainAgent`, `memory` et `requestContext` lorsqu’ils sont disponibles. - `WorkingMemoryExtractor` utilise le pipeline d’extraction normal pour mettre à jour la mémoire de travail au moyen de l’instance `Memory` active. Il utilise l’extraction structurée lorsque la mémoire de travail possède un schéma JSON et ignore la persistance des métadonnées OM, afin de ne pas dupliquer sa charge utile sous les métadonnées extraites OM. - `observationalMemory.observation.manageWorkingMemory` ajoute `WorkingMemoryExtractor`, définit par défaut `workingMemory.agentManaged` sur `false` et `workingMemory.useStateSignals` sur `true` lorsque la mémoire de travail est activée. - Les échecs d’extraction sont signalés dans les données des marqueurs OM et ne suppriment pas les autres valeurs extraites avec succès. ## Exemples ### Mises à jour de la mémoire de travail Utilisez `observationalMemory.observation.manageWorkingMemory` lorsqu’OM doit mettre à jour la mémoire de travail. ```typescript import { Memory } from '@mastra/memory' const memory = new Memory({ options: { workingMemory: { enabled: true, }, observationalMemory: { enabled: true, observation: { manageWorkingMemory: true, }, }, }, }) ``` Définissez `workingMemory.agentManaged: true` si l’Agent principal doit continuer à recevoir le Tool de mémoire de travail et l’injection d’instructions. ### Portée ressource avec seuils personnalisés (expérimental) ```typescript import { Memory } from '@mastra/memory' import { Agent } from '@mastra/core/agent' export const agent = new Agent({ id: 'my-agent', name: 'my-agent', instructions: 'You are a helpful assistant.', model: 'openai/gpt-5-mini', memory: new Memory({ options: { observationalMemory: { model: 'google/gemini-2.5-flash', scope: 'resource', observation: { messageTokens: 20_000, }, reflection: { observationTokens: 60_000, }, }, }, }), }) ``` ### Budget de tokens partagé Lorsque `shareTokenBudget` est activé, le budget total est `observation.messageTokens + reflection.observationTokens` (100 k dans cet exemple). Si les observations utilisent seulement 30 k tokens, les messages peuvent occuper jusqu’à 70 k tokens. Si les messages sont courts, les observations disposent de plus d’espace avant de déclencher la réflexion. ```typescript import { Memory } from '@mastra/memory' import { Agent } from '@mastra/core/agent' export const agent = new Agent({ id: 'my-agent', name: 'my-agent', instructions: 'You are a helpful assistant.', model: 'openai/gpt-5-mini', memory: new Memory({ options: { observationalMemory: { shareTokenBudget: true, observation: { messageTokens: 20_000, bufferTokens: false, // required when using shareTokenBudget (temporary limitation) }, reflection: { observationTokens: 80_000, }, }, }, }), }) ``` ### Modèle personnalisé En transmettant un `model` dans la configuration, vous pouvez utiliser n’importe quel modèle du routeur de modèles Mastra. ```typescript import { Memory } from '@mastra/memory' import { Agent } from '@mastra/core/agent' export const agent = new Agent({ id: 'my-agent', name: 'my-agent', instructions: 'You are a helpful assistant.', model: 'openai/gpt-5.6-sol', memory: new Memory({ options: { observationalMemory: { model: 'openai/gpt-5-mini', }, }, }), }) ``` ### Modèles différents pour chaque Agent ```typescript import { Memory } from '@mastra/memory' import { Agent } from '@mastra/core/agent' export const agent = new Agent({ id: 'my-agent', name: 'my-agent', instructions: 'You are a helpful assistant.', model: 'openai/gpt-5.6-sol', memory: new Memory({ options: { observationalMemory: { observation: { model: 'google/gemini-2.5-flash', }, reflection: { model: 'openai/gpt-5-mini', }, }, }, }), }) ``` ### Instructions personnalisées Personnalisez les éléments sur lesquels l’Observer et le Reflector se concentrent en fournissant des instructions personnalisées : ```typescript import { Memory } from '@mastra/memory' import { Agent } from '@mastra/core/agent' export const agent = new Agent({ id: 'health-assistant', name: 'health-assistant', instructions: 'You are a health and wellness assistant.', model: 'openai/gpt-5.6-sol', memory: new Memory({ options: { observationalMemory: { model: 'google/gemini-2.5-flash', observation: { // Focus observations on health-related preferences and goals instruction: 'Prioritize capturing user health goals, dietary restrictions, exercise preferences, and medical considerations. Avoid capturing general chit-chat.', }, reflection: { // Guide reflection to consolidate health patterns instruction: 'When consolidating, group related health information together. Preserve specific metrics, dates, and medical details.', }, }, }, }), }) ``` ### Mise en mémoire tampon asynchrone La mise en mémoire tampon asynchrone est **activée par défaut**. Elle précalcule les observations en arrière-plan à mesure que la conversation s’allonge : lorsque le seuil `messageTokens` est atteint, les observations mises en mémoire tampon s’activent instantanément sans appel LLM bloquant. Le cycle de vie suit le schéma **mettre en mémoire tampon → activer → supprimer les messages → répéter**. Les appels en arrière-plan de l’Observer s’exécutent aux intervalles `bufferTokens` et produisent chacun un chunk d’observations. Au seuil, les chunks s’activent : les observations passent dans le journal et les messages bruts sont retirés du contexte. Le seuil `blockAfter` force une solution de repli synchrone si la mise en mémoire tampon ne suit plus. Paramètres par défaut : - `observation.bufferTokens: 0.2` : mise en mémoire tampon tous les 20 % de `messageTokens` (par exemple, tous les \~6 k tokens avec un seuil de 30 k) - `observation.bufferActivation: 0.8` : lors de l’activation, supprime suffisamment de messages pour ne conserver que 20 % du seuil - Les observations mises en mémoire tampon incluent des indications de continuation (`suggestedResponse`, `currentTask`) qui survivent à l’activation afin de préserver la continuité de la conversation - `reflection.bufferActivation: 0.5` : démarre la réflexion en arrière-plan à 50 % du seuil d’observation Pour personnaliser ces paramètres : ```typescript import { Memory } from '@mastra/memory' import { Agent } from '@mastra/core/agent' export const agent = new Agent({ id: 'my-agent', name: 'my-agent', instructions: 'You are a helpful assistant.', model: 'openai/gpt-5-mini', memory: new Memory({ options: { observationalMemory: { model: 'google/gemini-2.5-flash', observation: { messageTokens: 30_000, // Buffer every 5k tokens (runs in background) bufferTokens: 5_000, // Activate to retain 30% of threshold bufferActivation: 0.7, // Force synchronous observation at 1.5x threshold blockAfter: 1.5, }, reflection: { observationTokens: 60_000, // Start background reflection at 50% of threshold bufferActivation: 0.5, // Force synchronous reflection at 1.2x threshold blockAfter: 1.2, }, }, }, }), }) ``` Pour désactiver entièrement la mise en mémoire tampon asynchrone : ```typescript observationalMemory: { model: "google/gemini-2.5-flash", observation: { bufferTokens: false, }, } ``` Définir `bufferTokens: false` désactive la mise en mémoire tampon asynchrone de l’observation et de la réflexion. Les observations et réflexions s’exécutent de manière synchrone lorsque leurs seuils sont atteints. > **Remarque:** La mise en mémoire tampon asynchrone n’est pas prise en charge avec `scope: 'resource'` et est automatiquement désactivée dans la portée ressource. ## Parties de données du streaming Observational Memory émet des parties de données typées pendant l’exécution de l’Agent, que les clients peuvent utiliser pour fournir un retour en temps réel dans l’interface utilisateur. Elles sont diffusées avec la réponse de l’Agent. ### Lecture des résultats des extracteurs Les deux événements de fin transportent la sortie des extracteurs dans leur charge utile `data`. Les champs des extracteurs sont les suivants : ```typescript interface DataOmObservationEndPart { type: 'data-om-observation-end' data: { /** Whether the completed work was an observation or reflection */ operationType: 'observation' | 'reflection' /** Values extracted during this OM operation, keyed by extractor slug */ extractedValues?: Record /** Extractor failures from this OM operation. Successful extractor values are still included */ extractionFailures?: Array<{ slug: string; error: string }> // ...other fields documented in the tables below } } ``` Les deux champs d’extracteur sont facultatifs. Un événement de fin peut inclure des valeurs, des échecs, les deux ou aucun. `data-om-observation-end` signale une fin synchrone. `data-om-buffering-end` signale la fin d’un travail en arrière-plan dont le contenu mis en mémoire tampon attend encore son activation, bien que les métadonnées d’extraction soient déjà persistées. `DataOmBufferingEndPart` contient les mêmes champs d’extracteur, et les deux types sont exportés depuis `@mastra/memory/processors`. Consultez [Lire les valeurs extraites depuis un flux](https://mastra.zisheng.pro/fr/docs/memory/observational-memory) pour découvrir un exemple de consommation. ### `data-om-status` Émis une fois par étape de la boucle de l’Agent, avant la génération du modèle. Fournit un instantané de l’état actuel de la mémoire, notamment l’utilisation des tokens dans les deux fenêtres de contexte et l’état du contenu mis en mémoire tampon de manière asynchrone. ```typescript interface DataOmStatusPart { type: 'data-om-status' data: { windows: { active: { /** Unobserved message tokens and the threshold that triggers observation */ messages: { tokens: number; threshold: number } /** Observation tokens and the threshold that triggers reflection */ observations: { tokens: number; threshold: number } } buffered: { observations: { /** Number of buffered chunks staged for activation */ chunks: number /** Total message tokens across all buffered chunks */ messageTokens: number /** Projected message tokens that would be removed if activation happened now (based on bufferActivation ratio and chunk boundaries) */ projectedMessageRemoval: number /** Observation tokens that will be added on activation */ observationTokens: number /** idle: no buffering in progress. running: background observer is working. complete: chunks are ready for activation. */ status: 'idle' | 'running' | 'complete' } reflection: { /** Observation tokens that were fed into the reflector (pre-compression size) */ inputObservationTokens: number /** Observation tokens the reflection will produce on activation (post-compression size) */ observationTokens: number /** idle: no reflection buffered. running: background reflector is working. complete: reflection is ready for activation. */ status: 'idle' | 'running' | 'complete' } } } recordId: string threadId: string stepNumber: number /** Increments each time the Reflector creates a new generation */ generationCount: number } } ``` `buffered.reflection.inputObservationTokens` correspond à la taille des observations envoyées au Reflector. `buffered.reflection.observationTokens` correspond au résultat compressé : la taille du contenu qui remplacera ces observations lors de l’activation de la réflexion. Un client peut utiliser ces deux valeurs pour afficher un taux de compression. Les clients peuvent calculer des pourcentages et des estimations après activation à partir des valeurs brutes : ```typescript // Message window usage % const msgPercent = status.windows.active.messages.tokens / status.windows.active.messages.threshold // Observation window usage % const obsPercent = status.windows.active.observations.tokens / status.windows.active.observations.threshold // Projected message tokens after buffered observations activate // Uses projectedMessageRemoval which accounts for bufferActivation ratio and chunk boundaries const postActivation = status.windows.active.messages.tokens - status.windows.buffered.observations.projectedMessageRemoval // Reflection compression ratio (when buffered reflection exists) const { inputObservationTokens, observationTokens } = status.windows.buffered.reflection if (inputObservationTokens > 0) { const compressionRatio = observationTokens / inputObservationTokens } ``` ### `data-om-observation-start` Émis lorsque l’Agent Observer ou Reflector commence le traitement. **cycleId** (`string`): ID unique de ce cycle, partagé entre les marqueurs de début, de fin et d’échec. **operationType** (`'observation' | 'reflection'`): Indique s’il s’agit d’une opération d’observation ou de réflexion. **startedAt** (`string`): Horodatage ISO du début du traitement. **tokensToObserve** (`number`): Tokens de message (entrée) traités dans ce lot. **recordId** (`string`): ID de l’enregistrement OM. **threadId** (`string`): ID de ce thread. **threadIds** (`string[]`): Tous les ID de thread de ce lot (pour la portée ressource). **config** (`ObservationMarkerConfig`): Instantané de messageTokens, observationTokens et scope au moment de l’observation. ### `data-om-observation-end` Émis lorsque l’observation ou la réflexion se termine avec succès. **cycleId** (`string`): Correspond au marqueur start associé. **operationType** (`'observation' | 'reflection'`): Type de l’opération terminée. **completedAt** (`string`): Horodatage ISO de la fin du traitement. **durationMs** (`number`): Durée en millisecondes. **tokensObserved** (`number`): Tokens de message (entrée) traités. **observationTokens** (`number`): Tokens d’observation obtenus (sortie) après leur compression par l’Observer. **observations** (`string`): Texte des observations générées. **currentTask** (`string`): Tâche actuelle extraite par l’Observer. **suggestedResponse** (`string`): Réponse suggérée extraite par l’Observer. **extractedValues** (`Record`): Valeurs extraites pendant cette opération OM, indexées par slug d’extracteur. **extractionFailures** (`Array<{ slug: string; error: string }>`): Échecs des extracteurs pendant cette opération OM. Les valeurs extraites avec succès restent incluses. **recordId** (`string`): ID de l’enregistrement OM. **threadId** (`string`): ID de ce thread. ### `data-om-observation-failed` Émis lorsque l’observation ou la réflexion échoue. Le système revient au traitement synchrone. **cycleId** (`string`): Correspond au marqueur start associé. **operationType** (`'observation' | 'reflection'`): Type de l’opération ayant échoué. **failedAt** (`string`): Horodatage ISO de l’échec. **durationMs** (`number`): Durée avant l’échec, en millisecondes. **tokensAttempted** (`number`): Tokens de message (entrée) dont le traitement a été tenté. **error** (`string`): Message d’erreur. **observations** (`string`): Tout contenu partiel disponible pour l’affichage. **recordId** (`string`): ID de l’enregistrement OM. **threadId** (`string`): ID de ce thread. ### `data-om-buffering-start` Émis lorsque la mise en mémoire tampon asynchrone démarre en arrière-plan. Elle précalcule les observations ou réflexions avant que le seuil principal ne soit atteint. **cycleId** (`string`): ID unique de ce cycle de mise en mémoire tampon. **operationType** (`'observation' | 'reflection'`): Type de l’opération mise en mémoire tampon. **startedAt** (`string`): Horodatage ISO du début de la mise en mémoire tampon. **tokensToBuffer** (`number`): Tokens de message (entrée) mis en mémoire tampon pendant ce cycle. **recordId** (`string`): ID de l’enregistrement OM. **threadId** (`string`): ID de ce thread. **threadIds** (`string[]`): Tous les ID de thread mis en mémoire tampon (pour la portée ressource). **config** (`ObservationMarkerConfig`): Instantané de la configuration au moment de la mise en mémoire tampon. ### `data-om-buffering-end` Émis lorsque la mise en mémoire tampon asynchrone se termine. Le contenu est stocké, mais pas encore activé dans le contexte principal. **cycleId** (`string`): Correspond au marqueur buffering-start associé. **operationType** (`'observation' | 'reflection'`): Type de l’opération mise en mémoire tampon. **completedAt** (`string`): Horodatage ISO de la fin de la mise en mémoire tampon. **durationMs** (`number`): Durée en millisecondes. **tokensBuffered** (`number`): Tokens de message (entrée) mis en mémoire tampon. **bufferedTokens** (`number`): Tokens d’observation (sortie) après leur compression par l’Observer. **observations** (`string`): Contenu mis en mémoire tampon. **extractedValues** (`Record`): Valeurs extraites pendant cette opération OM mise en mémoire tampon, indexées par slug d’extracteur. **extractionFailures** (`Array<{ slug: string; error: string }>`): Échecs des extracteurs pendant cette opération OM mise en mémoire tampon. Les valeurs extraites avec succès restent incluses. **recordId** (`string`): ID de l’enregistrement OM. **threadId** (`string`): ID de ce thread. ### `data-om-buffering-failed` Émis lorsque la mise en mémoire tampon asynchrone échoue. Le système revient au traitement synchrone lorsque le seuil est atteint. **cycleId** (`string`): Correspond au marqueur buffering-start associé. **operationType** (`'observation' | 'reflection'`): Type de l’opération ayant échoué. **failedAt** (`string`): Horodatage ISO de l’échec. **durationMs** (`number`): Durée avant l’échec, en millisecondes. **tokensAttempted** (`number`): Tokens de message (entrée) dont la mise en mémoire tampon a été tentée. **error** (`string`): Message d’erreur. **observations** (`string`): Tout contenu partiel. **recordId** (`string`): ID de l’enregistrement OM. **threadId** (`string`): ID de ce thread. ### `data-om-activation` Émis lorsque les observations ou réflexions mises en mémoire tampon sont activées (déplacées dans la fenêtre de contexte active). Cette opération est instantanée : elle n’implique aucun appel LLM. **cycleId** (`string`): ID unique de cet événement d’activation. **operationType** (`'observation' | 'reflection'`): Type du contenu activé. **activatedAt** (`string`): Horodatage ISO de l’activation. **chunksActivated** (`number`): Nombre de chunks mis en mémoire tampon et activés. **tokensActivated** (`number`): Tokens de message (entrée) provenant des chunks activés. Lors de l’activation d’une observation, ils sont retirés de la fenêtre de messages. Lors de l’activation d’une réflexion, il s’agit des tokens d’observation qui ont été compressés. **observationTokens** (`number`): Tokens d’observation obtenus après l’activation. **messagesActivated** (`number`): Nombre de messages observés au moyen de l’activation. **generationCount** (`number`): Nombre actuel de générations de réflexion. **observations** (`string`): Texte des observations activées. **triggeredBy** (`'threshold' | 'ttl' | 'provider_change'`): Indique si l’activation a été déclenchée par le franchissement du seuil, l’expiration d’activateAfterIdle ou un changement de modèle/Provider. **lastActivityAt** (`number`): Horodatage Unix en millisecondes de la dernière partie de message de l’assistant utilisée pour les vérifications de durée de vie. **ttlExpiredMs** (`number`): Durée de dépassement d’activateAfterIdle au moment du déclenchement de l’activation. **previousModel** (`string`): Identifiant du modèle précédent de l’assistant ayant déclenché l’activation, par exemple openai/gpt-4o. **currentModel** (`string`): Identifiant du modèle actuel de l’acteur ayant déclenché l’activation. **recordId** (`string`): ID de l’enregistrement OM. **threadId** (`string`): ID de ce thread. **config** (`ObservationMarkerConfig`): Instantané de la configuration au moment de l’activation. ### `data-om-thread-update` Émis lorsque l’Observer met à jour le titre du thread. Uniquement émis lorsque `observation.threadTitle` est activé. **cycleId** (`string`): ID unique de ce cycle d’observation, partagé avec les marqueurs d’observation. **threadId** (`string`): ID du thread mis à jour. **oldTitle** (`string`): Titre précédent du thread. Vaut undefined si le thread n’avait aucun titre. **newTitle** (`string`): Nouveau titre du thread. **timestamp** (`string`): Moment où cette mise à jour a eu lieu. ## Utilisation autonome La plupart des utilisateurs doivent employer la classe `Memory` présentée ci-dessus. L’utilisation directe d’`ObservationalMemory` est surtout utile pour les benchmarks, l’expérimentation ou lorsque vous devez contrôler l’ordre des processeurs avec d’autres processeurs, tels que les [garde-fous](https://mastra.zisheng.pro/fr/docs/agents/guardrails). La classe `ObservationalMemory` constitue le moteur. Pour l’associer à un Agent, encapsulez-la dans un `ObservationalMemoryProcessor`, qui nécessite une instance `Memory` pour charger et persister les messages. Notez que `stores.memory` est typé comme facultatif sur les adaptateurs de stockage ; une assertion non nulle (ou une vérification à l’exécution) est donc nécessaire : ```typescript import { ObservationalMemory, ObservationalMemoryProcessor } from '@mastra/memory/processors' import { Memory } from '@mastra/memory' import { Agent } from '@mastra/core/agent' import { LibSQLStore } from '@mastra/libsql' const storage = new LibSQLStore({ id: 'my-storage', url: 'file:./memory.db', }) const memory = new Memory({ storage }) const om = new ObservationalMemory({ storage: storage.stores.memory!, memory, model: 'google/gemini-2.5-flash', scope: 'resource', observation: { messageTokens: 20_000, }, reflection: { observationTokens: 60_000, }, }) const omProcessor = new ObservationalMemoryProcessor(om, memory) export const agent = new Agent({ id: 'my-agent', name: 'my-agent', instructions: 'You are a helpful assistant.', model: 'openai/gpt-5-mini', inputProcessors: [omProcessor], outputProcessors: [omProcessor], }) ``` ### Configuration autonome La classe `ObservationalMemory` autonome accepte les mêmes options que l’objet de configuration `observationalMemory` ci-dessus, auxquelles s’ajoutent les suivantes : **storage** (`MemoryStorage`): Adaptateur de stockage servant à persister les observations. Doit être une instance MemoryStorage (issue de MastraStorage.stores.memory). **onDebugEvent** (`(event: ObservationDebugEvent) => void`): Callback de débogage des événements d’observation. Appelé chaque fois qu’un événement lié à l’observation se produit. Utile pour déboguer et comprendre le flux d’observation. **obscureThreadIds** (`boolean`): Lorsque cette option est activée, les ID de thread sont hachés avant leur inclusion dans le contexte d’observation. Cela empêche le LLM de reconnaître des motifs dans les identifiants de thread. Activé automatiquement lors de l’utilisation de la portée ressource par l’intermédiaire de la classe Memory. (Default: `false`) ## Tool de rappel Lorsque `retrieval` est défini sur une valeur vraie, un Tool `recall` est enregistré afin que l’Agent puisse parcourir les messages bruts à l’origine des plages de groupes d’observations. Par défaut (portée `'resource'`), le Tool permet de répertorier les threads (`mode: "threads"`), de parcourir d’autres threads (`threadId`) et d’effectuer une recherche interthreads. Avec `retrieval: { vector: true }`, la recherche sémantique est disponible (`mode: "search"`). Définissez `scope: 'thread'` pour limiter le Tool au thread actuel. Le Tool est automatiquement ajouté à la liste des Tools de l’Agent. Mastra injecte également dans le contexte de l’Agent des instructions d’utilisation adaptées à la portée. Pour la portée ressource avec `vector: true`, elles couvrent le routage entre `search`, `threads` et `messages`, y compris le repli vers la découverte des threads lorsque les résultats de recherche ne conviennent pas. Sans `vector: true`, les instructions couvrent uniquement la navigation dans `threads` et `messages`, afin de ne pas orienter l’Agent vers un mode de recherche non configuré. Les instructions de portée ressource sont injectées avant même l’existence d’un groupe d’observations ; l’Agent peut donc parcourir d’autres threads dès le premier message. Utilisez `retrieval: { instructions: '...' }` pour ajouter des consignes propres à l’application après les instructions intégrées. ### Paramètres **mode** (`'messages' | 'threads' | 'search'`): Éléments à récupérer. "messages" (valeur par défaut) parcourt l’historique des messages. "threads" répertorie tous les threads de l’utilisateur actuel. "search" recherche des messages par similarité sémantique dans tous les threads (nécessite un stockage vectoriel et un Embedder). (Default: `'messages'`) **query** (`string`): Requête de recherche pour mode: "search". Recherche dans tous les threads de l’utilisateur actuel les messages sémantiquement similaires à ce texte. **cursor** (`string`): ID de message servant à ancrer la requête de rappel. Extrayez l’ID de début ou de fin d’une plage de groupe d’observations (par exemple, depuis \_range: \startId:endId\\\_, utilisez startId ou endId). Si une chaîne de plage est transmise directement, le Tool renvoie une indication expliquant comment extraire l’ID correct. Lorsque cursor et threadId sont tous deux omis pour mode: "messages", le Tool parcourt le thread actuel depuis la position définie par anchor. **threadId** (`string`): Parcourt un autre thread à partir de son ID, ou transmettez "current" pour le thread actif. Utilisez d’abord mode: "threads" pour découvrir les ID de thread. Lorsque cette option est fournie sans cursor, la lecture commence au début du thread. **anchor** (`'start' | 'end'`): Pour mode: "messages" sans cursor, parcourt le thread depuis le début (plus ancien en premier) ou la fin (plus récent en premier). (Default: `'start'`) **page** (`number`): Décalage de pagination. Pour les messages : les valeurs positives avancent depuis le curseur, les valeurs négatives reculent. Pour les threads : numéro de page (indexé à partir de 0). Pour les messages, 0 est traité comme 1. (Default: `1`) **limit** (`number`): Nombre maximal d’éléments à renvoyer par page. (Default: `20`) **detail** (`'low' | 'high'`): Contrôle la quantité de contenu affichée pour chaque partie de message. 'low' affiche le texte tronqué et les noms des Tools avec des index de position (\[p0], \[p1]). 'high' affiche le contenu complet, notamment les arguments et résultats des Tools, limité à une partie par appel avec des indications de continuation. (Default: `'low'`) **partType** (`'text' | 'tool-call' | 'tool-result' | 'reasoning' | 'image' | 'file'`): Filtre les résultats pour inclure uniquement les parties de message de ce type. S’applique uniquement à mode: "messages". **toolName** (`string`): Filtre les résultats pour inclure uniquement les parties d’appel et de résultat de Tool correspondant à ce nom de Tool. S’applique uniquement à mode: "messages". **partIndex** (`number`): Récupère une seule partie de message avec tous ses détails à partir de son index de position. Utilisez cette option lorsqu’un rappel peu détaillé affiche une partie intéressante à \[p1] ; effectuez un nouvel appel avec partIndex: 1 pour consulter le contenu complet sans charger toutes les parties. **before** (`string`): Uniquement pour mode: "threads". Filtre les threads créés avant cette date. Accepte le format ISO 8601, par exemple "2026-03-15" ou "2026-03-10T00:00:00Z". **after** (`string`): Uniquement pour mode: "threads". Filtre les threads créés après cette date. Accepte le format ISO 8601, par exemple "2026-03-01" ou "2026-03-10T00:00:00Z". ### Valeur renvoyée (mode messages) **messages** (`string`): Contenu formaté des messages. Le format dépend du niveau detail. **count** (`number`): Nombre de messages sur cette page. **cursor** (`string`): ID du message curseur utilisé pour cette requête. **page** (`number`): Numéro de la page renvoyée. **limit** (`number`): Limite utilisée pour cette requête. **detail** (`'low' | 'high'`): Niveau de détail utilisé pour cette requête. **hasNextPage** (`boolean`): Indique si d’autres messages existent après cette page. **hasPrevPage** (`boolean`): Indique si d’autres messages existent avant cette page. **truncated** (`boolean`): Présent et défini sur true lorsque la sortie a été limitée par le budget de tokens. L’Agent peut paginer ou utiliser partIndex pour accéder au contenu restant. **tokenOffset** (`number`): Nombre approximatif de tokens supprimés lorsque truncated vaut true. ### Valeur renvoyée (mode threads) **threads** (`string`): Liste formatée des threads. Chaque thread affiche son titre, son ID et ses dates. Le thread actuel est marqué par ← current. **count** (`number`): Nombre de threads renvoyés. **page** (`number`): Numéro de la page renvoyée. **hasMore** (`boolean`): Indique si d’autres threads existent sur la page suivante. ### Valeur renvoyée (mode recherche) **results** (`string`): Résultats de recherche formatés et regroupés par thread. Chaque résultat affiche le titre et l’ID du thread, le score de pertinence, un aperçu du message et un ID de curseur permettant de parcourir ce thread. **count** (`number`): Nombre de messages correspondants trouvés. ### ModelByInputTokens `ModelByInputTokens` sélectionne un modèle en fonction du nombre de tokens d’entrée. Il choisit le modèle associé au plus petit seuil couvrant la taille réelle de l’entrée. #### Constructeur ```typescript new ModelByInputTokens(config) ``` Où `config` est un objet dont les clés `upTo` associent des seuils de tokens (nombres) à des modèles cibles. #### Exemple ```typescript import { ModelByInputTokens } from '@mastra/memory' const selector = new ModelByInputTokens({ upTo: { 10_000: 'google/gemini-2.5-flash', // Fast for small inputs 40_000: 'openai/gpt-5-mini', // Stronger for medium inputs 1_000_000: 'openai/gpt-5.6-sol', // Most capable for large inputs }, }) ``` #### Comportement - Les seuils sont triés en interne ; leur ordre dans l’objet de configuration est donc sans importance. - `inputTokens ≤ smallest threshold` → utilise le modèle de ce seuil - `inputTokens > largest threshold` → `resolve()` lève une erreur. Si cela se produit pendant une exécution OM de l’Observer ou du Reflector, OM abandonne par l’intermédiaire de TripWire ; les appelants reçoivent donc un résultat `text` vide ou un `tripwire` diffusé en continu plutôt qu’une réponse normale de l’assistant. - OM calcule le nombre de tokens d’entrée de l’appel à l’Observer ou au Reflector et résout directement le niveau de modèle correspondant #### Méthodes **resolve** (`(inputTokens: number) => MastraModelConfig`): Renvoie le modèle correspondant au nombre de tokens d’entrée fourni. Lève une erreur si inputTokens dépasse le plus grand seuil configuré. Lorsque cela se produit pendant une exécution OM, les appelants reçoivent un résultat TripWire/texte vide plutôt qu’une réponse normale de l’assistant. **getThresholds** (`() => number[]`): Renvoie les seuils configurés par ordre croissant. Utile pour l’introspection. ### Voir aussi - [Observational Memory](https://mastra.zisheng.pro/fr/docs/memory/observational-memory) - [Présentation de Memory](https://mastra.zisheng.pro/fr/docs/memory/overview) - [Classe Memory](https://mastra.zisheng.pro/fr/reference/memory/memory-class) - [Processeurs de Memory](https://mastra.zisheng.pro/fr/docs/memory/memory-processors) - [Processeurs](https://mastra.zisheng.pro/fr/docs/agents/processors)