@mastra/core/dist/processors/memory/semantic-recall.d.ts

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

import type { Processor } from '..';
import { MessageList } from '../../agent/index.js';
import type { IMastraLogger } from '../../logger/index.js';
import type { MastraDBMessage } from '../../memory/index.js';
import type { ObservabilityContext } from '../../observability/index.js';
import type { RequestContext } from '../../request-context/index.js';
import type { MemoryStorage } from '../../storage/index.js';
import type { MastraEmbeddingModel, MastraEmbeddingOptions, MastraVector } from '../../vector/index.js';
export interface SemanticRecallOptions {
    /**
     * Storage instance for retrieving messages
     */
    storage: MemoryStorage;
    /**
     * Vector store for semantic search
     */
    vector: MastraVector;
    /**
     * Embedder for generating query embeddings
     */
    embedder: MastraEmbeddingModel<string>;
    /**
     * Number of most similar messages to retrieve
     * @default 4
     */
    topK?: number;
    /**
     * Number of context messages to include before/after each match
     * Can be a number (same for before/after) or an object with before/after
     * @default 1
     */
    messageRange?: number | {
        before: number;
        after: number;
    };
    /**
     * Scope of semantic search
     * - 'thread': Search within the current thread only
     * - 'resource': Search across all threads for the resource
     * @default 'resource'
     */
    scope?: 'thread' | 'resource';
    /**
     * Minimum similarity score threshold (0-1)
     * Messages below this threshold will be filtered out
     */
    threshold?: number;
    /**
     * Index name for the vector store
     * If not provided, will be auto-generated based on embedder model
     */
    indexName?: string;
    /**
     * Optional logger instance for structured logging
     */
    logger?: IMastraLogger;
    /**
     * Options to pass to the embedder when generating embeddings.
     * Use this to pass provider-specific options like outputDimensionality for Google models.
     *
     * @example
     * ```typescript
     * embedderOptions: {
     *   providerOptions: {
     *     google: {
     *       outputDimensionality: 768,
     *       taskType: 'RETRIEVAL_DOCUMENT'
     *     }
     *   }
     * }
     * ```
     */
    embedderOptions?: MastraEmbeddingOptions;
}
/**
 * SemanticRecall is both an input and output processor that:
 * - On input: performs semantic search on historical messages and adds relevant context
 * - On output: creates embeddings for messages being saved to enable future semantic search
 *
 * It uses vector embeddings to find messages similar to the user's query,
 * then retrieves those messages along with surrounding context.
 *
 * @example
 * ```typescript
 * const processor = new SemanticRecall({
 *   storage: memoryStorage,
 *   vector: vectorStore,
 *   embedder: openaiEmbedder,
 *   topK: 5,
 *   messageRange: 2,
 *   scope: 'resource'
 * });
 *
 * // Use with agent
 * const agent = new Agent({
 *   inputProcessors: [processor],
 *   outputProcessors: [processor]
 * });
 * ```
 */
export declare class SemanticRecall implements Processor {
    readonly id = "semantic-recall";
    readonly name = "SemanticRecall";
    private storage;
    private vector;
    private embedder;
    private topK;
    private messageRange;
    private scope;
    private threshold?;
    private indexName?;
    private logger?;
    private embedderOptions?;
    private hasher;
    private indexValidationCache;
    constructor(options: SemanticRecallOptions);
    processInput(args: {
        messages: MastraDBMessage[];
        messageList: MessageList;
        abort: (reason?: string) => never;
        requestContext?: RequestContext;
    } & Partial<ObservabilityContext>): Promise<MessageList | MastraDBMessage[]>;
    /**
     * Sort recalled messages into a stable order before formatting so that
     * vector-query result ordering (which depends on similarity scores and can
     * vary between runs for equivalent results) doesn't change the rendered
     * prompt. Ordering: createdAt, then threadId, then role (user → assistant →
     * tool → system), then id. Uses plain string comparison (ASCII identifiers)
     * to stay locale-independent across CI/dev machines.
     */
    private sortMessagesForRecall;
    /**
     * Format cross-thread messages as a system message with timestamps and labels
     * Uses the exact formatting logic from main that was tested with longmemeval benchmark
     */
    private formatCrossThreadMessages;
    /**
     * Extract the user query from messages for semantic search
     */
    private extractUserQuery;
    /**
     * Perform semantic search using vector embeddings
     */
    private performSemanticSearch;
    /**
     * Generate embeddings for message content
     */
    /**
     * Hash content using xxhash for fast cache key generation
     * Includes index name to ensure cache isolation between different embedding models/dimensions
     */
    private hashContent;
    private embedMessageContent;
    /**
     * Get default index name based on embedder model
     */
    private getDefaultIndexName;
    /**
     * Ensure vector index exists with correct dimensions
     * Uses in-memory cache to avoid redundant validation calls
     */
    private ensureVectorIndex;
    /**
     * Process output messages to create embeddings for messages being saved
     * This allows semantic recall to index new messages for future retrieval
     */
    processOutputResult(args: {
        messages: MastraDBMessage[];
        messageList?: MessageList;
        abort: (reason?: string) => never;
        requestContext?: RequestContext;
    } & Partial<ObservabilityContext>): Promise<MessageList | MastraDBMessage[]>;
    /**
     * Extract text content from a MastraDBMessage
     */
    private extractTextContent;
}
//# sourceMappingURL=semantic-recall.d.ts.map