SemanticRecall

SemanticRecall 是一款 混合处理器，可通过向量嵌入对对话历史进行语义搜索。输入时，它会执行语义搜索以查找相关的历史消息。输出时，它会为新消息创建嵌入，以便将来进行语义检索。

🌐 The SemanticRecall is a hybrid processor that enables semantic search over conversation history using vector embeddings. On input, it performs semantic search to find relevant historical messages. On output, it creates embeddings for new messages to enable future semantic retrieval.

使用示例

🌐 Usage example

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",
});

构造函数参数

🌐 Constructor parameters

options:

SemanticRecallOptions

Configuration options for the semantic recall processor

选项

🌐 Options

storage:

MemoryStorage

Storage instance for retrieving messages

vector:

MastraVector

Vector store for semantic search

embedder:

MastraEmbeddingModel<string>

Embedder for generating query embeddings

topK?:

number

Number of most similar messages to retrieve

messageRange?:

number | { before: number; after: number }

Number of context messages to include before/after each match. Can be a single number (same for both) or an object with separate values

scope?:

'thread' | 'resource'

Scope of semantic search. 'thread' searches within the current thread only. 'resource' searches across all threads for the resource

threshold?:

number

Minimum similarity score threshold (0-1). Messages below this threshold are filtered out

indexName?:

string

Index name for the vector store. If not provided, auto-generated based on embedder model

logger?:

IMastraLogger

Optional logger instance for structured logging

返回

🌐 Returns

id:

string

Processor identifier set to 'semantic-recall'

name:

string

Processor display name set to 'SemanticRecall'

processInput:

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

Performs semantic search on historical messages and adds relevant context to the message list

processOutputResult:

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

Creates embeddings for new messages to enable future semantic search

扩展使用示例

🌐 Extended usage example

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({
  name: "semantic-memory-agent",
  instructions: "You are a helpful assistant with semantic memory recall",
  model: "openai:gpt-4o",
  inputProcessors: [
    semanticRecall,
    new MessageHistory({ storage, lastMessages: 50 }),
  ],
  outputProcessors: [
    semanticRecall,
    new MessageHistory({ storage }),
  ],
});

行为

🌐 Behavior

输入处理

🌐 Input processing

1. 从最后一条用户消息中提取用户查询
2. 为查询生成嵌入
3. 执行向量搜索以查找语义相似的消息
4. 检索匹配的消息及其相关上下文（基于 messageRange）
5. scope: 'resource'会将跨线程消息格式化为带有时间戳的系统消息
6. 添加带有 source: 'memory' 标签的已撤回消息

输出处理

🌐 Output processing

1. 从新用户和助手消息中提取文本内容
2. 为每条消息生成嵌入
3. 将嵌入存储在向量存储中，并附带元数据（消息ID、线程ID、资源ID、角色、内容、时间戳）
4. 对嵌入使用LRU缓存以避免重复的API调用

跨线程调用

🌐 Cross-thread recall

当 scope 设置为 'resource' 时，处理器可以回忆来自其他线程的消息。这些跨线程消息会被格式化为带有时间戳和对话标签的系统消息，以提供关于对话发生时间和地点的上下文信息。

🌐 When scope is set to 'resource', the processor can recall messages from other threads. These cross-thread messages are formatted as a system message with timestamps and conversation labels to provide context about when and where the conversation occurred.

相关

🌐 Related

• 护栏