> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memmachine.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SearchMemoriesOptions

> Configuration options for filtering and limiting episodic and semantic search results.

## Overview

The `SearchMemoriesOptions` interface allows you to refine how the memory engine
retrieves and ranks episodic and semantic results. It is used as the optional
second argument in the `MemMachineMemory.search()` method.

***

## Properties

All properties in this interface are optional.

| Property          | Type                                  | Description                                                                                                                                                                                                                                                       |
| :---------------- | :------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `top_k`           | `number`                              | The maximum number of relevant memories to return.                                                                                                                                                                                                                |
| `score_threshold` | `number`                              | The minimum similarity score required for a memory to be included in results.                                                                                                                                                                                     |
| `filter`          | `string`                              | A metadata-based filter string to narrow the search scope. User metadata fields must be prefixed with `m.` / `metadata.` (for example `m.user_id = '123'`). String literals must be single-quoted. Unknown or misspelled user metadata fields return a 400 error. |
| `expand_context`  | `number`                              | The number of surrounding chronological episodes to retrieve for each hit.                                                                                                                                                                                        |
| `types`           | [`MemoryType[]`](../types/MemoryType) | Restricts the search to specific memory classifications (e.g., `semantic`).                                                                                                                                                                                       |
| `agent_mode`      | `boolean`                             | Enables top-level retrieval-agent orchestration for episodic retrieval.                                                                                                                                                                                           |

***

## Usage Example

The following example demonstrates how to perform a filtered search with a specific limit and context expansion.

```typescript theme={null}
import { SearchMemoriesOptions } from '@memmachine/client';

const memory = project.memory();

const searchConfig: SearchMemoriesOptions = {
  top_k: 5,
  score_threshold: 0.75,
  expand_context: 2, // Get 2 messages before and after each hit
  types: ['episodic', 'semantic'],
  agent_mode: true
};

const results = await memory.search(
  'What are the user preferences for UI themes?', 
  searchConfig
);
```

<Tip> Use `expand_context` when you need the LLM to understand the conversation flow surrounding a specific memory hit, rather than just the hit itself. </Tip>
<Tip> `agent_mode` defaults to `false`. When set to `true`, it changes episodic retrieval strategy (routing, splitting, and query rewriting) and does not change semantic retrieval behavior(yet). </Tip>