spatial-memory-mcp 1.6.1__py3-none-any.whl → 1.7.0__py3-none-any.whl

spatial_memory/services/__init__.py

@@ -7,6 +7,9 @@ from spatial_memory.core.errors import (
     NamespaceOperationError,
     ReinforcementError,
 )
+from spatial_memory.services.export_import import (
+    ExportImportService,
+)
 from spatial_memory.services.lifecycle import (
     ConsolidateResult,
     ConsolidationGroupResult,
@@ -33,9 +36,6 @@ from spatial_memory.services.spatial import (
 from spatial_memory.services.utility import (
     UtilityService,
 )
-from spatial_memory.services.export_import import (
-    ExportImportService,
-)
 
 __all__ = [
     # Lifecycle

spatial_memory/services/decay_manager.py

@@ -0,0 +1,406 @@
+"""Automatic decay manager for real-time importance decay.
+
+This service provides automatic decay calculation during recall operations,
+re-ranking search results based on time-decayed importance. Updates are
+optionally persisted to the database in the background.
+
+Architecture:
+    recall() / hybrid_recall()
+            │
+            ▼
+    DecayManager.apply_decay_to_results()  ← Real-time (~20-50μs)
+            │
+       ┌────┴────┐
+       ▼         ▼
+    [Re-ranked   [Background Queue]
+     Results]          │
+                       ▼
+                [Batch Persist Thread]
+                       │
+                       ▼
+                [LanceDB Update]
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+import threading
+import time
+from collections import deque
+from dataclasses import dataclass
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+from spatial_memory.core.models import AutoDecayConfig
+from spatial_memory.core.utils import to_aware_utc, utc_now
+
+if TYPE_CHECKING:
+    from spatial_memory.ports.repositories import MemoryRepositoryProtocol
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class DecayUpdate:
+    """A pending decay update for a memory."""
+
+    memory_id: str
+    old_importance: float
+    new_importance: float
+    timestamp: float  # time.monotonic() for deduplication
+
+
+class DecayManager:
+    """Manages automatic decay calculation and persistence.
+
+    This service calculates effective importance during search operations
+    using exponential decay based on time since last access. Results are
+    re-ranked by multiplying similarity with effective importance.
+
+    Background persistence is optional and uses a daemon thread with
+    batched updates to minimize database overhead.
+    """
+
+    def __init__(
+        self,
+        repository: MemoryRepositoryProtocol,
+        config: AutoDecayConfig | None = None,
+    ) -> None:
+        """Initialize the decay manager.
+
+        Args:
+            repository: Repository for persisting decay updates.
+            config: Configuration for decay behavior.
+        """
+        self._repo = repository
+        self._config = config or AutoDecayConfig()
+
+        # Threading primitives
+        self._lock = threading.Lock()
+        self._shutdown_event = threading.Event()
+        self._worker_thread: threading.Thread | None = None
+
+        # Update queue with backpressure (deque with maxlen)
+        # Using maxlen for automatic backpressure - oldest items dropped
+        self._update_queue: deque[DecayUpdate] = deque(
+            maxlen=self._config.max_queue_size
+        )
+
+        # Track pending updates by memory_id for deduplication
+        self._pending_updates: dict[str, DecayUpdate] = {}
+
+        # Statistics
+        self._stats_lock = threading.Lock()
+        self._updates_queued = 0
+        self._updates_persisted = 0
+        self._updates_deduplicated = 0
+
+    @property
+    def enabled(self) -> bool:
+        """Whether auto-decay is enabled."""
+        return self._config.enabled
+
+    @property
+    def persist_enabled(self) -> bool:
+        """Whether persistence is enabled."""
+        return self._config.persist_enabled
+
+    def start(self) -> None:
+        """Start the background persistence worker.
+
+        Safe to call multiple times - will only start if not already running.
+        """
+        if not self._config.enabled or not self._config.persist_enabled:
+            logger.debug("Auto-decay persistence disabled, skipping worker start")
+            return
+
+        if self._worker_thread is not None and self._worker_thread.is_alive():
+            logger.debug("Decay worker already running")
+            return
+
+        self._shutdown_event.clear()
+        self._worker_thread = threading.Thread(
+            target=self._background_worker,
+            name="decay-persist-worker",
+            daemon=True,
+        )
+        self._worker_thread.start()
+        logger.info("Auto-decay background worker started")
+
+    def stop(self, timeout: float = 5.0) -> None:
+        """Stop the background worker gracefully.
+
+        Flushes any pending updates before stopping.
+
+        Args:
+            timeout: Maximum time to wait for worker shutdown.
+        """
+        if self._worker_thread is None or not self._worker_thread.is_alive():
+            return
+
+        logger.info("Stopping auto-decay background worker...")
+        self._shutdown_event.set()
+
+        # Wait for worker to finish
+        self._worker_thread.join(timeout=timeout)
+
+        if self._worker_thread.is_alive():
+            logger.warning("Decay worker did not stop within timeout")
+        else:
+            logger.info(
+                f"Auto-decay worker stopped. "
+                f"Queued: {self._updates_queued}, "
+                f"Persisted: {self._updates_persisted}, "
+                f"Deduplicated: {self._updates_deduplicated}"
+            )
+
+    def calculate_effective_importance(
+        self,
+        stored_importance: float,
+        last_accessed: datetime,
+        access_count: int,
+    ) -> float:
+        """Calculate time-decayed effective importance.
+
+        Uses exponential decay: importance * 2^(-days/half_life)
+        Access count slows decay via effective_half_life adjustment.
+
+        Args:
+            stored_importance: The stored importance value (0-1).
+            last_accessed: When the memory was last accessed.
+            access_count: Number of times the memory has been accessed.
+
+        Returns:
+            Effective importance after decay (clamped to min_importance_floor).
+        """
+        if not self._config.enabled:
+            return stored_importance
+
+        # Calculate days since last access
+        # Normalize last_accessed to timezone-aware UTC (database may return naive)
+        now = utc_now()
+        last_accessed_aware = to_aware_utc(last_accessed)
+        delta = now - last_accessed_aware
+        days_since_access = delta.total_seconds() / 86400.0  # seconds in a day
+
+        if days_since_access <= 0:
+            return stored_importance
+
+        # Calculate effective half-life (access count slows decay)
+        # More accesses = longer effective half-life = slower decay
+        access_factor = 1.0 + self._config.access_weight * access_count
+        effective_half_life = self._config.half_life_days * access_factor
+
+        # Exponential decay: importance * 2^(-days/half_life)
+        decay_factor = math.pow(2, -days_since_access / effective_half_life)
+        effective_importance = stored_importance * decay_factor
+
+        # Clamp to minimum floor
+        return max(effective_importance, self._config.min_importance_floor)
+
+    def apply_decay_to_results(
+        self,
+        results: list[dict[str, Any]],
+        rerank: bool = True,
+    ) -> list[dict[str, Any]]:
+        """Apply decay to search results and optionally re-rank.
+
+        Calculates effective_importance for each result and optionally
+        re-ranks results by multiplying similarity with effective_importance.
+
+        Args:
+            results: List of memory result dictionaries.
+            rerank: Whether to re-rank by adjusted score (similarity × effective_importance).
+
+        Returns:
+            Results with effective_importance added, optionally re-ranked.
+        """
+        if not self._config.enabled or not results:
+            return results
+
+        updates_to_queue: list[DecayUpdate] = []
+
+        for result in results:
+            # Extract required fields
+            stored_importance = result.get("importance", 0.5)
+            last_accessed = result.get("last_accessed")
+            access_count = result.get("access_count", 0)
+            memory_id = result.get("id", "")
+
+            # Handle datetime parsing if needed
+            if isinstance(last_accessed, str):
+                try:
+                    last_accessed = datetime.fromisoformat(last_accessed.replace("Z", "+00:00"))
+                except (ValueError, AttributeError):
+                    last_accessed = utc_now()
+            elif last_accessed is None:
+                last_accessed = utc_now()
+
+            # Calculate effective importance
+            effective_importance = self.calculate_effective_importance(
+                stored_importance=stored_importance,
+                last_accessed=last_accessed,
+                access_count=access_count,
+            )
+
+            # Add to result
+            result["effective_importance"] = effective_importance
+
+            # Check if we should queue an update
+            if self._config.persist_enabled and memory_id:
+                change = abs(stored_importance - effective_importance)
+                if change >= self._config.min_change_threshold:
+                    updates_to_queue.append(
+                        DecayUpdate(
+                            memory_id=memory_id,
+                            old_importance=stored_importance,
+                            new_importance=effective_importance,
+                            timestamp=time.monotonic(),
+                        )
+                    )
+
+        # Queue updates in bulk
+        if updates_to_queue:
+            self._queue_updates(updates_to_queue)
+
+        # Re-rank by adjusted score if requested
+        if rerank:
+            # Calculate adjusted score: similarity × effective_importance
+            for result in results:
+                similarity = result.get("similarity", 0.0)
+                effective = result.get("effective_importance", result.get("importance", 0.5))
+                result["_adjusted_score"] = similarity * effective
+
+            # Sort by adjusted score (descending)
+            results.sort(key=lambda r: r.get("_adjusted_score", 0.0), reverse=True)
+
+            # Remove temporary score field
+            for result in results:
+                result.pop("_adjusted_score", None)
+
+        return results
+
+    def _queue_updates(self, updates: list[DecayUpdate]) -> None:
+        """Queue updates for background persistence with deduplication.
+
+        Latest update per memory_id wins - prevents duplicate writes.
+
+        Args:
+            updates: List of decay updates to queue.
+        """
+        with self._lock:
+            for update in updates:
+                # Deduplicate: keep latest update per memory_id
+                existing = self._pending_updates.get(update.memory_id)
+                if existing is not None:
+                    with self._stats_lock:
+                        self._updates_deduplicated += 1
+
+                self._pending_updates[update.memory_id] = update
+                self._update_queue.append(update)
+
+                with self._stats_lock:
+                    self._updates_queued += 1
+
+    def _background_worker(self) -> None:
+        """Background worker that batches and persists decay updates."""
+        logger.debug("Decay background worker started")
+
+        while not self._shutdown_event.is_set():
+            try:
+                # Wait for flush interval or shutdown
+                self._shutdown_event.wait(timeout=self._config.persist_flush_interval_seconds)
+
+                # Collect batch of updates
+                batch = self._collect_batch()
+
+                if batch:
+                    self._persist_batch(batch)
+
+            except Exception as e:
+                logger.error(f"Error in decay background worker: {e}", exc_info=True)
+                # Don't crash the worker on transient errors
+                time.sleep(1.0)
+
+        # Final flush on shutdown
+        try:
+            batch = self._collect_batch()
+            if batch:
+                logger.debug(f"Final flush: {len(batch)} updates")
+                self._persist_batch(batch)
+        except Exception as e:
+            logger.error(f"Error in final decay flush: {e}", exc_info=True)
+
+        logger.debug("Decay background worker stopped")
+
+    def _collect_batch(self) -> list[DecayUpdate]:
+        """Collect a batch of updates for persistence.
+
+        Returns:
+            List of unique updates (latest per memory_id).
+        """
+        with self._lock:
+            if not self._pending_updates:
+                return []
+
+            # Get unique updates (already deduplicated in _pending_updates)
+            batch = list(self._pending_updates.values())[:self._config.persist_batch_size]
+
+            # Clear processed updates from pending dict
+            for update in batch:
+                self._pending_updates.pop(update.memory_id, None)
+
+            return batch
+
+    def _persist_batch(self, batch: list[DecayUpdate]) -> None:
+        """Persist a batch of decay updates to the database.
+
+        Args:
+            batch: List of decay updates to persist.
+        """
+        if not batch:
+            return
+
+        # Build update tuples for batch update
+        updates = [
+            (update.memory_id, {"importance": update.new_importance})
+            for update in batch
+        ]
+
+        try:
+            success_count, failed_ids = self._repo.update_batch(updates)
+
+            with self._stats_lock:
+                self._updates_persisted += success_count
+
+            if failed_ids:
+                logger.warning(f"Failed to persist decay for {len(failed_ids)} memories")
+
+            logger.debug(f"Persisted decay updates for {success_count} memories")
+
+        except Exception as e:
+            logger.error(f"Failed to persist decay batch: {e}")
+            # Re-queue failed updates? For now, just log and continue
+            # In a production system, you might want retry logic here
+
+    def get_stats(self) -> dict[str, Any]:
+        """Get decay manager statistics.
+
+        Returns:
+            Dictionary with queue and persistence stats.
+        """
+        with self._stats_lock:
+            return {
+                "enabled": self._config.enabled,
+                "persist_enabled": self._config.persist_enabled,
+                "updates_queued": self._updates_queued,
+                "updates_persisted": self._updates_persisted,
+                "updates_deduplicated": self._updates_deduplicated,
+                "pending_updates": len(self._pending_updates),
+                "queue_size": len(self._update_queue),
+                "queue_max_size": self._config.max_queue_size,
+                "worker_alive": (
+                    self._worker_thread is not None and self._worker_thread.is_alive()
+                ),
+            }

spatial_memory/services/export_import.py

@@ -17,11 +17,11 @@ import csv
 import json
 import logging
 import time
-from collections.abc import Sequence
-from datetime import datetime, timezone
-from pathlib import Path
+from collections.abc import Iterator, Sequence
+from datetime import datetime
 from io import TextIOWrapper
-from typing import TYPE_CHECKING, Any, BinaryIO, Iterator
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, BinaryIO
 
 import numpy as np
 
@@ -45,6 +45,8 @@ from spatial_memory.core.models import (
 logger = logging.getLogger(__name__)
 
 if TYPE_CHECKING:
+    import pyarrow as pa
+
     from spatial_memory.ports.repositories import (
         EmbeddingServiceProtocol,
         MemoryRepositoryProtocol,
@@ -504,7 +506,7 @@ class ExportImportService:
     # Export Format Handlers
     # =========================================================================
 
-    def _create_parquet_schema(self, include_vectors: bool) -> "pa.Schema":
+    def _create_parquet_schema(self, include_vectors: bool) -> pa.Schema:
         """Create PyArrow schema for Parquet export.
 
         Args:
@@ -816,8 +818,7 @@ class ExportImportService:
         if content.startswith("["):
             # JSON array
             records = json.loads(content)
-            for record in records:
-                yield record
+            yield from records
         else:
             # JSON Lines (one object per line)
             for line in content.split("\n"):
@@ -959,7 +960,8 @@ class ExportImportService:
                                 ImportValidationError(
                                     row_number=row_number,
                                     field="vector",
-                                    error=f"Vector dimension mismatch: expected {expected_dims}, got {actual_dims}",
+                                    error=f"Vector dimension mismatch: expected "
+                                    f"{expected_dims}, got {actual_dims}",
                                     value=f"[{actual_dims} dimensions]",
                                 )
                             )

spatial_memory/services/lifecycle.py

@@ -20,6 +20,10 @@ from typing import TYPE_CHECKING, Any, Literal
 
 import numpy as np
 
+from spatial_memory.core.consolidation_strategies import (
+    ConsolidationAction,
+    get_strategy,
+)
 from spatial_memory.core.errors import (
     ConsolidationError,
     DecayError,
@@ -27,10 +31,6 @@ from spatial_memory.core.errors import (
     ReinforcementError,
     ValidationError,
 )
-from spatial_memory.core.consolidation_strategies import (
-    ConsolidationAction,
-    get_strategy,
-)
 from spatial_memory.core.lifecycle_ops import (
     apply_decay,
     calculate_decay_factor,
@@ -52,11 +52,11 @@ from spatial_memory.core.models import (
     ReinforcedMemory,
     ReinforceResult,
 )
+from spatial_memory.core.utils import to_naive_utc, utc_now, utc_now_naive
+from spatial_memory.core.validation import validate_namespace
 
 # Alias for backward compatibility
 ConsolidationGroupResult = ConsolidationGroup
-from spatial_memory.core.utils import to_naive_utc, utc_now, utc_now_naive
-from spatial_memory.core.validation import validate_namespace
 
 logger = logging.getLogger(__name__)
 
@@ -384,7 +384,8 @@ class LifecycleService:
             # Calculate reinforcement for all found memories
             now = utc_now()
             batch_updates: list[tuple[str, dict[str, Any]]] = []
-            reinforcement_info: list[tuple[str, Memory, float, float]] = []  # id, memory, new_imp, boost
+            # Tuple: (id, memory, new_importance, boost_applied)
+            reinforcement_info: list[tuple[str, Memory, float, float]] = []
 
             for memory_id, memory in memory_map.items():
                 # Calculate new importance
@@ -413,7 +414,9 @@ class LifecycleService:
                     f"{len(batch_failed_ids)} failed"
                 )
             except Exception as e:
-                logger.warning(f"Batch reinforce update failed: {e}, falling back to individual updates")
+                logger.warning(
+                    f"Batch reinforce update failed: {e}, falling back to individual updates"
+                )
                 # Fall back to individual updates on batch failure
                 batch_failed_ids = []
                 for memory_id, updates in batch_updates:

spatial_memory/services/spatial.py

@@ -267,8 +267,11 @@ class SpatialService:
                     steps_with_memories += 1
 
                 # Use 0.0 if no memories found (inf means no distance calculated)
-                # Clamp to 0.0 to handle floating point precision errors (e.g., -4.89e-08)
-                final_distance = 0.0 if distance_to_path == float("inf") else max(0.0, distance_to_path)
+                # Clamp to 0.0 to handle floating point precision errors
+                if distance_to_path == float("inf"):
+                    final_distance = 0.0
+                else:
+                    final_distance = max(0.0, distance_to_path)
                 journey_steps.append(
                     JourneyStep(
                         step=step_num,

spatial_memory/services/utility.py

@@ -243,7 +243,8 @@ class UtilityService:
                     namespace=namespace,
                     memories_deleted=memory_count,
                     success=True,
-                    message=f"DRY RUN: Would delete {memory_count} memories from namespace '{namespace}'",
+                    message=f"DRY RUN: Would delete {memory_count} memories "
+                    f"from namespace '{namespace}'",
                     dry_run=True,
                 )
 
@@ -261,7 +262,7 @@ class UtilityService:
                 namespace=namespace,
                 memories_deleted=deleted_count,
                 success=True,
-                message=f"Successfully deleted {deleted_count} memories from namespace '{namespace}'",
+                message=f"Deleted {deleted_count} memories from namespace '{namespace}'",
                 dry_run=False,
             )
 
@@ -313,7 +314,8 @@ class UtilityService:
                 new_namespace=new_namespace,
                 memories_renamed=renamed_count,
                 success=True,
-                message=f"Successfully renamed {renamed_count} memories from '{old_namespace}' to '{new_namespace}'",
+                message=f"Renamed {renamed_count} memories "
+                f"from '{old_namespace}' to '{new_namespace}'",
             )
 
         except NamespaceNotFoundError:
@@ -397,9 +399,21 @@ class UtilityService:
                         vector_score=getattr(result, "vector_score", None),
                         fts_score=getattr(result, "fts_score", None),
                         combined_score=result.similarity,
+                        # For auto-decay support
+                        last_accessed=result.last_accessed,
+                        access_count=result.access_count,
                     )
                 )
 
+        # Update access stats for returned memories (batch for efficiency)
+        if memories:
+            memory_ids = [m.id for m in memories]
+            try:
+                self._repo.update_access_batch(memory_ids)
+            except Exception as e:
+                # Log but don't fail the search if access update fails
+                logger.warning(f"Failed to update access stats: {e}")
+
         return HybridRecallResult(
             query=query,
             alpha=alpha,

{spatial_memory_mcp-1.6.1.dist-info → spatial_memory_mcp-1.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatial-memory-mcp
-Version: 1.6.1
+Version: 1.7.0
 Summary: Spatial bidirectional persistent memory MCP server for LLMs - vector-based semantic memory as a navigable landscape
 Project-URL: Homepage, https://github.com/arman-tech/spatial-memory-mcp
 Project-URL: Repository, https://github.com/arman-tech/spatial-memory-mcp
@@ -48,7 +48,7 @@ Description-Content-Type: text/markdown
 
 A vector-based spatial memory system that treats knowledge as a navigable landscape, not a filing cabinet.
 
-> **Version 1.6.1** — Production-ready with 1,360 tests passing.
+> **Version 1.6.2** — Production-ready with 1,360 tests passing.
 
 ## Supported Platforms