Memory

La configuration de la Memory exige désormais des paramètres explicites, et les paramètres par défaut ont été mis à jour pour améliorer les performances et la prévisibilité.

Modifications

Paramètres par défaut du rappel sémantique et des derniers messages

Les paramètres par défaut ont été remplacés par des valeurs plus adaptées aux usages observés. La valeur par défaut de lastMessages est passée de 40 à 10, semanticRecall est désormais désactivé par défaut, tout comme la génération du titre des threads. Ces modifications améliorent les performances et réduisent les appels inattendus à l’API du LLM.

Pour effectuer la migration, configurez explicitement ces paramètres si vous dépendiez des anciennes valeurs par défaut.

  const memory = new Memory({
    storage,
    vector,
    embedder,
+   options: {
+     lastMessages: 40, // Was default before
+     semanticRecall: {
+       topK: 2,
+       messageRange: 2,
+       scope: 'thread',
+     }, // Was enabled by default before
+     generateTitle: true, // Was enabled by default before
+   },
  });

Portée par défaut de la Memory : de thread à resource

La portée par défaut de la working memory et du rappel sémantique est passée de 'thread' à 'resource'. Cette modification correspond aux cas d’usage courants dans lesquels les applications doivent mémoriser les informations de l’utilisateur entre plusieurs conversations. Lorsque le rappel sémantique est activé, il recherche désormais par défaut dans toutes les conversations de l’utilisateur plutôt que dans le thread actuel.

Pour effectuer la migration, si vous souhaitez conserver l’ancien comportement qui isole la Memory pour chaque thread de conversation, définissez explicitement scope: 'thread'.

  const memory = new Memory({
    storage,
    vector,
    embedder,
    options: {
      workingMemory: {
        enabled: true,
+       scope: 'thread', // Explicitly set to thread-scoped
        template: `# User Profile...`,
      },
      semanticRecall: {
        topK: 3,
+       scope: 'thread', // Explicitly set to thread-scoped
      },
    },
  });

Emplacement de la génération du titre du thread

L’option generateTitle a été déplacée de threads.generateTitle vers le niveau supérieur des options de Memory. Cette modification simplifie l’API en plaçant l’option à l’emplacement qui lui correspond logiquement.

Pour effectuer la migration, déplacez generateTitle de la configuration threads vers le niveau supérieur des options.

  const memory = new Memory({
    storage,
    vector,
    embedder,
    options: {
-     threads: {
-       generateTitle: true,
-     },
+     generateTitle: true,
    },
  });

Optimisation des paramètres par défaut du rappel sémantique

Les paramètres par défaut du rappel sémantique ont été optimisés à partir des recherches sur le RAG. La valeur de topK est passée de 2 à 4, et messageRange est passé de { before: 2, after: 2 } à { before: 1, after: 1 }. Ces modifications améliorent la précision tout en n’augmentant que légèrement le nombre de messages.

Pour effectuer la migration, définissez explicitement ces valeurs si vous dépendiez des anciennes valeurs par défaut.

  const memory = new Memory({
    storage,
    vector,
    embedder,
    options: {
      semanticRecall: {
+       topK: 2, // Was default before
+       messageRange: { before: 2, after: 2 }, // Was default before
      },
    },
  });

Déplacement de memory.readOnly vers memory.options.readOnly

La propriété readOnly a été déplacée du niveau supérieur de l’option de Memory vers options. Cette modification aligne readOnly sur les autres options de configuration de la Memory, telles que lastMessages et semanticRecall.

Pour effectuer la migration, déplacez readOnly du niveau supérieur vers options.

  agent.stream('Hello', {
    memory: {
      thread: threadId,
      resource: resourceId,
-     readOnly: true,
+     options: {
+       readOnly: true,
+     },
    },
  });

Codemod

Vous pouvez utiliser la CLI codemod de Mastra pour mettre votre code à jour automatiquement :

npx @mastra/codemod@latest v1/memory-readonly-to-options .

Memory.query() renommée Memory.recall()

La méthode Memory.query() a été renommée Memory.recall(). La nouvelle méthode renvoie un format plus simple avec { messages: MastraDBMessage[] } au lieu de plusieurs variantes de format. Cette modification décrit mieux l’action de récupération des messages depuis la Memory et simplifie l’API.

Pour effectuer la migration, renommez query() en recall() et mettez à jour le code qui attend l’ancien format de retour.

- const result = await memory.query({ threadId: 'thread-123' });
+ const result = await memory.recall({ threadId: 'thread-123' });
- // result: { messages: CoreMessage[], uiMessages: UIMessageWithMetadata[], messagesV2: MastraMessageV2[] }
+ // result: { messages: MastraDBMessage[] }
+ const messages = result.messages;

Codemod

Vous pouvez utiliser la CLI codemod de Mastra pour mettre votre code à jour automatiquement :

npx @mastra/codemod@latest v1/memory-query-to-recall .

Modification des paramètres de Memory.recall()

La méthode Memory.recall() utilise désormais le format StorageListMessagesInput avec pagination, et le paramètre vectorMessageSearch a été renommé vectorSearchString. Ces modifications alignent l’API de la Memory sur l’API de pagination du stockage et rendent le nommage plus cohérent.

Pour effectuer la migration, mettez à jour le nom de la méthode, les paramètres de requête et le paramètre de recherche vectorielle.

- memory.query({
+ memory.recall({
    threadId: 'thread-123',
-   vectorMessageSearch: 'What did we discuss?',
-   selectBy: { ... },
+   vectorSearchString: 'What did we discuss?',
+   page: 0,
+   perPage: 20,
+   orderBy: 'createdAt',
+   filter: { ... },
+   threadConfig: { semanticRecall: true },
  });

Codemod

Vous pouvez utiliser la CLI codemod de Mastra pour mettre votre code à jour automatiquement :

npx @mastra/codemod@latest v1/memory-vector-search-param .

Type MastraMessageV2 renommé MastraDBMessage

Le type MastraMessageV2 a été renommé MastraDBMessage pour plus de clarté. Ce nouveau nom décrit mieux sa fonction de format de message de base de données.

Pour effectuer la migration, remplacez toutes les occurrences de MastraMessageV2 par MastraDBMessage.

- import { MastraMessageV2 } from '@mastra/core';
- function yourCustomFunction(input: MastraMessageV2) {}
+ import { MastraDBMessage } from '@mastra/core';
+ function yourCustomFunction(input: MastraDBMessage) {}

Codemod

Vous pouvez utiliser la CLI codemod de Mastra pour mettre votre code à jour automatiquement :

npx @mastra/codemod@latest v1/memory-message-v2-type .

Suppressions

Mode text-stream de la working memory

L’option use: "text-stream" de la working memory a été supprimée. Seul le mode tool-call est pris en charge. Cette modification simplifie l’API de la working memory en supprimant le mode de streaming moins fiable.

Pour effectuer la migration, supprimez l’option use: "text-stream". La working memory utilisera par défaut le mode tool-call.

  const memory = new Memory({
    storage,
    vector,
    embedder,
    options: {
      workingMemory: {
        enabled: true,
-       use: 'text-stream',
        template: '...',
      },
    },
  });

Méthode Memory.rememberMessages()

La méthode Memory.rememberMessages() a été supprimée. Elle remplissait la même fonction que query(), désormais recall(), et le regroupement en une seule méthode simplifie l’API.

Pour effectuer la migration, remplacez les appels à rememberMessages() par recall().

- const { messages } = await memory.rememberMessages({
+ const { messages } = await memory.recall({
    threadId,
    resourceId,
  });

Suppression du paramètre format des méthodes de Memory

Le paramètre format a été supprimé de toutes les méthodes de récupération de la Memory. MastraDBMessage est désormais le format de retour par défaut partout. La conversion au format AI SDK a été déplacée vers des fonctions utilitaires dédiées dans @mastra/ai-sdk/ui. Cette modification améliore le tree-shaking en déplaçant le code de conversion propre à l’UI vers un package distinct.

Pour effectuer la migration, supprimez le paramètre format et utilisez les fonctions de conversion pour les formats AI SDK.

- const messages = await memory.getMessages({ threadId, format: 'v2' });
- const uiMessages = await memory.getMessages({ threadId, format: 'ui' });

+ const result = await memory.recall({ threadId });
+ const messages = result.messages; // Always MastraDBMessage[]
+ 
+ // Use conversion functions for AI SDK formats
+ import { toAISdkV5Messages } from '@mastra/ai-sdk/ui';
+ const uiMessages = toAISdkV5Messages(messages);

Type MastraMessageV3

Le type MastraMessageV3 et les méthodes de conversion associées ont été supprimés. Les messages sont désormais convertis directement entre MastraMessageV2, devenu MastraDBMessage, et les formats AI SDK v5. Cette modification simplifie l’architecture en supprimant un format intermédiaire.

Pour effectuer la migration, utilisez directement MastraDBMessage pour le stockage ou les formats de message AI SDK v5.

- import type { MastraMessageV3 } from '@mastra/core/agent';
- const v3Messages = messageList.get.all.v3();

+ // For storage
+ const v2Messages = messageList.get.all.v2();
+ 
+ // For AI SDK v5
+ const uiMessages = messageList.get.all.aiV5.ui();
+ const modelMessages = messageList.get.all.aiV5.model();

Suppression de la configuration processors du constructeur Memory

L’option de configuration processors du constructeur Memory n’est plus prise en charge et lève une erreur. Configurez les Processors au niveau de l’Agent, où leur comportement est limité à l’exécution de l’Agent.

Pour effectuer la migration, déplacez la configuration des Processors de la Memory vers l’Agent en utilisant inputProcessors et/ou outputProcessors.

+ import { TokenLimiter } from '@mastra/core/processors';
+
  const memory = new Memory({
    storage,
    vector,
    embedder,
-   processors: [/* ... */],
  });

  const agent = new Agent({
    id: 'agent',
    memory,
+   inputProcessors: [
+     new TokenLimiter({ limit: 4000 }), // Limits historical messages to fit context window
+   ],
  });

En outre, le chemin d’import @mastra/memory/processors a été supprimé. Importez plutôt les Processors depuis @mastra/core/processors. Consultez le guide de migration des Processors pour plus de détails.

Pour en savoir plus sur l’utilisation des Processors avec les Agents, consultez la documentation des Processors. Pour un exemple complet avec la Memory, consultez la référence de TokenLimiter.