spatial-memory-mcp 1.0.3__py3-none-any.whl → 1.6.0__py3-none-any.whl

spatial_memory/services/memory.py

@@ -13,7 +13,7 @@ from __future__ import annotations
 
 import logging
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Protocol
 
 from spatial_memory.core.errors import MemoryNotFoundError, ValidationError
 from spatial_memory.core.models import Memory, MemorySource
@@ -22,6 +22,7 @@ from spatial_memory.core.validation import validate_content, validate_importance
 logger = logging.getLogger(__name__)
 
 if TYPE_CHECKING:
+    from spatial_memory.core.database import IdempotencyRecord
     from spatial_memory.core.models import MemoryResult
     from spatial_memory.ports.repositories import (
         EmbeddingServiceProtocol,
@@ -29,6 +30,39 @@ if TYPE_CHECKING:
     )
 
 
+class IdempotencyProviderProtocol(Protocol):
+    """Protocol for idempotency key storage and lookup.
+
+    Implementations should handle key-to-memory-id mappings with TTL support.
+    """
+
+    def get_by_idempotency_key(self, key: str) -> IdempotencyRecord | None:
+        """Look up an idempotency record by key.
+
+        Args:
+            key: The idempotency key to look up.
+
+        Returns:
+            IdempotencyRecord if found and not expired, None otherwise.
+        """
+        ...
+
+    def store_idempotency_key(
+        self,
+        key: str,
+        memory_id: str,
+        ttl_hours: float = 24.0,
+    ) -> None:
+        """Store an idempotency key mapping.
+
+        Args:
+            key: The idempotency key.
+            memory_id: The memory ID that was created.
+            ttl_hours: Time-to-live in hours (default: 24 hours).
+        """
+        ...
+
+
 @dataclass
 class RememberResult:
     """Result of storing a memory."""
@@ -36,6 +70,7 @@ class RememberResult:
     id: str
     content: str
     namespace: str
+    deduplicated: bool = False
 
 
 @dataclass
@@ -80,15 +115,18 @@ class MemoryService:
         self,
         repository: MemoryRepositoryProtocol,
         embeddings: EmbeddingServiceProtocol,
+        idempotency_provider: IdempotencyProviderProtocol | None = None,
     ) -> None:
         """Initialize the memory service.
 
         Args:
             repository: Repository for memory storage.
             embeddings: Service for generating embeddings.
+            idempotency_provider: Optional provider for idempotency key support.
         """
         self._repo = repository
         self._embeddings = embeddings
+        self._idempotency = idempotency_provider
 
     # Use centralized validation functions
     _validate_content = staticmethod(validate_content)
@@ -101,6 +139,7 @@ class MemoryService:
         tags: list[str] | None = None,
         importance: float = 0.5,
         metadata: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
     ) -> RememberResult:
         """Store a new memory.
 
@@ -110,13 +149,40 @@ class MemoryService:
             tags: Optional list of tags.
             importance: Importance score (0-1).
             metadata: Optional metadata dict.
+            idempotency_key: Optional key for idempotent requests. If provided
+                and a memory was already created with this key, returns the
+                existing memory ID with deduplicated=True.
 
         Returns:
-            RememberResult with the new memory's ID.
+            RememberResult with the new memory's ID. If idempotency_key was
+            provided and matched an existing request, deduplicated=True.
 
         Raises:
             ValidationError: If input validation fails.
         """
+        # Check idempotency key first (before any expensive operations)
+        if idempotency_key and self._idempotency:
+            existing = self._idempotency.get_by_idempotency_key(idempotency_key)
+            if existing:
+                logger.debug(
+                    f"Idempotency key '{idempotency_key}' matched existing "
+                    f"memory '{existing.memory_id}'"
+                )
+                # Return cached result - fetch the memory to get content
+                cached_memory = self._repo.get(existing.memory_id)
+                if cached_memory:
+                    return RememberResult(
+                        id=existing.memory_id,
+                        content=cached_memory.content,
+                        namespace=cached_memory.namespace,
+                        deduplicated=True,
+                    )
+                # Memory was deleted but key exists - proceed with new insert
+                logger.warning(
+                    f"Idempotency key '{idempotency_key}' references deleted "
+                    f"memory '{existing.memory_id}', creating new memory"
+                )
+
         # Validate inputs
         self._validate_content(content)
         self._validate_importance(importance)
@@ -138,10 +204,21 @@ class MemoryService:
         # Store in repository
         memory_id = self._repo.add(memory, vector)
 
+        # Store idempotency key mapping if provided
+        if idempotency_key and self._idempotency:
+            try:
+                self._idempotency.store_idempotency_key(idempotency_key, memory_id)
+            except Exception as e:
+                # Log but don't fail the memory creation
+                logger.warning(
+                    f"Failed to store idempotency key '{idempotency_key}': {e}"
+                )
+
         return RememberResult(
             id=memory_id,
             content=content,
             namespace=namespace,
+            deduplicated=False,
         )
 
     def remember_batch(
@@ -327,9 +404,9 @@ class MemoryService:
         if not memory_ids:
             raise ValidationError("Memory ID list cannot be empty")
 
-        deleted_count = self._repo.delete_batch(memory_ids)
+        deleted_count, deleted_ids = self._repo.delete_batch(memory_ids)
 
         return ForgetResult(
             deleted=deleted_count,
-            ids=memory_ids[:deleted_count] if deleted_count > 0 else [],
+            ids=deleted_ids,
         )

spatial_memory/services/spatial.py

@@ -63,6 +63,28 @@ except ImportError:
     UMAP_AVAILABLE = False
     logger.debug("UMAP not available - visualize operation will be disabled")
 
+try:
+    from scipy.spatial.distance import cdist
+
+    SCIPY_AVAILABLE = True
+except ImportError:
+    SCIPY_AVAILABLE = False
+    logger.debug("scipy not available - using fallback for similarity calculations")
+
+# Common stop words for keyword extraction (module-level to avoid recreation)
+_STOP_WORDS: frozenset[str] = frozenset({
+    "the", "a", "an", "is", "are", "was", "were", "be", "been", "being",
+    "have", "has", "had", "do", "does", "did", "will", "would", "could",
+    "should", "may", "might", "must", "can", "to", "of", "in", "for",
+    "on", "with", "at", "by", "from", "as", "into", "through", "during",
+    "before", "after", "above", "below", "between", "under", "again",
+    "further", "then", "once", "here", "there", "when", "where", "why",
+    "how", "all", "each", "few", "more", "most", "other", "some", "such",
+    "no", "nor", "not", "only", "own", "same", "so", "than", "too",
+    "very", "just", "also", "now", "and", "but", "or", "if", "it", "its",
+    "this", "that", "these", "those", "i", "you", "he", "she", "we", "they",
+})
+
 if TYPE_CHECKING:
     from spatial_memory.ports.repositories import (
         EmbeddingServiceProtocol,
@@ -212,11 +234,12 @@ class SpatialService:
             )
 
             # Find nearest memories for each interpolation point
-            # Use batch search for efficiency
+            # Use batch search for efficiency, include vectors to avoid N+1 queries
             search_results = self._batch_vector_search(
                 interpolated_vectors,
                 limit_per_query=self._config.journey_neighbors_per_step,
                 namespace=namespace,
+                include_vector=True,  # Include vectors to avoid follow-up queries
             )
 
             # Build journey steps
@@ -230,9 +253,15 @@ class SpatialService:
                 distance_to_path = float("inf")
                 if neighbors:
                     for neighbor in neighbors:
-                        dist = self._cosine_distance(
-                            interp_vec, self._get_vector_for_memory(neighbor.id)
-                        )
+                        # Use vector from search result (included via include_vector=True)
+                        if neighbor.vector is not None:
+                            neighbor_vec = np.array(neighbor.vector, dtype=np.float32)
+                            dist = self._cosine_distance(interp_vec, neighbor_vec)
+                        else:
+                            # Fallback if vector not included (shouldn't happen)
+                            dist = self._cosine_distance(
+                                interp_vec, self._get_vector_for_memory(neighbor.id)
+                            )
                         if dist < distance_to_path:
                             distance_to_path = dist
                     steps_with_memories += 1
@@ -330,10 +359,12 @@ class SpatialService:
 
             for step_num in range(actual_steps):
                 # Find candidates from current position
+                # Include vectors to avoid follow-up get_with_vector queries
                 neighbors = self._repo.search(
                     current_vector,
                     limit=self._config.wander_candidates_per_step + len(visited_ids),
                     namespace=namespace,
+                    include_vector=True,
                 )
 
                 # Filter out recently visited
@@ -358,12 +389,16 @@ class SpatialService:
                     candidates, actual_temp
                 )
 
-                # Calculate distance traveled
-                next_result = self._repo.get_with_vector(next_memory.id)
-                if next_result is None:
-                    logger.warning(f"Memory {next_memory.id} disappeared during wander")
-                    break
-                _, next_vector = next_result
+                # Get vector from search result (included via include_vector=True)
+                if next_memory.vector is not None:
+                    next_vector = np.array(next_memory.vector, dtype=np.float32)
+                else:
+                    # Fallback if vector not included (shouldn't happen)
+                    next_result = self._repo.get_with_vector(next_memory.id)
+                    if next_result is None:
+                        logger.warning(f"Memory {next_memory.id} disappeared during wander")
+                        break
+                    _, next_vector = next_result
 
                 step_distance = self._cosine_distance(prev_vector, next_vector)
                 total_distance += step_distance
@@ -665,18 +700,26 @@ class SpatialService:
             # Build edges if requested
             edges: list[VisualizationEdge] = []
             if include_edges:
-                # Calculate pairwise similarities and create edges for high similarity
-                for i in range(len(vectors)):
-                    for j in range(i + 1, len(vectors)):
-                        similarity = 1.0 - self._cosine_distance(vectors[i], vectors[j])
-                        if similarity >= self._config.visualize_similarity_threshold:
-                            edges.append(
-                                VisualizationEdge(
-                                    from_id=nodes[i].id,
-                                    to_id=nodes[j].id,
-                                    weight=similarity,
-                                )
-                            )
+                # Calculate pairwise similarities using vectorized operations
+                similarity_matrix = self._compute_pairwise_similarities(vectors)
+                threshold = self._config.visualize_similarity_threshold
+
+                # Extract upper triangle indices where similarity >= threshold
+                # (upper triangle avoids duplicate edges)
+                upper_tri_indices = np.triu_indices(len(vectors), k=1)
+                similarities = similarity_matrix[upper_tri_indices]
+
+                # Filter by threshold and create edges
+                mask = similarities >= threshold
+                for idx in np.where(mask)[0]:
+                    i, j = upper_tri_indices[0][idx], upper_tri_indices[1][idx]
+                    edges.append(
+                        VisualizationEdge(
+                            from_id=nodes[i].id,
+                            to_id=nodes[j].id,
+                            weight=float(similarities[idx]),
+                        )
+                    )
 
             # Calculate bounds
             x_coords = [n.x for n in nodes]
@@ -783,25 +826,50 @@ class SpatialService:
         vectors: list[np.ndarray],
         limit_per_query: int,
         namespace: str | None,
+        include_vector: bool = False,
     ) -> list[list[MemoryResult]]:
-        """Perform batch vector search.
+        """Perform batch vector search using repository's native batch capability.
 
-        Delegates to repository if batch search is available, otherwise
-        performs individual searches.
+        Uses the repository's batch_vector_search for efficient multi-query
+        searches in a single database operation.
 
         Args:
             vectors: List of query vectors.
             limit_per_query: Results per query.
             namespace: Optional namespace filter.
+            include_vector: Whether to include embedding vectors in results.
+                Defaults to False to reduce response size.
 
         Returns:
-            List of result lists.
+            List of result lists. If include_vector=True, each MemoryResult
+            includes its embedding vector.
         """
-        # Fall back to individual searches (repository handles batch internally)
+        # Use native batch search for efficiency
+        raw_results = self._repo.batch_vector_search(
+            query_vectors=vectors,
+            limit_per_query=limit_per_query,
+            namespace=namespace,
+            include_vector=include_vector,
+        )
+
+        # Convert raw dict results to MemoryResult objects
         results: list[list[MemoryResult]] = []
-        for vec in vectors:
-            neighbors = self._repo.search(vec, limit=limit_per_query, namespace=namespace)
-            results.append(neighbors)
+        for query_results in raw_results:
+            memory_results: list[MemoryResult] = []
+            for record in query_results:
+                memory_result = MemoryResult(
+                    id=record["id"],
+                    content=record["content"],
+                    similarity=record.get("similarity", 0.0),
+                    namespace=record.get("namespace", "default"),
+                    tags=record.get("tags", []),
+                    importance=record.get("importance", 0.5),
+                    created_at=record.get("created_at"),
+                    metadata=record.get("metadata", {}),
+                    vector=record.get("vector") if include_vector else None,
+                )
+                memory_results.append(memory_result)
+            results.append(memory_results)
         return results
 
     def _get_vector_for_memory(self, memory_id: str) -> np.ndarray:
@@ -838,6 +906,35 @@ class SpatialService:
         similarity = np.dot(vec1, vec2) / (norm1 * norm2)
         return float(1.0 - similarity)
 
+    def _compute_pairwise_similarities(self, vectors: np.ndarray) -> np.ndarray:
+        """Compute pairwise cosine similarities using vectorized operations.
+
+        Uses scipy.cdist if available for optimal performance, otherwise
+        falls back to numpy matrix operations.
+
+        Args:
+            vectors: 2D array of shape (n_vectors, embedding_dim).
+
+        Returns:
+            Symmetric similarity matrix of shape (n_vectors, n_vectors).
+            Values range from -1 (opposite) to 1 (identical).
+        """
+        # Normalize vectors to unit length
+        norms = np.linalg.norm(vectors, axis=1, keepdims=True)
+        # Avoid division by zero for zero vectors
+        norms = np.where(norms < 1e-10, 1.0, norms)
+        normalized = vectors / norms
+
+        if SCIPY_AVAILABLE:
+            # scipy.cdist with cosine metric returns distances (1 - similarity)
+            distances = cdist(normalized, normalized, metric="cosine")
+            similarities = 1.0 - distances
+        else:
+            # Fallback: use numpy dot product (A @ A.T for normalized vectors)
+            similarities = normalized @ normalized.T
+
+        return similarities
+
     def _temperature_select(
         self,
         candidates: list[MemoryResult],
@@ -888,23 +985,9 @@ class SpatialService:
             List of top keywords.
         """
         # Simple keyword extraction using word frequency
-        # Remove common stop words and short words
-        stop_words = {
-            "the", "a", "an", "is", "are", "was", "were", "be", "been", "being",
-            "have", "has", "had", "do", "does", "did", "will", "would", "could",
-            "should", "may", "might", "must", "can", "to", "of", "in", "for",
-            "on", "with", "at", "by", "from", "as", "into", "through", "during",
-            "before", "after", "above", "below", "between", "under", "again",
-            "further", "then", "once", "here", "there", "when", "where", "why",
-            "how", "all", "each", "few", "more", "most", "other", "some", "such",
-            "no", "nor", "not", "only", "own", "same", "so", "than", "too",
-            "very", "just", "also", "now", "and", "but", "or", "if", "it", "its",
-            "this", "that", "these", "those", "i", "you", "he", "she", "we", "they",
-        }
-
-        # Tokenize and filter
+        # Tokenize and filter using module-level stop words
         words = re.findall(r"\b[a-zA-Z]+\b", text.lower())
-        filtered = [w for w in words if w not in stop_words and len(w) > 2]
+        filtered = [w for w in words if w not in _STOP_WORDS and len(w) > 2]
 
         # Count frequencies
         counter = Counter(filtered)