Mastra Memory Overview

Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference

Published: 2026-05-10 · Source: crawler_authoritative

Tình huống

Documentation for Mastra framework developers configuring agent memory to enable conversation persistence, context retention, and multi-turn interaction capabilities.

Insight

Mastra Memory enables agents to remember user messages, agent replies, and tool results across interactions. Three memory types are available: Message History stores raw conversation exchanges; Observational Memory (recommended) uses background agents to compress old messages into dense observations, preserving long-term memory while keeping context windows small; Working Memory stores persistent structured user data like names, preferences, and goals; Semantic Recall retrieves past messages based on semantic meaning. Memory processors can filter, trim, or prioritize content when combined memory exceeds context limits. Storage providers persist all memory data. In multi-agent systems, delegation creates a fresh threadId per call but derives resourceId as {parentResourceId}-{agentName}, allowing subagents to maintain stable resource-scoped memory across delegations. Message history uses scope ‘resource’ (user/entity identifier) and ‘thread’ (conversation session ID). Thread-scoped sharing shares full message history between agents using identical resource and thread IDs. Subagent resource IDs are always suffixed with agent name, preventing cross-subagent resource sharing. Observability via Tracing in Studio shows which messages and observations were included in context.

Hành động

1. Install @mastra/memory@latest using npm/pnpm/yarn/bun. 2. Install a storage provider (e.g., @mastra/libsql@latest) and configure it in the Mastra instance: new Mastra({ storage: new LibSQLStore({ id: ‘mastra-storage’, url: ‘:memory:’ }) }). 3. Create a Memory instance with options (lastMessages: 20, observationalMemory: true) and pass to Agent: new Agent({ memory: new Memory({ options: { lastMessages: 20 } }) }). 4. Track message history by passing resource and thread identifiers to generate() calls: agent.generate(‘message’, { memory: { resource: ‘user-123’, thread: ‘conversation-123’ } }). 5. Access memory via Studio Observability tab to monitor span traces. 6. Switch memory per request using requestContext to conditionally select Memory instances based on request values.

Kết quả

Agents maintain consistent conversation flow, recall user preferences across sessions, and produce better answers over time by retaining context from prior interactions. Observational Memory compresses long conversations into dense observations, preventing context window overflow. Subagents receive fresh message history per delegation but retain resource-scoped memory across calls.

Điều kiện áp dụng

Memory requires a storage provider to persist message history. @mastra/libsql is used for quickstart; other providers available in storage documentation. Observational Memory requires model support for agent delegation.

---

Nội dung gốc (Original)

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.

   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.

   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 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.

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. No flag enables 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 isn’t 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 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.

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
• Mastra Code: A coding agent using Mastra’s memory system

Liên kết

• Nền tảng: Dev Framework · Mastra
• Nguồn: https://mastra.ai/docs/memory/overview

Xem thêm:

• Message history
• Observational Memory
• Semantic recall
• Working Memory - Mastra Agent Persistence
• Memory processors