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 { DefaultStorage, DefaultVectorDB } from "@mastra/core/storage";
import { Agent } from "@mastra/core/agent";
 
const memory = new Memory({
  // Custom storage configuration
  storage: new DefaultStorage({
    url: "file:memory.db",
  }),
 
  // Custom vector database for semantic search
  vector: new DefaultVectorDB({
    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></first_name><last_name></last_name></user>",
    },
  },
});
 
const agent = new Agent({
  memory,
  ...otherOptions,
});

Parameters

storage:

MastraStorage

Storage implementation for persisting memory data

vector?:

MastraVector

Vector store for semantic search capabilities

embedder?:

EmbeddingModel

Embedder instance for vector embeddings. Uses FastEmbed (bge-small-en-v1.5) by default

options?:

MemoryConfig

General memory configuration options

options

lastMessages?:

number | false

= 40

Number of most recent messages to retrieve. Set to false to disable.

semanticRecall?:

boolean | SemanticRecallConfig

= false (true if vector store provided)

Enable semantic search in message history. Automatically enabled when vector store is provided.

topK?:

number

= 2

Number of similar messages to retrieve when using semantic search

messageRange?:

number | { before: number; after: number }

= 2

Range of messages to include around semantic search results

workingMemory?:

{ enabled: boolean; template: string }

= { enabled: false, template: '<user><first_name></first_name><last_name></last_name>...</user>' }

Configuration for working memory feature that allows persistent storage of user information across conversations

Working Memory

The working memory feature allows agents to maintain persistent information across conversations. When enabled, the Memory class will automatically manage XML-based working memory updates through the conversation 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. See the Agent 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.

Additional Notes

Vector Search Configuration

When using vector search capabilities with custom configuration, ensure you configure both the vector store and appropriate search options. Here’s an example:

import { Memory } from "@mastra/memory";
import { DefaultStorage, DefaultVectorDB } from "@mastra/core/storage";
 
const memory = new Memory({
  storage: new DefaultStorage({
    url: ":memory:",
  }),
  vector: new DefaultVectorDB({
    url: ":memory:",
  }),
  options: {
    semanticRecall: {
      topK: 5,
      messageRange: 2,
    },
  },
});

mastra build .createThread()