The Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.
Python agentic-memoryagentic-memory-systemagentsaiai-agentschatgptgenaillmlong-term-memorymemorymemory-managementpythonragstate-management
[docs] Filters fix in docs (#3815)
Parth Sharma654089fcfcbc
diff --git a/docs/cookbooks/essentials/building-ai-companion.mdx b/docs/cookbooks/essentials/building-ai-companion.mdxindex bcaaada17..95e6df5c9 100644--- a/docs/cookbooks/essentials/building-ai-companion.mdx+++ b/docs/cookbooks/essentials/building-ai-companion.mdx@@ -144,9 +144,14 @@ Retrieve just constraints for workout planning:```pythonconstraints = 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"]diff --git a/docs/cookbooks/essentials/entity-partitioning-playbook.mdx b/docs/cookbooks/essentials/entity-partitioning-playbook.mdxindex 6511d95a2..9295bbf8c 100644--- a/docs/cookbooks/essentials/entity-partitioning-playbook.mdx+++ b/docs/cookbooks/essentials/entity-partitioning-playbook.mdx@@ -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```pythonenterprise_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 appdef 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 conversationsdiff --git a/docs/platform/features/entity-scoped-memory.mdx b/docs/platform/features/entity-scoped-memory.mdxindex b7f09bfcb..d325623d2 100644--- a/docs/platform/features/entity-scoped-memory.mdx+++ b/docs/platform/features/entity-scoped-memory.mdx@@ -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```pythonapp_scope = {"AND": [- {"app_id": "concierge_portal"},+ {"app_id": "concierge_portal"}+ ],+ "OR": [{"user_id": "*"},{"agent_id": "*"}]diff --git a/docs/platform/features/v2-memory-filters.mdx b/docs/platform/features/v2-memory-filters.mdxindex b74757adf..95eb7fee9 100644--- a/docs/platform/features/v2-memory-filters.mdx+++ b/docs/platform/features/v2-memory-filters.mdx@@ -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 patternsUse 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 searchFind 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 ownfilters = {"AND": [- {"agent_id": "finance_bot"},- {"user_id": "*"}+ {"agent_id": "finance_bot"}]}- # Any entity populated+ # Or broaden within that scope using wildcardsfilters = {- "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>@@ -400,7 +415,7 @@ When you specify `user_id` only, other entity fields default to null. Use wildcaUse `keywords` with `contains` (case-sensitive) or `icontains` (case-insensitive).</Accordion>- <Accordion title="Can I nest AND/OR?">+<Accordion title="Can I nest AND/OR?">```python{"AND": [@@ -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.