WorkingMemory

The WorkingMemory is an input processor that injects working memory data as a system message. It retrieves persistent information from storage and formats it as instructions for the LLM, enabling the agent to maintain context about users across conversations.

Usage example

import { WorkingMemory } from "@mastra/core/processors";

const processor = new WorkingMemory({
  storage: memoryStorage,
  scope: "resource",
  template: {
    format: "markdown",
    content: `# User Profile
- **Name**:
- **Preferences**:
- **Goals**:
`,
  },
});

Constructor parameters

options:

Options

Configuration options for the working memory processor

Options

storage:

MemoryStorage

Storage instance for retrieving working memory data

template?:

WorkingMemoryTemplate

Template defining the format and structure of working memory

scope?:

'thread' | 'resource'

Scope of working memory. 'thread' scopes to current thread, 'resource' shares across all threads for the resource

useVNext?:

boolean

Use the next-generation instruction format with improved guidelines

readOnly?:

boolean

When true, working memory is provided as read-only context. The data is injected into the conversation but without the updateWorkingMemory tool or update instructions. Useful for agents that should reference working memory without modifying it.

templateProvider?:

{ getWorkingMemoryTemplate(args: { memoryConfig?: MemoryConfig }): Promise<WorkingMemoryTemplate | null> }

Dynamic template provider for runtime template resolution

logger?:

IMastraLogger

Optional logger instance for structured logging

WorkingMemoryTemplate

format:

'markdown' | 'json'

Format of the working memory content

content:

string

Template content defining the structure of working memory data

Returns

id:

string

Processor identifier set to 'working-memory'

name:

string

Processor display name set to 'WorkingMemory'

defaultWorkingMemoryTemplate:

string

The default markdown template used when no custom template is provided

processInput:

(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>

Retrieves working memory and adds it as a system message to the message list

Extended usage example

src/mastra/agents/personalized-agent.ts

import { Agent } from "@mastra/core/agent";
import { WorkingMemory, MessageHistory } from "@mastra/core/processors";
import { PostgresStorage } from "@mastra/pg";

const storage = new PostgresStorage({
  connectionString: process.env.DATABASE_URL,
});

export const agent = new Agent({
  name: "personalized-agent",
  instructions: "You are a helpful assistant that remembers user preferences",
  model: "openai:gpt-4o",
  inputProcessors: [
    new WorkingMemory({
      storage,
      scope: "resource",
      template: {
        format: "markdown",
        content: `# User Information
- **Name**:
- **Location**:
- **Preferences**:
- **Communication Style**:
- **Current Projects**:
`,
      },
    }),
    new MessageHistory({ storage, lastMessages: 50 }),
  ],
  outputProcessors: [
    new MessageHistory({ storage }),
  ],
});

JSON format example

import { WorkingMemory } from "@mastra/core/processors";

const processor = new WorkingMemory({
  storage: memoryStorage,
  scope: "resource",
  template: {
    format: "json",
    content: JSON.stringify({
      user: {
        name: { type: "string" },
        preferences: { type: "object" },
        goals: { type: "array" },
      },
    }),
  },
});

Behavior

Input processing

1. Retrieves threadId and resourceId from the request context
2. Based on scope, fetches working memory from either:
   • Thread metadata (scope: 'thread')
   • Resource record (scope: 'resource')
3. Resolves the template (from provider, options, or default)
4. Generates system instructions based on mode:
   • Normal mode: Includes guidelines for storing/updating information, template structure, and current data
   • Read-only mode (readOnly: true): Includes only the current data as context without update instructions
5. Adds the instruction as a system message with source: 'memory' tag

Working memory updates

Working memory updates happen through the updateWorkingMemory tool provided by the Memory class, not through this processor. The processor only handles injecting the current working memory state into conversations.

Default template

If no template is provided, the processor uses a default markdown template with fields for:

• First Name, Last Name
• Location, Occupation
• Interests, Goals
• Events, Facts, Projects

Related

• Guardrails