Documentation Index Fetch the complete documentation index at: https://mintlify.com/mastra-ai/mastra/llms.txt
Use this file to discover all available pages before exploring further.
Overview MastraMemory is the abstract base class for implementing conversation memory systems in Mastra. It provides thread-based conversation organization, optional vector database integration for semantic similarity search, and working memory templates for structured conversation state.Type Definition abstract class MastraMemory extends MastraBase { readonly id : string ; MAX_CONTEXT_TOKENS ?: number ; protected _storage ?: MastraCompositeStore ; vector ?: MastraVector ; embedder ?: MastraEmbeddingModel < string >; embedderOptions ?: MastraEmbeddingOptions ; protected threadConfig : MemoryConfig ; }
Constructor constructor ( config : { id? : string ; name : string ; options ?: MemoryConfig ; storage ?: MastraCompositeStore ; vector ?: MastraVector ; embedder ?: EmbeddingModelId | MastraEmbeddingModel < string > ; embedderOptions ?: MastraEmbeddingOptions ; })
Memory configuration Unique identifier for the memory instance. Defaults to name if not provided.
Name of the memory instance
Memory configuration options
Storage provider for persisting memory data
Vector store for semantic recall (required if semanticRecall is enabled)
embedder
EmbeddingModelId | MastraEmbeddingModel
Embedding model for semantic recall (required if semanticRecall is enabled)
Options for the embedding model
Properties Unique identifier for the memory instance
Maximum context tokens to maintain
The storage provider (throws error if accessed before initialization)
Vector store for semantic search
embedder
MastraEmbeddingModel | undefined
Embedding model for generating vectors
embedderOptions
MastraEmbeddingOptions | undefined
Options for the embedding model
Whether this memory instance has its own storage configured
Abstract Methods getThreadById abstract getThreadById ( params : { threadId: string }): Promise < StorageThreadType | null >
Retrieves a specific thread by its ID.
The unique identifier of the thread
The thread or null if not found
listThreads abstract listThreads ( args : StorageListThreadsInput ): Promise < StorageListThreadsOutput >
Lists threads with optional filtering by resourceId and metadata.
args
StorageListThreadsInput
required
Query parameters Optional resource ID to filter by
Optional metadata key-value pairs to filter by (AND logic)
Zero-indexed page number for pagination
perPage
number | false
default: "100"
Number of items per page, or false to fetch all
Optional sorting configuration
Paginated thread results with metadata
saveThread abstract saveThread ( params : { thread: StorageThreadType ; memoryConfig ?: MemoryConfig ; }): Promise < StorageThreadType >
Saves or updates a thread.
thread
StorageThreadType
required
The thread data to save
Optional memory configuration
saveMessages abstract saveMessages ( args : { messages: MastraDBMessage []; memoryConfig ?: MemoryConfig ; }): Promise < { messages : MastraDBMessage []; usage ?: { tokens: number } } >
Saves messages to a thread.
messages
MastraDBMessage[]
required
Array of messages to save
Optional memory configuration
result
{ messages: MastraDBMessage[]; usage?: { tokens: number } }
The saved messages with optional token usage
recall abstract recall ( args : StorageListMessagesInput & { threadConfig? : MemoryConfig ; vectorSearchString ?: string ; }): Promise < { messages : MastraDBMessage []; usage ?: { tokens: number } } >
Retrieves messages for a specific thread with optional semantic recall.
threadId
string | string[]
required
Thread ID(s) to query messages from
Optional resource ID for validation
Optional search string for semantic recall
Optional memory configuration
result
{ messages: MastraDBMessage[]; usage?: { tokens: number } }
Array of messages in mastra-db format with optional token usage
deleteThread abstract deleteThread ( threadId : string ): Promise < void >
Deletes a thread.
The ID of the thread to delete
Public Methods createThread createThread ( params : { resourceId: string ; threadId ?: string ; title ?: string ; metadata ?: Record < string , unknown>; memoryConfig? : MemoryConfig ; saveThread ?: boolean ; }): Promise < StorageThreadType >
Helper method to create a new thread.
Resource ID for the thread
Optional custom thread ID (auto-generated if not provided)
Optional title for the thread
Optional metadata for the thread
Optional memory configuration
Whether to save the thread immediately
getSystemMessage getSystemMessage ( input : { threadId: string ; resourceId ?: string ; memoryConfig ?: MemoryConfig ; }): Promise < string | null >
Get a system message to inject into the conversation. Can be overridden by implementations.
The system message, or null
listTools ( config ?: MemoryConfig ): Record < string , ToolAction >
Get tools that should be available to the agent. Can be overridden by implementations.
tools
Record<string, ToolAction>
Tools provided by this memory instance
setStorage setStorage ( storage : MastraCompositeStore ): void
Sets the storage provider.
storage
MastraCompositeStore
required
The storage provider to use
setVector setVector ( vector : MastraVector ): void
Sets the vector store.
setEmbedder setEmbedder ( embedder : EmbeddingModelId | MastraEmbeddingModel < string > , embedderOptions ?: MastraEmbeddingOptions ): void
Sets the embedding model.
embedder
EmbeddingModelId | MastraEmbeddingModel
required
The embedding model to use
Options for the embedding model
getMergedThreadConfig getMergedThreadConfig ( config ?: MemoryConfig ): MemoryConfig
Merges provided config with instance defaults.
estimateTokens estimateTokens ( text : string ): number
Estimates the number of tokens in a text string.
Example Implementation import { MastraMemory } from '@mastra/core/memory' ; export class MyCustomMemory extends MastraMemory { async getThreadById ({ threadId } : { threadId : string }) { // Implementation return this . storage . getThreadById ( threadId ); } async listThreads ( args : StorageListThreadsInput ) { // Implementation return this . storage . listThreads ( args ); } async saveThread ({ thread , memoryConfig }) { // Implementation return this . storage . saveThread ( thread ); } async saveMessages ({ messages , memoryConfig }) { // Implementation return this . storage . saveMessages ( messages ); } async recall ( args ) { // Implementation with optional semantic recall const messages = await this . storage . listMessages ( args ); if ( args . vectorSearchString && this . vector && this . embedder ) { // Perform semantic search const results = await this . vector . query ({ query: args . vectorSearchString , topK: 5 }); // Merge with chronological messages } return { messages }; } async deleteThread ( threadId : string ) { // Implementation await this . storage . deleteThread ( threadId ); } }