Clarify hybrid search score handling

Author: abrookins

agent_memory_server/api.py

@@ -27,6 +27,7 @@
     ModelNameLiteral,
     RunSummaryViewPartitionRequest,
     RunSummaryViewRequest,
+    SearchModeEnum,
     SearchRequest,
     SessionListResponse,
     SummaryView,
@@ -657,6 +658,15 @@ async def search_long_term_memory(
     if not settings.long_term_memory:
         raise HTTPException(status_code=400, detail="Long-term memory is disabled")
 
+    if (
+        payload.distance_threshold is not None
+        and payload.search_mode != SearchModeEnum.SEMANTIC
+    ):
+        raise HTTPException(
+            status_code=400,
+            detail="distance_threshold is only supported for semantic search mode",
+        )
+
     # Extract filter objects from the payload
     filters = payload.get_filters()
 

agent_memory_server/cli.py

@@ -613,6 +613,12 @@ def search(
 
     configure_logging()
 
+    if distance_threshold is not None and search_mode != "semantic":
+        raise click.BadParameter(
+            "distance_threshold is only supported for semantic search mode",
+            param_hint="--distance-threshold",
+        )
+
     async def run_search():
         # Build filter objects
         namespace_filter = Namespace(eq=namespace) if namespace else None

agent_memory_server/long_term_memory.py

@@ -1123,6 +1123,11 @@ async def search_long_term_memories(
     Returns:
         MemoryRecordResults containing matching memories
     """
+    if distance_threshold is not None and search_mode != SearchModeEnum.SEMANTIC:
+        raise ValueError(
+            "distance_threshold is only supported for semantic search mode"
+        )
+
     # If no query text is provided, perform a filter-only listing (no semantic search).
     # This enables patterns like: "return all memories for this user/namespace".
     if not (text or "").strip():

agent_memory_server/mcp.py

@@ -585,6 +585,11 @@ async def search_long_term_memory(
     if namespace is None and settings.default_mcp_namespace:
         namespace = Namespace(eq=settings.default_mcp_namespace)
 
+    if distance_threshold is not None and search_mode != SearchModeEnum.SEMANTIC:
+        raise ValueError(
+            "distance_threshold is only supported for semantic search mode"
+        )
+
     try:
         payload = SearchRequest(
             text=text,

agent_memory_server/memory_vector_db.py

@@ -499,7 +499,7 @@ def _normalize_rank_scores(self, raw_scores: list[float]) -> list[float]:
 
         max_score = max(raw_scores)
         if max_score <= 0:
-            return [1.0 for _ in raw_scores]
+            return [0.0 for _ in raw_scores]
 
         return [min(max(score / max_score, 0.0), 1.0) for score in raw_scores]
 

tests/test_api.py

@@ -902,6 +902,27 @@ async def test_search_with_optimize_query_explicit_true(self, mock_search, clien
         assert data["memories"][0]["id"] == "1"
         assert data["memories"][0]["text"] == "Optimized result"
 
+    @patch("agent_memory_server.api.long_term_memory.search_long_term_memories")
+    @pytest.mark.asyncio
+    async def test_search_rejects_distance_threshold_for_keyword_mode(
+        self, mock_search, client
+    ):
+        """distance_threshold only applies to semantic search."""
+        payload = {
+            "text": "preference",
+            "search_mode": "keyword",
+            "distance_threshold": 0.5,
+        }
+
+        response = await client.post("/v1/long-term-memory/search", json=payload)
+
+        assert response.status_code == 400
+        assert (
+            response.json()["detail"]
+            == "distance_threshold is only supported for semantic search mode"
+        )
+        mock_search.assert_not_called()
+
 
 @pytest.mark.requires_api_keys
 class TestMemoryPromptEndpoint:

tests/test_cli.py

@@ -805,6 +805,22 @@ def test_search_with_distance_threshold(self, mock_search):
         call_kwargs = mock_search.call_args[1]
         assert call_kwargs["distance_threshold"] == 0.5
 
+    @patch("agent_memory_server.long_term_memory.search_long_term_memories")
+    def test_search_rejects_distance_threshold_for_keyword_mode(self, mock_search):
+        """distance_threshold should fail fast outside semantic mode."""
+        runner = CliRunner()
+        result = runner.invoke(
+            search,
+            ["test query", "--search-mode", "keyword", "--distance-threshold", "0.5"],
+        )
+
+        assert result.exit_code != 0
+        assert (
+            "distance_threshold is only supported for semantic search mode"
+            in result.output
+        )
+        mock_search.assert_not_called()
+
     @patch("agent_memory_server.long_term_memory.search_long_term_memories")
     def test_search_json_output(self, mock_search):
         """Test search with JSON output format."""

tests/test_memory_vector_db.py

@@ -488,6 +488,14 @@ def test_data_to_memory_result_decodes_legacy_pipe_delimited_tags(self):
         assert result.topics == ["cooking", "italian"]
         assert result.entities == ["pasta", "rome"]
 
+    def test_normalize_rank_scores_zero_scores_remain_zero(self):
+        """Zero-score batches should not be normalized into perfect matches."""
+        mock_index = MagicMock()
+        mock_embeddings = MockEmbeddings()
+        db = RedisVLMemoryVectorDatabase(mock_index, mock_embeddings)
+
+        assert db._normalize_rank_scores([0.0, 0.0]) == [0.0, 0.0]
+
     @pytest.mark.asyncio
     async def test_list_memories_does_not_overwrite_dist_with_score(self):
         """Filter-only listings should keep neutral distance semantics."""