Relevance-ranked hybrid search across stored memories. V3 uses multi-signal retrieval — semantic, BM25 keyword, and entity matching scored in parallel and fused. The returned score is a combined [0, 1] value.

Entity IDs (user_id, agent_id, app_id, run_id) must be passed inside the filters object — top-level entity IDs are rejected with 400. At least one entity ID is required.

Expired memories are hidden by default. Pass show_expired: true to include memories whose expiration_date has passed.

Python uses show_expired; TypeScript uses showExpired.

The filters object supports complex logical operations (AND, OR, NOT) and comparison operators:

in: Matches any of the values specified
gte: Greater than or equal to
lte: Less than or equal to
gt: Greater than
lt: Less than
ne: Not equal to
icontains: Case-insensitive containment check
*: Wildcard character that matches everything

Search parameter defaults

Parameter	Default
`top_k`	`10` (range 1–1000)
`threshold`	`0.1` (pass `0.0` to disable)
`rerank`	`false` (pass `true` to enable)

<CodeGroup> ```python Platform API Example related_memories = client.search( query="What are Alice's hobbies?", show_expired=False, filters={ "OR": [ { "user_id": "alice" }, { "agent_id": {"in": ["travel-agent", "sports-agent"]} } ] }, ) ```

json

{
  "results": [
    {
      "id": "ea925981-272f-40dd-b576-be64e4871429",
      "memory": "Likes to play cricket and plays cricket on weekends.",
      "user_id": "alice",
      "metadata": {
        "category": "hobbies"
      },
      "score": 0.82,
      "expiration_date": null,
      "created_at": "2024-07-26T10:29:36.630547-07:00",
      "updated_at": null,
      "categories": ["hobbies"]
    }
  ]
}

</CodeGroup> <CodeGroup> ```python Wildcard Example # Using wildcard to match all run_ids for a specific user all_memories = client.search( query="What are Alice's hobbies?", filters={ "AND": [ { "user_id": "alice" }, { "run_id": "*" } ] }, ) ``` </CodeGroup> <CodeGroup> ```python Categories Filter Examples # Example 1: Using 'contains' for partial matching finance_memories = client.search( query="What are my financial goals?", filters={ "AND": [ { "user_id": "alice" }, { "categories": { "contains": "finance" } } ] }, )

Example 2: Using 'in' for exact matching

personal_memories = client.search( query="What personal information do you have?", filters={ "AND": [ { "user_id": "alice" }, { "categories": { "in": ["personal_information"] } } ] }, )

</CodeGroup>

Search Memories

Search parameter defaults

Example 2: Using 'in' for exact matching