Memory

Memory enables your agent to remember user messages, agent replies, and tool results across interactions, giving it the context it needs to stay consistent, maintain conversation flow, and produce better answers over time.

Mastra agents can be configured to store message history. Additionally, you can enable:

• Observational Memory (Recommended): Uses background agents to maintain a dense observation log that replaces raw message history as it grows. This keeps the context window small while preserving long-term memory.
• Working memory: Stores persistent, structured user data such as names, preferences, and goals.
• Semantic recall: Retrieves relevant past messages based on semantic meaning rather than exact keywords.

If the combined memory exceeds the model's context limit, memory processors can filter, trim, or prioritize content so the most relevant information is preserved.

Memory results will be stored in one or more of your configured storage providers.

When to use memory

Use memory when your agent needs to maintain multi-turn conversations that reference prior exchanges, recall user preferences or facts from earlier in a session, or build context over time within a conversation thread. Skip memory for single-turn requests where each interaction is independent.

Quickstart

1. Install the @mastra/memory package.

   npm

   npm install @mastra/memory@latest

   pnpm

   pnpm add @mastra/memory@latest

   Yarn

   yarn add @mastra/memory@latest

   Bun

   bun add @mastra/memory@latest

2. Memory requires a storage provider to persist message history, including user messages and agent responses.

   For the purposes of this quickstart, use @mastra/libsql.

   npm

   npm install @mastra/libsql@latest

   pnpm

   pnpm add @mastra/libsql@latest

   Yarn

   yarn add @mastra/libsql@latest

   Bun

   bun add @mastra/libsql@latest

   note

   For more details on available providers and how storage works in Mastra, visit the storage documentation.

3. Add the storage provider to your main Mastra instance to enable memory across all configured agents.

   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:',
     }),
   })

4. Create a Memory instance and pass it to the agent's memory option.

   src/mastra/agents/memory-agent.ts

   import { Agent } from '@mastra/core/agent'
   import { Memory } from '@mastra/memory'
   
   export const memoryAgent = new Agent({
     id: 'memory-agent',
     name: 'Memory Agent',
     memory: new Memory({
       options: {
         lastMessages: 20,
       },
     }),
   })

   note

   Visit Memory Class for a full list of configuration options.

5. Call your agent, for example in Mastra Studio. Inside Studio, start a new chat with your agent and take a look at the right sidebar. It'll now display various memory-related information.

Message history

Pass a memory object with resource and thread to track message history.

• resource: A stable identifier for the user or entity.
• thread: An ID that isolates a specific conversation or session.

const response = await memoryAgent.generate('Remember my favorite color is blue.', {
  memory: {
    resource: 'user-123',
    thread: 'conversation-123',
  },
})

To recall information stored in memory, call the agent with the same resource and thread values used in the original conversation.

const response = await memoryAgent.generate("What's my favorite color?", {
  memory: {
    resource: 'user-123',
    thread: 'conversation-123',
  },
})

// Response: "Your favorite color is blue."

warning

Each thread has an owner (resourceId) that can't be changed after creation. Avoid reusing the same thread ID for threads with different owners, as this will cause errors when querying.

To list all threads for a resource, or retrieve a specific thread, use the memory API directly.

Observational Memory

For long-running conversations, raw message history grows until it fills the context window, degrading agent performance. Observational Memory solves this by running background agents that compress old messages into dense observations, keeping the context window small while preserving long-term memory.

src/mastra/agents/memory-agent.ts

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

export const memoryAgent = new Agent({
  id: 'memory-agent',
  name: 'Memory Agent',
  memory: new Memory({
    options: {
      observationalMemory: true,
    },
  }),
})

note

See Observational Memory for details on how observations and reflections work, and the reference for all configuration options.

Memory in multi-agent systems

When a supervisor agent delegates to a subagent, Mastra isolates subagent memory automatically. There is no flag to enable this as it happens on every delegation. Understanding how this scoping works lets you decide what stays private and what to share intentionally.

How delegation scopes memory

Each delegation creates a fresh threadId and a deterministic resourceId for the subagent:

• Thread ID: Unique per delegation. The subagent starts with a clean message history every time it's called.
• Resource ID: Derived as {parentResourceId}-{agentName}. Because the resource ID is stable across delegations, resource-scoped memory persists between calls. A subagent remembers facts from previous delegations by the same user.
• Memory instance: If a subagent has no memory configured, it inherits the supervisor's Memory instance. If the subagent defines its own, that takes precedence.

The supervisor forwards its conversation context to the subagent so it has enough background to complete the task. Only the delegation prompt and the subagent's response are saved — the full parent conversation is not stored. You can control which messages reach the subagent with the messageFilter callback.

note

Subagent resource IDs are always suffixed with the agent name ({parentResourceId}-{agentName}). Two different subagents under the same supervisor never share a resource ID through delegation.

To go beyond this default isolation, you can share memory between agents by passing matching identifiers when you call them directly.

Share memory between agents

When you call agents directly (outside the delegation flow), memory sharing is controlled by two identifiers: resourceId and threadId. Agents that use the same values read and write to the same data. This is useful when agents collaborate on a shared context — for example, a researcher that saves notes and a writer that reads them.

Resource-scoped sharing is the most common pattern. Working memory and semantic recall default to scope: 'resource'. If two agents share a resourceId, they share observations, working memory, and embeddings — even across different threads:

// Both agents share the same resource-scoped memory
await researcher.generate('Find information about quantum computing.', {
  memory: { resource: 'project-42', thread: 'research-session' },
})

await writer.generate('Write a summary from the research notes.', {
  memory: { resource: 'project-42', thread: 'writing-session' },
})

Because both calls use resource: 'project-42', the writer can access the researcher's observations, working memory, and semantic embeddings. Each agent still has its own thread, so message histories stay separate.

Thread-scoped sharing gives tighter coupling. Observational Memory uses scope: 'thread' by default. If two agents use the same resource and thread, they share the full message history. Each agent sees every message the other has written. This is useful when agents need to build on each other's exact outputs.

Observability

Enable Tracing to monitor and debug memory in action. Traces show you exactly which messages and observations the agent included in its context for each request, helping you understand agent behavior and verify that memory retrieval is working as expected.

Open Mastra Studio and select the Observability tab in the sidebar. Open the trace of a recent agent request, then look for spans of LLMs calls.

Switch memory per request

Use RequestContext to access request-specific values. This lets you conditionally select different memory or storage configurations based on the context of the request.

src/mastra/agents/memory-agent.ts

export type UserTier = {
  'user-tier': 'enterprise' | 'pro'
}

const premiumMemory = new Memory()
const standardMemory = new Memory()

export const memoryAgent = new Agent({
  id: 'memory-agent',
  name: 'Memory Agent',
  memory: ({ requestContext }) => {
    const userTier = requestContext.get('user-tier') as UserTier['user-tier']

    return userTier === 'enterprise' ? premiumMemory : standardMemory
  },
})

note

Visit Request Context for more information.

Related

• Memory reference
• Tracing
• Request Context