API Memory

L'API Memory fournit des méthodes permettant de gérer les fils de conversation et l'historique des messages dans Mastra.

Obtenir tous les fils

Récupérez tous les fils de mémoire d'une ressource donnée :

const threads = await mastraClient.listMemoryThreads({
  resourceId: 'resource-1',
  agentId: 'agent-1', // Optional - can be omitted if storage is configured
})

Lorsque agentId est omis et que le stockage est configuré sur le serveur, les fils sont récupérés directement depuis le stockage. Cela s'avère utile lorsque plusieurs agents partagent les mêmes fils (par exemple, dans les workflows comprenant plusieurs étapes d'agent).

Créer un nouveau fil

Créez un nouveau fil de mémoire :

const thread = await mastraClient.createMemoryThread({
  title: 'New Conversation',
  metadata: { category: 'support' },
  resourceId: 'resource-1',
  agentId: 'agent-1',
})

Travailler avec un fil précis

Obtenez une instance d'un fil de mémoire précis :

const thread = mastraClient.getMemoryThread({ threadId: 'thread-id', agentId: 'agent-id' })

Méthodes des fils

Obtenir les détails d'un fil

Récupérez les détails d'un fil précis :

const details = await thread.get()

Mettre à jour un fil

Mettez à jour les propriétés d'un fil :

const updated = await thread.update({
  title: 'Updated Title',
  metadata: { status: 'resolved' },
  resourceId: 'resource-1',
})

Supprimer un fil

Supprimez un fil et ses messages :

await thread.delete()

Cloner un fil

Créez une copie d'un fil avec tous ses messages :

const { thread: clonedThread, clonedMessages } = await thread.clone()

Clonez-le avec des options :

const { thread: clonedThread, clonedMessages } = await thread.clone({
  newThreadId: 'custom-clone-id',
  title: 'Cloned Conversation',
  metadata: { branch: 'experiment-1' },
  options: {
    messageLimit: 10, // Only clone last 10 messages
  },
})

Clonez-le en filtrant les messages :

const { thread: clonedThread } = await thread.clone({
  options: {
    messageFilter: {
      startDate: new Date('2024-01-01'),
      endDate: new Date('2024-01-31'),
    },
  },
})

La réponse du clonage comprend :

• thread : le nouveau fil cloné, accompagné des métadonnées de clonage
• clonedMessages : tableau des messages clonés avec de nouveaux identifiants

Opérations sur les messages

Enregistrer des messages

Enregistrez des messages dans la mémoire :

const result = await mastraClient.saveMessageToMemory({
  messages: [
    {
      role: 'user',
      content: 'Hello!',
      id: '1',
      threadId: 'thread-1',
      resourceId: 'resource-1',
      createdAt: new Date(),
      format: 2,
    },
  ],
  agentId: 'agent-1',
})

// result.messages contains the saved messages
console.log(result.messages)

Récupérer les messages d'un fil

Obtenez les messages associés à un fil de mémoire :

// Get all messages in the thread (paginated)
const result = await thread.listMessages()
console.log(result.messages) // Array of messages
console.log(result.total) // Total count
console.log(result.hasMore) // Whether more pages exist

// Get messages with pagination
const result = await thread.listMessages({
  page: 0,
  perPage: 20,
})

// Get messages with ordering
const result = await thread.listMessages({
  orderBy: { field: 'createdAt', direction: 'ASC' },
})

// Get messages with shallow metadata filters
const result = await thread.listMessages({
  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. Chaque paire clé-valeur doit correspondre selon une logique AND. null ne correspond qu'aux clés explicitement définies sur null. 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 ou des traits de soulignement. Leur longueur est limitée à 128 caractères. Les clés de prototype réservées telles que __proto__, constructor et prototype ne sont pas autorisées. Les performances dépendent du backend de stockage du serveur, et des filtres de métadonnées arbitraires peuvent nécessiter l'analyse des messages candidats.

Supprimer des messages

Supprimez un ou plusieurs messages d'un fil :

// Delete a single message
const result = await thread.deleteMessages('message-id')

// Delete multiple messages
const result = await thread.deleteMessages(['message-1', 'message-2', 'message-3'])

// Returns: { success: true, message: "Message deleted successfully" }

Mémoire de travail

La mémoire de travail permet aux agents de conserver des informations persistantes sur les utilisateurs d'une interaction à l'autre. Sa portée peut se limiter à un fil précis ou s'étendre à tous les fils d'une ressource (utilisateur).

Obtenir la mémoire de travail

Récupérez la mémoire de travail actuelle d'un fil :

const workingMemory = await mastraClient.getWorkingMemory({
  agentId: 'agent-1',
  threadId: 'thread-1',
  resourceId: 'user-123', // Optional, required for resource-scoped memory
})

La réponse comprend :

• workingMemory : le contenu actuel de la mémoire de travail (chaîne ou null)
• source : indique si la mémoire provient de la portée "thread" ou "resource"
• workingMemoryTemplate : le modèle utilisé pour la mémoire de travail (s'il est configuré)
• threadExists : indique si le fil existe

Mettre à jour la mémoire de travail

Mettez à jour le contenu de la mémoire de travail d'un fil :

await mastraClient.updateWorkingMemory({
  agentId: 'agent-1',
  threadId: 'thread-1',
  workingMemory: `# User Profile
- Name: John Doe
- Location: New York
- Preferences: Prefers formal communication
`,
  resourceId: 'user-123', // Optional, required for resource-scoped memory
})

// Returns: { success: true }

Pour une mémoire de travail dont la portée est une ressource, vous devez fournir le paramètre resourceId. Il permet à la mémoire de persister dans tous les fils de conversation de cet utilisateur.

Obtenir l'état de la mémoire

Vérifiez l'état du système de mémoire :

const status = await mastraClient.getMemoryStatus('agent-id')