@mastra/core/dist/docs/references/reference-processors-working-memory-processor.md

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

# 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

```typescript
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

**options.template** (`WorkingMemoryTemplate`): Template defining the format and structure of working memory

**options.template.format** (`'markdown' | 'json'`): Format of the working memory content

**options.template.content** (`string`): Template content defining the structure of working memory data

**options.scope** (`'thread' | 'resource'`): Scope of working memory. 'thread' scopes to current thread, 'resource' shares across all threads for the resource

**options.useVNext** (`boolean`): Use the next-generation instruction format with improved guidelines

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

**options.templateProvider** (`{ getWorkingMemoryTemplate(args: { memoryConfig?: MemoryConfig }): Promise<WorkingMemoryTemplate | null> }`): Dynamic template provider for runtime template resolution

**options.logger** (`IMastraLogger`): Optional logger instance for structured logging

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

```typescript
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-5.4',
  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

```typescript
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](https://mastra.ai/docs/agents/guardrails)