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

# 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

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

**options.storage** (`MemoryStorage`): Instance de stockage permettant de récupérer les messages

**options.vector** (`MastraVector`): Stockage vectoriel utilisé pour la recherche sémantique

**options.embedder** (`MastraEmbeddingModel<string>`): Embedder utilisé pour générer les embeddings des requêtes

**options.topK** (`number`): Nombre de messages les plus similaires à récupérer

**options.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

**options.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

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

**options.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

**options.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

```typescript
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](https://mastra.zisheng.pro/fr/docs/agents/guardrails)