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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.