opencode-semantic-memory 0.1.0__py3-none-any.whl

opencode_memory/__init__.py

@@ -0,0 +1,3 @@
+"""OpenCode Memory - Persistent semantic memory for OpenCode sessions."""
+
+__version__ = "0.1.0"

opencode_memory/cache.py

@@ -0,0 +1,261 @@
+"""LRU cache for memories with background prefetching of linked memories."""
+
+import asyncio
+import logging
+import threading
+import time
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from opencode_memory.models import Memory
+    from opencode_memory.storage.sqlite import SQLiteStorage
+
+logger = logging.getLogger(__name__)
+
+# Cache configuration
+DEFAULT_MAX_SIZE = 50000  # Max memories to cache (~100MB at 2KB avg)
+DEFAULT_TTL_SECONDS = 86400  # 24 hours TTL (effectively no expiry for active use)
+PREFETCH_BATCH_SIZE = 20  # Max linked memories to prefetch at once
+
+
+@dataclass
+class CacheEntry:
+    """A cached memory with metadata."""
+
+    memory: "Memory"
+    cached_at: float = field(default_factory=time.time)
+    access_count: int = 0
+    last_accessed: float = field(default_factory=time.time)
+
+    def is_expired(self, ttl_seconds: float) -> bool:
+        """Check if this entry has expired."""
+        return (time.time() - self.cached_at) > ttl_seconds
+
+
+class MemoryCache:
+    """Thread-safe LRU cache for Memory objects with TTL and prefetching.
+
+    Features:
+    - LRU eviction when max size reached
+    - TTL-based expiration
+    - Background prefetching of linked memories
+    - Cache invalidation on memory updates/deletes
+    - Thread-safe operations
+    """
+
+    def __init__(
+        self,
+        storage: "SQLiteStorage",
+        max_size: int = DEFAULT_MAX_SIZE,
+        ttl_seconds: float = DEFAULT_TTL_SECONDS,
+    ):
+        self.storage = storage
+        self.max_size = max_size
+        self.ttl_seconds = ttl_seconds
+
+        # OrderedDict for LRU behavior (most recently used at end)
+        self._cache: OrderedDict[int, CacheEntry] = OrderedDict()
+        self._lock = threading.RLock()
+
+        # Track pending prefetch tasks to avoid duplicates
+        self._pending_prefetch: set[int] = set()
+        self._prefetch_lock = threading.Lock()
+
+        # Stats
+        self._hits = 0
+        self._misses = 0
+
+    def get(self, memory_id: int) -> "Memory | None":
+        """Get a memory from cache, returning None if not cached or expired."""
+        with self._lock:
+            entry = self._cache.get(memory_id)
+            if entry is None:
+                self._misses += 1
+                return None
+
+            if entry.is_expired(self.ttl_seconds):
+                # Remove expired entry
+                del self._cache[memory_id]
+                self._misses += 1
+                return None
+
+            # Update access metadata and move to end (most recently used)
+            entry.access_count += 1
+            entry.last_accessed = time.time()
+            self._cache.move_to_end(memory_id)
+            self._hits += 1
+            return entry.memory
+
+    def get_many(self, memory_ids: list[int]) -> dict[int, "Memory"]:
+        """Get multiple memories from cache. Returns dict of found entries."""
+        result = {}
+        with self._lock:
+            for memory_id in memory_ids:
+                entry = self._cache.get(memory_id)
+                if entry and not entry.is_expired(self.ttl_seconds):
+                    entry.access_count += 1
+                    entry.last_accessed = time.time()
+                    self._cache.move_to_end(memory_id)
+                    result[memory_id] = entry.memory
+                    self._hits += 1
+                else:
+                    if entry:
+                        del self._cache[memory_id]
+                    self._misses += 1
+        return result
+
+    def put(self, memory: "Memory") -> None:
+        """Add a memory to the cache."""
+        if memory.id is None:
+            return
+
+        with self._lock:
+            # If already cached, update and move to end
+            if memory.id in self._cache:
+                self._cache[memory.id] = CacheEntry(memory=memory)
+                self._cache.move_to_end(memory.id)
+            else:
+                # Evict oldest if at capacity
+                while len(self._cache) >= self.max_size:
+                    self._cache.popitem(last=False)  # Remove oldest
+
+                self._cache[memory.id] = CacheEntry(memory=memory)
+
+    def put_many(self, memories: list["Memory"]) -> None:
+        """Add multiple memories to the cache."""
+        with self._lock:
+            for memory in memories:
+                if memory.id is not None:
+                    if memory.id in self._cache:
+                        self._cache[memory.id] = CacheEntry(memory=memory)
+                        self._cache.move_to_end(memory.id)
+                    else:
+                        while len(self._cache) >= self.max_size:
+                            self._cache.popitem(last=False)
+                        self._cache[memory.id] = CacheEntry(memory=memory)
+
+    def invalidate(self, memory_id: int) -> bool:
+        """Remove a memory from cache. Returns True if it was cached."""
+        with self._lock:
+            if memory_id in self._cache:
+                del self._cache[memory_id]
+                return True
+            return False
+
+    def invalidate_many(self, memory_ids: list[int]) -> int:
+        """Remove multiple memories from cache. Returns count removed."""
+        removed = 0
+        with self._lock:
+            for memory_id in memory_ids:
+                if memory_id in self._cache:
+                    del self._cache[memory_id]
+                    removed += 1
+        return removed
+
+    def clear(self) -> int:
+        """Clear all cached entries. Returns count cleared."""
+        with self._lock:
+            count = len(self._cache)
+            self._cache.clear()
+            return count
+
+    def prefetch_linked(self, memory_id: int) -> None:
+        """Schedule background prefetch of memories linked to this one.
+
+        This is fire-and-forget - errors are logged but not raised.
+        Duplicate prefetch requests are ignored.
+        """
+        with self._prefetch_lock:
+            if memory_id in self._pending_prefetch:
+                return
+            self._pending_prefetch.add(memory_id)
+
+        # Run prefetch in background thread
+        def do_prefetch():
+            try:
+                self._do_prefetch_sync(memory_id)
+            finally:
+                with self._prefetch_lock:
+                    self._pending_prefetch.discard(memory_id)
+
+        thread = threading.Thread(target=do_prefetch, daemon=True)
+        thread.start()
+
+    async def prefetch_linked_async(self, memory_id: int) -> None:
+        """Async version of prefetch_linked for use in async contexts."""
+        with self._prefetch_lock:
+            if memory_id in self._pending_prefetch:
+                return
+            self._pending_prefetch.add(memory_id)
+
+        try:
+            # Run sync DB operations in thread pool
+            loop = asyncio.get_event_loop()
+            await loop.run_in_executor(None, self._do_prefetch_sync, memory_id)
+        finally:
+            with self._prefetch_lock:
+                self._pending_prefetch.discard(memory_id)
+
+    def _do_prefetch_sync(self, memory_id: int) -> None:
+        """Synchronously prefetch linked memories."""
+        try:
+            # Get linked memory IDs
+            linked_ids = self.storage.get_linked_memory_ids(memory_id)
+            if not linked_ids:
+                return
+
+            # Filter out already cached
+            with self._lock:
+                uncached_ids = [
+                    mid for mid in linked_ids[:PREFETCH_BATCH_SIZE] if mid not in self._cache
+                ]
+
+            if not uncached_ids:
+                return
+
+            # Batch fetch from database
+            memories_map = self.storage.get_memories_by_ids(uncached_ids)
+
+            # Cache the fetched memories
+            self.put_many(list(memories_map.values()))
+
+            logger.debug(f"Prefetched {len(memories_map)} linked memories for memory {memory_id}")
+        except Exception as e:
+            logger.warning(f"Failed to prefetch linked memories for {memory_id}: {e}")
+
+    def get_stats(self) -> dict:
+        """Get cache statistics."""
+        with self._lock:
+            total_requests = self._hits + self._misses
+            hit_rate = self._hits / total_requests if total_requests > 0 else 0.0
+
+            # Count expired entries without removing them
+            now = time.time()
+            expired_count = sum(
+                1 for entry in self._cache.values() if entry.is_expired(self.ttl_seconds)
+            )
+
+            return {
+                "size": len(self._cache),
+                "max_size": self.max_size,
+                "hits": self._hits,
+                "misses": self._misses,
+                "hit_rate": round(hit_rate, 3),
+                "expired_entries": expired_count,
+                "pending_prefetch": len(self._pending_prefetch),
+                "ttl_seconds": self.ttl_seconds,
+            }
+
+    def cleanup_expired(self) -> int:
+        """Remove all expired entries. Returns count removed."""
+        removed = 0
+        with self._lock:
+            expired_ids = [
+                mid for mid, entry in self._cache.items() if entry.is_expired(self.ttl_seconds)
+            ]
+            for mid in expired_ids:
+                del self._cache[mid]
+                removed += 1
+        return removed