docs: document the real search filter grammar (#6906)

docs/platform/features/v2-memory-filters.mdx

@@ -29,6 +29,46 @@ Filters use a nested JSON structure with logical operators at the root:
 }
 ```
 
+A single bare condition needs no wrapper:
+
+```python
+# Works: one condition, no wrapper needed
+filters = {"user_id": "user_123"}
+```
+
+Sibling top-level keys in a flat object are accepted too: the API implicitly ANDs them, so the flat form and the explicit `AND` form are equivalent:
+
+```python
+# Works: sibling keys are implicitly ANDed
+filters = {
+    "user_id": "user_123",
+    "categories": {"in": ["finance"]}
+}
+
+# Equivalent, explicit form
+filters = {
+    "AND": [
+        {"user_id": "user_123"},
+        {"categories": {"in": ["finance"]}}
+    ]
+}
+```
+
+Reach for an explicit `AND`, `OR`, or `NOT` wrapper when you need `OR` or `NOT` semantics, or when you need to nest conditions. What the API does reject is an unrecognized top-level key:
+
+```python
+# Rejected: unknown top-level key
+filters = {"user_id": "user_123", "bogus_key": "z"}
+# 400: Top-level key must be a logical operator or an allowed field:
+# ['AND', 'OR', 'NOT', 'user_id', 'agent_id', 'app_id', 'run_id',
+#  'created_at', 'updated_at', 'timestamp', 'expiration_date', 'text',
+#  'categories', 'metadata', 'keywords_search', 'memory_ids', 'keywords']
+```
+
+<Callout type="info" icon="cloud" color="#00A8FF">
+Both the hosted Platform API and the self-hosted OSS SDK implicitly AND sibling top-level keys, so the flat and explicit `AND` forms behave the same way on either. The real differences: Platform validates each top-level key against a fixed allow-list and returns a 400 for anything else, and Platform has no `nin` operator. See [Enhanced Metadata Filtering](/open-source/features/metadata-filtering) for the OSS grammar.
+</Callout>
+
 ## Available fields and operators
 
 ### Entity fields
@@ -67,6 +107,14 @@ The `*` wildcard matches any non-null value. Records with null values for that f
 Use operator keywords exactly as shown (`eq`, `ne`, `gte`, etc.). SQL-style symbols such as `>=` or `!=` are rejected by the Platform API.
 </Callout>
 
+<Callout type="warning" icon="exclamation-triangle" color="#E74C3C">
+There is no `nin` ("not in") operator on Platform. It is an OSS-only operator; see [Enhanced Metadata Filtering](/open-source/features/metadata-filtering). To exclude a set of values on Platform, wrap an `in` clause in `NOT`:
+
+```python
+{"NOT": {"categories": {"in": ["spam", "test"]}}}
+```
+</Callout>
+
 ## Common filter patterns
 
 Use these ready-made filters to target typical retrieval scenarios without rebuilding logic from scratch.