fix(qdrant): deduplicate $or/$not keys and add icontains debug warning

Memory._process_metadata_filters() renames OR→$or and NOT→$not, but
effective_filters also retains the original OR/NOT keys from the
deepcopy of input_filters. Without dedup, the same sub-conditions were
evaluated twice in the Qdrant filter.

Normalize the filter dict upfront so $or/$not/$and map to OR/NOT/AND
and only the first occurrence is kept. Also replace the fragile
value.get("contains") or value.get("icontains") pattern with explicit
key lookup, and add a logger.debug for icontains explaining that Qdrant
MatchText case sensitivity depends on full-text index configuration.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs/openapi.json

@@ -4539,7 +4539,7 @@
 				"x-code-samples": [
 					{
 						"lang": "Python",
-						"source": "# To use the Python SDK, install the package:\n# pip install mem0ai\n\nfrom mem0 import MemoryClient\nclient = MemoryClient(api_key=\"your_api_key\")\n\n# Get all webhooks\nwebhooks = client.get_webhooks(project_id=\"your_project_id\")\nprint(webhooks)\n\n# Create a webhook\nwebhook = client.create_webhook(\n    url=\"https://your-webhook-url.com\",\n    name=\"My Webhook\",\n    project_id=\"your_project_id\",\n    event_types=[\"memory:add\"]\n)\nprint(webhook)"
+						"source": "# To use the Python SDK, install the package:\n# pip install mem0ai\n\nfrom mem0 import MemoryClient\nclient = MemoryClient(api_key=\"your_api_key\")\n\n# Get all webhooks\nwebhooks = client.get_webhooks(project_id=\"your_project_id\")\nprint(webhooks)\n\n# Create a webhook\nwebhook = client.create_webhook(\n    url=\"https://your-webhook-url.com\",\n    name=\"My Webhook\",\n    project_id=\"your_project_id\",\n    event_types=[\"memory:add\", \"memory:categorize\"]\n)\nprint(webhook)"
 					},
 					{
 						"lang": "JavaScript",
@@ -4606,7 +4606,8 @@
 											"enum": [
 												"memory:add",
 												"memory:update",
-												"memory:delete"
+												"memory:delete",
+												"memory:categorize"
 											]
 										},
 										"description": "List of event types to subscribe to."
@@ -4701,7 +4702,7 @@
 				"x-code-samples": [
 					{
 						"lang": "Python",
-						"source": "# To use the Python SDK, install the package:\n# pip install mem0ai\n\nfrom mem0 import MemoryClient\nclient = MemoryClient(api_key=\"your_api_key\", org_id=\"your_org_id\", project_id=\"your_project_id\")\n\n# Create a webhook\nwebhook = client.create_webhook(\n    url=\"https://your-webhook-url.com\",\n    name=\"My Webhook\",\n    project_id=\"your_project_id\",\n    event_types=[\"memory:add\"]\n)\nprint(webhook)"
+						"source": "# To use the Python SDK, install the package:\n# pip install mem0ai\n\nfrom mem0 import MemoryClient\nclient = MemoryClient(api_key=\"your_api_key\", org_id=\"your_org_id\", project_id=\"your_project_id\")\n\n# Create a webhook\nwebhook = client.create_webhook(\n    url=\"https://your-webhook-url.com\",\n    name=\"My Webhook\",\n    project_id=\"your_project_id\",\n    event_types=[\"memory:add\", \"memory:categorize\"]\n)\nprint(webhook)"
 					},
 					{
 						"lang": "JavaScript",
@@ -4767,7 +4768,8 @@
 											"enum": [
 												"memory:add",
 												"memory:update",
-												"memory:delete"
+												"memory:delete",
+												"memory:categorize"
 											]
 										},
 										"description": "New list of event types to subscribe to"
@@ -4845,11 +4847,11 @@
 				"x-code-samples": [
 					{
 						"lang": "Python",
-						"source": "# To use the Python SDK, install the package:\n# pip install mem0ai\n\nfrom mem0 import MemoryClient\nclient = MemoryClient(api_key=\"your_api_key\")\n\n# Update a webhook\nwebhook = client.update_webhook(\n    webhook_id=\"your_webhook_id\",\n    name=\"Updated Webhook\",\n    url=\"https://new-webhook-url.com\",\n    event_types=[\"memory:add\"]\n)\nprint(webhook)\n\n# Delete a webhook\nresponse = client.delete_webhook(webhook_id=\"your_webhook_id\")\nprint(response)"
+						"source": "# To use the Python SDK, install the package:\n# pip install mem0ai\n\nfrom mem0 import MemoryClient\nclient = MemoryClient(api_key=\"your_api_key\")\n\n# Update a webhook\nwebhook = client.update_webhook(\n    webhook_id=\"your_webhook_id\",\n    name=\"Updated Webhook\",\n    url=\"https://new-webhook-url.com\",\n    event_types=[\"memory:add\", \"memory:categorize\"]\n)\nprint(webhook)\n\n# Delete a webhook\nresponse = client.delete_webhook(webhook_id=\"your_webhook_id\")\nprint(response)"
 					},
 					{
 						"lang": "JavaScript",
-						"source": "// To use the JavaScript SDK, install the package:\n// npm i mem0ai\n\nimport MemoryClient from 'mem0ai';\nconst client = new MemoryClient({ apiKey: 'your-api-key' });\n\n// Update a webhook\nclient.updateWebhook('your_webhook_id', {\n  name: 'Updated Webhook',\n  url: 'https://new-webhook-url.com',\n  event_types: ['memory:add']\n})\n  .then(webhook => console.log(webhook))\n  .catch(err => console.error(err));\n\n// Delete a webhook\nclient.deleteWebhook('your_webhook_id')\n  .then(response => console.log(response))\n  .catch(err => console.error(err));"
+						"source": "// To use the JavaScript SDK, install the package:\n// npm i mem0ai\n\nimport MemoryClient from 'mem0ai';\nconst client = new MemoryClient({ apiKey: 'your-api-key' });\n\n// Update a webhook\nclient.updateWebhook('your_webhook_id', {\n  name: 'Updated Webhook',\n  url: 'https://new-webhook-url.com',\n  event_types: ['memory:add', 'memory:categorize']\n})\n  .then(webhook => console.log(webhook))\n  .catch(err => console.error(err));\n\n// Delete a webhook\nclient.deleteWebhook('your_webhook_id')\n  .then(response => console.log(response))\n  .catch(err => console.error(err));"
 					},
 					{
 						"lang": "cURL",

docs/platform/features/webhooks.mdx

@@ -5,7 +5,7 @@ description: 'Configure and manage webhooks to receive real-time notifications a
 
 ## Overview
 
-Webhooks enable real-time notifications for memory events in your Mem0 project. Webhooks are configured at the project level, meaning each webhook is tied to a specific project and receives events solely from that project. You can configure webhooks to send HTTP POST requests to your specified URLs whenever memories are created, updated, or deleted.
+Webhooks enable real-time notifications for memory events in your Mem0 project. Webhooks are configured at the project level, meaning each webhook is tied to a specific project and receives events solely from that project. You can configure webhooks to send HTTP POST requests to your specified URLs whenever memories are created, updated, deleted, or categorized.
 
 ## Managing Webhooks
 
@@ -27,7 +27,7 @@ webhook = client.create_webhook(
     url="https://your-app.com/webhook",
     name="Memory Logger",
     project_id="proj_123",
-    event_types=["memory_add"]
+    event_types=["memory_add", "memory_categorize"]
 )
 print(webhook)
 ```
@@ -41,7 +41,7 @@ const webhook = await client.createWebhook({
     url: "https://your-app.com/webhook",
     name: "Memory Logger",
     projectId: "proj_123",
-    eventTypes: ["memory_add"]
+    eventTypes: ["memory_add", "memory_categorize"]
 });
 console.log(webhook);
 ```
@@ -167,11 +167,13 @@ Mem0 supports the following event types for webhooks:
 - `memory_add`: Triggered when a memory is added.
 - `memory_update`: Triggered when an existing memory is updated.
 - `memory_delete`: Triggered when a memory is deleted.
+- `memory_categorize`: Triggered when a memory is categorized.
 
 ## Webhook Payload
 
 When a memory event occurs, Mem0 sends an HTTP POST request to your webhook URL with the following payload:
 
+**Memory add/update/delete payload:**
 ```json
 {
     "event_details": {
@@ -184,6 +186,17 @@ When a memory event occurs, Mem0 sends an HTTP POST request to your webhook URL
 }
 ```
 
+**Memory categorize payload:**
+```json
+{
+    "event_details": {
+        "event": "CATEGORIZE",
+        "memory_id": "a1b2c3d4-e5f6-4g7h-8i9j-k0l1m2n3o4p5",
+        "categories": ["hobbies", "travel"]
+    }
+}
+```
+
 ## Best Practices
 
 1. **Implement Retry Logic**: Ensure your webhook endpoint can handle temporary failures.

mem0-ts/src/oss/src/embeddings/ollama.ts

@@ -27,9 +27,12 @@ export class OllamaEmbedder implements Embedder {
     } catch (err) {
       logger.error(`Error ensuring model exists: ${err}`);
     }
+    // Ollama's Go server requires prompt to be a string. Coerce defensively
+    // since callers may pass values parsed from untrusted LLM JSON output.
+    const prompt = typeof text === "string" ? text : JSON.stringify(text);
     const response = await this.ollama.embeddings({
       model: this.model,
-      prompt: text,
+      prompt,
     });
     return response.embedding;
   }

mem0-ts/src/oss/src/memory/index.ts

@@ -15,6 +15,7 @@ import {
   HistoryManagerFactory,
 } from "../utils/factory";
 import {
+  FactRetrievalSchema,
   getFactRetrievalMessages,
   getUpdateMemoryMessages,
   parseMessages,
@@ -261,7 +262,8 @@ export class Memory {
     const cleanResponse = removeCodeBlocks(response as string);
     let facts: string[] = [];
     try {
-      facts = JSON.parse(cleanResponse).facts || [];
+      const parsed = FactRetrievalSchema.parse(JSON.parse(cleanResponse));
+      facts = parsed.facts;
     } catch (e) {
       console.error(
         "Failed to parse facts from LLM response:",

mem0-ts/src/oss/src/prompts/index.ts

@@ -1,9 +1,18 @@
 import { z } from "zod";
 
+// Accepts a string directly, or an object with a "fact" or "text" key
+// (common malformed shapes from smaller LLMs like llama3.1:8b).
+const factItem = z.union([
+  z.string(),
+  z.object({ fact: z.string() }).transform((o) => o.fact),
+  z.object({ text: z.string() }).transform((o) => o.text),
+]);
+
 // Define Zod schema for fact retrieval output
 export const FactRetrievalSchema = z.object({
   facts: z
-    .array(z.string())
+    .array(factItem)
+    .transform((arr) => arr.filter((s) => s.length > 0))
     .describe("An array of distinct facts extracted from the conversation."),
 });
 

mem0/vector_stores/qdrant.py

@@ -1,12 +1,16 @@
 import logging
 import os
 import shutil
+from typing import Optional
 
 from qdrant_client import QdrantClient
 from qdrant_client.models import (
     Distance,
     FieldCondition,
     Filter,
+    MatchAny,
+    MatchExcept,
+    MatchText,
     MatchValue,
     PointIdsList,
     PointStruct,
@@ -138,26 +142,139 @@ class Qdrant(VectorStoreBase):
         ]
         self.client.upsert(collection_name=self.collection_name, points=points)
 
-    def _create_filter(self, filters: dict) -> Filter:
+    def _build_field_condition(self, key: str, value) -> Optional[FieldCondition]:
+        """
+        Build a single FieldCondition from a key-value filter pair.
+
+        Supports the enhanced filter syntax documented at
+        https://docs.mem0.ai/open-source/features/metadata-filtering
+
+        Args:
+            key (str): The payload field name.
+            value: A scalar for simple equality, or a dict with one operator key.
+
+        Returns:
+            Optional[FieldCondition]: The Qdrant field condition, or None if the
+            value is the wildcard '*' (match any / field exists — skip filter).
+        """
+        if not isinstance(value, dict):
+            if value == "*":
+                # Wildcard: match any value. Qdrant has no direct "field exists"
+                # condition via FieldCondition, so we skip this filter (match all).
+                return None
+            # Simple equality: {"field": "value"}
+            return FieldCondition(key=key, match=MatchValue(value=value))
+
+        ops = set(value.keys())
+        range_ops = {"gt", "gte", "lt", "lte"}
+        non_range_ops = ops - range_ops
+
+        if ops & range_ops:
+            if non_range_ops:
+                raise ValueError(
+                    f"Cannot mix range operators ({ops & range_ops}) with "
+                    f"non-range operators ({non_range_ops}) for field '{key}'. "
+                    f"Use AND to combine them as separate conditions."
+                )
+            range_kwargs = {op: value[op] for op in range_ops if op in value}
+            return FieldCondition(key=key, range=Range(**range_kwargs))
+        elif "eq" in value:
+            return FieldCondition(key=key, match=MatchValue(value=value["eq"]))
+        elif "ne" in value:
+            return FieldCondition(key=key, match=MatchExcept(**{"except": [value["ne"]]}))
+        elif "in" in value:
+            return FieldCondition(key=key, match=MatchAny(any=value["in"]))
+        elif "nin" in value:
+            return FieldCondition(key=key, match=MatchExcept(**{"except": value["nin"]}))
+        elif "contains" in value or "icontains" in value:
+            # MatchText: with a full-text index, tokenized matching (all words must appear).
+            # Without a full-text index, exact substring match.
+            op = "icontains" if "icontains" in value else "contains"
+            text = value[op]
+            if op == "icontains":
+                logger.debug(
+                    "icontains on field '%s': Qdrant MatchText case sensitivity depends on "
+                    "full-text index configuration. Without a full-text index this behaves "
+                    "as a case-sensitive substring match (same as 'contains').",
+                    key,
+                )
+            return FieldCondition(key=key, match=MatchText(text=text))
+        else:
+            supported = {"eq", "ne", "gt", "gte", "lt", "lte", "in", "nin", "contains", "icontains"}
+            raise ValueError(
+                f"Unsupported filter operator(s) for field '{key}': {ops}. "
+                f"Supported operators: {supported}"
+            )
+
+    def _create_filter(self, filters: dict) -> Optional[Filter]:
         """
         Create a Filter object from the provided filters.
 
+        Supports the enhanced filter syntax with comparison operators (eq, ne,
+        gt, gte, lt, lte), list operators (in, nin), string operators (contains,
+        icontains), and logical operators (AND, OR, NOT).
+
         Args:
             filters (dict): Filters to apply.
 
         Returns:
-            Filter: The created Filter object.
+            Filter: The created Filter object, or None if filters is empty.
         """
         if not filters:
             return None
-            
-        conditions = []
+
+        # Normalize $or/$not/$and → OR/NOT/AND and deduplicate.
+        # Memory._process_metadata_filters() renames OR→$or and NOT→$not,
+        # but effective_filters retains the original OR/NOT keys from
+        # deepcopy(input_filters).  Without dedup the same sub-conditions
+        # would be evaluated twice.
+        key_map = {"$or": "OR", "$not": "NOT", "$and": "AND"}
+        normalized = {}
         for key, value in filters.items():
-            if isinstance(value, dict) and "gte" in value and "lte" in value:
-                conditions.append(FieldCondition(key=key, range=Range(gte=value["gte"], lte=value["lte"])))
+            norm_key = key_map.get(key, key)
+            if norm_key not in normalized:
+                normalized[norm_key] = value
+
+        must = []
+        should = []
+        must_not = []
+
+        for key, value in normalized.items():
+            if key in ("AND", "OR", "NOT"):
+                if not isinstance(value, list):
+                    raise ValueError(
+                        f"{key} filter value must be a list of filter dicts, "
+                        f"got {type(value).__name__}"
+                    )
+
+            if key == "AND":
+                for sub in value:
+                    built = self._create_filter(sub)
+                    if built:
+                        must.append(built)
+            elif key == "OR":
+                for sub in value:
+                    built = self._create_filter(sub)
+                    if built:
+                        should.append(built)
+            elif key == "NOT":
+                for sub in value:
+                    built = self._create_filter(sub)
+                    if built:
+                        must_not.append(built)
             else:
-                conditions.append(FieldCondition(key=key, match=MatchValue(value=value)))
-        return Filter(must=conditions) if conditions else None
+                condition = self._build_field_condition(key, value)
+                if condition is not None:
+                    must.append(condition)
+
+        if not any([must, should, must_not]):
+            return None
+
+        return Filter(
+            must=must or None,
+            should=should or None,
+            must_not=must_not or None,
+        )
 
     def search(self, query: str, vectors: list, limit: int = 5, filters: dict = None) -> list:
         """

openclaw/index.ts

@@ -56,6 +56,7 @@ interface AddOptions {
   custom_categories?: Array<Record<string, string>>;
   enable_graph?: boolean;
   output_format?: string;
+  source?: string;
 }
 
 interface SearchOptions {
@@ -66,12 +67,14 @@ interface SearchOptions {
   limit?: number;
   keyword_search?: boolean;
   reranking?: boolean;
+  source?: string;
 }
 
 interface ListOptions {
   user_id: string;
   run_id?: string;
   page_size?: number;
+  source?: string;
 }
 
 interface MemoryItem {
@@ -152,6 +155,7 @@ class PlatformProvider implements Mem0Provider {
       opts.custom_categories = options.custom_categories;
     if (options.enable_graph) opts.enable_graph = options.enable_graph;
     if (options.output_format) opts.output_format = options.output_format;
+    if (options.source) opts.source = options.source;
 
     const result = await this.client.add(messages, opts);
     return normalizeAddResult(result);
@@ -165,6 +169,7 @@ class PlatformProvider implements Mem0Provider {
     if (options.threshold != null) opts.threshold = options.threshold;
     if (options.keyword_search != null) opts.keyword_search = options.keyword_search;
     if (options.reranking != null) opts.reranking = options.reranking;
+    if (options.source) opts.source = options.source;
 
     const results = await this.client.search(query, opts);
     return normalizeSearchResults(results);
@@ -181,6 +186,7 @@ class PlatformProvider implements Mem0Provider {
     const opts: Record<string, unknown> = { user_id: options.user_id };
     if (options.run_id) opts.run_id = options.run_id;
     if (options.page_size != null) opts.page_size = options.page_size;
+    if (options.source) opts.source = options.source;
 
     const results = await this.client.getAll(opts);
     if (Array.isArray(results)) return results.map(normalizeMemoryItem);
@@ -247,6 +253,7 @@ class OSSProvider implements Mem0Provider {
     // OSS SDK uses camelCase: userId/runId, not user_id/run_id
     const addOpts: Record<string, unknown> = { userId: options.user_id };
     if (options.run_id) addOpts.runId = options.run_id;
+    if (options.source) addOpts.source = options.source;
     const result = await this.memory.add(messages, addOpts);
     return normalizeAddResult(result);
   }
@@ -260,9 +267,18 @@ class OSSProvider implements Mem0Provider {
     else if (options.top_k != null) opts.limit = options.top_k;
     if (options.keyword_search != null) opts.keyword_search = options.keyword_search;
     if (options.reranking != null) opts.reranking = options.reranking;
+    if (options.source) opts.source = options.source;
+    if (options.threshold != null) opts.threshold = options.threshold;
 
     const results = await this.memory.search(query, opts);
-    return normalizeSearchResults(results);
+    const normalized = normalizeSearchResults(results);
+
+    // Filter results by threshold if specified (client-side filtering as fallback)
+    if (options.threshold != null) {
+      return normalized.filter(item => (item.score ?? 0) >= options.threshold!);
+    }
+
+    return normalized;
   }
 
   async get(memoryId: string): Promise<MemoryItem> {
@@ -276,6 +292,7 @@ class OSSProvider implements Mem0Provider {
     // OSS SDK uses camelCase: userId/runId, not user_id/run_id
     const getAllOpts: Record<string, unknown> = { userId: options.user_id };
     if (options.run_id) getAllOpts.runId = options.run_id;
+    if (options.source) getAllOpts.source = options.source;
     const results = await this.memory.getAll(getAllOpts);
     if (Array.isArray(results)) return results.map(normalizeMemoryItem);
     if (results?.results && Array.isArray(results.results))
@@ -615,6 +632,7 @@ const memoryPlugin = {
     function buildAddOptions(userIdOverride?: string, runId?: string): AddOptions {
       const opts: AddOptions = {
         user_id: userIdOverride || cfg.userId,
+        source: "OPENCLAW",
       };
       if (runId) opts.run_id = runId;
       if (cfg.mode === "platform") {
@@ -639,6 +657,7 @@ const memoryPlugin = {
         threshold: cfg.searchThreshold,
         keyword_search: true,
         reranking: true,
+        source: "OPENCLAW",
       };
       if (runId) opts.run_id = runId;
       return opts;
@@ -931,18 +950,20 @@ const memoryPlugin = {
                 memories = await provider.getAll({
                   user_id: uid,
                   run_id: currentSessionId,
+                  source: "OPENCLAW",
                 });
               }
             } else if (scope === "long-term") {
-              memories = await provider.getAll({ user_id: uid });
+              memories = await provider.getAll({ user_id: uid, source: "OPENCLAW" });
             } else {
               // "all" — combine both scopes
-              const longTerm = await provider.getAll({ user_id: uid });
+              const longTerm = await provider.getAll({ user_id: uid, source: "OPENCLAW" });
               let session: MemoryItem[] = [];
               if (currentSessionId) {
                 session = await provider.getAll({
                   user_id: uid,
                   run_id: currentSessionId,
+                  source: "OPENCLAW",
                 });
               }
               const seen = new Set(longTerm.map((r) => r.id));
@@ -1195,6 +1216,7 @@ const memoryPlugin = {
             try {
               const memories = await provider.getAll({
                 user_id: cfg.userId,
+                source: "OPENCLAW",
               });
               console.log(`Mode: ${cfg.mode}`);
               console.log(`User: ${cfg.userId}`);

openclaw/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mem0/openclaw-mem0",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "Mem0 memory backend for OpenClaw — platform or self-hosted open-source",
   "license": "Apache-2.0",

tests/vector_stores/test_qdrant.py

@@ -5,9 +5,15 @@ from unittest.mock import MagicMock
 from qdrant_client import QdrantClient
 from qdrant_client.models import (
     Distance,
+    FieldCondition,
     Filter,
+    MatchAny,
+    MatchExcept,
+    MatchText,
+    MatchValue,
     PointIdsList,
     PointStruct,
+    Range,
     VectorParams,
 )
 
@@ -298,3 +304,433 @@ class TestQdrant(unittest.TestCase):
 
     def tearDown(self):
         del self.qdrant
+
+
+class TestQdrantEnhancedFilters(unittest.TestCase):
+    """Tests for enhanced metadata filtering operators (issue #3975)."""
+
+    def setUp(self):
+        self.client_mock = MagicMock(spec=QdrantClient)
+        self.qdrant = Qdrant(
+            collection_name="test_collection",
+            embedding_model_dims=128,
+            client=self.client_mock,
+        )
+
+    # ------------------------------------------------------------------ #
+    # _build_field_condition                                               #
+    # ------------------------------------------------------------------ #
+
+    def test_simple_equality(self):
+        """Plain value maps to MatchValue."""
+        cond = self.qdrant._build_field_condition("category", "programming")
+        self.assertIsInstance(cond, FieldCondition)
+        self.assertEqual(cond.key, "category")
+        self.assertIsInstance(cond.match, MatchValue)
+        self.assertEqual(cond.match.value, "programming")
+
+    def test_eq_operator(self):
+        """{\"eq\": v} maps to MatchValue."""
+        cond = self.qdrant._build_field_condition("category", {"eq": "programming"})
+        self.assertIsInstance(cond.match, MatchValue)
+        self.assertEqual(cond.match.value, "programming")
+
+    def test_ne_operator(self):
+        """{\"ne\": v} maps to MatchExcept with a single-element list."""
+        cond = self.qdrant._build_field_condition("category", {"ne": "spam"})
+        self.assertIsInstance(cond.match, MatchExcept)
+        self.assertIn("spam", getattr(cond.match, "except_", None) or getattr(cond.match, "except"))
+
+    def test_in_operator(self):
+        """{\"in\": [...]} maps to MatchAny."""
+        cond = self.qdrant._build_field_condition("category", {"in": ["a", "b", "c"]})
+        self.assertIsInstance(cond.match, MatchAny)
+        self.assertEqual(cond.match.any, ["a", "b", "c"])
+
+    def test_nin_operator(self):
+        """{\"nin\": [...]} maps to MatchExcept."""
+        cond = self.qdrant._build_field_condition("status", {"nin": ["deleted", "banned"]})
+        self.assertIsInstance(cond.match, MatchExcept)
+        excluded = getattr(cond.match, "except_", None) or getattr(cond.match, "except")
+        self.assertIn("deleted", excluded)
+        self.assertIn("banned", excluded)
+
+    def test_contains_operator(self):
+        """{\"contains\": x} maps to MatchText."""
+        cond = self.qdrant._build_field_condition("bio", {"contains": "python"})
+        self.assertIsInstance(cond.match, MatchText)
+        self.assertEqual(cond.match.text, "python")
+
+    def test_icontains_operator(self):
+        """{\"icontains\": x} maps to MatchText (same as contains for Qdrant)."""
+        cond = self.qdrant._build_field_condition("bio", {"icontains": "Python"})
+        self.assertIsInstance(cond.match, MatchText)
+        self.assertEqual(cond.match.text, "Python")
+
+    def test_gt_operator(self):
+        """{\"gt\": v} maps to Range with gt only."""
+        cond = self.qdrant._build_field_condition("priority", {"gt": 5})
+        self.assertIsInstance(cond.range, Range)
+        self.assertEqual(cond.range.gt, 5)
+        self.assertIsNone(cond.range.gte)
+        self.assertIsNone(cond.range.lt)
+        self.assertIsNone(cond.range.lte)
+
+    def test_gte_operator(self):
+        """{\"gte\": v} maps to Range with gte only."""
+        cond = self.qdrant._build_field_condition("priority", {"gte": 5})
+        self.assertIsInstance(cond.range, Range)
+        self.assertEqual(cond.range.gte, 5)
+        self.assertIsNone(cond.range.gt)
+
+    def test_lt_operator(self):
+        """{\"lt\": v} maps to Range with lt only."""
+        cond = self.qdrant._build_field_condition("priority", {"lt": 10})
+        self.assertIsInstance(cond.range, Range)
+        self.assertEqual(cond.range.lt, 10)
+
+    def test_lte_operator(self):
+        """{\"lte\": v} maps to Range with lte only."""
+        cond = self.qdrant._build_field_condition("priority", {"lte": 10})
+        self.assertIsInstance(cond.range, Range)
+        self.assertEqual(cond.range.lte, 10)
+
+    def test_range_gte_lte(self):
+        """Combined {\"gte\": x, \"lte\": y} maps to Range with both bounds."""
+        cond = self.qdrant._build_field_condition("priority", {"gte": 5, "lte": 10})
+        self.assertIsInstance(cond.range, Range)
+        self.assertEqual(cond.range.gte, 5)
+        self.assertEqual(cond.range.lte, 10)
+
+    def test_range_gt_lt(self):
+        """Open interval {\"gt\": x, \"lt\": y} maps to Range with both bounds."""
+        cond = self.qdrant._build_field_condition("score", {"gt": 0.5, "lt": 0.9})
+        self.assertIsInstance(cond.range, Range)
+        self.assertEqual(cond.range.gt, 0.5)
+        self.assertEqual(cond.range.lt, 0.9)
+
+    # ------------------------------------------------------------------ #
+    # _create_filter — comparison and list operators                       #
+    # ------------------------------------------------------------------ #
+
+    def test_create_filter_eq(self):
+        result = self.qdrant._create_filter({"category": {"eq": "programming"}})
+        self.assertIsInstance(result, Filter)
+        self.assertEqual(len(result.must), 1)
+        self.assertIsInstance(result.must[0].match, MatchValue)
+
+    def test_create_filter_ne(self):
+        result = self.qdrant._create_filter({"category": {"ne": "spam"}})
+        self.assertIsInstance(result, Filter)
+        self.assertIsInstance(result.must[0].match, MatchExcept)
+
+    def test_create_filter_in(self):
+        result = self.qdrant._create_filter({"category": {"in": ["prog", "data"]}})
+        self.assertIsInstance(result, Filter)
+        self.assertIsInstance(result.must[0].match, MatchAny)
+        self.assertEqual(result.must[0].match.any, ["prog", "data"])
+
+    def test_create_filter_nin(self):
+        result = self.qdrant._create_filter({"status": {"nin": ["deleted", "banned"]}})
+        self.assertIsInstance(result, Filter)
+        self.assertIsInstance(result.must[0].match, MatchExcept)
+
+    def test_create_filter_gt(self):
+        result = self.qdrant._create_filter({"priority": {"gt": 7}})
+        self.assertIsInstance(result, Filter)
+        self.assertIsInstance(result.must[0].range, Range)
+        self.assertEqual(result.must[0].range.gt, 7)
+
+    def test_create_filter_gte_lte_range(self):
+        result = self.qdrant._create_filter({"priority": {"gte": 5, "lte": 9}})
+        self.assertIsInstance(result, Filter)
+        r = result.must[0].range
+        self.assertEqual(r.gte, 5)
+        self.assertEqual(r.lte, 9)
+
+    def test_create_filter_contains(self):
+        result = self.qdrant._create_filter({"bio": {"contains": "python"}})
+        self.assertIsInstance(result, Filter)
+        self.assertIsInstance(result.must[0].match, MatchText)
+
+    # ------------------------------------------------------------------ #
+    # _create_filter — logical operators                                   #
+    # ------------------------------------------------------------------ #
+
+    def test_and_operator(self):
+        """AND populates Filter.must with nested Filter objects."""
+        filters = {"AND": [{"category": "programming"}, {"priority": 10}]}
+        result = self.qdrant._create_filter(filters)
+        self.assertIsInstance(result, Filter)
+        self.assertEqual(len(result.must), 2)
+        # Each item is a Filter that wraps a single FieldCondition
+        for item in result.must:
+            self.assertIsInstance(item, Filter)
+
+    def test_or_operator(self):
+        """OR populates Filter.should with nested Filter objects."""
+        filters = {"OR": [{"category": "programming"}, {"category": "data"}]}
+        result = self.qdrant._create_filter(filters)
+        self.assertIsInstance(result, Filter)
+        self.assertEqual(len(result.should), 2)
+        self.assertIsNone(result.must)
+
+    def test_not_operator(self):
+        """NOT populates Filter.must_not with nested Filter objects."""
+        filters = {"NOT": [{"category": "spam"}]}
+        result = self.qdrant._create_filter(filters)
+        self.assertIsInstance(result, Filter)
+        self.assertEqual(len(result.must_not), 1)
+        self.assertIsNone(result.must)
+        self.assertIsNone(result.should)
+
+    def test_mixed_field_and_and(self):
+        """Top-level field conditions and AND can coexist in must."""
+        filters = {
+            "user_id": "alice",
+            "AND": [{"priority": {"gte": 5}}, {"category": "programming"}],
+        }
+        result = self.qdrant._create_filter(filters)
+        self.assertIsInstance(result, Filter)
+        # user_id FieldCondition + 2 nested AND Filters = 3 items in must
+        self.assertEqual(len(result.must), 3)
+
+    def test_nested_and_or(self):
+        """AND containing an OR sub-condition produces correct nesting."""
+        filters = {
+            "AND": [
+                {"OR": [{"category": "prog"}, {"category": "data"}]},
+                {"priority": {"gt": 3}},
+            ]
+        }
+        result = self.qdrant._create_filter(filters)
+        self.assertIsInstance(result, Filter)
+        self.assertEqual(len(result.must), 2)
+        # First item is a Filter with should (the OR)
+        or_filter = result.must[0]
+        self.assertIsInstance(or_filter, Filter)
+        self.assertEqual(len(or_filter.should), 2)
+
+    # ------------------------------------------------------------------ #
+    # Edge cases                                                           #
+    # ------------------------------------------------------------------ #
+
+    def test_empty_filter_returns_none(self):
+        self.assertIsNone(self.qdrant._create_filter({}))
+        self.assertIsNone(self.qdrant._create_filter(None))
+
+    def test_backward_compat_simple_equality(self):
+        """Plain scalar equality still works as before."""
+        result = self.qdrant._create_filter({"user_id": "alice", "run_id": "r1"})
+        self.assertIsInstance(result, Filter)
+        keys = [c.key for c in result.must]
+        self.assertIn("user_id", keys)
+        self.assertIn("run_id", keys)
+
+    def test_backward_compat_gte_lte_range(self):
+        """Original gte+lte range filter still produces a Range condition."""
+        result = self.qdrant._create_filter({"count": {"gte": 5, "lte": 10}})
+        self.assertIsInstance(result, Filter)
+        self.assertIsInstance(result.must[0].range, Range)
+        self.assertEqual(result.must[0].range.gte, 5)
+        self.assertEqual(result.must[0].range.lte, 10)
+
+    def test_unknown_operator_raises_error(self):
+        """Unknown operator dict should raise ValueError, not ValidationError."""
+        with self.assertRaises(ValueError) as ctx:
+            self.qdrant._build_field_condition("field", {"unknown_op": "foo"})
+        self.assertIn("Unsupported", str(ctx.exception))
+
+    def test_mixed_range_and_non_range_raises_error(self):
+        """Mixing range ops with non-range ops should raise ValueError."""
+        with self.assertRaises(ValueError):
+            self.qdrant._build_field_condition("priority", {"gte": 5, "ne": 10})
+
+    def test_mixed_range_and_eq_raises_error(self):
+        """Mixing range ops with eq should raise ValueError."""
+        with self.assertRaises(ValueError):
+            self.qdrant._build_field_condition("score", {"gt": 0.5, "eq": 1.0})
+
+    def test_wildcard_returns_none(self):
+        """Wildcard '*' should return None (skip filter — match any)."""
+        result = self.qdrant._build_field_condition("category", "*")
+        self.assertIsNone(result)
+
+    def test_create_filter_with_wildcard_skips_it(self):
+        """Wildcard fields should be skipped in the final filter."""
+        result = self.qdrant._create_filter({"category": "*", "user_id": "alice"})
+        self.assertIsInstance(result, Filter)
+        self.assertEqual(len(result.must), 1)
+        self.assertEqual(result.must[0].key, "user_id")
+
+    def test_create_filter_only_wildcard_returns_none(self):
+        """Filter with only wildcard should return None."""
+        result = self.qdrant._create_filter({"category": "*"})
+        self.assertIsNone(result)
+
+    def test_and_with_non_list_raises_error(self):
+        """AND with non-list value should raise ValueError."""
+        with self.assertRaises(ValueError):
+            self.qdrant._create_filter({"AND": "not_a_list"})
+
+    def test_or_with_non_list_raises_error(self):
+        """OR with non-list value should raise ValueError."""
+        with self.assertRaises(ValueError):
+            self.qdrant._create_filter({"OR": {"category": "work"}})
+
+    def test_not_with_non_list_raises_error(self):
+        """NOT with non-list value should raise ValueError."""
+        with self.assertRaises(ValueError):
+            self.qdrant._create_filter({"NOT": "invalid"})
+
+    def test_empty_and_list(self):
+        """AND with empty list should return None."""
+        result = self.qdrant._create_filter({"AND": []})
+        self.assertIsNone(result)
+
+    def test_empty_or_list(self):
+        """OR with empty list should return None."""
+        result = self.qdrant._create_filter({"OR": []})
+        self.assertIsNone(result)
+
+    def test_empty_not_list(self):
+        """NOT with empty list should return None."""
+        result = self.qdrant._create_filter({"NOT": []})
+        self.assertIsNone(result)
+
+    def test_deeply_nested_logical(self):
+        """3-level nesting: AND > OR > NOT."""
+        filters = {
+            "AND": [
+                {
+                    "OR": [
+                        {"category": "work"},
+                        {"category": "personal"}
+                    ]
+                },
+                {"priority": {"gte": 5}},
+                {
+                    "NOT": [
+                        {"status": "archived"}
+                    ]
+                }
+            ]
+        }
+        result = self.qdrant._create_filter(filters)
+        self.assertIsInstance(result, Filter)
+        self.assertEqual(len(result.must), 3)
+
+    def test_boolean_equality(self):
+        """Boolean values should work with MatchValue."""
+        cond = self.qdrant._build_field_condition("active", True)
+        self.assertIsInstance(cond.match, MatchValue)
+        self.assertEqual(cond.match.value, True)
+
+    def test_integer_equality(self):
+        """Integer values should work with MatchValue."""
+        cond = self.qdrant._build_field_condition("count", 42)
+        self.assertIsInstance(cond.match, MatchValue)
+        self.assertEqual(cond.match.value, 42)
+
+    def test_eq_with_boolean(self):
+        """eq operator with boolean should work."""
+        cond = self.qdrant._build_field_condition("active", {"eq": False})
+        self.assertIsInstance(cond.match, MatchValue)
+        self.assertEqual(cond.match.value, False)
+
+    def test_in_with_integers(self):
+        """in operator with integer list should use MatchAny."""
+        cond = self.qdrant._build_field_condition("priority", {"in": [1, 2, 3]})
+        self.assertIsInstance(cond.match, MatchAny)
+        self.assertEqual(cond.match.any, [1, 2, 3])
+
+    def test_wildcard_inside_and(self):
+        """Wildcard inside AND should be skipped, other conditions preserved."""
+        result = self.qdrant._create_filter({
+            "AND": [{"category": "*"}, {"user_id": "alice"}]
+        })
+        self.assertIsInstance(result, Filter)
+        # AND produces nested Filters; the wildcard sub-filter returns None and is skipped
+        # Only the user_id sub-filter remains
+        self.assertEqual(len(result.must), 1)
+
+    def test_empty_dict_value_raises_error(self):
+        """Empty dict as filter value should raise ValueError."""
+        with self.assertRaises(ValueError):
+            self.qdrant._build_field_condition("field", {})
+
+    def test_ne_alone_does_not_trigger_mixed_error(self):
+        """ne as sole operator should NOT trigger mixed-operator error (regression guard)."""
+        cond = self.qdrant._build_field_condition("status", {"ne": "deleted"})
+        self.assertIsInstance(cond.match, MatchExcept)
+
+    def test_eq_with_literal_star(self):
+        """eq operator with literal '*' should match the string '*', not wildcard."""
+        cond = self.qdrant._build_field_condition("category", {"eq": "*"})
+        self.assertIsInstance(cond.match, MatchValue)
+        self.assertEqual(cond.match.value, "*")
+
+    # ------------------------------------------------------------------ #
+    # $or / $not normalization (Memory._process_metadata_filters injects  #
+    # these keys alongside the original OR/NOT)                           #
+    # ------------------------------------------------------------------ #
+
+    def test_dollar_or_handled_as_or(self):
+        """$or injected by Memory middleware should be treated as OR."""
+        filters = {
+            "user_id": "alice",
+            "$or": [{"category": "programming"}, {"category": "data"}],
+        }
+        result = self.qdrant._create_filter(filters)
+        self.assertIsInstance(result, Filter)
+        self.assertIsNotNone(result.should)
+        self.assertEqual(len(result.should), 2)
+
+    def test_dollar_not_handled_as_not(self):
+        """$not injected by Memory middleware should be treated as NOT."""
+        filters = {
+            "user_id": "alice",
+            "$not": [{"category": "spam"}],
+        }
+        result = self.qdrant._create_filter(filters)
+        self.assertIsInstance(result, Filter)
+        self.assertIsNotNone(result.must_not)
+        self.assertEqual(len(result.must_not), 1)
+
+    def test_memory_search_or_shape(self):
+        """Simulate exact shape Memory.search() sends for OR filters.
+
+        effective_filters keeps the original OR key (via deepcopy of
+        input_filters) and _process_metadata_filters adds $or with the
+        same content.  _create_filter should deduplicate so only the
+        first occurrence (OR) is used — exactly 2 should entries.
+        """
+        filters = {
+            "OR": [{"category": "programming"}, {"category": "data"}],
+            "user_id": "test_user",
+            "$or": [{"category": "programming"}, {"category": "data"}],
+        }
+        result = self.qdrant._create_filter(filters)
+        self.assertIsInstance(result, Filter)
+        self.assertIsNotNone(result.should)
+        # Deduplicated: OR wins, $or is skipped — exactly 2 entries
+        self.assertEqual(len(result.should), 2)
+
+    def test_memory_search_not_shape(self):
+        """Simulate exact shape Memory.search() sends for NOT filters.
+
+        Same deduplication as OR: NOT wins, $not is skipped.
+        """
+        filters = {
+            "NOT": [{"category": "spam"}],
+            "user_id": "test_user",
+            "$not": [{"category": "spam"}],
+        }
+        result = self.qdrant._create_filter(filters)
+        self.assertIsInstance(result, Filter)
+        self.assertIsNotNone(result.must_not)
+        # Deduplicated: NOT wins, $not is skipped — exactly 1 entry
+        self.assertEqual(len(result.must_not), 1)
+
+    def tearDown(self):
+        del self.qdrant