feat: docs with new array contains (#534)

2 files changed, 569 insertions, 722 deletions

diff --git a/apps/docs/changelog/developer-platform.mdx b/apps/docs/changelog/developer-platform.mdx
index 62d610e8..98a75d6f 100644
--- a/apps/docs/changelog/developer-platform.mdx
+++ b/apps/docs/changelog/developer-platform.mdx
@@ -6,6 +6,10 @@ description: "API updates, new endpoints, and SDK releases"
 
 API updates, new endpoints, SDK releases, and developer-focused features.
 
+## October 27, 2025
+
+- **Enhanced Filtering Capabilities:** Major improvements to the search filtering API with new `string_contains` filter type for partial string matching, `ignoreCase` option for case-insensitive string operations, and improved negation support across all filter types including proper numeric equality negation. The implementation also includes enhanced SQL injection protection and wildcard escaping for improved security.
+
 ## September 17, 2025
 
 - **Forgotten Memories Search:** New `include.forgottenMemories` parameter in v4 search API allows searching through memories that have been explicitly forgotten or expired. Set to `true` to include forgotten memories in search results, helping recover previously archived information.
diff --git a/apps/docs/search/filtering.mdx b/apps/docs/search/filtering.mdx
index c20f4f2c..a9efecba 100644
--- a/apps/docs/search/filtering.mdx
+++ b/apps/docs/search/filtering.mdx
@@ -1,63 +1,85 @@
 ---
-title: "Grouping and filtering"
-description: "Container tags, metadata filters, and advanced search filtering techniques"
+title: "Filtering Memories"
+description: "Filter and search memories using container tags and metadata"
 icon: "filter"
 ---
 
+Supermemory provides two complementary filtering mechanisms that work independently or together to help you find exactly what you need.
 
-Supermemory supports filtering search results using container tags, metadata conditions, and advanced filtering techniques for both `/v3/search` and `/v4/search` endpoints.
+## How Filtering Works
+
+Supermemory uses two types of filters for different purposes:
+
+<CardGroup cols={2}>
+  <Card title="Container Tags" icon="folder">
+    **Organize memories** into isolated spaces by user, project, or workspace
+  </Card>
+  <Card title="Metadata Filtering" icon="database">
+    **Query memories** by custom properties like category, status, or date
+  </Card>
+</CardGroup>
+
+Both filtering types can be used:
+- **Independently** - Use container tags alone OR metadata filters alone
+- **Together** - Combine both for precise filtering (most common)
+
+Think of it as: `[Container Tags] → [Your Memories] ← [Metadata Filters]`
 
 ## Container Tags
 
-Container tags group memories by user, project, or organization. They're the primary way to isolate search results.
+Container tags create isolated memory spaces. They're perfect for multi-tenant applications, user profiles, and project organization.
 
-**Important**: Container tags use **exact array matching**. A document with `["technology", "quantum-computing"]` will NOT match a search for `["technology"]`. The arrays must be identical.
+### How Container Tags Work
 
-### Document Search (v3/search)
+- **Exact matching**: Arrays must match exactly. A memory tagged with `["user_123", "project_ai"]` will NOT match a search for just `["user_123"]`
+- **Isolation**: Each container tag combination creates a separate knowledge graph
+- **Naming patterns**: Use consistent patterns like `user_{id}`, `project_{id}`, or `org_{id}_team_{id}`
+
+### Basic Usage
 
 <Tabs>
   <Tab title="TypeScript">
     ```typescript
-    // Single container tag
+    // Search within a user's memories
     const results = await client.search.documents({
-      q: "machine learning",
+      q: "machine learning notes",
       containerTags: ["user_123"],
       limit: 10
     });
 
-    // Multiple container tags
-    const results2 = await client.search.documents({
-      q: "project status",
-      containerTags: ["project_ai", "team_research"],
+    // Search within a project
+    const projectResults = await client.search.documents({
+      q: "requirements",
+      containerTags: ["project_ai"],
       limit: 10
     });
     ```
   </Tab>
   <Tab title="Python">
     ```python
-    # Single container tag
+    # Search within a user's memories
     results = client.search.documents(
-        q="machine learning",
+        q="machine learning notes",
         container_tags=["user_123"],
         limit=10
     )
 
-    # Multiple container tags
-    results2 = client.search.documents(
-        q="project status",
-        container_tags=["project_ai", "team_research"],
+    # Search within a project
+    project_results = client.search.documents(
+        q="requirements",
+        container_tags=["project_ai"],
         limit=10
     )
     ```
   </Tab>
   <Tab title="cURL">
     ```bash
-    # Single container tag
+    # Search within a user's memories
     curl -X POST "https://api.supermemory.ai/v3/search" \
       -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
       -H "Content-Type: application/json" \
       -d '{
-        "q": "machine learning",
+        "q": "machine learning notes",
         "containerTags": ["user_123"],
         "limit": 10
       }'
@@ -65,136 +87,94 @@ Container tags group memories by user, project, or organization. They're the pri
   </Tab>
 </Tabs>
 
-### Memory Search (v4/search)
+### Container Tag Patterns
 
-<Tabs>
-  <Tab title="TypeScript">
-    ```typescript
-    // Note: singular "containerTag" for v4/search
-    const results = await client.search.memories({
-      q: "research findings",
-      containerTag: "user_123",  // Single string, not array
-      limit: 5
-    });
-    ```
-  </Tab>
-  <Tab title="Python">
-    ```python
-    # Note: singular "container_tag" for v4/search
-    results = client.search.memories(
-        q="research findings",
-        container_tag="user_123",  # Single string, not array
-        limit=5
-    )
-    ```
-  </Tab>
-  <Tab title="cURL">
-    ```bash
-    curl -X POST "https://api.supermemory.ai/v4/search" \
-      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-      -H "Content-Type: application/json" \
-      -d '{
-        "q": "research findings",
-        "containerTag": "user_123",
-        "limit": 5
-      }'
-    ```
-  </Tab>
-</Tabs>
+<Tip>
+**Best Practice**: Use single container tags when possible. Multi-tag arrays require exact matching, which can be restrictive.
+</Tip>
 
-<Note>
-**Container Tag Differences**:
-- `/v3/search` uses `containerTags` (plural array) with exact array matching
-- `/v4/search` uses `containerTag` (singular string) for single tag filtering
-- Exact matching means `["user", "project"]` ≠ `["user"]`
-</Note>
+#### Recommended Patterns
+- User isolation: `user_{userId}`
+- Project grouping: `project_{projectId}`
+- Workspace separation: `workspace_{workspaceId}`
+- Hierarchical: `org_{orgId}_team_{teamId}`
+- Temporal: `user_{userId}_2024_q1`
+
+#### API Differences
 
-## Basic Metadata Filtering
+| Endpoint | Field Name | Type | Example |
+|----------|------------|------|---------|
+| `/v3/search` | `containerTags` | Array | `["user_123"]` |
+| `/v4/search` | `containerTag` | String | `"user_123"` |
+| `/v3/documents/list` | `containerTags` | Array | `["user_123"]` |
 
-Filter by metadata fields with simple conditions:
+## Metadata Filtering
+
+Metadata filters let you query memories by any custom property. They use SQL-like AND/OR logic with explicit grouping.
+
+### Filter Structure
+
+All metadata filters must be wrapped in AND or OR arrays:
+
+```javascript
+// ✅ Correct - wrapped in AND array
+filters: {
+  AND: [
+    { key: "category", value: "tech", negate: false }
+  ]
+}
+
+// ❌ Wrong - not wrapped
+filters: {
+  key: "category", value: "tech", negate: false
+}
+```
+
+### Why Explicit Grouping?
+
+Without explicit grouping, this SQL query is ambiguous:
+```sql
+category = 'tech' OR status = 'published' AND priority = 'high'
+```
+
+Our structure forces clarity:
+```javascript
+// Clear: (category = 'tech') OR (status = 'published' AND priority = 'high')
+{
+  OR: [
+    { key: "category", value: "tech" },
+    { AND: [
+      { key: "status", value: "published" },
+      { key: "priority", value: "high" }
+    ]}
+  ]
+}
+```
+
+### Basic Metadata Filtering
 
 <Tabs>
   <Tab title="TypeScript">
     ```typescript
+    // Single condition
     const results = await client.search.documents({
-      q: "artificial intelligence",
+      q: "neural networks",
       filters: {
         AND: [
-          {
-            key: "category",
-            value: "technology",
-            negate: false
-          }
+          { key: "category", value: "ai", negate: false }
         ]
       },
       limit: 10
     });
-    ```
-  </Tab>
-  <Tab title="Python">
-    ```python
-    results = client.search.documents(
-        q="artificial intelligence",
-        filters={
-            "AND": [
-                {
-                    "key": "category",
-                    "value": "technology",
-                    "negate": False
-                }
-            ]
-        },
-        limit=10
-    )
-    ```
-  </Tab>
-  <Tab title="cURL">
-    ```bash
-    curl -X POST "https://api.supermemory.ai/v3/search" \
-      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-      -H "Content-Type: application/json" \
-      -d '{
-        "q": "artificial intelligence",
-        "filters": {
-          "AND": [
-            {
-              "key": "category",
-              "value": "technology",
-              "negate": false
-            }
-          ]
-        },
-        "limit": 10
-      }'
-    ```
-  </Tab>
-</Tabs>
-
-## Numeric Filtering
 
-Filter by numeric values with operators:
-
-<Tabs>
-  <Tab title="TypeScript">
-    ```typescript
-    const results = await client.search.documents({
-      q: "research papers",
+    // Multiple AND conditions
+    const filtered = await client.search.documents({
+      q: "research",
       filters: {
         AND: [
-          {
-            filterType: "numeric",
-            key: "readingTime",
-            value: "10",
-            numericOperator: "<=",
-            negate: false
-          },
-          {
-            filterType: "numeric",
-            key: "wordCount",
-            value: "1000",
-            numericOperator: ">=",
-            negate: false
-          }
+          { key: "category", value: "science", negate: false },
+          { key: "status", value: "published", negate: false },
+          { key: "year", value: "2024", negate: false }
         ]
       },
       limit: 10
@@ -203,24 +183,25 @@ Filter by numeric values with operators:
   </Tab>
   <Tab title="Python">
     ```python
+    # Single condition
     results = client.search.documents(
-        q="research papers",
+        q="neural networks",
         filters={
             "AND": [
-                {
-                    "filterType": "numeric",
-                    "key": "readingTime",
-                    "value": "10",
-                    "numericOperator": "<=",
-                    "negate": False
-                },
-                {
-                    "filterType": "numeric",
-                    "key": "wordCount",
-                    "value": "1000",
-                    "numericOperator": ">=",
-                    "negate": False
-                }
+                {"key": "category", "value": "ai", "negate": False}
+            ]
+        },
+        limit=10
+    )
+
+    # Multiple AND conditions
+    filtered = client.search.documents(
+        q="research",
+        filters={
+            "AND": [
+                {"key": "category", "value": "science", "negate": False},
+                {"key": "status", "value": "published", "negate": False},
+                {"key": "year", "value": "2024", "negate": False}
             ]
         },
         limit=10
@@ -229,27 +210,15 @@ Filter by numeric values with operators:
   </Tab>
   <Tab title="cURL">
     ```bash
+    # Single condition
     curl -X POST "https://api.supermemory.ai/v3/search" \
       -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
       -H "Content-Type: application/json" \
       -d '{
-        "q": "research papers",
+        "q": "neural networks",
         "filters": {
           "AND": [
-            {
-              "filterType": "numeric",
-              "key": "readingTime",
-              "value": "10",
-              "numericOperator": "<=",
-              "negate": false
-            },
-            {
-              "filterType": "numeric",
-              "key": "wordCount",
-              "value": "1000",
-              "numericOperator": ">=",
-              "negate": false
-            }
+            {"key": "category", "value": "ai", "negate": false}
           ]
         },
         "limit": 10
@@ -258,86 +227,212 @@ Filter by numeric values with operators:
   </Tab>
 </Tabs>
 
-## Array Contains Filtering
+## Filter Types in Detail
 
-Filter by array values like participants, tags, or categories. The `array_contains` filter type checks if an array field contains a specific value.
+Supermemory supports four filter types, each designed for specific use cases.
 
-### Basic Array Contains
+### 1. String Equality (Default)
+
+Exact string matching with optional case-insensitive comparison.
 
 <Tabs>
-  <Tab title="TypeScript">
-    ```typescript
-    const results = await client.search.documents({
-      q: "meeting notes",
-      filters: {
-        AND: [
-          {
-            key: "participants",
-            value: "john.doe",
-            filterType: "array_contains"
-          }
-        ]
-      },
-      limit: 10
-    });
+  <Tab title="Basic">
+    ```javascript
+    // Case-sensitive exact match (default)
+    {
+      key: "status",
+      value: "Published",
+      negate: false
+    }
+    ```
+  </Tab>
+  <Tab title="Case-Insensitive">
+    ```javascript
+    // Matches "published", "Published", "PUBLISHED"
+    {
+      key: "status",
+      value: "PUBLISHED",
+      ignoreCase: true,
+      negate: false
+    }
+    ```
+  </Tab>
+  <Tab title="Negation">
+    ```javascript
+    // Exclude specific status
+    {
+      key: "status",
+      value: "draft",
+      negate: true
+    }
     ```
   </Tab>
-  <Tab title="Python">
-    ```python
-    results = client.search.documents(
-        q="meeting notes",
-        filters={
-            "AND": [
-                {
-                    "key": "participants",
-                    "value": "john.doe",
-                    "filterType": "array_contains"
-                }
-            ]
-        },
-        limit=10
-    )
+</Tabs>
+
+### 2. String Contains
+
+Search for substrings within text fields.
+
+<Tabs>
+  <Tab title="Basic">
+    ```javascript
+    // Find all documents containing "machine learning"
+    {
+      filterType: "string_contains",
+      key: "description",
+      value: "machine learning",
+      negate: false
+    }
+    ```
+  </Tab>
+  <Tab title="Case-Insensitive">
+    ```javascript
+    // Case-insensitive substring search
+    {
+      filterType: "string_contains",
+      key: "title",
+      value: "NEURAL",
+      ignoreCase: true,
+      negate: false
+    }
+    ```
+  </Tab>
+  <Tab title="Exclusion">
+    ```javascript
+    // Exclude documents containing "deprecated"
+    {
+      filterType: "string_contains",
+      key: "content",
+      value: "deprecated",
+      negate: true
+    }
     ```
   </Tab>
-  <Tab title="cURL">
-    ```bash
-    curl -X POST "https://api.supermemory.ai/v3/search" \
-      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-      -H "Content-Type: application/json" \
-      -d '{
-        "q": "meeting notes",
-        "filters": {
-          "AND": [
-            {
-              "key": "participants",
-              "value": "john.doe",
-              "filterType": "array_contains"
-            }
-          ]
+</Tabs>
+
+### 3. Numeric Comparisons
+
+Filter by numeric values with comparison operators.
+
+<Tabs>
+  <Tab title="Basic Operators">
+    ```javascript
+    // Greater than or equal
+    {
+      filterType: "numeric",
+      key: "score",
+      value: "80",
+      numericOperator: ">=",
+      negate: false
+    }
+
+    // Less than
+    {
+      filterType: "numeric",
+      key: "readingTime",
+      value: "10",
+      numericOperator: "<",
+      negate: false
+    }
+    ```
+  </Tab>
+  <Tab title="With Negation">
+    ```javascript
+    // NOT equal to 5 (becomes !=)
+    {
+      filterType: "numeric",
+      key: "priority",
+      value: "5",
+      numericOperator: "=",
+      negate: true
+    }
+
+    // NOT less than 80 (becomes >=)
+    {
+      filterType: "numeric",
+      key: "score",
+      value: "80",
+      numericOperator: "<",
+      negate: true
+    }
+    ```
+  </Tab>
+</Tabs>
+
+<Note>
+**Numeric Negation Mapping**:
+When using `negate: true` with numeric filters, operators are reversed:
+- `<` → `>=`
+- `<=` → `>`
+- `>` → `<=`
+- `>=` → `<`
+- `=` → `!=`
+</Note>
+
+### 4. Array Contains
+
+Check if an array field contains a specific value.
+
+<Tabs>
+  <Tab title="Basic">
+    ```javascript
+    // Find documents with specific participant
+    {
+      filterType: "array_contains",
+      key: "participants",
+      value: "john.doe",
+      negate: false
+    }
+    ```
+  </Tab>
+  <Tab title="Exclusion">
+    ```javascript
+    // Exclude documents with specific tag
+    {
+      filterType: "array_contains",
+      key: "tags",
+      value: "archived",
+      negate: true
+    }
+    ```
+  </Tab>
+  <Tab title="Multiple Checks">
+    ```javascript
+    // Must have both participants (use AND)
+    {
+      AND: [
+        {
+          filterType: "array_contains",
+          key: "participants",
+          value: "project.manager"
         },
-        "limit": 10
-      }'
+        {
+          filterType: "array_contains",
+          key: "participants",
+          value: "lead.developer"
+        }
+      ]
+    }
     ```
   </Tab>
 </Tabs>
 
-### Array Contains with Negation
+## Common Patterns
+
+Ready-to-use filtering patterns for common scenarios.
 
-Exclude documents that contain specific values in arrays:
+### User-Specific Content with Category
 
 <Tabs>
   <Tab title="TypeScript">
     ```typescript
     const results = await client.search.documents({
-      q: "team meetings",
+      q: "project updates",
+      containerTags: ["user_123"],
       filters: {
         AND: [
-          {
-            key: "participants",
-            value: "john.doe",
-            filterType: "array_contains",
-            negate: true  // Exclude meetings with john.doe
-          }
+          { key: "category", value: "work", negate: false },
+          { key: "visibility", value: "private", negate: false }
         ]
       },
       limit: 10
@@ -347,160 +442,105 @@ Exclude documents that contain specific values in arrays:
   <Tab title="Python">
     ```python
     results = client.search.documents(
-        q="team meetings",
+        q="project updates",
+        container_tags=["user_123"],
         filters={
             "AND": [
-                {
-                    "key": "participants",
-                    "value": "john.doe",
-                    "filterType": "array_contains",
-                    "negate": True  # Exclude meetings with john.doe
-                }
+                {"key": "category", "value": "work", "negate": False},
+                {"key": "visibility", "value": "private", "negate": False}
             ]
         },
         limit=10
     )
     ```
   </Tab>
-  <Tab title="cURL">
-    ```bash
-    curl -X POST "https://api.supermemory.ai/v3/search" \
-      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-      -H "Content-Type: application/json" \
-      -d '{
-        "q": "team meetings",
-        "filters": {
-          "AND": [
-            {
-              "key": "participants",
-              "value": "john.doe",
-              "filterType": "array_contains",
-              "negate": true
-            }
-          ]
-        },
-        "limit": 10
-      }'
-    ```
-  </Tab>
 </Tabs>
 
-### Multiple Array Contains Conditions
-
-Find documents with multiple required participants:
+### Recent High-Priority Content
 
 <Tabs>
   <Tab title="TypeScript">
     ```typescript
     const results = await client.search.documents({
-      q: "project planning",
+      q: "important tasks",
       filters: {
         AND: [
           {
-            key: "participants",
-            value: "project.manager",
-            filterType: "array_contains"
-          },
-          {
-            key: "participants",
-            value: "lead.developer",
-            filterType: "array_contains"
+            filterType: "numeric",
+            key: "priority",
+            value: "7",
+            numericOperator: ">=",
+            negate: false
           },
           {
-            key: "tags",
-            value: "urgent",
-            filterType: "array_contains"
+            filterType: "numeric",
+            key: "created_timestamp",
+            value: "1704067200", // 2024-01-01
+            numericOperator: ">=",
+            negate: false
           }
         ]
       },
-      limit: 10
+      limit: 20
     });
     ```
   </Tab>
   <Tab title="Python">
     ```python
     results = client.search.documents(
-        q="project planning",
+        q="important tasks",
         filters={
             "AND": [
                 {
-                    "key": "participants",
-                    "value": "project.manager",
-                    "filterType": "array_contains"
-                },
-                {
-                    "key": "participants",
-                    "value": "lead.developer",
-                    "filterType": "array_contains"
+                    "filterType": "numeric",
+                    "key": "priority",
+                    "value": "7",
+                    "numericOperator": ">=",
+                    "negate": False
                 },
                 {
-                    "key": "tags",
-                    "value": "urgent",
-                    "filterType": "array_contains"
+                    "filterType": "numeric",
+                    "key": "created_timestamp",
+                    "value": "1704067200",  # 2024-01-01
+                    "numericOperator": ">=",
+                    "negate": False
                 }
             ]
         },
-        limit=10
+        limit=20
     )
     ```
   </Tab>
-  <Tab title="cURL">
-    ```bash
-    curl -X POST "https://api.supermemory.ai/v3/search" \
-      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-      -H "Content-Type: application/json" \
-      -d '{
-        "q": "project planning",
-        "filters": {
-          "AND": [
-            {
-              "key": "participants",
-              "value": "project.manager",
-              "filterType": "array_contains"
-            },
-            {
-              "key": "participants",
-              "value": "lead.developer",
-              "filterType": "array_contains"
-            },
-            {
-              "key": "tags",
-              "value": "urgent",
-              "filterType": "array_contains"
-            }
-          ]
-        },
-        "limit": 10
-      }'
-    ```
-  </Tab>
 </Tabs>
 
-### Array Contains with OR Logic
-
-Find documents with any of several participants:
+### Team Collaboration Filter
 
 <Tabs>
   <Tab title="TypeScript">
     ```typescript
     const results = await client.search.documents({
-      q: "weekly reports",
+      q: "meeting notes",
+      containerTags: ["project_alpha"],
       filters: {
-        OR: [
-          {
-            key: "reviewers",
-            value: "senior.manager",
-            filterType: "array_contains"
-          },
+        AND: [
           {
-            key: "reviewers",
-            value: "department.head",
-            filterType: "array_contains"
+            OR: [
+              {
+                filterType: "array_contains",
+                key: "participants",
+                value: "alice"
+              },
+              {
+                filterType: "array_contains",
+                key: "participants",
+                value: "bob"
+              }
+            ]
           },
           {
-            key: "reviewers",
-            value: "project.lead",
-            filterType: "array_contains"
+            key: "type",
+            value: "meeting",
+            negate: false
           }
         ]
       },
@@ -511,23 +551,28 @@ Find documents with any of several participants:
   <Tab title="Python">
     ```python
     results = client.search.documents(
-        q="weekly reports",
+        q="meeting notes",
+        container_tags=["project_alpha"],
         filters={
-            "OR": [
-                {
-                    "key": "reviewers",
-                    "value": "senior.manager",
-                    "filterType": "array_contains"
-                },
+            "AND": [
                 {
-                    "key": "reviewers",
-                    "value": "department.head",
-                    "filterType": "array_contains"
+                    "OR": [
+                        {
+                            "filterType": "array_contains",
+                            "key": "participants",
+                            "value": "alice"
+                        },
+                        {
+                            "filterType": "array_contains",
+                            "key": "participants",
+                            "value": "bob"
+                        }
+                    ]
                 },
                 {
-                    "key": "reviewers",
-                    "value": "project.lead",
-                    "filterType": "array_contains"
+                    "key": "type",
+                    "value": "meeting",
+                    "negate": False
                 }
             ]
         },
@@ -535,63 +580,33 @@ Find documents with any of several participants:
     )
     ```
   </Tab>
-  <Tab title="cURL">
-    ```bash
-    curl -X POST "https://api.supermemory.ai/v3/search" \
-      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-      -H "Content-Type: application/json" \
-      -d '{
-        "q": "weekly reports",
-        "filters": {
-          "OR": [
-            {
-              "key": "reviewers",
-              "value": "senior.manager",
-              "filterType": "array_contains"
-            },
-            {
-              "key": "reviewers",
-              "value": "department.head",
-              "filterType": "array_contains"
-            },
-            {
-              "key": "reviewers",
-              "value": "project.lead",
-              "filterType": "array_contains"
-            }
-          ]
-        },
-        "limit": 15
-      }'
-    ```
-  </Tab>
 </Tabs>
 
-## OR Conditions
-
-Combine multiple conditions with OR logic:
+### Exclude Drafts and Deprecated Content
 
 <Tabs>
   <Tab title="TypeScript">
     ```typescript
     const results = await client.search.documents({
-      q: "technology updates",
+      q: "documentation",
       filters: {
-        OR: [
+        AND: [
           {
-            key: "category",
-            value: "ai",
-            negate: false
+            key: "status",
+            value: "draft",
+            negate: true  // Exclude drafts
           },
           {
-            key: "category",
-            value: "machine-learning",
-            negate: false
+            filterType: "string_contains",
+            key: "content",
+            value: "deprecated",
+            negate: true  // Exclude deprecated
           },
           {
-            key: "topic",
-            value: "neural-networks",
-            negate: false
+            filterType: "array_contains",
+            key: "tags",
+            value: "archived",
+            negate: true  // Exclude archived
           }
         ]
       },
@@ -602,23 +617,25 @@ Combine multiple conditions with OR logic:
   <Tab title="Python">
     ```python
     results = client.search.documents(
-        q="technology updates",
+        q="documentation",
         filters={
-            "OR": [
+            "AND": [
                 {
-                    "key": "category",
-                    "value": "ai",
-                    "negate": False
+                    "key": "status",
+                    "value": "draft",
+                    "negate": True  # Exclude drafts
                 },
                 {
-                    "key": "category",
-                    "value": "machine-learning",
-                    "negate": False
+                    "filterType": "string_contains",
+                    "key": "content",
+                    "value": "deprecated",
+                    "negate": True  # Exclude deprecated
                 },
                 {
-                    "key": "topic",
-                    "value": "neural-networks",
-                    "negate": False
+                    "filterType": "array_contains",
+                    "key": "tags",
+                    "value": "archived",
+                    "negate": True  # Exclude archived
                 }
             ]
         },
@@ -626,434 +643,260 @@ Combine multiple conditions with OR logic:
     )
     ```
   </Tab>
-  <Tab title="cURL">
-    ```bash
-    curl -X POST "https://api.supermemory.ai/v3/search" \
-      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-      -H "Content-Type: application/json" \
-      -d '{
-        "q": "technology updates",
-        "filters": {
-          "OR": [
-            {
-              "key": "category",
-              "value": "ai",
-              "negate": false
-            },
-            {
-              "key": "category",
-              "value": "machine-learning",
-              "negate": false
-            },
-            {
-              "key": "topic",
-              "value": "neural-networks",
-              "negate": false
-            }
-          ]
-        },
-        "limit": 10
-      }'
-    ```
-  </Tab>
 </Tabs>
 
-## Complex Nested Conditions
+## API-Specific Notes
+
+Different endpoints have slightly different requirements:
+
+| Endpoint | Container Tag Field | Type | Filter Format | Notes |
+|----------|---------------------|------|---------------|-------|
+| `/v3/search` | `containerTags` | Array | JSON object | Document search |
+| `/v4/search` | `containerTag` | String | JSON object | Memory search |
+| `/v3/documents/list` | `containerTags` | Array | **JSON string** | Must use `JSON.stringify()` |
+
+<Warning>
+**List API Special Requirement**: The `/v3/documents/list` endpoint requires filters as a JSON string:
+
+```javascript
+// ✅ Correct for List API
+filters: JSON.stringify({ AND: [...] })
+
+// ❌ Wrong for List API (but correct for Search API)
+filters: { AND: [...] }
+```
+</Warning>
+
+## Combining Container Tags and Metadata
+
+Most real-world applications combine both filtering types for precise control.
 
-Combine AND and OR logic for advanced filtering:
+### Example: User's Work Documents from 2024
 
 <Tabs>
   <Tab title="TypeScript">
     ```typescript
     const results = await client.search.documents({
-      q: "research publications",
+      q: "quarterly report",
+      containerTags: ["user_123"],  // User isolation
       filters: {
         AND: [
-          {
-            key: "status",
-            value: "published",
-            negate: false
-          },
-          {
-            OR: [
-              {
-                key: "category",
-                value: "ai",
-                negate: false
-              },
-              {
-                key: "category",
-                value: "machine-learning",
-                negate: false
-              }
-            ]
-          },
+          { key: "category", value: "work" },
+          { key: "type", value: "report" },
           {
             filterType: "numeric",
             key: "year",
-            value: "2023",
-            numericOperator: ">=",
-            negate: false
+            value: "2024",
+            numericOperator: "="
           }
         ]
       },
-      limit: 15
+      limit: 10
     });
     ```
   </Tab>
   <Tab title="Python">
     ```python
     results = client.search.documents(
-        q="research publications",
+        q="quarterly report",
+        container_tags=["user_123"],  # User isolation
         filters={
             "AND": [
-                {
-                    "key": "status",
-                    "value": "published",
-                    "negate": False
-                },
-                {
-                    "OR": [
-                        {
-                            "key": "category",
-                            "value": "ai",
-                            "negate": False
-                        },
-                        {
-                            "key": "category",
-                            "value": "machine-learning",
-                            "negate": False
-                        }
-                    ]
-                },
+                {"key": "category", "value": "work"},
+                {"key": "type", "value": "report"},
                 {
                     "filterType": "numeric",
                     "key": "year",
-                    "value": "2023",
-                    "numericOperator": ">=",
-                    "negate": False
+                    "value": "2024",
+                    "numericOperator": "="
                 }
             ]
         },
-        limit=15
+        limit=10
     )
     ```
   </Tab>
-  <Tab title="cURL">
-    ```bash
-    curl -X POST "https://api.supermemory.ai/v3/search" \
-      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-      -H "Content-Type: application/json" \
-      -d '{
-        "q": "research publications",
-        "filters": {
-          "AND": [
-            {
-              "key": "status",
-              "value": "published",
-              "negate": false
-            },
-            {
-              "OR": [
-                {
-                  "key": "category",
-                  "value": "ai",
-                  "negate": false
-                },
-                {
-                  "key": "category",
-                  "value": "machine-learning",
-                  "negate": false
-                }
-              ]
-            },
-            {
-              "filterType": "numeric",
-              "key": "year",
-              "value": "2023",
-              "numericOperator": ">=",
-              "negate": false
-            }
-          ]
-        },
-        "limit": 15
-      }'
-    ```
-  </Tab>
 </Tabs>
 
-## Negation Filters
-
-Exclude specific values with negation:
+### Example: Project's Active High-Priority Tasks
 
 <Tabs>
   <Tab title="TypeScript">
     ```typescript
     const results = await client.search.documents({
-      q: "machine learning",
+      q: "implementation",
+      containerTags: ["project_alpha"],  // Project isolation
       filters: {
         AND: [
           {
-            key: "category",
-            value: "ai",
-            negate: false
+            key: "status",
+            value: "completed",
+            negate: true  // Not completed
           },
           {
-            key: "status",
-            value: "draft",
-            negate: true  // Exclude drafts
+            filterType: "numeric",
+            key: "priority",
+            value: "7",
+            numericOperator: ">=",
+            negate: false
           },
           {
-            key: "author",
-            value: "deprecated_user",
-            negate: true  // Exclude specific author
+            filterType: "array_contains",
+            key: "assignees",
+            value: "current_user"
           }
         ]
       },
-      limit: 10
+      limit: 20
     });
     ```
   </Tab>
   <Tab title="Python">
     ```python
     results = client.search.documents(
-        q="machine learning",
+        q="implementation",
+        container_tags=["project_alpha"],  # Project isolation
         filters={
             "AND": [
                 {
-                    "key": "category",
-                    "value": "ai",
-                    "negate": False
+                    "key": "status",
+                    "value": "completed",
+                    "negate": True  # Not completed
                 },
                 {
-                    "key": "status",
-                    "value": "draft",
-                    "negate": True  # Exclude drafts
+                    "filterType": "numeric",
+                    "key": "priority",
+                    "value": "7",
+                    "numericOperator": ">=",
+                    "negate": False
                 },
                 {
-                    "key": "author",
-                    "value": "deprecated_user",
-                    "negate": True  # Exclude specific author
+                    "filterType": "array_contains",
+                    "key": "assignees",
+                    "value": "current_user"
                 }
             ]
         },
-        limit=10
+        limit=20
     )
     ```
   </Tab>
-  <Tab title="cURL">
-    ```bash
-    curl -X POST "https://api.supermemory.ai/v3/search" \
-      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-      -H "Content-Type: application/json" \
-      -d '{
-        "q": "machine learning",
-        "filters": {
-          "AND": [
-            {
-              "key": "category",
-              "value": "ai",
-              "negate": false
-            },
-            {
-              "key": "status",
-              "value": "draft",
-              "negate": true
-            },
-            {
-              "key": "author",
-              "value": "deprecated_user",
-              "negate": true
-            }
-          ]
-        },
-        "limit": 10
-      }'
-    ```
-  </Tab>
 </Tabs>
 
 ## Document-Specific Search
 
-Search within a specific document:
+Search within a single large document using the `docId` parameter:
 
 <Tabs>
   <Tab title="TypeScript">
     ```typescript
+    // Search within a specific book or manual
     const results = await client.search.documents({
-      q: "neural network architecture",
-      docId: "doc_large_textbook_123",  // Search only within this document
+      q: "neural architecture",
+      docId: "doc_textbook_ml_2024",
       limit: 20
     });
     ```
   </Tab>
   <Tab title="Python">
     ```python
+    # Search within a specific book or manual
     results = client.search.documents(
-        q="neural network architecture",
-        doc_id="doc_large_textbook_123",  # Search only within this document
+        q="neural architecture",
+        doc_id="doc_textbook_ml_2024",
         limit=20
     )
     ```
   </Tab>
-  <Tab title="cURL">
-    ```bash
-    curl -X POST "https://api.supermemory.ai/v3/search" \
-      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-      -H "Content-Type: application/json" \
-      -d '{
-        "q": "neural network architecture",
-        "docId": "doc_large_textbook_123",
-        "limit": 20
-      }'
-    ```
-  </Tab>
 </Tabs>
 
-## Filter Best Practices
+Use this for:
+- Large textbooks or manuals
+- Multi-chapter books
+- Long podcast transcripts
+- Course materials
+
+## Validation & Limits
+
+### Metadata Key Requirements
+- **Pattern**: `/^[a-zA-Z0-9_.-]+$/`
+- **Allowed**: Letters, numbers, underscore, hyphen, dot
+- **Max length**: 64 characters
+- **No spaces or special characters**
+
+### Valid vs Invalid Keys
+```javascript
+// ✅ Valid keys
+"user_email"
+"created-date"
+"version.number"
+"priority_level_2"
+
+// ❌ Invalid keys
+"user email"        // Spaces not allowed
+"created@date"      // @ not allowed
+"priority!"         // ! not allowed
+"very_long_key_name_that_exceeds_64_characters_limit"  // Too long
+```
 
-<Callout type="info">
-**Performance Tips**:
-- Use container tags as the primary filter (fastest)
-- Combine with simple metadata filters for precision
-- Avoid complex nested OR conditions for better performance
-- Use numeric operators only when necessary
-</Callout>
+### Query Complexity Limits
+- **Maximum conditions**: 200 per query
+- **Maximum nesting depth**: 8 levels
+- **Container tag arrays**: Must match exactly
 
-<Warning>
-**Filter Structure**: All conditions must be wrapped in `AND` or `OR` arrays. Single conditions still need the array wrapper: `{"AND": [{"key": "category", "value": "ai"}]}`.
-</Warning>
+## Troubleshooting
 
-<Note>
-**Supported Operators**:
-- **String**: Exact matching only
-- **Numeric**: `<=`, `>=`, `<`, `>`, `=`
-- **Array**: `array_contains` for checking if array contains value
-- **Negation**: Works with all filter types
-</Note>
+### No Results Returned
 
-## Common Filter Patterns
+<AccordionGroup>
+  <Accordion title="Container tag mismatch">
+    **Problem**: Container tags must match exactly as arrays.
 
-### User-Specific Content
-```json
-{
-  "containerTags": ["user_123"],
-  "filters": {
-    "AND": [
-      {"key": "visibility", "value": "private", "negate": false}
-    ]
-  }
-}
-```
+    **Solution**: Verify the exact array structure. `["user_123"]` ≠ `["user_123", "project_1"]`
+  </Accordion>
+  <Accordion title="Wrong metadata key casing">
+    **Problem**: Keys are case-sensitive by default.
 
-### Recent High-Quality Content
-```json
-{
-  "filters": {
-    "AND": [
-      {
-        "filterType": "numeric",
-        "key": "created_year",
-        "value": "2024",
-        "numericOperator": ">="
-      },
-      {
-        "filterType": "numeric",
-        "key": "quality_score",
-        "value": "7",
-        "numericOperator": ">="
-      }
-    ]
-  }
-}
-```
+    **Solution**: Check exact key spelling and casing, or use `ignoreCase: true` for values.
+  </Accordion>
+  <Accordion title="Incorrect negate value">
+    **Problem**: Using `negate: true` when you meant `false`.
 
-### Multi-Category Search
-```json
-{
-  "filters": {
-    "OR": [
-      {"key": "category", "value": "ai"},
-      {"key": "category", "value": "machine-learning"},
-      {"key": "category", "value": "data-science"}
-    ]
-  }
-}
-```
+    **Solution**: Review your negate values. `false` = include, `true` = exclude.
+  </Accordion>
+</AccordionGroup>
 
-### Team Member Participation
-```json
-{
-  "filters": {
-    "AND": [
-      {
-        "key": "participants",
-        "value": "team.lead",
-        "filterType": "array_contains"
-      },
-      {
-        "key": "project_tags",
-        "value": "high-priority",
-        "filterType": "array_contains"
-      }
-    ]
-  }
-}
-```
+### Validation Errors
 
-### Exclude Specific Teams
-```json
-{
-  "filters": {
-    "AND": [
-      {
-        "key": "department",
-        "value": "marketing",
-        "filterType": "array_contains",
-        "negate": true
-      },
-      {
-        "key": "confidential_tags",
-        "value": "executive-only",
-        "filterType": "array_contains",
-        "negate": true
-      }
-    ]
-  }
-}
-```
+<AccordionGroup>
+  <Accordion title="Invalid metadata key format">
+    **Error**: "Invalid metadata key: contains unsafe characters"
 
-### Complex Meeting Filter
-```json
-{
-  "filters": {
-    "AND": [
-      {
-        "OR": [
-          {
-            "key": "attendees",
-            "value": "ceo",
-            "filterType": "array_contains"
-          },
-          {
-            "key": "attendees",
-            "value": "cto",
-            "filterType": "array_contains"
-          }
-        ]
-      },
-      {
-        "key": "meeting_type",
-        "value": "cancelled",
-        "negate": true
-      },
-      {
-        "filterType": "numeric",
-        "key": "duration_minutes",
-        "value": "30",
-        "numericOperator": ">="
-      }
-    ]
-  }
-}
-```
+    **Solution**: Remove spaces, special characters. Use only alphanumeric, underscore, hyphen, dot.
+  </Accordion>
+  <Accordion title="Filter structure error">
+    **Error**: "Invalid filter structure"
+
+    **Solution**: Ensure all conditions are wrapped in AND or OR arrays.
+  </Accordion>
+  <Accordion title="List API filter error">
+    **Error**: "Invalid filter format"
+
+    **Solution**: For `/v3/documents/list`, use `JSON.stringify()` on the filter object.
+  </Accordion>
+</AccordionGroup>
+
+### Performance Issues
+
+<AccordionGroup>
+  <Accordion title="Slow queries">
+    **Problem**: Complex nested OR conditions with many branches.
+
+    **Solution**: Simplify logic, reduce nesting, or split into multiple queries.
+  </Accordion>
+  <Accordion title="Hitting complexity limits">
+    **Problem**: "Query exceeds maximum complexity"
+
+    **Solution**: Reduce conditions (max 200) or nesting depth (max 8).
+  </Accordion>
+</AccordionGroup>
\ No newline at end of file