Memory

Memory gives your agent coherence across interactions and allows it to improve over time by retaining relevant information from past conversations.

Mastra requires a storage provider to persist memory and supports three types:

• Message history captures recent messages from the current conversation, providing short-term continuity and maintaining dialogue flow.
• Working memory stores persistent user-specific details such as names, preferences, goals, and other structured data.
• Semantic recall retrieves older messages from past conversations based on semantic relevance. Matches are retrieved using vector search and can include surrounding context for better comprehension.

You can enable any combination of these memory types. Mastra assembles the relevant memories into the model’s context window. If the total exceeds the model's token limit, use memory processors to trim or filter messages before sending them to the model.

Getting started

Install Mastra's memory module and the storage adapter for your preferred database (see the storage section below):

npm

npm install @mastra/memory@latest @mastra/libsql@latest

pnpm

pnpm add @mastra/memory@latest @mastra/libsql@latest

Yarn

yarn add @mastra/memory@latest @mastra/libsql@latest

Bun

bun add @mastra/memory@latest @mastra/libsql@latest

Add the storage adapter to the main Mastra instance:

src/mastra/index.ts

import { Mastra } from "@mastra/core";
import { LibSQLStore } from "@mastra/libsql";

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: ":memory:",
  }),
});

Enable memory by passing a Memory instance to your agent:

src/mastra/agents/test-agent.ts

import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core/agent";

export const testAgent = new Agent({
  id: "test-agent",
  memory: new Memory({
    options: {
      lastMessages: 20,
    },
  }),
});

When you send a new message, the model can now "see" the previous 20 messages, which gives it better context for the conversation and leads to more coherent, accurate replies.

This example configures basic message history. You can also enable working memory and semantic recall by passing additional options to Memory.

Storage

Before enabling memory, you must first configure a storage adapter. Mastra supports multiple database providers including PostgreSQL, MongoDB, libSQL, and more.

Storage can be configured at the instance level (shared across all agents) or at the agent level (dedicated per agent). You can also use different databases for storage and vector operations.

See the Storage documentation for configuration options, supported providers, and examples.

Debugging memory

When tracing is enabled, you can inspect exactly which messages the agent uses for context in each request. The trace output shows all memory included in the agent's context window - both recent message history and messages recalled via semantic recall.

This visibility helps you understand why an agent made specific decisions and verify that memory retrieval is working as expected.

For more details on enabling and configuring tracing, see Tracing.

Next Steps

• Learn more about Storage providers and configuration options
• Add Message History, Working Memory, or Semantic Recall
• Visit Memory configuration reference for all available options