Memory Class Reference
The Memory class provides a robust system for managing conversation history and thread-based message storage in Mastra. It enables persistent storage of conversations, semantic search capabilities, and efficient message retrieval. By default, it uses LibSQL for storage and vector search, and FastEmbed for embeddings.
Basic Usage
import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core/agent";
const agent = new Agent({
memory: new Memory(),
...otherOptions,
});Custom Configuration
import { Memory } from "@mastra/memory";
import { LibSQLStore } from "@mastra/core/storage/libsql";
import { LibSQLVector } from "@mastra/core/vector/libsql";
import { Agent } from "@mastra/core/agent";
const memory = new Memory({
// Optional storage configuration - libsql will be used by default
storage: new LibSQLStore({
url: "file:memory.db",
}),
// Optional vector database for semantic search - libsql will be used by default
vector: new LibSQLVector({
url: "file:vector.db",
}),
// Memory configuration options
options: {
// Number of recent messages to include
lastMessages: 20,
// Semantic search configuration
semanticRecall: {
topK: 3, // Number of similar messages to retrieve
messageRange: {
// Messages to include around each result
before: 2,
after: 1,
},
},
// Working memory configuration
workingMemory: {
enabled: true,
template: `
# User
- First Name:
- Last Name:
`,
},
},
});
const agent = new Agent({
memory,
...otherOptions,
});Working Memory
The working memory feature allows agents to maintain persistent information across conversations. When enabled, the Memory class will automatically manage working memory updates through either text stream tags or tool calls.
There are two modes for handling working memory updates:
-
text-stream (default): The agent includes working memory updates directly in its responses using XML tags containing Markdown (
<working_memory># User \n ## Preferences...</working_memory>). These tags are automatically processed and stripped from the visible output. -
tool-call: The agent uses a dedicated tool to update working memory. This mode should be used when working with
toDataStream()as text-stream mode is not compatible with data streaming. Additionally, this mode provides more explicit control over memory updates and may be preferred when working with agents that are better at using tools than managing text tags.
Example configuration:
const memory = new Memory({
options: {
workingMemory: {
enabled: true,
template: "# User\n- **First Name**:\n- **Last Name**:",
use: "tool-call", // or 'text-stream'
},
},
});If no template is provided, the Memory class uses a default template that includes fields for user details, preferences, goals, and other contextual information in Markdown format. See the Working Memory guide for detailed usage examples and best practices.
embedder
By default, Memory uses FastEmbed with the bge-small-en-v1.5 model, which provides a good balance of performance and model size (~130MB). You only need to specify an embedder if you want to use a different model or provider.
For environments where local embedding isn’t supported, you can use an API-based embedder:
import { Memory } from "@mastra/memory";
import { openai } from "@ai-sdk/openai";
const agent = new Agent({
memory: new Memory({
embedder: openai.embedding("text-embedding-3-small"), // Adds network request
}),
});Mastra supports many embedding models through the Vercel AI SDK , including options from OpenAI, Google, Mistral, and Cohere.