fix: backend-specific distance-to-similarity conversion (#593)

Signed-off-by: Drew Cain <groksrc@gmail.com>
Signed-off-by: phernandez <paul@basicmachines.co>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Paul Hernandez <60959+phernandez@users.noreply.github.com>
Co-authored-by: phernandez <paul@basicmachines.co>

Author: 3 people

src/basic_memory/repository/postgres_search_repository.py

@@ -509,6 +509,14 @@ async def _delete_stale_chunks(
     async def _update_timestamp_sql(self) -> str:
         return "NOW()"  # pragma: no cover
 
+    def _distance_to_similarity(self, distance: float) -> float:
+        """Convert pgvector cosine distance to cosine similarity.
+
+        pgvector's <=> operator returns cosine distance in [0, 2],
+        where cos_distance = 1 - cos_similarity.
+        """
+        return max(0.0, 1.0 - distance)
+
     def _timestamp_now_expr(self) -> str:
         return "NOW()"
 

src/basic_memory/repository/search_repository_base.py

@@ -204,6 +204,16 @@ async def _update_timestamp_sql(self) -> str:
         """Return the SQL expression for current timestamp in the backend."""
         pass  # pragma: no cover
 
+    @abstractmethod
+    def _distance_to_similarity(self, distance: float) -> float:
+        """Convert a backend-specific vector distance to cosine similarity in [0, 1].
+
+        Backend-specific implementations:
+        - SQLite (vec0): L2/Euclidean distance → cosine similarity via 1 - d²/2
+        - Postgres (pgvector <=>): Cosine distance → cosine similarity via 1 - d
+        """
+        pass  # pragma: no cover
+
     # ------------------------------------------------------------------
     # Shared index / delete operations
     # ------------------------------------------------------------------
@@ -866,7 +876,7 @@ async def _search_vector_only(
         for row in vector_rows:
             chunk_key = row.get("chunk_key", "")
             distance = float(row["best_distance"])
-            similarity = 1.0 / (1.0 + max(distance, 0.0))
+            similarity = self._distance_to_similarity(distance)
             try:
                 _, si_id = self._parse_chunk_key(chunk_key)
             except (ValueError, IndexError):

src/basic_memory/repository/sqlite_search_repository.py

@@ -58,6 +58,9 @@ def __init__(
         self._vector_dimensions = 384
 
         if self._semantic_enabled and self._embedding_provider is None:
+            # Constraint: SQLite maps L2 distance to cosine similarity via 1 - L2²/2.
+            # This conversion is correct only for unit-normalized embeddings.
+            # Provider implementations must return normalized vectors.
             self._embedding_provider = create_embedding_provider(self._app_config)
         if self._embedding_provider is not None:
             self._vector_dimensions = self._embedding_provider.dimensions
@@ -543,6 +546,14 @@ async def _delete_stale_chunks(
     async def _update_timestamp_sql(self) -> str:
         return "CURRENT_TIMESTAMP"  # pragma: no cover
 
+    def _distance_to_similarity(self, distance: float) -> float:
+        """Convert L2 distance to cosine similarity for normalized embeddings.
+
+        sqlite-vec vec0 returns Euclidean (L2) distance by default.
+        For unit-normalized vectors: L2² = 2·(1 - cos_sim), so cos_sim = 1 - L2²/2.
+        """
+        return max(0.0, 1.0 - (distance * distance) / 2.0)
+
     def _orphan_detection_sql(self) -> str:
         """SQLite sqlite-vec uses rowid-based embedding table."""
         return (