Skip to main content

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.

​
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.
PropertyTypeDescription
top_knumberThe maximum number of relevant memories to return.
score_thresholdnumberThe minimum similarity score required for a memory to be included in results.
filterstringA 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_contextnumberThe number of surrounding chronological episodes to retrieve for each hit.
typesMemoryType[]Restricts the search to specific memory classifications (e.g., semantic).
agent_modebooleanEnables 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).