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

src/mastra/agents/agent.ts

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

= true

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.

model?:

string | LanguageModel | DynamicModel | ModelByInputTokens | ModelWithRetries[]

= 'google/gemini-2.5-flash'

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).

scope?:

'resource' | 'thread'

= '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.

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

= false

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.

shareTokenBudget?:

boolean

= false

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).

temporalMarkers?:

boolean

= false

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.

retrieval?:

boolean | { vector?: boolean; scope?: 'thread' | 'resource'; instructions?: string }

= false

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.

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.

ObservationalMemoryObservationConfig

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.

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.

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.

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.

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.

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.

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.

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.

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.

ObservationalMemoryModelSettings

temperature?:

number

Température de génération. Des valeurs plus faibles produisent une sortie plus cohérente.

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.

providerOptions?:

ProviderOptions

Options propres au Provider transmises à l’Agent Observer, telles que la configuration du raisonnement de Google.

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).

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.

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.

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.

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.

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.

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.

ObservationalMemoryReflectionConfig

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.

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.

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.

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.

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.

ObservationalMemoryModelSettings

temperature?:

number

Température de génération. Des valeurs plus faibles produisent une sortie plus cohérente.

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.

providerOptions?:

ProviderOptions

Options propres au Provider transmises à l’Agent Reflector, telles que la configuration du raisonnement de Google.

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.

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(...).

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(...).

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.

src/mastra/agents/agent.ts

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<T> | (context) => ZodType<T> | 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

= true

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.

metadataKeyPath?:

string | false

= 'extracted.<slug>'

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.

onExtracted?:

(context) => T | void | Promise<T | void>

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.

src/mastra/agents/agent.ts

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)

src/mastra/agents/agent.ts

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.

src/mastra/agents/agent.ts

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.

src/mastra/agents/agent.ts

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

src/mastra/agents/agent.ts

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 :

src/mastra/agents/agent.ts

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 :

src/mastra/agents/agent.ts

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 :

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 :

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<string, unknown>
    /** 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 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.

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 :

// 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<string, unknown>

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<string, unknown>

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.

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 :

src/mastra/agents/agent.ts

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

= false

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.

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'

= 'messages'

É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).

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'

= 'start'

Pour mode: "messages" sans cursor, parcourt le thread depuis le début (plus ancien en premier) ou la fin (plus récent en premier).

page?:

number

= 1

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.

limit?:

number

= 20

Nombre maximal d’éléments à renvoyer par page.

detail?:

'low' | 'high'

= 'low'

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.

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

new ModelByInputTokens(config)

Où config est un objet dont les clés upTo associent des seuils de tokens (nombres) à des modèles cibles.

Exemple

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
• Présentation de Memory
• Classe Memory
• Processeurs de Memory
• Processeurs