mastra-ai/mastra · error · Error

Memory instance is required for working memory updates

Error message

Memory instance is required for working memory updates

What it means

The update-working-memory tool reads the Memory instance from the tool execution context. If context.memory is missing, it cannot load or persist working memory, so it throws immediately. Memory is injected automatically when the agent runs inside a Mastra instance or is passed directly to a standalone agent.

Source

Thrown at packages/memory/src/tools/working-memory.ts:205

  return createTool({
    id: 'update-working-memory',
    description,
    inputSchema,
    // Merge semantics depend on the model being able to omit fields it is not updating.
    // Strict structured outputs would force every field into `required`, so the model has to
    // emit placeholder values for untouched sections, which then overwrite stored data.
    ...(usesMergeSemantics ? { strict: false as const } : {}),
    execute: async (inputData, context) => {
      const workingMemoryInput = inputData as { memory: any };
      const threadId = context?.agent?.threadId;
      const resourceId = context?.agent?.resourceId;

      // Memory can be accessed via context.memory (when agent is part of Mastra instance)
      // or context.memory (when agent is standalone with memory passed directly)
      const memory = (context as any)?.memory;

      if (!memory) {
        throw new Error('Memory instance is required for working memory updates');
      }

      const scope = memoryConfig?.workingMemory?.scope || 'resource';
      if (scope === 'thread' && !threadId) {
        throw new Error('Thread ID is required for thread-scoped working memory updates');
      }
      if (scope === 'resource' && !resourceId) {
        throw new Error('Resource ID is required for resource-scoped working memory updates');
      }

      if (threadId) {
        let thread = await memory.getThreadById({ threadId });

        if (!thread) {
          thread = await memory.createThread({
            threadId,
            resourceId,
            memoryConfig,

View on GitHub (pinned to 75dd419e61)

Solutions

Pass `memory` when creating the Agent (new Agent({ name, instructions, model, memory })) or register the agent with a Mastra instance so memory is injected.
When calling the tool's execute() manually, include memory in the context object.
In tests, construct a real Memory instance (with storage) and supply it in the context.

Example fix

// before
const tool = createUpdateWorkingMemoryTool();
await tool.execute({ context: { taskId: 't1' } }); // throws
// after
await tool.execute({ context: { taskId: 't1', memory: myMemoryInstance } });

Defensive patterns

Strategy: type-guard

Validate before calling

if (!context?.memory) {
  throw new Error('Working memory tool requires context.memory');
}

Type guard

function hasMemory(ctx: unknown): ctx is { memory: Memory } {
  return (ctx as any)?.memory != null && typeof (ctx as any).memory.getWorkingMemory === 'function';
}

Try / catch

try {
  await updateWorkingMemoryTool.execute({ context: { taskId, memory } });
} catch (err) {
  if (err instanceof Error && err.message === 'Memory instance is required for working memory updates') {
    throw new Error('Agent misconfigured: attach a Memory instance to the agent or Mastra instance');
  }
  throw err;
}

Prevention

Always pass memory to new Agent(...) or register the agent in a Mastra instance.
When invoking tools manually in tests, inject a real Memory instance into context.
Assert agent.memory is defined at app startup for memory-dependent agents.

When it happens

Trigger: Executing updateWorkingMemoryTool directly (or via a custom runner) with a context object lacking `memory`; agent created without a Mastra instance registration and without memory passed in its config.

Common situations: Unit-testing the tool with a bare context; standalone agent built without the `memory` option; custom orchestration invoking the tool's execute() manually without injecting memory.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/bffcb3e062c237a5. Report an issue: GitHub.