> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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](#threads-and-resources) 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](https://mastra.zisheng.pro/fr/guides/build-your-ui/ai-sdk-ui).

## 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](https://mastra.zisheng.pro/fr/docs/storage/overview) 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**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

```bash
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 :

```typescript
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`](https://mastra.zisheng.pro/fr/reference/memory/memory-class) dans votre agent :

```typescript
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()**:

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

**.stream()**:

```typescript
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()`](https://mastra.zisheng.pro/fr/reference/memory/createThread) et [`saveMessages()`](https://mastra.zisheng.pro/fr/reference/memory/memory-class).

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**](#querying) : 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](https://mastra.zisheng.pro/fr/docs/studio/overview) 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.

```typescript
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`](https://mastra.zisheng.pro/fr/models) plus petit et des `instructions` personnalisées :

```typescript
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 :

```typescript
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()`](https://mastra.zisheng.pro/fr/reference/memory/listThreads) pour récupérer les threads d’une ressource :

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

Parcourez les threads par pages :

```typescript
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 :

```typescript
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()`](https://mastra.zisheng.pro/fr/reference/memory/getThreadById) :

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

### Messages

Une fois que vous disposez d’un thread, utilisez [`recall()`](https://mastra.zisheng.pro/fr/reference/memory/recall) pour récupérer ses messages. Cette fonction prend en charge la pagination, le filtrage par date et la [recherche sémantique](https://mastra.zisheng.pro/fr/docs/memory/semantic-recall).

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

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

Parcourez les messages par pages :

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

Filtrez par plage de dates :

```typescript
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 :

```typescript
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 :

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

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

```typescript
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](https://mastra.zisheng.pro/fr/docs/memory/semantic-recall) pour la configuration) :

```typescript
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`](https://mastra.zisheng.pro/fr/reference/ai-sdk/to-ai-sdk-v5-messages) 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.

```typescript
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()`](https://mastra.zisheng.pro/fr/reference/memory/cloneThread) et les [utilitaires de clonage](https://mastra.zisheng.pro/fr/reference/memory/clone-utilities) pour découvrir l’API complète.

## Suppression de messages

Pour supprimer des messages d’un thread, utilisez [`deleteMessages()`](https://mastra.zisheng.pro/fr/reference/memory/deleteMessages). Vous pouvez les supprimer par identifiant de message ou effacer tous les messages d’un thread.