> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mem0.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Search Memories
> Search memories with hybrid retrieval (semantic + BM25 + entity matching) and advanced filtering using logical and comparison operators.
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) |
```python Platform API Example theme={null}
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 theme={null}
{
"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"]
}
]
}
```
```python Wildcard Example theme={null}
# 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": "*"
}
]
},
)
```
```python Categories Filter Examples theme={null}
# 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"]
}
}
]
},
)
```
## OpenAPI
````yaml post /v3/memories/search/
openapi: 3.0.1
info:
title: Mem0 API Docs
description: mem0.ai API Docs
contact:
email: support@mem0.ai
license:
name: Apache 2.0
version: v1
servers:
- url: https://api.mem0.ai/
security:
- ApiKeyAuth: []
paths:
/v3/memories/search/:
post:
tags:
- memories
summary: Search memories (V3)
description: >-
Relevance-ranked search across stored memories. V3 uses hybrid retrieval
and can also apply temporal reasoning for time-aware queries. Entity IDs
**must** be passed inside the `filters` object. Top-level `user_id` /
`agent_id` / `run_id` are rejected with 400. At least one entity ID is
required.
operationId: memories_search_v3
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- query
- filters
properties:
query:
type: string
minLength: 1
description: Natural-language search query.
filters:
type: object
description: >-
Entity and metadata filters. Must include at least one
entity ID (`user_id`, `agent_id`, `app_id`, or `run_id`).
Supports `AND`, `OR`, `NOT`, and comparison operators (`in`,
`gte`, `lte`, `gt`, `lt`, `contains`, `icontains`, `ne`).
additionalProperties: true
show_expired:
type: boolean
default: false
description: >-
When true, include memories whose `expiration_date` has
passed. Expired memories are hidden by default.
top_k:
type: integer
minimum: 1
maximum: 1000
default: 10
description: Number of results to return.
threshold:
type: number
minimum: 0
maximum: 1
default: 0.1
description: >-
Minimum semantic relevance score. Pass `0.0` to disable
filtering.
rerank:
type: boolean
default: false
description: >-
Apply the managed reranker for better ordering (adds
latency).
reference_date:
oneOf:
- type: integer
- type: number
- type: string
nullable: true
description: >-
Optional query anchor time for relative temporal
interpretation. Accepts Unix epoch, YYYY-MM-DD, or ISO
datetime.
example:
query: where does the user live?
filters:
user_id: alice
top_k: 10
responses:
'200':
description: Ranked search results.
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
description: Unique memory identifier.
memory:
type: string
description: The extracted memory fact.
score:
type: number
format: float
minimum: 0
maximum: 1
description: >-
Combined multi-signal relevance score in [0, 1]
(search responses only).
metadata:
type: object
additionalProperties: true
description: User-supplied metadata attached to the memory.
categories:
type: array
items:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
required:
- id
- memory
- created_at
required:
- results
example:
results:
- id: mem-uuid
memory: User moved to San Francisco from New York in January 2026
score: 0.82
metadata: {}
categories:
- location
created_at: '2026-01-15T10:30:00Z'
updated_at: '2026-01-15T10:30:00Z'
'400':
description: >-
Validation error, e.g. empty `query`, missing `filters`, or no
positively-scoped entity ID.
'401':
description: 'Unauthorized: missing or invalid API key.'
security:
- tokenAuth: []
x-codeSamples:
- lang: cURL
source: |-
curl -X POST https://api.mem0.ai/v3/memories/search/ \
-H "Authorization: Token " \
-H "Content-Type: application/json" \
-d '{
"query": "where does the user live?",
"filters": {"user_id": "alice"},
"top_k": 10
}'
- lang: Python
source: |-
from mem0 import MemoryClient
client = MemoryClient(api_key="your-api-key")
results = client.search(
"where does the user live?",
filters={"user_id": "alice"},
top_k=10,
)
for r in results["results"]:
print(r["memory"], r["score"])
- lang: JavaScript
source: |-
import MemoryClient from "mem0ai";
const client = new MemoryClient({ apiKey: "your-api-key" });
const results = await client.search("where does the user live?", {
filters: { userId: "alice" },
topK: 10,
});
for (const r of results.results) {
console.log(r.memory, r.score);
}
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: >-
API key authentication. Prefix your Mem0 API key with 'Token '. Example:
'Token your_api_key'
````