JDSS/mem0
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[docs] Filters fix in docs (#3815)

Browse Source
This commit is contained in:
Parth Sharma
2025-12-11 18:38:08 +05:30
committed by GitHub
parent 222c6ceea1
commit 654089fcfc
4 changed files with 73 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/cookbooks/essentials/building-ai-companion.mdx
+8 -3
View File
@@ -144,9 +144,14 @@ Retrieve just constraints for workout planning:
```python
constraints = mem0_client.search(
"injury concerns",
user_id="max",
filters={"categories": {"in": ["constraints"]}}
query="injury concerns",
filters={
"AND": [
{"user_id": "max"},
{"categories": {"in": ["constraints"]}}
]
},
threshold=0.0 # optional: widen recall for short phrases
)
print([m["memory"] for m in constraints["results"]])
# Output: ["Max's right knee flares up on downhills"]
docs/cookbooks/essentials/entity-partitioning-playbook.mdx
+10 -3
View File
@@ -63,8 +63,10 @@ print(agent_memories)
**Output:**
```
# User scope returns user's memory
{'results': [{'memory': 'avoids shellfish and prefers boutique hotels', ...}]}
{'results': [{'memory': 'avoids shellfish and prefers boutique hotels', ...}]}
# Agent scope returns agent's own memory
{'results': [{'memory': 'Cam prefers boutique hotels and avoids shellfish', ...}]}
```
<Tip icon="compass">
@@ -137,7 +139,9 @@ Nora white-labels her travel service for a sports brand. Use `app_id` to keep en
```python
enterprise_filters = {
"AND": [
{"app_id": "sports_brand_portal"},
{"app_id": "sports_brand_portal"}
],
"OR": [
{"user_id": "*"},
{"agent_id": "*"}
]
@@ -176,7 +180,10 @@ client.delete_all(app_id="sports_brand_portal")
```python
# Nightly audits - check all data for an app
def audit_app(app_id: str):
filters = {"AND": [{"app_id": app_id}, {"user_id": "*"}, {"agent_id": "*"}]}
filters = {
"AND": [{"app_id": app_id}],
"OR": [{"user_id": "*"}, {"agent_id": "*"}]
}
return client.get_all(filters=filters, page=1, page_size=50)
# Session cleanup - delete temporary conversations
docs/platform/features/entity-scoped-memory.mdx
+7 -1
View File
@@ -73,6 +73,10 @@ client.add(
The response will include one or more memory IDs. Check the dashboard → Memories to confirm the entry appears under the correct user, agent, app, and run.
<Warning>
Platform writes that include both `user_id` and `agent_id` (or other combinations) are persisted as separate records per entity so we can enforce privacy boundaries. Each record carries exactly one primary entity, which is why `{"AND": [{"user_id": ...}, {"agent_id": ...}]}` never returns results. Plan searches per entity scope or combine scopes with `OR`.
</Warning>
The HTTP equivalent uses `POST /v1/memories/` with the same identifiers in the JSON body. See the Add Memories API reference for REST details.
## See it in action
@@ -133,7 +137,9 @@ Want to experiment with AND/OR logic, nested operators, or wildcards? The <Link
```python
app_scope = {
"AND": [
{"app_id": "concierge_portal"},
{"app_id": "concierge_portal"}
],
"OR": [
{"user_id": "*"},
{"agent_id": "*"}
]
docs/platform/features/v2-memory-filters.mdx
+47 -26
View File
@@ -38,23 +38,23 @@ Filters use a nested JSON structure with logical operators at the root:
### Entity fields
| Field | Operators | Example |
|-------|-----------|---------|
| `user_id` | `=`, `!=`, `in`, `*` | `{"user_id": "user_123"}` |
| `agent_id` | `=`, `!=`, `in`, `*` | `{"agent_id": "*"}` |
| `app_id` | `=`, `!=`, `in`, `*` | `{"app_id": {"in": ["app1", "app2"]}}` |
| `run_id` | `=`, `!=`, `in`, `*` | `{"run_id": "*"}` |
| `user_id` | `eq`, `ne`, `in`, `*` | `{"user_id": "user_123"}` |
| `agent_id` | `eq`, `ne`, `in`, `*` | `{"agent_id": "*"}` |
| `app_id` | `eq`, `ne`, `in`, `*` | `{"app_id": {"in": ["app1", "app2"]}}` |
| `run_id` | `eq`, `ne`, `in`, `*` | `{"run_id": "*"}` |
### Time fields
| Field | Operators | Example |
|-------|-----------|---------|
| `created_at` | `>`, `>=`, `<`, `<=`, `=`, `!=` | `{"created_at": {"gte": "2024-01-01"}}` |
| `updated_at` | `>`, `>=`, `<`, `<=`, `=`, `!=` | `{"updated_at": {"lt": "2024-12-31"}}` |
| `timestamp` | `>`, `>=`, `<`, `<=`, `=`, `!=` | `{"timestamp": {"gt": "2024-01-01"}}` |
| `created_at` | `gt`, `gte`, `lt`, `lte`, `eq`, `ne` | `{"created_at": {"gte": "2024-01-01"}}` |
| `updated_at` | `gt`, `gte`, `lt`, `lte`, `eq`, `ne` | `{"updated_at": {"lt": "2024-12-31"}}` |
| `timestamp` | `gt`, `gte`, `lt`, `lte`, `eq`, `ne` | `{"timestamp": {"gt": "2024-01-01"}}` |
### Content fields
| Field | Operators | Example |
|-------|-----------|---------|
| `categories` | `=`, `!=`, `in`, `contains` | `{"categories": {"in": ["finance"]}}` |
| `metadata` | `=`, `!=` | `{"metadata": {"key": "value"}}` |
| `categories` | `eq`, `ne`, `in`, `contains` | `{"categories": {"in": ["finance"]}}` |
| `metadata` | `eq`, `ne`, `contains` | `{"metadata": {"key": "value"}}` |
| `keywords` | `contains`, `icontains` | `{"keywords": {"icontains": "invoice"}}` |
### Special fields
@@ -66,6 +66,10 @@ Filters use a nested JSON structure with logical operators at the root:
The `*` wildcard matches any non-null value. Records with null values for that field are excluded.
</Callout>
<Callout type="info" icon="keyboard" color="#00A8FF">
Use operator keywords exactly as shown (`eq`, `ne`, `gte`, etc.). SQL-style symbols such as `>=` or `!=` are rejected by the Platform API.
</Callout>
## Common filter patterns
Use these ready-made filters to target typical retrieval scenarios without rebuilding logic from scratch.
@@ -101,6 +105,20 @@ Use these ready-made filters to target typical retrieval scenarios without rebui
</Accordion>
</AccordionGroup>
<Callout type="warning" icon="exclamation-triangle" color="#E74C3C">
Metadata filters only support bare values/`eq`, `contains`, and `ne`. Operators such as `in`, `gt`, or `lt` trigger a `FilterValidationError`. For multi-value checks, wrap multiple equality clauses in `OR`.
</Callout>
```python
# Multi-value metadata workaround
filters = {
"OR": [
{"metadata": {"type": "semantic"}},
{"metadata": {"type": "episodic"}}
]
}
```
### Content search
Find memories containing specific text, categories, or metadata values.
@@ -240,13 +258,13 @@ Combine various filters for complex queries across different dimensions.
```
</Accordion>
<Accordion title="All entities populated">
<Accordion title="All entities populated (single entity scope)">
```python
# Require every entity field to be non-null
# Require user_id plus non-null run/app IDs
# (Memories are stored separately per entity, so scope one dimension at a time.)
filters = {
"AND": [
{"user_id": "*"},
{"agent_id": "*"},
{"user_id": "user_123"},
{"run_id": "*"},
{"app_id": "*"}
]
@@ -275,23 +293,20 @@ Level up foundational patterns with compound filters that coordinate entity scop
```
</Accordion>
<Accordion title="Cross-entity relationships">
<Accordion title="Entity-specific retrieval">
```python
# From specific agent, all users
# Query agent scope on its own
filters = {
"AND": [
{"agent_id": "finance_bot"},
{"user_id": "*"}
{"agent_id": "finance_bot"}
]
}
# Any entity populated
# Or broaden within that scope using wildcards
filters = {
"OR": [
{"user_id": "*"},
{"agent_id": "*"},
{"run_id": "*"},
{"app_id": "*"}
"AND": [
{"agent_id": "finance_bot"},
{"run_id": "*"}
]
}
```
@@ -327,7 +342,7 @@ Use `"*"` to match any non-null value for a field.
</Callout>
<Callout type="warning" icon="exclamation-triangle" color="#E74C3C">
When you specify `user_id` only, other entity fields default to null. Use wildcards to include them.
Memories are stored per-entity (user, agent, app, run). Combining `user_id` **and** `agent_id` in the same `AND` clause returns no results because no record contains both values at once. Query one entity scope at a time or use `OR` logic for parallel lookups.
</Callout>
## Troubleshooting
@@ -336,9 +351,9 @@ When you specify `user_id` only, other entity fields default to null. Use wildca
<Accordion title="Missing results with agent_id">
**Problem**: Filtered by `user_id` but don't see agent memories.
**Solution**: Add a wildcard for `agent_id` so non-null entries return:
**Solution**: User and agent memories are stored as separate records. Use OR to query both scopes:
```python
{"AND": [{"user_id": "user_123"}, {"agent_id": "*"}]}
{"OR": [{"user_id": "user_123"}, {"agent_id": "agent_name"}]}
```
</Accordion>
@@ -414,3 +429,9 @@ When you specify `user_id` only, other entity fields default to null. Use wildca
```
</Accordion>
</AccordionGroup>
## Known limitations
- Entity filters operate on a single scope per record. Use separate queries or `OR` logic to compare users vs agents.
- Metadata supports only bare/`eq`, `contains`, and `ne` comparisons.
- Wildcards (`"*"` ) match only records where the field is already non-null.