Skip to Content
DocsMemoryOverview

Overview

Memory is how agents manage the context that’s available to them, it’s a condensation of all chat messages into their context window.

The Context Window

The context window is the total information visible to the language model at any given time.

In Mastra, context is broken up into three parts: system instructions and information about the user (working memory), recent messages (message history), and older messages that are relevant to the user’s query (semantic recall).

In addition, we provide memory processors to trim context or remove information if the context is too long.

Quick Start

The fastest way to see memory in action is using the built-in development playground.

If you haven’t already, create a new Mastra project following the main Getting Started guide.

1. Install the memory package:

npm install @mastra/memory

2. Create an agent and attach a Memory instance:

src/mastra/agents/index.ts
import { Agent } from "@mastra/core/agent";
import { Memory } from "@mastra/memory";
import { openai } from "@ai-sdk/openai";
 
export const myMemoryAgent = new Agent({
  name: "MemoryAgent",
  instructions: "...",
  model: openai("gpt-4o"),
 
  memory: new Memory(),
});

3. Start the Development Server:

npm run dev

4. Open the playground (http://localhost:4111 ) and select your MemoryAgent:

Send a few messages and notice that it remembers information across turns:

➡️ You: My favorite color is blue.
⬅️ Agent: Got it! I'll remember that your favorite color is blue.
➡️ You: What is my favorite color?
⬅️ Agent: Your favorite color is blue.

Memory Threads

Mastra organizes memory into threads, which are records that identify specific conversation histories, using two identifiers:

  1. threadId: A specific conversation id (e.g., support_123).
  2. resourceId: The user or entity id that owns each thread (e.g., user_123, org_456).
const response = await myMemoryAgent.stream("Hello, my name is Alice.", {
  resourceId: "user_alice",
  threadId: "conversation_123",
});

Important: without these ID’s your agent will not use memory, even if memory is properly configured. The playground handles this for you, but you need to add ID’s yourself when using memory in your application.

Conversation History

By default, the Memory instance includes the last 40 messages from the current Memory thread in each new request. This provides the agent with immediate conversational context.

const memory = new Memory({
  options: {
    lastMessages: 10,
  },
});

Important: Only send the newest user message in each agent call. Mastra handles retrieving and injecting the necessary history. Sending the full history yourself will cause duplication. See the AI SDK Memory Example for how to handle this with when using the useChat frontend hooks.

Storage Configuration

Conversation history relies on a storage adapter to store messages.

import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core/agent";
import { LibSQLStore } from "@mastra/core/storage/libsql";
 
const agent = new Agent({
  memory: new Memory({
    // this is the default storage db if omitted
    storage: new LibSQLStore({
      config: {
        url: "file:local.db",
      },
    }),
  }),
});

Storage code Examples:

Next Steps

Now that you understand the core concepts, continue to semantic recall to learn how to add RAG memory to your Mastra agents.

Alternatively you can visit the configuration reference for available options, or browse usage examples.

Adding VoiceSemantic Recall