Skip to Content
DocsMemoryWorking Memory

Working Memory

While conversation history and semantic recall help agents remember conversations, working memory allows them to maintain persistent information about users across interactions within a thread.

Think of it as the agent’s active thoughts or scratchpad – the key information they keep available about the user or task. It’s similar to how a person would naturally remember someone’s name, preferences, or important details during a conversation.

This is useful for maintaining ongoing state that’s always relevant and should always be available to the agent.

Quick Start

Here’s a minimal example of setting up an agent with working memory:

import { Agent } from "@mastra/core/agent";
import { Memory } from "@mastra/memory";
import { openai } from "@ai-sdk/openai";
 
// Create agent with working memory enabled
const agent = new Agent({
  name: "PersonalAssistant",
  instructions: "You are a helpful personal assistant.",
  model: openai("gpt-4o"),
  memory: new Memory({
    options: {
      workingMemory: {
        enabled: true,
        use: "tool-call", // Will be the only option in a future breaking change release
      },
    },
  }),
});

How it Works

Working memory is a block of Markdown text that the agent is able to update over time to store continuously relevant information:

Custom Templates

Templates guide the agent on what information to track and update in working memory. While a default template is used if none is provided, you’ll typically want to define a custom template tailored to your agent’s specific use case to ensure it remembers the most relevant information.

Here’s an example of a custom template. In this example the agent will store the users name, location, timezone, etc as soon as the user sends a message containing any of the info:

const memory = new Memory({
  options: {
    workingMemory: {
      enabled: true,
      template: `
# User Profile
 
## Personal Info
 
- Name:
- Location:
- Timezone:
 
## Preferences
 
- Communication Style: [e.g., Formal, Casual]
- Project Goal:
- Key Deadlines:
  - [Deadline 1]: [Date]
  - [Deadline 2]: [Date]
 
## Session State
 
- Last Task Discussed:
- Open Questions:
  - [Question 1]
  - [Question 2]
`,
    },
  },
});

Designing Effective Templates

A well-structured template keeps the information easy for the agent to parse and update. Treat the template as a short form that you want the assistant to keep up to date.

  • Short, focused labels. Avoid paragraphs or very long headings. Keep labels brief (for example ## Personal Info or - Name:) so updates are easy to read and less likely to be truncated.
  • Use consistent casing. Inconsistent capitalization (Timezone: vs timezone:) can cause messy updates. Stick to Title Case or lower case for headings and bullet labels.
  • Keep placeholder text simple. Use hints such as [e.g., Formal] or [Date] to help the LLM fill in the correct spots.
  • Abbreviate very long values. If you only need a short form, include guidance like - Name: [First name or nickname] or - Address (short): rather than the full legal text.
  • Mention update rules in instructions. You can instruct how and when to fill or clear parts of the template directly in the agent’s instructions field.

Alternative Template Styles

Use a shorter single block if you only need a few items:

const basicMemory = new Memory({
  options: {
    workingMemory: {
      enabled: true,
      template: `User Facts:\n- Name:\n- Favorite Color:\n- Current Topic:`,
    },
  },
});

You can also store the key facts in a short paragraph format if you prefer a more narrative style:

const paragraphMemory = new Memory({
  options: {
    workingMemory: {
      enabled: true,
      template: `Important Details:\n\nKeep a short paragraph capturing the user's important facts (name, main goal, current task).`,
    },
  },
});

Example: Multi-step Retention

Below is a simplified view of how the User Profile template updates across a short user conversation:

# User Profile

## Personal Info

- Name:
- Location:
- Timezone:

--- After user says "My name is **Sam** and I'm from **Berlin**" ---

# User Profile
- Name: Sam
- Location: Berlin
- Timezone:

--- After user adds "By the way I'm normally in **CET**" ---

# User Profile
- Name: Sam
- Location: Berlin
- Timezone: CET

The agent can now refer to Sam or Berlin in later responses without requesting the information again because it has been stored in working memory.

If your agent is not properly updating working memory when you expect it to, you can add system instructions on how and when to use this template in your agent’s instructions setting.

Examples

Semantic RecallMemory Processors