Historique des messages

L’historique des messages est la forme de mémoire la plus élémentaire et la plus importante. Il donne au LLM une vue des messages récents dans la fenêtre de contexte, ce qui permet à votre agent de faire référence aux échanges précédents et de répondre de manière cohérente.

Vous pouvez également récupérer l’historique des messages pour afficher les conversations passées dans votre interface utilisateur.

info

Chaque message appartient à un thread (la conversation) et à une ressource (l’utilisateur ou l’entité qui lui est associée). Consultez Threads et ressources pour en savoir plus.

attention

Lorsque vous utilisez la mémoire avec une application cliente, envoyez depuis le client uniquement le nouveau message, et non l’intégralité de l’historique de la conversation.

Envoyer l’historique complet est superflu, car Mastra charge les messages depuis le stockage. Cela peut également entraîner des erreurs dans l’ordre des messages lorsque les horodatages côté client entrent en conflit avec ceux qui sont stockés.

Pour consulter un exemple avec AI SDK, reportez-vous à Utiliser la mémoire Mastra.

Threads et ressources

Mastra organise les conversations à l’aide de deux identifiants :

• Thread : une session de conversation contenant une séquence de messages.
• Ressource : l’entité propriétaire du thread, par exemple un utilisateur, une organisation, un projet ou une autre entité métier de votre application.

Studio génère automatiquement pour vous un identifiant de thread et un identifiant de ressource. Lorsque vous appelez vous-même stream() ou generate(), fournissez explicitement ces identifiants.

Prise en main

Installez le module de mémoire Mastra ainsi qu’un adaptateur de stockage pour votre base de données. Les exemples ci-dessous utilisent @mastra/libsql, qui stocke les données localement dans un fichier mastra.db.

npm

npm install @mastra/memory@latest @mastra/libsql@latest

pnpm

pnpm add @mastra/memory@latest @mastra/libsql@latest

Yarn

yarn add @mastra/memory@latest @mastra/libsql@latest

Bun

bun add @mastra/memory@latest @mastra/libsql@latest

L’historique des messages nécessite un adaptateur de stockage pour assurer la persistance des conversations. Si ce n’est pas déjà fait, configurez le stockage sur votre instance Mastra :

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
})

Instanciez une instance de Memory dans votre agent :

src/mastra/agents/test-agent.ts

import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'

export const agent = new Agent({
  id: 'test-agent',
  memory: new Memory({
    options: {
      lastMessages: 10,
    },
  }),
})

Lorsque vous appelez l’agent, les messages sont automatiquement enregistrés dans la base de données. Vous pouvez spécifier un threadId, un resourceId et des metadata facultatives :

.generate()

await agent.generate('Hello', {
  memory: {
    thread: {
      id: 'thread-123',
      title: 'Support conversation',
      metadata: { category: 'billing' },
    },
    resource: 'user-456',
  },
})

.stream()

await agent.stream('Hello', {
  memory: {
    thread: {
      id: 'thread-123',
      title: 'Support conversation',
      metadata: { category: 'billing' },
    },
    resource: 'user-456',
  },
})

info

Les threads et les messages sont créés automatiquement lorsque vous appelez agent.generate() ou agent.stream(), mais vous pouvez également les créer manuellement avec createThread() et saveMessages().

Vous pouvez utiliser cet historique de deux façons :

• Inclusion automatique : Mastra récupère et inclut automatiquement les messages récents dans la fenêtre de contexte. Par défaut, il inclut les 10 derniers messages afin que les agents restent ancrés dans la conversation. Vous pouvez ajuster ce nombre avec lastMessages, mais dans la plupart des cas, vous n’avez pas à vous en préoccuper.
• Interrogation manuelle : pour davantage de contrôle, utilisez la fonction recall() afin d’interroger directement les threads et les messages. Vous pouvez ainsi choisir précisément les souvenirs inclus dans la fenêtre de contexte ou récupérer des messages pour afficher l’historique de la conversation dans votre interface utilisateur.

astuce

Lorsque la mémoire est activée, Studio utilise l’historique des messages pour afficher les conversations passées dans la barre latérale du chat.

Génération du titre des threads

Mastra peut générer automatiquement des titres descriptifs pour les threads à partir de la transcription de la conversation lorsque generateTitle est activé. Utilisez cette option lorsque vous créez une interface de chat qui affiche les titres des conversations dans une liste de threads ou une barre latérale.

src/mastra/agents/support-agent.ts

import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'

export const supportAgent = new Agent({
  id: 'support-agent',
  name: 'Support agent',
  instructions: 'Answer customer support questions.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    options: {
      generateTitle: true,
    },
  }),
})

La génération du titre s’exécute de manière asynchrone après la réponse de l’agent et n’a aucune incidence sur le temps de réponse.

Pour optimiser le coût ou le comportement, fournissez un model plus petit et des instructions personnalisées :

src/mastra/agents/support-agent.ts

import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'

export const supportAgent = new Agent({
  id: 'support-agent',
  name: 'Support agent',
  instructions: 'Answer customer support questions.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    options: {
      generateTitle: {
        model: 'openai/gpt-5-mini',
        instructions: 'Generate a one-word title.',
      },
    },
  }),
})

Accéder à la mémoire

Pour accéder aux fonctions de mémoire permettant d’interroger, de cloner ou de supprimer des threads et des messages, appelez getMemory() sur un agent :

const agent = mastra.getAgentById('test-agent')
const memory = await agent.getMemory()

L’instance Memory vous donne accès à des fonctions permettant notamment de répertorier les threads, de rappeler des messages et de cloner des conversations.

Interrogation

Utilisez ces méthodes pour récupérer des threads et des messages afin d’afficher l’historique des conversations dans votre interface utilisateur ou de mettre en œuvre une logique personnalisée de récupération de la mémoire.

attention

Le système de mémoire n’applique aucun contrôle d’accès. Avant d’exécuter une requête, vérifiez dans la logique de votre application que l’utilisateur actuel est autorisé à accéder au resourceId interrogé.

Threads

Utilisez listThreads() pour récupérer les threads d’une ressource :

const result = await memory.listThreads({
  filter: { resourceId: 'user-123' },
  perPage: false,
})

Parcourez les threads par pages :

const result = await memory.listThreads({
  filter: { resourceId: 'user-123' },
  page: 0,
  perPage: 10,
})

console.log(result.threads) // thread objects
console.log(result.hasMore) // more pages available?

Vous pouvez également filtrer selon les métadonnées et contrôler l’ordre de tri :

const result = await memory.listThreads({
  filter: {
    resourceId: 'user-123',
    metadata: { status: 'active' },
  },
  orderBy: { field: 'createdAt', direction: 'DESC' },
})

Pour récupérer un seul thread par son identifiant, utilisez getThreadById() :

const thread = await memory.getThreadById({ threadId: 'thread-123' })

Messages

Une fois que vous disposez d’un thread, utilisez recall() pour récupérer ses messages. Cette fonction prend en charge la pagination, le filtrage par date et la recherche sémantique.

Un rappel simple renvoie tous les messages d’un thread :

const { messages } = await memory.recall({
  threadId: 'thread-123',
  perPage: false,
})

Parcourez les messages par pages :

const { messages } = await memory.recall({
  threadId: 'thread-123',
  page: 0,
  perPage: 50,
})

Filtrez par plage de dates :

const { messages } = await memory.recall({
  threadId: 'thread-123',
  filter: {
    dateRange: {
      start: new Date('2025-01-01'),
      end: new Date('2025-06-01'),
    },
  },
})

Filtrez selon les métadonnées de premier niveau des messages :

const { messages } = await memory.recall({
  threadId: 'thread-123',
  filter: {
    metadata: {
      category: 'billing',
      escalated: true,
      priority: 2,
      archivedAt: null,
    },
  },
})

Les filtres de métadonnées ne correspondent qu’aux valeurs scalaires de premier niveau : string, number fini, boolean et null.

Toutes les clés de métadonnées spécifiées suivent une logique ET. Un filtre null ne correspond qu’à une valeur null explicite. Une clé de métadonnées absente ne produit aucune correspondance.

Les clés de métadonnées doivent commencer par une lettre ou un trait de soulignement et ne contenir que des caractères alphanumériques. Elles ne doivent pas dépasser 128 caractères et ne peuvent pas utiliser de clés de prototype réservées telles que __proto__, constructor ou prototype.

Les performances dépendent du backend de stockage. Certains backends peuvent déléguer une partie du filtre à la base de données, tandis que d’autres analysent les messages candidats après l’application des contraintes de thread, de ressource et de date, mais avant la pagination.

Récupérez un seul message par son identifiant :

const { messages } = await memory.recall({
  threadId: 'thread-123',
  include: [{ id: 'msg-123' }],
})

Récupérez plusieurs messages par leur identifiant avec le contexte environnant :

const { messages } = await memory.recall({
  threadId: 'thread-123',
  include: [
    { id: 'msg-123' },
    {
      id: 'msg-456',
      withPreviousMessages: 3,
      withNextMessages: 1,
    },
  ],
})

Effectuez une recherche par sens (consultez Rappel sémantique pour la configuration) :

const { messages } = await memory.recall({
  threadId: 'thread-123',
  vectorSearchString: 'project deadline discussion',
  threadConfig: {
    semanticRecall: true,
  },
})

Format de l’interface utilisateur

Les requêtes de messages renvoient le format MastraDBMessage[]. Pour afficher les messages dans un frontend, vous devrez peut-être les convertir dans un format attendu par votre bibliothèque d’interface utilisateur. Par exemple, toAISdkV5Messages convertit les messages au format UI d’AI SDK.

Clonage de threads

Le clonage de thread crée une copie d’un thread existant avec ses messages. Cette fonctionnalité permet de créer des branches de conversation ou des points de contrôle avant une opération potentiellement destructive, ou encore de tester des variantes d’une conversation.

const { thread, clonedMessages } = await memory.cloneThread({
  sourceThreadId: 'thread-123',
  title: 'Branched conversation',
})

Vous pouvez filtrer les messages à cloner (par nombre ou par plage de dates), spécifier des identifiants de thread personnalisés et utiliser des méthodes utilitaires pour examiner les relations entre les clones.

Consultez cloneThread() et les utilitaires de clonage pour découvrir l’API complète.

Suppression de messages

Pour supprimer des messages d’un thread, utilisez deleteMessages(). Vous pouvez les supprimer par identifiant de message ou effacer tous les messages d’un thread.