What causes "Memory instance is required for recall" in mastra-ai/mastra?

Pass an actual `new Memory({ ... })` (or equivalent Mastra Memory) instance into the tool/function.

Memory instance is required for recall

Error message

Memory instance is required for recall

What it means

The high-detail recall reader validates its `memory` argument structurally: it must exist and expose `getMemoryStore()` (duck-typing a Mastra Memory instance). Throwing here prevents a confusing deep TypeError later when the function tries to hit the storage layer. It indicates the caller wired the om tool without a real Memory instance.

Source

Thrown at packages/memory/src/tools/om-tools.ts:791

  resourceId?: string;
  cursor: string;
  partIndex: number;
  charOffset?: number;
  threadScope?: string;
  maxTokens?: number;
}): Promise<{
  text: string;
  messageId: string;
  partIndex: number;
  role: string;
  type: string;
  truncated: boolean;
  charOffset: number;
  nextCharOffset?: number;
  note?: string;
}> {
  if (!memory || typeof memory.getMemoryStore !== 'function') {
    throw new Error('Memory instance is required for recall');
  }

  if (!threadId) {
    throw new Error('Thread ID is required for recall');
  }

  const resolved = await resolveCursorMessage(memory, cursor, {
    resourceId,
    threadScope,
    enforceThreadScope: false,
  });

  if ('hint' in resolved) {
    throw new Error(resolved.hint);
  }

  const allParts = formatMessageParts(resolved, 'high');

View on GitHub (pinned to 75dd419e61)

Solutions

Pass an actual `new Memory({ ... })` (or equivalent Mastra Memory) instance into the tool/function.
Check the call site for swapped/missing arguments — memory is the first parameter.
Ensure any async Memory construction is awaited before the tool executes.
In tests, provide a Memory stub implementing getMemoryStore() and recall().

Example fix

// before
const tool = createOmRecallTool({ memory: undefined });
// after
import { Memory } from '@mastra/core/memory';
const memory = new Memory({ store: libsqlStore });
const tool = createOmRecallTool({ memory });

Defensive patterns

Strategy: type-guard

Validate before calling

function isRecallMemory(m: unknown): m is RecallMemory {
  return !!m && typeof m === 'object' && typeof (m as any).getMemoryStore === 'function' && typeof (m as any).recall === 'function';
}
if (!isRecallMemory(memory)) throw new TypeError('Pass a Mastra Memory instance to the recall tool.');

Type guard

const isMemory = (m: unknown): m is RecallMemory =>
  !!m && typeof (m as RecallMemory).getMemoryStore === 'function';

Try / catch

try {
  return await recallDetail({ memory, threadId, cursor, partIndex });
} catch (e) {
  if (e instanceof Error && e.message.includes('Memory instance is required')) {
    throw new Error('Tool misconfigured: attach a Memory instance when registering the om recall tool.');
  }
  throw e;
}

Prevention

Construct Memory once at startup and share it via DI/config, not per-call literals.
Typecheck tool factories so the memory parameter cannot be optional.
Await async memory initialization before registering tools.

When it happens

Trigger: Passing null/undefined as memory; passing the wrong object (e.g. a storage adapter, a config object, or an agent) instead of a Memory instance; destructuring/mis-ordered arguments in a custom tool execute; memory created lazily and still undefined at call time.

Common situations: Tool registered before Memory initialization (async setup not awaited); refactoring changed the argument shape; unit test omitted the memory mock; DI container in mastra/ not providing memory to the tool factory.

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/dcf32c4ba3679361. Report an issue: GitHub.