Memory.cloneThread()

La méthode .cloneThread() crée une copie d'un fil de discussion existant, avec tous ses messages. Elle permet de créer des parcours de conversation divergents à partir d'un point précis. Lorsque le rappel sémantique est activé, elle crée également des embeddings vectoriels pour les messages clonés.

Exemple d'utilisation

L'exemple suivant crée une instance de Memory et clone un fil de discussion existant.

import { Memory } from '@mastra/memory'
import { LibSQLStore } from '@mastra/libsql'

const memory = new Memory({
  storage: new LibSQLStore({ id: 'memory-store', url: 'file:./memory.db' }),
})

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

Paramètres

sourceThreadId:

string

Identifiant du fil de discussion à cloner

newThreadId?:

string

Identifiant personnalisé facultatif du fil de discussion cloné. S'il n'est pas fourni, un identifiant est généré.

resourceId?:

string

Identifiant de ressource facultatif du fil de discussion cloné. Utilise par défaut le resourceId du fil source.

title?:

string

Titre facultatif du fil de discussion cloné. S'il est omis, le clone utilise Clone of ${sourceThread.title} lorsque le fil source possède un titre. Sinon, le titre est vide.

metadata?:

Record<string, unknown>

Métadonnées facultatives à fusionner avec celles du fil source. Les métadonnées du clone sont ajoutées automatiquement.

options?:

CloneOptions

Options de filtrage facultatives pour l'opération de clonage.

CloneOptions

messageLimit?:

number

Nombre maximal de messages à cloner. Lorsque cette option est définie, les N messages les plus récents sont clonés.

messageFilter?:

MessageFilter

Critères de filtrage permettant de sélectionner les messages à cloner.

MessageFilter

startDate?:

Date

Clone uniquement les messages créés à cette date ou ultérieurement.

endDate?:

Date

Clone uniquement les messages créés à cette date ou antérieurement.

messageIds?:

string[]

Clone uniquement les messages possédant ces identifiants précis.

Valeur renvoyée

thread:

StorageThreadType

Nouveau fil de discussion cloné avec ses métadonnées de clonage.

clonedMessages:

MastraDBMessage[]

Tableau des messages clonés avec les nouveaux identifiants attribués au nouveau fil de discussion.

messageIdMap?:

Record<string, string>

Correspondance entre les identifiants des messages sources et ceux de leurs messages clonés.

Métadonnées du clone

Les métadonnées du fil de discussion cloné comprennent une propriété clone contenant :

sourceThreadId:

string

Identifiant du fil de discussion d'origine qui a été cloné.

clonedAt:

Date

Horodatage de la création du clone.

lastMessageId?:

string

Identifiant du dernier message du fil source au moment du clonage.

Exemple d'utilisation étendu

src/test-clone.ts

import { mastra } from './mastra'

const agent = mastra.getAgent('agent')
const memory = await agent.getMemory()

// Clone a thread with all messages
const { thread: fullClone } = await memory.cloneThread({
  sourceThreadId: 'original-thread-123',
  title: 'Alternative Conversation Path',
})

// Clone with a custom ID
const { thread: customIdClone } = await memory.cloneThread({
  sourceThreadId: 'original-thread-123',
  newThreadId: 'my-custom-clone-id',
})

// Clone only the last 5 messages
const { thread: partialClone, clonedMessages } = await memory.cloneThread({
  sourceThreadId: 'original-thread-123',
  options: {
    messageLimit: 5,
  },
})

// Clone messages from a specific date range
const { thread: dateFilteredClone } = await memory.cloneThread({
  sourceThreadId: 'original-thread-123',
  options: {
    messageFilter: {
      startDate: new Date('2024-01-01'),
      endDate: new Date('2024-01-31'),
    },
  },
})

// Clone specific messages
const { thread: selectedMessagesClone } = await memory.cloneThread({
  sourceThreadId: 'original-thread-123',
  options: {
    messageFilter: {
      messageIds: ['message-1', 'message-2'],
    },
  },
})

// Continue conversation on the cloned thread
const response = await agent.generate('Try a different approach', {
  memory: {
    thread: fullClone.id,
    resource: fullClone.resourceId,
  },
})

Transmettez les valeurs thread.id et thread.resourceId du clone à agent.generate() afin de poursuivre la conversation à partir du fil de discussion cloné.

Embeddings vectoriels

Lorsque le rappel sémantique est activé sur l'instance de Memory avec un stockage vectoriel et un embedder configurés, cloneThread() crée automatiquement des embeddings vectoriels pour tous les messages clonés. Cela garantit le bon fonctionnement de la recherche sémantique dans le fil de discussion cloné.

Dans cet exemple, embeddingModel est le modèle d'embedding configuré pour le projet.

import { Memory } from '@mastra/memory'
import { LibSQLStore, LibSQLVector } from '@mastra/libsql'

const memory = new Memory({
  storage: new LibSQLStore({ id: 'memory-store', url: 'file:./memory.db' }),
  vector: new LibSQLVector({ id: 'vector-store', url: 'file:./vector.db' }),
  embedder: embeddingModel,
  options: {
    semanticRecall: true,
  },
})

// Clone will also create embeddings for cloned messages
const { thread } = await memory.cloneThread({
  sourceThreadId: 'original-thread',
})

// Semantic search works on the cloned thread
const results = await memory.recall({
  threadId: thread.id,
  vectorSearchString: 'search query',
})

Mémoire de travail

Lorsque la mémoire de travail est activée, cloneThread() la copie ou la partage selon sa portée et le resourceId du clone :

• Mémoire de travail limitée au fil de discussion : la mémoire de travail est copiée dans le fil cloné.
• Mémoire de travail limitée à la ressource avec le même resourceId : la mémoire de travail est partagée, car les fils source et cloné appartiennent à la même ressource.
• Mémoire de travail limitée à la ressource avec un resourceId différent : la mémoire de travail est copiée dans la ressource du fil cloné.

Observational Memory

Lorsque Observational Memory est activée, cloneThread() clone automatiquement les enregistrements OM associés au fil source. Le comportement dépend de la portée d'OM :

• OM limitée au fil de discussion : l'enregistrement OM est cloné dans le nouveau fil. Toutes les références internes aux identifiants de messages sont remappées vers les messages clonés.
• OM limitée à la ressource (même resourceId) : l'enregistrement OM est partagé entre les fils source et cloné puisqu'ils appartiennent à la même ressource. Aucune duplication n'a lieu.
• OM limitée à la ressource (resourceId différent) : l'enregistrement OM est cloné dans la nouvelle ressource. Les identifiants des messages sont remappés et toutes les balises identifiant un fil dans les observations sont mises à jour afin de référencer le fil cloné.

Seule la génération OM actuelle (la plus récente) est clonée. Les générations historiques plus anciennes ne sont pas copiées. L'état de traitement transitoire (indicateurs signalant une observation ou une réflexion en cours) est réinitialisé dans l'enregistrement cloné.