# 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

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

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

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