SearchMemoriesOptions - MemMachine Documentation

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[]`	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.

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
);

Use expand_context when you need the LLM to understand the conversation flow surrounding a specific memory hit, rather than just the hit itself.

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