Skip to main content

Search API

Query memories semantically using natural language.

Search Memories

Request Body:
ParameterTypeRequiredDescription
space_idstringYesWhich space to search
querystringYesNatural language query
limitintegerNoMax results, 1–100 (default: 10)
filtersobjectNoOptional filters (e.g. memory type)
Response (200 OK):
FieldTypeDescription
relevance_scorenumber0.0–1.0, higher = more relevant
Python SDK:
client.search() returns the results list directly (empty list if no matches).

How Semantic Search Works

Search understands meaning, not just keywords - “Where does Alice work?”, “Alice’s employer”, and “What company is Alice at?” all surface the same memory. Your query is embedded and compared against stored memory embeddings; results are ranked by relevance_score.

Error Responses

Same shape as other endpoints - see the error reference.
StatusCodeCause
400bad_requestMissing query or space_id
401unauthorizedMissing/invalid API key
403forbiddenSpace not owned by your org
404not_foundSpace doesn’t exist
429rate_limitedQuota or rate limit exceeded

Next Steps

Insights API

Synthesize learned patterns

Concepts

Learn how semantic search works