---
title: 'Search Memories'
description: "Search memories with hybrid retrieval (semantic + BM25 + entity matching) and advanced filtering using logical and comparison operators."
openapi: post /v3/memories/search/
---

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 Output
{
  "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>