SemanticRecall

SemanticRecall est un Processor hybride qui permet d’effectuer une recherche sémantique dans l’historique des conversations au moyen d’embeddings vectoriels. En entrée, il lance une recherche sémantique afin de trouver les anciens messages pertinents. En sortie, il crée des embeddings pour les nouveaux messages afin de permettre leur récupération sémantique ultérieure.

Exemple d’utilisation

import { SemanticRecall } from '@mastra/core/processors'
import { openai } from '@ai-sdk/openai'

const processor = new SemanticRecall({
  storage: memoryStorage,
  vector: vectorStore,
  embedder: openai.embedding('text-embedding-3-small'),
  topK: 5,
  messageRange: 2,
  scope: 'resource',
})

Paramètres du constructeur

options:

SemanticRecallOptions

Options de configuration du Processor de rappel sémantique

SemanticRecallOptions

storage:

MemoryStorage

Instance de stockage permettant de récupérer les messages

vector:

MastraVector

Stockage vectoriel utilisé pour la recherche sémantique

embedder:

MastraEmbeddingModel<string>

Embedder utilisé pour générer les embeddings des requêtes

topK?:

number

Nombre de messages les plus similaires à récupérer

messageRange?:

number | { before: number; after: number }

Nombre de messages de contexte à inclure avant et après chaque correspondance. Peut être un nombre unique (identique dans les deux directions) ou un objet contenant des valeurs distinctes

scope?:

'thread' | 'resource'

Portée de la recherche sémantique. 'thread' recherche uniquement dans le fil actuel. 'resource' recherche dans tous les fils de la ressource

threshold?:

number

Seuil minimal du score de similarité (0 à 1). Les messages dont le score est inférieur à ce seuil sont filtrés

indexName?:

string

Nom de l’index du stockage vectoriel. S’il n’est pas fourni, il est généré automatiquement à partir du modèle de l’embedder

logger?:

IMastraLogger

Instance facultative du logger pour des logs structurés

Valeur renvoyée

id:

string

Identifiant du Processor défini sur 'semantic-recall'

name:

string

Nom d’affichage du Processor défini sur 'SemanticRecall'

processInput:

(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; tracingContext?: TracingContext; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>

Effectue une recherche sémantique dans les anciens messages et ajoute le contexte pertinent à la liste des messages

processOutputResult:

(args: { messages: MastraDBMessage[]; messageList?: MessageList; abort: (reason?: string) => never; tracingContext?: TracingContext; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>

Crée des embeddings pour les nouveaux messages afin de permettre de futures recherches sémantiques

Exemple d’utilisation avancée

src/mastra/agents/semantic-memory-agent.ts

import { Agent } from '@mastra/core/agent'
import { SemanticRecall, MessageHistory } from '@mastra/core/processors'
import { PostgresStorage } from '@mastra/pg'
import { PgVector } from '@mastra/pg'
import { openai } from '@ai-sdk/openai'

const storage = new PostgresStorage({
  id: 'pg-storage',
  connectionString: process.env.DATABASE_URL,
})

const vector = new PgVector({
  id: 'pg-vector',
  connectionString: process.env.DATABASE_URL,
})

const semanticRecall = new SemanticRecall({
  storage,
  vector,
  embedder: openai.embedding('text-embedding-3-small'),
  topK: 5,
  messageRange: { before: 2, after: 1 },
  scope: 'resource',
  threshold: 0.7,
})

export const agent = new Agent({
  id: 'semantic-memory-agent',
  name: 'semantic-memory-agent',
  instructions: 'You are a helpful assistant with semantic memory recall',
  model: 'openai/gpt-5.6-sol',
  inputProcessors: [semanticRecall, new MessageHistory({ storage, lastMessages: 50 })],
  outputProcessors: [semanticRecall, new MessageHistory({ storage })],
})

Comportement

Traitement des entrées

1. Extrait la requête de l’utilisateur depuis son dernier message
2. Génère des embeddings pour la requête
3. Effectue une recherche vectorielle afin de trouver des messages sémantiquement similaires
4. Récupère les messages correspondants avec leur contexte environnant (selon messageRange)
5. Pour scope: 'resource', formate les messages provenant d’autres fils comme un message système horodaté
6. Ajoute les messages rappelés avec le tag source: 'memory'

Traitement des sorties

1. Extrait le contenu textuel des nouveaux messages de l’utilisateur et de l’assistant
2. Génère des embeddings pour chaque message
3. Stocke les embeddings dans le stockage vectoriel avec leurs métadonnées (ID du message, ID du fil, ID de la ressource, rôle, contenu et horodatage)
4. Utilise un cache LRU pour les embeddings afin d’éviter les appels redondants à l’API

Rappel entre plusieurs fils

Lorsque scope vaut 'resource', le Processor peut rappeler des messages provenant d’autres fils. Ces messages sont formatés sous forme de message système avec des horodatages et des libellés de conversation, afin de préciser où et quand la conversation a eu lieu.

Voir aussi

• Guardrails