> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# Memory.recall()

The `Memory.recall()` method retrieves messages from a specific thread, with support for pagination, filtering options, and semantic search.

## Usage example

```typescript
const { messages } = await memory.recall({
  threadId: 'thread-123',
  perPage: 20,
})
```

## Parameters

**threadId** (`string`): The unique identifier of the thread to retrieve messages from

**resourceId** (`string`): Optional ID of the resource that owns the thread. If provided, validates thread ownership

**vectorSearchString** (`string`): Search string for finding semantically similar messages. Requires semantic recall to be enabled in threadConfig.

**perPage** (`number | false`): Number of messages to retrieve per page. Set to false to fetch all messages without pagination. If not provided, defaults to threadConfig.lastMessages.

**page** (`number`): Zero-based page number for pagination. Used with perPage to retrieve messages in batches.

**include** (`{ id: string; threadId?: string; withPreviousMessages?: number; withNextMessages?: number }[]`): Array of specific message IDs to include with optional context messages. Each item has an id (required), optional threadId (defaults to main threadId), withPreviousMessages (number of messages before, defaults to 2 for vector search, 0 otherwise), and withNextMessages (number of messages after, defaults to 2 for vector search, 0 otherwise).

**filter** (`{ dateRange?: { start?: Date; end?: Date; startExclusive?: boolean; endExclusive?: boolean }; metadata?: Record<string, string | number | boolean | null> }`): Filter options for message retrieval. dateRange filters messages by creation date. metadata filters shallow message metadata by exact scalar key-value pairs using AND semantics. Metadata values can be strings, finite numbers, booleans, or null.

**orderBy** (`{ field: 'createdAt'; direction: 'ASC' | 'DESC' }`): Sort order for retrieved messages. Defaults to descending by creation date.

**threadConfig** (`MemoryConfig`): Configuration options for message retrieval and semantic search

**threadConfig.lastMessages** (`number | false`): Number of most recent messages to retrieve. Set to false to disable. When perPage is not explicitly provided, this value is used as the default.

**threadConfig.semanticRecall** (`boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }`): Enable semantic search in message history. Can be a boolean or an object with configuration options. When enabled, requires both vector store and embedder to be configured.

**threadConfig.workingMemory** (`WorkingMemory`): Configuration for working memory feature. Can be { enabled: boolean; template?: string; schema?: ZodObject\<any> | JSONSchema7; scope?: 'thread' | 'resource' } or { enabled: boolean } to disable.

**threadConfig.threads** (`{ generateTitle?: boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> } }`): Settings related to memory thread creation. generateTitle controls automatic thread title generation from the conversation transcript. Can be a boolean or an object with custom model and instructions.

## Metadata filtering

Use `filter.metadata` to match shallow scalar metadata stored on messages:

```typescript
const { messages } = await memory.recall({
  threadId: 'thread-123',
  filter: {
    metadata: {
      category: 'billing',
      escalated: true,
      priority: 2,
      archivedAt: null,
    },
  },
})
```

All metadata entries are combined with AND semantics. A message must match every key and value with exact type equality. `null` matches metadata that's explicitly set to `null`. It doesn't match a missing key.

Metadata filters only support shallow scalar values: `string`, finite `number`, `boolean`, and `null`. Nested objects, arrays, `NaN`, and infinities aren't supported. Metadata keys must start with a letter or underscore and contain only alphanumeric or underscore characters. The limit is 128 characters. Reserved prototype keys such as `__proto__`, `constructor`, and `prototype` aren't allowed. Performance depends on the storage backend. Arbitrary metadata filters may require scanning candidate messages, so narrow the query with `threadId`, `resourceId`, or `dateRange` when possible.

## Returns

**messages** (`MastraDBMessage[]`): Array of retrieved messages in the database format

## Extended usage example

```typescript
import { mastra } from './mastra'

const agent = mastra.getAgent('agent')
const memory = await agent.getMemory()

// Retrieve messages with pagination
const { messages } = await memory!.recall({
  threadId: 'thread-123',
  perPage: 50,
  vectorSearchString: 'What messages are there?',
  include: [
    {
      id: 'msg-123',
    },
    {
      id: 'msg-456',
      withPreviousMessages: 3,
      withNextMessages: 1,
    },
  ],
  threadConfig: {
    semanticRecall: true,
  },
})

console.log(messages) // MastraDBMessage[]

// Fetch all messages without pagination
const allMessages = await memory!.recall({
  threadId: 'thread-123',
  perPage: false, // Fetch all
})

// Convert to AI SDK format if needed
import { toAISdkV5Messages } from '@mastra/ai-sdk/ui'
const uiMessages = toAISdkV5Messages(messages)
```

### Related

- [Memory Class Reference](https://mastra.ai/reference/memory/memory-class)
- [Getting Started with Memory](https://mastra.ai/docs/memory/overview)
- [Semantic Recall](https://mastra.ai/docs/memory/semantic-recall)
- [createThread](https://mastra.ai/reference/memory/createThread)