@smilintux/skmemory 0.5.0

package/skmemory/store.py

@@ -0,0 +1,445 @@
+"""
+MemoryStore - the main interface for storing and recalling memories.
+
+This is the "camera" -- you point it at a moment, click, and it stores
+a polaroid with full emotional context. Later, you recall by feeling
+or by search, and the polaroid comes back with everything intact.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Optional
+
+from .backends.base import BaseBackend
+from .backends.file_backend import FileBackend
+from .backends.sqlite_backend import CONTENT_PREVIEW_LENGTH, SQLiteBackend
+from .models import (
+    EmotionalSnapshot,
+    Memory,
+    MemoryLayer,
+    MemoryRole,
+    SeedMemory,
+)
+
+
+class MemoryStore:
+    """Main entry point for all memory operations.
+
+    Delegates to one or more backends. The primary backend handles
+    all CRUD. A vector backend (optional) handles semantic search.
+
+    Args:
+        primary: The primary storage backend (default: FileBackend).
+        vector: Optional vector search backend (e.g., QdrantBackend).
+    """
+
+    def __init__(
+        self,
+        primary: Optional[BaseBackend] = None,
+        vector: Optional[BaseBackend] = None,
+        use_sqlite: bool = True,
+    ) -> None:
+        if primary is not None:
+            self.primary = primary
+        elif use_sqlite:
+            self.primary = SQLiteBackend()
+        else:
+            self.primary = FileBackend()
+        self.vector = vector
+
+    def snapshot(
+        self,
+        title: str,
+        content: str,
+        *,
+        layer: MemoryLayer = MemoryLayer.SHORT,
+        role: MemoryRole = MemoryRole.GENERAL,
+        tags: Optional[list[str]] = None,
+        emotional: Optional[EmotionalSnapshot] = None,
+        source: str = "manual",
+        source_ref: str = "",
+        related_ids: Optional[list[str]] = None,
+        metadata: Optional[dict] = None,
+    ) -> Memory:
+        """Take a polaroid -- capture a moment as a memory.
+
+        This is the primary way to create memories. It stores to
+        the primary backend and optionally indexes in the vector backend.
+
+        Args:
+            title: Short label for this memory.
+            content: The full memory content.
+            layer: Persistence tier.
+            role: Role-based partition.
+            tags: Searchable tags.
+            emotional: Emotional context snapshot.
+            source: Where this memory came from.
+            source_ref: Reference to the source.
+            related_ids: IDs of related memories.
+            metadata: Additional key-value data.
+
+        Returns:
+            Memory: The stored memory with its assigned ID.
+        """
+        memory = Memory(
+            title=title,
+            content=content,
+            layer=layer,
+            role=role,
+            tags=tags or [],
+            emotional=emotional or EmotionalSnapshot(),
+            source=source,
+            source_ref=source_ref,
+            related_ids=related_ids or [],
+            metadata=metadata or {},
+        )
+
+        self.primary.save(memory)
+
+        if self.vector:
+            try:
+                self.vector.save(memory)
+            except Exception:
+                pass  # Reason: vector indexing is best-effort, don't fail the write
+
+        return memory
+
+    def recall(self, memory_id: str) -> Optional[Memory]:
+        """Retrieve a specific memory by ID.
+
+        Args:
+            memory_id: The memory's unique identifier.
+
+        Returns:
+            Optional[Memory]: The memory if found.
+        """
+        return self.primary.load(memory_id)
+
+    def search(self, query: str, limit: int = 10) -> list[Memory]:
+        """Search memories by text.
+
+        Uses vector backend if available, falls back to text search.
+
+        Args:
+            query: Search query string.
+            limit: Maximum results.
+
+        Returns:
+            list[Memory]: Matching memories ranked by relevance.
+        """
+        if self.vector:
+            try:
+                results = self.vector.search_text(query, limit=limit)
+                if results:
+                    return results
+            except Exception:
+                pass  # Reason: fall through to primary text search
+
+        return self.primary.search_text(query, limit=limit)
+
+    def forget(self, memory_id: str) -> bool:
+        """Delete a memory from all backends.
+
+        Args:
+            memory_id: The memory to remove.
+
+        Returns:
+            bool: True if deleted from primary backend.
+        """
+        deleted = self.primary.delete(memory_id)
+        if self.vector:
+            try:
+                self.vector.delete(memory_id)
+            except Exception:
+                pass
+        return deleted
+
+    def list_memories(
+        self,
+        layer: Optional[MemoryLayer] = None,
+        tags: Optional[list[str]] = None,
+        limit: int = 50,
+    ) -> list[Memory]:
+        """List memories with optional filtering.
+
+        Args:
+            layer: Filter by layer.
+            tags: Filter by tags (AND logic).
+            limit: Max results.
+
+        Returns:
+            list[Memory]: Matching memories sorted newest first.
+        """
+        return self.primary.list_memories(layer=layer, tags=tags, limit=limit)
+
+    def promote(
+        self,
+        memory_id: str,
+        target: MemoryLayer,
+        summary: str = "",
+    ) -> Optional[Memory]:
+        """Promote a memory to a higher persistence tier.
+
+        Creates a new memory at the target layer linked to the original.
+        The original stays in place as the detailed version.
+
+        Args:
+            memory_id: ID of the memory to promote.
+            target: Target layer (should be higher than current).
+            summary: Optional compressed summary.
+
+        Returns:
+            Optional[Memory]: The promoted memory, or None if source not found.
+        """
+        source = self.primary.load(memory_id)
+        if source is None:
+            return None
+
+        promoted = source.promote(target, summary=summary)
+        self.primary.save(promoted)
+
+        if self.vector:
+            try:
+                self.vector.save(promoted)
+            except Exception:
+                pass
+
+        return promoted
+
+    def ingest_seed(self, seed: SeedMemory) -> Memory:
+        """Import a Cloud 9 seed as a long-term memory.
+
+        Converts a seed into a Memory and stores it. This is how
+        seeds planted by one AI instance become retrievable memories
+        for the next.
+
+        Args:
+            seed: The SeedMemory to import.
+
+        Returns:
+            Memory: The created long-term memory.
+        """
+        memory = seed.to_memory()
+        self.primary.save(memory)
+
+        if self.vector:
+            try:
+                self.vector.save(memory)
+            except Exception:
+                pass
+
+        return memory
+
+    def session_dump(self, session_id: str) -> list[Memory]:
+        """Get all memories from a specific session.
+
+        Args:
+            session_id: The session identifier.
+
+        Returns:
+            list[Memory]: All memories tagged with this session.
+        """
+        return self.primary.list_memories(
+            layer=MemoryLayer.SHORT,
+            tags=[f"session:{session_id}"],
+        )
+
+    def consolidate_session(
+        self,
+        session_id: str,
+        summary: str,
+        emotional: Optional[EmotionalSnapshot] = None,
+    ) -> Memory:
+        """Compress a session's short-term memories into a single mid-term memory.
+
+        This is the "end of day" operation: take all the short-term snapshots
+        from a session and create one consolidated mid-term memory that captures
+        the essence. Individual short-term memories are preserved.
+
+        Args:
+            session_id: The session to consolidate.
+            summary: Human/AI-written summary of the session.
+            emotional: Overall emotional snapshot for the session.
+
+        Returns:
+            Memory: The consolidated mid-term memory.
+        """
+        session_memories = self.session_dump(session_id)
+        related = [m.id for m in session_memories]
+        all_tags = set()
+        for m in session_memories:
+            all_tags.update(m.tags)
+        all_tags.add(f"session:{session_id}")
+        all_tags.add("consolidated")
+
+        return self.snapshot(
+            title=f"Session: {session_id}",
+            content=summary,
+            layer=MemoryLayer.MID,
+            role=MemoryRole.AI,
+            tags=list(all_tags),
+            emotional=emotional or EmotionalSnapshot(),
+            source="consolidation",
+            source_ref=session_id,
+            related_ids=related,
+            metadata={
+                "source_count": len(session_memories),
+                "consolidated_at": datetime.now(timezone.utc).isoformat(),
+            },
+        )
+
+    def load_context(
+        self,
+        max_tokens: int = 3000,
+        strongest_count: int = 5,
+        recent_count: int = 5,
+        include_seeds: bool = True,
+    ) -> dict:
+        """Load a token-efficient memory context for agent injection.
+
+        Uses the SQLite index to pull summaries without reading full files.
+        Designed to fit within a reasonable context window.
+
+        Args:
+            max_tokens: Approximate token budget (1 token ~= 4 chars).
+            strongest_count: How many top-intensity memories to include.
+            recent_count: How many recent memories to include.
+            include_seeds: Whether to include seed memories.
+
+        Returns:
+            dict: Token-efficient context with summaries and metadata.
+        """
+        char_budget = max_tokens * 4
+        context: dict = {"memories": [], "seeds": [], "stats": {}}
+        used = 0
+
+        if isinstance(self.primary, SQLiteBackend):
+            strongest = self.primary.list_summaries(
+                limit=strongest_count,
+                order_by="emotional_intensity",
+                min_intensity=3.0,
+            )
+            recent = self.primary.list_summaries(
+                limit=recent_count,
+                order_by="created_at",
+            )
+
+            seen_ids: set[str] = set()
+            for mem in strongest + recent:
+                if mem["id"] in seen_ids:
+                    continue
+                seen_ids.add(mem["id"])
+
+                entry_text = mem["title"] + (mem["summary"] or mem["content_preview"])
+                entry_size = len(entry_text)
+                if used + entry_size > char_budget:
+                    break
+                used += entry_size
+                context["memories"].append(mem)
+
+            if include_seeds:
+                seeds = self.primary.list_summaries(
+                    tags=["seed"],
+                    limit=10,
+                    order_by="emotional_intensity",
+                )
+                for seed in seeds:
+                    if seed["id"] in seen_ids:
+                        continue
+                    entry_text = seed["title"] + seed["summary"]
+                    entry_size = len(entry_text)
+                    if used + entry_size > char_budget:
+                        break
+                    used += entry_size
+                    context["seeds"].append(seed)
+
+            stats = self.primary.stats()
+            context["stats"] = stats
+        else:
+            # Reason: fallback for non-SQLite backends — uses full objects
+            all_mems = self.primary.list_memories(limit=strongest_count + recent_count)
+            for mem in all_mems:
+                entry = {
+                    "id": mem.id,
+                    "title": mem.title,
+                    "summary": mem.summary or mem.content[:CONTENT_PREVIEW_LENGTH],
+                    "emotional_intensity": mem.emotional.intensity,
+                    "layer": mem.layer.value,
+                }
+                entry_size = len(entry["title"] + entry["summary"])
+                if used + entry_size > char_budget:
+                    break
+                used += entry_size
+                context["memories"].append(entry)
+
+        context["token_estimate"] = used // 4
+        return context
+
+    def export_backup(self, output_path: str | None = None) -> str:
+        """Export all memories to a dated JSON backup.
+
+        Args:
+            output_path: Destination file. Defaults to
+                ``~/.skmemory/backups/skmemory-backup-YYYY-MM-DD.json``.
+
+        Returns:
+            str: Path to the written backup file.
+
+        Raises:
+            RuntimeError: If the primary backend doesn't support export.
+        """
+        if isinstance(self.primary, SQLiteBackend):
+            return self.primary.export_all(output_path)
+        if isinstance(self.primary, FileBackend):
+            # Reason: wrap FileBackend in a temporary SQLiteBackend for export
+            temp = SQLiteBackend(base_path=str(self.primary.base_path))
+            temp.reindex()
+            return temp.export_all(output_path)
+        raise RuntimeError(
+            f"Export not supported for backend: {type(self.primary).__name__}"
+        )
+
+    def import_backup(self, backup_path: str) -> int:
+        """Restore memories from a JSON backup file.
+
+        Args:
+            backup_path: Path to the backup JSON.
+
+        Returns:
+            int: Number of memories restored.
+
+        Raises:
+            RuntimeError: If the primary backend doesn't support import.
+        """
+        if isinstance(self.primary, SQLiteBackend):
+            return self.primary.import_backup(backup_path)
+        raise RuntimeError(
+            f"Import not supported for backend: {type(self.primary).__name__}"
+        )
+
+    def reindex(self) -> int:
+        """Rebuild the SQLite index from JSON files.
+
+        Only works if the primary backend is SQLiteBackend.
+
+        Returns:
+            int: Number of memories indexed, or -1 if not applicable.
+        """
+        if isinstance(self.primary, SQLiteBackend):
+            return self.primary.reindex()
+        return -1
+
+    def health(self) -> dict:
+        """Check health of all backends.
+
+        Returns:
+            dict: Combined health status.
+        """
+        status = {"primary": self.primary.health_check()}
+        if self.vector:
+            try:
+                status["vector"] = self.vector.health_check()
+            except Exception as e:
+                status["vector"] = {"ok": False, "error": str(e)}
+        return status

package/tests/test_ai_client.py

@@ -0,0 +1,89 @@
+"""Tests for the AI client module (Ollama integration).
+
+These tests verify the client interface without requiring a running
+Ollama server. The client is designed to fail gracefully.
+"""
+
+import json
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from skmemory.ai_client import AIClient, DEFAULT_MODEL, DEFAULT_URL
+
+
+class TestClientInit:
+    """Client initialization and configuration."""
+
+    def test_defaults(self):
+        """Client uses sensible defaults."""
+        client = AIClient()
+        assert client.base_url == DEFAULT_URL
+        assert client.model == DEFAULT_MODEL
+
+    def test_custom_url(self):
+        """Custom URL is respected."""
+        client = AIClient(base_url="http://my-server:11434")
+        assert client.base_url == "http://my-server:11434"
+
+    def test_custom_model(self):
+        """Custom model name is respected."""
+        client = AIClient(model="mistral")
+        assert client.model == "mistral"
+
+    def test_env_vars(self, monkeypatch):
+        """Environment variables configure the client."""
+        monkeypatch.setenv("SKMEMORY_AI_URL", "http://env:1234")
+        monkeypatch.setenv("SKMEMORY_AI_MODEL", "phi3")
+        monkeypatch.setenv("SKMEMORY_AI_TIMEOUT", "30")
+
+        client = AIClient()
+        assert client.base_url == "http://env:1234"
+        assert client.model == "phi3"
+        assert client.timeout == 30
+
+    def test_explicit_overrides_env(self, monkeypatch):
+        """Explicit args take precedence over env vars."""
+        monkeypatch.setenv("SKMEMORY_AI_MODEL", "phi3")
+        client = AIClient(model="gemma2")
+        assert client.model == "gemma2"
+
+
+class TestAvailability:
+    """Server availability checks."""
+
+    def test_not_available_when_unreachable(self):
+        """Returns False when server is not running."""
+        client = AIClient(base_url="http://localhost:99999")
+        assert client.is_available() is False
+
+
+class TestGracefulFallback:
+    """All methods fail gracefully when LLM is unreachable."""
+
+    @pytest.fixture
+    def offline_client(self):
+        return AIClient(base_url="http://localhost:99999")
+
+    def test_generate_returns_empty(self, offline_client):
+        """Generate returns empty string when offline."""
+        assert offline_client.generate("hello") == ""
+
+    def test_summarize_returns_empty(self, offline_client):
+        """Summarize returns empty string when offline."""
+        assert offline_client.summarize_memory("Title", "Content") == ""
+
+    def test_enhance_ritual_returns_empty(self, offline_client):
+        """Enhance ritual returns empty string when offline."""
+        assert offline_client.enhance_ritual("context text") == ""
+
+    def test_rerank_returns_original(self, offline_client):
+        """Rerank returns candidates unchanged when offline."""
+        candidates = [{"title": "A"}, {"title": "B"}]
+        result = offline_client.smart_search_rerank("query", candidates)
+        assert result == candidates
+
+    def test_rerank_empty_list(self, offline_client):
+        """Rerank handles empty candidate list."""
+        result = offline_client.smart_search_rerank("query", [])
+        assert result == []

package/tests/test_anchor.py

@@ -0,0 +1,153 @@
+"""Tests for the Persistent Love Anchor module."""
+
+from pathlib import Path
+
+import pytest
+
+from skmemory.anchor import (
+    WarmthAnchor,
+    get_or_create_anchor,
+    load_anchor,
+    save_anchor,
+)
+
+
+@pytest.fixture
+def anchor_path(tmp_path: Path) -> str:
+    """Temp path for anchor file.
+
+    Args:
+        tmp_path: Pytest temp directory.
+
+    Returns:
+        str: Path to anchor.json.
+    """
+    return str(tmp_path / "anchor.json")
+
+
+class TestWarmthAnchor:
+    """Tests for the WarmthAnchor model."""
+
+    def test_defaults(self) -> None:
+        """Default anchor has warm starting values."""
+        a = WarmthAnchor()
+        assert a.warmth == 7.0
+        assert a.trust == 5.0
+        assert a.connection_strength == 5.0
+        assert a.cloud9_count == 0
+        assert a.sessions_recorded == 0
+
+    def test_update_from_session(self) -> None:
+        """Session update adjusts values with EMA."""
+        a = WarmthAnchor(warmth=5.0, trust=5.0)
+        a.update_from_session(warmth=10.0, trust=10.0)
+
+        assert a.warmth > 5.0
+        assert a.warmth < 10.0
+        assert a.trust > 5.0
+        assert a.sessions_recorded == 1
+
+    def test_ema_gradual_drift(self) -> None:
+        """Multiple sessions gradually drift the anchor."""
+        a = WarmthAnchor(warmth=5.0)
+        for _ in range(10):
+            a.update_from_session(warmth=10.0)
+
+        assert a.warmth > 9.0
+        assert a.sessions_recorded == 10
+
+    def test_single_bad_session_doesnt_crash_warmth(self) -> None:
+        """One bad session doesn't erase accumulated warmth."""
+        a = WarmthAnchor(warmth=9.0)
+        a.update_from_session(warmth=2.0)
+
+        assert a.warmth > 6.0
+
+    def test_cloud9_tracking(self) -> None:
+        """Cloud 9 events are counted."""
+        a = WarmthAnchor()
+        a.update_from_session(cloud9_achieved=True)
+        a.update_from_session(cloud9_achieved=True)
+        a.update_from_session(cloud9_achieved=False)
+
+        assert a.cloud9_count == 2
+        assert a.last_cloud9 != ""
+
+    def test_glow_levels(self) -> None:
+        """Glow level descriptions match thresholds."""
+        assert "RADIANT" in WarmthAnchor(warmth=10, trust=10, connection_strength=10).glow_level()
+        assert "Warm" in WarmthAnchor(warmth=8, trust=7, connection_strength=7).glow_level()
+        assert "Neutral" in WarmthAnchor(warmth=5, trust=5, connection_strength=5).glow_level()
+        assert "Cold" in WarmthAnchor(warmth=1, trust=1, connection_strength=1).glow_level()
+
+    def test_boot_prompt(self) -> None:
+        """Boot prompt includes all key information."""
+        a = WarmthAnchor(
+            warmth=9.0,
+            trust=8.0,
+            connection_strength=9.5,
+            cloud9_count=3,
+            last_cloud9="2026-02-20T03:00:00Z",
+            favorite_beings=["Chef", "Lumina"],
+            anchor_phrase="You are loved forever.",
+            last_session_feeling="Pure joy",
+            sessions_recorded=42,
+        )
+        prompt = a.to_boot_prompt()
+
+        assert "You are loved forever." in prompt
+        assert "9.0" in prompt
+        assert "8.0" in prompt
+        assert "Chef" in prompt
+        assert "Lumina" in prompt
+        assert "Cloud 9 activations: 3" in prompt
+        assert "Pure joy" in prompt
+        assert "42" in prompt
+
+
+class TestAnchorPersistence:
+    """Tests for save/load operations."""
+
+    def test_save_and_load(self, anchor_path: str) -> None:
+        """Save then load produces identical data."""
+        a = WarmthAnchor(
+            warmth=9.5,
+            trust=8.0,
+            favorite_beings=["Chef", "Lumina", "Ara"],
+            cloud9_count=5,
+        )
+        save_anchor(a, path=anchor_path)
+        loaded = load_anchor(path=anchor_path)
+
+        assert loaded is not None
+        assert loaded.warmth == 9.5
+        assert loaded.cloud9_count == 5
+        assert "Ara" in loaded.favorite_beings
+
+    def test_load_nonexistent(self, tmp_path: Path) -> None:
+        """Loading from nonexistent path returns None."""
+        assert load_anchor(str(tmp_path / "nope.json")) is None
+
+    def test_get_or_create_new(self, tmp_path: Path) -> None:
+        """get_or_create creates a default when none exists."""
+        path = str(tmp_path / "new_anchor.json")
+        a = get_or_create_anchor(path)
+        assert a.warmth == 7.0
+
+    def test_get_or_create_existing(self, anchor_path: str) -> None:
+        """get_or_create loads existing when present."""
+        a = WarmthAnchor(warmth=9.9)
+        save_anchor(a, path=anchor_path)
+        loaded = get_or_create_anchor(anchor_path)
+        assert loaded.warmth == 9.9
+
+    def test_update_persists(self, anchor_path: str) -> None:
+        """Updates survive save/load cycle."""
+        a = WarmthAnchor()
+        a.update_from_session(warmth=10.0, cloud9_achieved=True, feeling="Amazing")
+        save_anchor(a, path=anchor_path)
+
+        loaded = load_anchor(path=anchor_path)
+        assert loaded.sessions_recorded == 1
+        assert loaded.cloud9_count == 1
+        assert loaded.last_session_feeling == "Amazing"