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

spatial_memory/core/embeddings.py

@@ -175,6 +175,7 @@ class EmbeddingService:
         circuit_breaker_enabled: bool = True,
         circuit_breaker_failure_threshold: int = 5,
         circuit_breaker_reset_timeout: float = 60.0,
+        cache_max_size: int = 1000,
     ) -> None:
         """Initialize the embedding service.
 
@@ -192,6 +193,8 @@ class EmbeddingService:
                 opening the circuit. Default is 5.
             circuit_breaker_reset_timeout: Seconds to wait before attempting recovery.
                 Default is 60.0 seconds.
+            cache_max_size: Maximum number of embeddings to cache (LRU eviction).
+                Default is 1000. Set to 0 to disable caching.
         """
         self.model_name = model_name
         # Handle both plain strings and SecretStr (pydantic)
@@ -209,7 +212,7 @@ class EmbeddingService:
 
         # Embedding cache (LRU with max size)
         self._embed_cache: OrderedDict[str, np.ndarray] = OrderedDict()
-        self._cache_max_size = 1000
+        self._cache_max_size = cache_max_size
         self._cache_lock = threading.Lock()
 
         # Determine if using OpenAI
@@ -308,8 +311,11 @@ class EmbeddingService:
             raise EmbeddingError(f"Failed to initialize OpenAI client: {masked_error}") from e
 
     def _get_cache_key(self, text: str) -> str:
-        """Generate cache key from text content."""
-        return hashlib.md5(text.encode()).hexdigest()
+        """Generate cache key from text content.
+
+        Uses MD5 for speed (not security) - collisions are acceptable for cache.
+        """
+        return hashlib.md5(text.encode(), usedforsecurity=False).hexdigest()
 
     @property
     def dimensions(self) -> int:
@@ -379,23 +385,27 @@ class EmbeddingService:
         else:
             embedding = self._embed_local([text])[0]
 
-        # Cache the result
-        with self._cache_lock:
-            # Check if another thread already cached it
-            if cache_key not in self._embed_cache:
-                # Evict oldest entries if at capacity
-                while len(self._embed_cache) >= self._cache_max_size:
-                    self._embed_cache.popitem(last=False)
-                self._embed_cache[cache_key] = embedding.copy()
-            else:
-                # Another thread cached it, move to end
-                self._embed_cache.move_to_end(cache_key)
+        # Cache the result (if caching enabled)
+        if self._cache_max_size > 0:
+            with self._cache_lock:
+                # Check if another thread already cached it
+                if cache_key not in self._embed_cache:
+                    # Evict oldest entries if at capacity
+                    while len(self._embed_cache) >= self._cache_max_size:
+                        self._embed_cache.popitem(last=False)
+                    self._embed_cache[cache_key] = embedding.copy()
+                else:
+                    # Another thread cached it, move to end
+                    self._embed_cache.move_to_end(cache_key)
 
         return embedding
 
     def embed_batch(self, texts: list[str]) -> list[np.ndarray]:
         """Generate embeddings for multiple texts.
 
+        Uses cache for already-embedded texts and only generates
+        embeddings for texts not in cache.
+
         Args:
             texts: List of texts to embed.
 
@@ -406,10 +416,47 @@ class EmbeddingService:
             logger.debug("embed_batch called with empty input, returning empty list")
             return []
 
-        if self.use_openai:
-            return self._embed_openai_with_circuit_breaker(texts)
-        else:
-            return self._embed_local(texts)
+        # If caching disabled, generate all embeddings directly
+        if self._cache_max_size <= 0:
+            if self.use_openai:
+                return self._embed_openai_with_circuit_breaker(texts)
+            else:
+                return self._embed_local(texts)
+
+        # Check cache for each text
+        results: list[np.ndarray | None] = [None] * len(texts)
+        texts_to_embed: list[tuple[int, str]] = []  # (index, text)
+
+        with self._cache_lock:
+            for i, text in enumerate(texts):
+                cache_key = self._get_cache_key(text)
+                if cache_key in self._embed_cache:
+                    self._embed_cache.move_to_end(cache_key)
+                    results[i] = self._embed_cache[cache_key].copy()
+                else:
+                    texts_to_embed.append((i, text))
+
+        # Generate embeddings for uncached texts
+        if texts_to_embed:
+            uncached_texts = [t for _, t in texts_to_embed]
+            if self.use_openai:
+                new_embeddings = self._embed_openai_with_circuit_breaker(uncached_texts)
+            else:
+                new_embeddings = self._embed_local(uncached_texts)
+
+            # Store results and cache them
+            with self._cache_lock:
+                for (idx, text), embedding in zip(texts_to_embed, new_embeddings):
+                    results[idx] = embedding
+                    cache_key = self._get_cache_key(text)
+                    if cache_key not in self._embed_cache:
+                        # Evict oldest entries if at capacity
+                        while len(self._embed_cache) >= self._cache_max_size:
+                            self._embed_cache.popitem(last=False)
+                        self._embed_cache[cache_key] = embedding.copy()
+
+        # Type assertion - all results should be filled
+        return [r for r in results if r is not None]
 
     def clear_cache(self) -> int:
         """Clear embedding cache. Returns number of entries cleared."""

spatial_memory/core/errors.py

@@ -1,5 +1,24 @@
 """Custom exceptions for Spatial Memory MCP Server."""
 
+from pathlib import Path
+
+
+def sanitize_path_for_error(path: str | Path) -> str:
+    """Extract only the filename from a path for safe error messages.
+
+    Prevents leaking full system paths in error messages which could
+    expose sensitive directory structure information.
+
+    Args:
+        path: Full path or filename.
+
+    Returns:
+        Just the filename portion.
+    """
+    if isinstance(path, Path):
+        return path.name
+    return Path(path).name
+
 
 class SpatialMemoryError(Exception):
     """Base exception for all spatial memory errors."""
@@ -35,6 +54,37 @@ class StorageError(SpatialMemoryError):
     pass
 
 
+class PartialBatchInsertError(StorageError):
+    """Raised when batch insert partially fails.
+
+    Provides information about which records were successfully inserted
+    before the failure, enabling recovery or rollback.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        succeeded_ids: list[str],
+        total_requested: int,
+        failed_batch_index: int | None = None,
+    ) -> None:
+        """Initialize with details about partial failure.
+
+        Args:
+            message: Error description.
+            succeeded_ids: IDs of successfully inserted records.
+            total_requested: Total number of records requested to insert.
+            failed_batch_index: Index of the batch that failed (if batched).
+        """
+        self.succeeded_ids = succeeded_ids
+        self.total_requested = total_requested
+        self.failed_batch_index = failed_batch_index
+        super().__init__(
+            f"{message}. "
+            f"Inserted {len(succeeded_ids)}/{total_requested} records before failure."
+        )
+
+
 class ValidationError(SpatialMemoryError):
     """Raised when input validation fails."""
 
@@ -141,6 +191,10 @@ class PathSecurityError(SpatialMemoryError):
         - Path outside allowed directories
         - Symlink to disallowed location
         - Invalid file extension
+
+    Note:
+        Error messages only include the filename, not the full path,
+        to avoid leaking system directory structure.
     """
 
     def __init__(
@@ -151,12 +205,18 @@ class PathSecurityError(SpatialMemoryError):
     ) -> None:
         self.path = path
         self.violation_type = violation_type
-        self.message = message or f"Path security violation ({violation_type}): {path}"
+        safe_name = sanitize_path_for_error(path)
+        self.message = message or f"Path security violation ({violation_type}): {safe_name}"
         super().__init__(self.message)
 
 
 class FileSizeLimitError(SpatialMemoryError):
-    """Raised when a file exceeds size limits."""
+    """Raised when a file exceeds size limits.
+
+    Note:
+        Error messages only include the filename, not the full path,
+        to avoid leaking system directory structure.
+    """
 
     def __init__(
         self,
@@ -169,8 +229,9 @@ class FileSizeLimitError(SpatialMemoryError):
         self.max_size_bytes = max_size_bytes
         actual_mb = actual_size_bytes / (1024 * 1024)
         max_mb = max_size_bytes / (1024 * 1024)
+        safe_name = sanitize_path_for_error(path)
         super().__init__(
-            f"File exceeds size limit: {path} is {actual_mb:.2f}MB "
+            f"File exceeds size limit: {safe_name} is {actual_mb:.2f}MB "
             f"(max: {max_mb:.2f}MB)"
         )
 
@@ -243,3 +304,14 @@ class FileLockError(SpatialMemoryError):
         self.timeout = timeout
         self.message = message or f"Failed to acquire file lock at {lock_path} after {timeout}s"
         super().__init__(self.message)
+
+
+# =============================================================================
+# Migration Error
+# =============================================================================
+
+
+class MigrationError(SpatialMemoryError):
+    """Raised when a database migration fails."""
+
+    pass

spatial_memory/core/filesystem.py

@@ -0,0 +1,178 @@
+"""Filesystem detection utilities for identifying network filesystems.
+
+This module provides utilities to detect if a path is on a network filesystem
+(NFS, SMB/CIFS) where file-based locking may not work reliably.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import platform
+import subprocess
+from enum import Enum
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class FilesystemType(Enum):
+    """Types of filesystems that can be detected."""
+
+    LOCAL = "local"
+    NFS = "nfs"
+    SMB = "smb"
+    CIFS = "cifs"
+    NETWORK_UNKNOWN = "network_unknown"
+    UNKNOWN = "unknown"
+
+
+def detect_filesystem_type(path: Path) -> FilesystemType:
+    """Detect the filesystem type for a given path.
+
+    Args:
+        path: Path to check. Will resolve to absolute path.
+
+    Returns:
+        FilesystemType indicating the detected filesystem.
+        Returns LOCAL for local filesystems, specific types for
+        network filesystems, or UNKNOWN if detection fails.
+    """
+    try:
+        resolved = path.resolve()
+
+        if platform.system() == "Windows":
+            return _detect_windows(resolved)
+        else:
+            return _detect_unix(resolved)
+    except Exception as e:
+        logger.debug(f"Filesystem detection failed for {path}: {e}")
+        return FilesystemType.UNKNOWN
+
+
+def _detect_windows(path: Path) -> FilesystemType:
+    """Detect filesystem type on Windows.
+
+    Uses GetDriveTypeW to check if drive is remote.
+    """
+    try:
+        import ctypes
+
+        # Get the drive letter (e.g., "C:\\")
+        drive = str(path)[:3] if len(str(path)) >= 3 else str(path)
+
+        # Ensure it ends with backslash for GetDriveTypeW
+        if not drive.endswith("\\"):
+            drive = drive + "\\"
+
+        # DRIVE_REMOTE = 4
+        drive_type = ctypes.windll.kernel32.GetDriveTypeW(drive)
+
+        if drive_type == 4:  # DRIVE_REMOTE
+            logger.debug(f"Detected remote drive: {drive}")
+            return FilesystemType.NETWORK_UNKNOWN
+        else:
+            return FilesystemType.LOCAL
+
+    except Exception as e:
+        logger.debug(f"Windows filesystem detection failed: {e}")
+        return FilesystemType.UNKNOWN
+
+
+def _detect_unix(path: Path) -> FilesystemType:
+    """Detect filesystem type on Unix-like systems.
+
+    Uses 'df -T' or 'mount' to determine filesystem type.
+    """
+    try:
+        # Try using df -T first (more portable)
+        result = subprocess.run(
+            ["df", "-T", str(path)],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+
+        if result.returncode == 0:
+            output = result.stdout.lower()
+            # Check for common network filesystem types
+            if "nfs" in output:
+                return FilesystemType.NFS
+            if "cifs" in output:
+                return FilesystemType.CIFS
+            if "smb" in output:
+                return FilesystemType.SMB
+            if "fuse.sshfs" in output:
+                return FilesystemType.NETWORK_UNKNOWN
+            # If none of the above, assume local
+            return FilesystemType.LOCAL
+
+    except subprocess.TimeoutExpired:
+        logger.debug("df command timed out - may indicate network filesystem issue")
+        return FilesystemType.NETWORK_UNKNOWN
+    except FileNotFoundError:
+        # df not available, try alternative
+        pass
+    except Exception as e:
+        logger.debug(f"df command failed: {e}")
+
+    # Fallback: try reading /proc/mounts on Linux
+    try:
+        if os.path.exists("/proc/mounts"):
+            with open("/proc/mounts") as f:
+                mounts = f.read().lower()
+                path_str = str(path).lower()
+                # Find the mount point for this path
+                for line in mounts.split("\n"):
+                    parts = line.split()
+                    if len(parts) >= 3:
+                        mount_point = parts[1]
+                        fs_type = parts[2]
+                        if path_str.startswith(mount_point):
+                            if "nfs" in fs_type:
+                                return FilesystemType.NFS
+                            if "cifs" in fs_type or "smb" in fs_type:
+                                return FilesystemType.SMB
+    except Exception as e:
+        logger.debug(f"/proc/mounts check failed: {e}")
+
+    return FilesystemType.LOCAL
+
+
+def is_network_filesystem(path: Path) -> bool:
+    """Check if a path is on a network filesystem.
+
+    Args:
+        path: Path to check.
+
+    Returns:
+        True if the path appears to be on a network filesystem
+        (NFS, SMB, CIFS, or unknown network type).
+    """
+    fs_type = detect_filesystem_type(path)
+    return fs_type in (
+        FilesystemType.NFS,
+        FilesystemType.SMB,
+        FilesystemType.CIFS,
+        FilesystemType.NETWORK_UNKNOWN,
+    )
+
+
+def get_filesystem_warning_message(fs_type: FilesystemType, path: Path) -> str:
+    """Generate a warning message for network filesystem detection.
+
+    Args:
+        fs_type: The detected filesystem type.
+        path: The path that was checked.
+
+    Returns:
+        A warning message string explaining the risks.
+    """
+    return (
+        f"WARNING: Storage path appears to be on a network filesystem ({fs_type.value}). "
+        f"Path: {path}\n"
+        f"File-based locking does not work reliably on network filesystems. "
+        f"Running multiple instances against this storage may cause data corruption. "
+        f"To suppress this warning, set SPATIAL_MEMORY_ACKNOWLEDGE_NETWORK_FS_RISK=true "
+        f"or use a local filesystem path."
+    )

spatial_memory/core/models.py

@@ -53,6 +53,10 @@ class MemoryResult(BaseModel):
     importance: float
     created_at: datetime
     metadata: dict[str, Any] = Field(default_factory=dict)
+    vector: list[float] | None = Field(
+        default=None,
+        description="Embedding vector (only included when include_vector=True in search)",
+    )
 
 
 class ClusterInfo(BaseModel):

spatial_memory/core/rate_limiter.py

@@ -52,6 +52,19 @@ class RateLimiter:
         self._tokens = min(self.capacity, self._tokens + elapsed * self.rate)
         self._last_refill = now
 
+    def can_acquire(self, tokens: int = 1) -> bool:
+        """Check if tokens could be acquired without consuming them.
+
+        Args:
+            tokens: Number of tokens to check.
+
+        Returns:
+            True if tokens are available, False otherwise.
+        """
+        with self._lock:
+            self._refill()
+            return self._tokens >= tokens
+
     def acquire(self, tokens: int = 1) -> bool:
         """Try to acquire tokens without blocking.
 
@@ -201,6 +214,7 @@ class AgentAwareRateLimiter:
         """Try to acquire tokens without blocking.
 
         Must pass BOTH global AND per-agent limits (if agent_id provided).
+        Tokens are only consumed if both limits pass.
 
         Args:
             agent_id: Optional agent identifier. If None, only global limit applies.
@@ -209,21 +223,24 @@ class AgentAwareRateLimiter:
         Returns:
             True if tokens were acquired, False if rate limited.
         """
-        # Check global limit first (cheaper)
-        if not self._global.acquire(tokens):
-            return False
-
         # If no agent_id, only global limit applies
         if agent_id is None:
-            return True
+            return self._global.acquire(tokens)
 
-        # Check per-agent limit
+        # Check both limits first without consuming
         agent_limiter = self._get_agent_limiter(agent_id)
-        if not agent_limiter.acquire(tokens):
-            # Failed per-agent limit, but we already consumed global tokens
-            # This is acceptable - prevents gaming by switching agents
+
+        if not self._global.can_acquire(tokens):
             return False
 
+        if not agent_limiter.can_acquire(tokens):
+            return False
+
+        # Both limits pass, now actually consume tokens from both
+        # Note: Small race window here, but acceptable for rate limiting
+        self._global.acquire(tokens)
+        agent_limiter.acquire(tokens)
+
         return True
 
     def wait(