Guard tool relevance filters by search mode

Author: abrookins

agent-memory-client/agent_memory_client/client.py

@@ -1265,12 +1265,23 @@ async def search_memory_tool(
         """
         from .filters import Entities, MemoryType, Topics
 
+        normalized_search_mode = (
+            search_mode.value
+            if isinstance(search_mode, SearchModeEnum)
+            else search_mode
+        ).lower()
+
         # Convert simple parameters to filter objects
         topics_filter = Topics(any=list(topics)) if topics else None
         entities_filter = Entities(any=list(entities)) if entities else None
         memory_type_filter = MemoryType(eq=memory_type) if memory_type else None
         user_id_filter = UserId(eq=user_id) if user_id else None
 
+        if min_relevance is not None and normalized_search_mode != "semantic":
+            raise ValueError(
+                "min_relevance is only supported when search_mode='semantic'"
+            )
+
         # Convert min_relevance to distance_threshold (assuming 0-1 relevance maps to 1-0 distance)
         distance_threshold = (
             (1.0 - min_relevance) if min_relevance is not None else None
@@ -1431,7 +1442,7 @@ async def handle_tool_calls(client, tool_calls):
                                 "type": "number",
                                 "minimum": 0.0,
                                 "maximum": 1.0,
-                                "description": "Optional minimum relevance score (0.0-1.0, higher = more relevant)",
+                                "description": "Optional minimum relevance score (0.0-1.0, higher = more relevant). Supported only when `search_mode` is `semantic`.",
                             },
                             "user_id": {
                                 "type": "string",

agent-memory-client/tests/test_client.py

@@ -401,6 +401,21 @@ async def test_search_memory_tool_forwards_hybrid_parameters(
             assert kwargs["hybrid_alpha"] == 0.35
             assert kwargs["text_scorer"] == "TFIDF"
 
+    @pytest.mark.asyncio
+    async def test_search_memory_tool_rejects_min_relevance_for_keyword_mode(
+        self, enhanced_test_client
+    ):
+        """Test that non-semantic tool searches fail early on min_relevance."""
+        with pytest.raises(
+            ValueError,
+            match="min_relevance is only supported when search_mode='semantic'",
+        ):
+            await enhanced_test_client.search_memory_tool(
+                query="alpha beta",
+                search_mode=SearchModeEnum.KEYWORD,
+                min_relevance=0.5,
+            )
+
     def test_memory_search_tool_schema_exposes_search_controls(self):
         """Test that the LLM tool schema advertises keyword/hybrid controls."""
         schema = MemoryAPIClient.get_memory_search_tool_schema().to_dict()
@@ -414,6 +429,8 @@ def test_memory_search_tool_schema_exposes_search_controls(self):
         assert properties["search_mode"]["default"] == "semantic"
         assert properties["hybrid_alpha"]["default"] == 0.7
         assert properties["text_scorer"]["default"] == "BM25STD"
+        assert "search_mode" in properties["min_relevance"]["description"]
+        assert "semantic" in properties["min_relevance"]["description"]
 
 
 class TestClientSideValidation: