# Memory.recall()

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

## Usage Example

```typescript
await memory?.recall({ threadId: "user-123" });
```

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

Filter options for message retrieval. Currently supports \`dateRange\` to filter messages by creation date. Use \`startExclusive\` or \`endExclusive\` to exclude boundary dates (useful for cursor-based pagination).

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

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

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

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

### threads?:

{ generateTitle?: boolean | { model: DynamicArgument\<MastraLanguageModel>; instructions?: DynamicArgument\<string> } }

Settings related to memory thread creation. \`generateTitle\` controls automatic thread title generation from the user's first message. Can be a boolean or an object with custom model and instructions.

## 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/llms.txt)
- [Getting Started with Memory](https://mastra.ai/docs/memory/overview/llms.txt)
- [Semantic Recall](https://mastra.ai/docs/memory/semantic-recall/llms.txt)
- [createThread](https://mastra.ai/reference/memory/createThread/llms.txt)