Skip to main content
POST
Search Memories

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Specification model for searching memories.

query
string
required

The natural language query used for semantic memory search. This should be a descriptive string of the information you are looking for.

Example:

"What was the user's last conversation about finance?"

project_id
string
default:""

The identifier of the project. If empty, the user's default project is used.

Maximum string length: 255
Pattern: ^[\p{L}\p{N}_:-]*$
agent_mode
boolean
default:false

Whether to enable top-level retrieval-agent orchestration for episodic search. When false, episodic search uses direct memory retrieval.

Example:

false

expand_context
integer
default:0

The number of additional episodes to include around each matched episode from long term memory for better context.

Example:

0

filter
string
default:""

An optional string filter applied to the memory metadata. This uses a simple query language (e.g., 'metadata.user_id=123') for exact matches. Multiple conditions can be combined using AND operators. The metadata fields are prefixed with 'metadata.' to distinguish them from other fields.

Example:

"metadata.user_id=123 AND metadata.session_id=abc"

score_threshold
number | null

The minimum score for a memory to be included in the search results. Defaults to -inf (no threshold) represented as None. Meaningful only for certain ranking methods.

Example:

0

set_metadata
Set Metadata · object | null

Optional metadata key-value pairs used to filter or identify a specific semantic memory set. Applies only when searching semantic memories.

top_k
integer
default:10

The maximum number of memories to return in the search results.

Example:

5

types
enum<string>[]

A list of memory types to include in the search (e.g., episodic, semantic). If empty, all available types are searched.

Memory type.

Available options:
semantic,
episodic
Example:

Response

Successful Response

Response model for memory search results.

content
SearchResultContent · object
required

Payload for SearchResult.content returned by /memories/search.

status
integer
default:0

The status code of the search operation. 0 typically indicates success.

Example:

0