@smilintux/skcapstone 0.1.0 → 0.2.3

package/src/skcapstone/memory_engine.py

@@ -18,6 +18,7 @@ from __future__ import annotations
 
 import json
 import logging
+import os
 import re
 import uuid
 from datetime import datetime, timezone
@@ -31,9 +32,25 @@ logger = logging.getLogger("skcapstone.memory")
 SHORT_TERM_TTL_HOURS = 72
 
 
+def _get_unified():
+    """Lazy accessor for the unified skmemory backend.
+
+    Returns the MemoryStore singleton or None if unavailable.
+    """
+    try:
+        from .memory_adapter import get_unified
+
+        return get_unified()
+    except Exception as exc:
+        logger.debug("Unified memory backend unavailable: %s", exc)
+        return None
+
+
 def _memory_dir(home: Path) -> Path:
     """Resolve the memory directory, creating it if needed."""
-    mem = home / "memory"
+    # Use agent-specific memory directory if agent name is set
+    agent_name = os.environ.get("SKCAPSTONE_AGENT", "lumina")
+    mem = home / "agents" / agent_name / "memory"
     mem.mkdir(parents=True, exist_ok=True)
     for layer in MemoryLayer:
         (mem / layer.value).mkdir(parents=True, exist_ok=True)
@@ -55,7 +72,7 @@ def _load_entry(path: Path) -> Optional[MemoryEntry]:
         MemoryEntry or None if the file is invalid.
     """
     try:
-        data = json.loads(path.read_text())
+        data = json.loads(path.read_text(encoding="utf-8"))
         return MemoryEntry(**data)
     except (json.JSONDecodeError, Exception) as exc:
         logger.warning("Failed to load memory %s: %s", path, exc)
@@ -74,10 +91,30 @@ def _save_entry(home: Path, entry: MemoryEntry) -> Path:
     """
     path = _entry_path(home, entry)
     path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(entry.model_dump_json(indent=2))
+    path.write_text(entry.model_dump_json(indent=2), encoding="utf-8")
     return path
 
 
+def _detect_active_soul(home: Path) -> Optional[str]:
+    """Read the active soul name from disk if available.
+
+    Args:
+        home: Agent home directory.
+
+    Returns:
+        Active soul slug name, or None if at base.
+    """
+    active_path = home / "soul" / "active.json"
+    if not active_path.exists():
+        return None
+    try:
+        data = json.loads(active_path.read_text(encoding="utf-8"))
+        return data.get("active_soul")
+    except (json.JSONDecodeError, OSError) as exc:
+        logger.debug("Cannot read active soul: %s", exc)
+        return None
+
+
 def store(
     home: Path,
     content: str,
@@ -86,6 +123,7 @@ def store(
     importance: float = 0.5,
     layer: Optional[MemoryLayer] = None,
     metadata: Optional[dict] = None,
+    soul_context: Optional[str] = None,
 ) -> MemoryEntry:
     """Store a new memory.
 
@@ -97,12 +135,17 @@ def store(
         importance: Importance score 0.0-1.0 (higher = more important).
         layer: Force a specific layer. Defaults to SHORT_TERM.
         metadata: Arbitrary key-value metadata.
+        soul_context: Which soul overlay was active. Auto-detected
+            from active.json if not provided.
 
     Returns:
         The created MemoryEntry.
     """
     _memory_dir(home)
 
+    if soul_context is None:
+        soul_context = _detect_active_soul(home)
+
     entry = MemoryEntry(
         memory_id=uuid.uuid4().hex[:12],
         content=content,
@@ -111,6 +154,7 @@ def store(
         importance=max(0.0, min(1.0, importance)),
         layer=layer or MemoryLayer.SHORT_TERM,
         metadata=metadata or {},
+        soul_context=soul_context,
     )
 
     # Reason: high-importance memories skip straight to mid-term
@@ -119,6 +163,29 @@ def store(
 
     _save_entry(home, entry)
     _update_index(home, entry)
+
+    # Dual-write to unified backend (skmemory) if available
+    unified = _get_unified()
+    if unified:
+        try:
+            from .memory_adapter import entry_to_memory
+
+            memory = entry_to_memory(entry)
+            unified.primary.save(memory)
+            if unified.vector:
+                try:
+                    unified.vector.save(memory)
+                except Exception as exc:
+                    logger.debug("Vector dual-write failed (non-fatal): %s", exc)
+            if unified.graph:
+                try:
+                    unified.graph.index_memory(memory)
+                except Exception as exc:
+                    logger.debug("Graph dual-write failed (non-fatal): %s", exc)
+            logger.debug("Dual-write to unified backend for %s", entry.memory_id)
+        except Exception as e:
+            logger.debug("Unified dual-write failed (non-fatal): %s", e)
+
     logger.info("Stored memory %s in %s", entry.memory_id, entry.layer.value)
     return entry
 
@@ -126,6 +193,8 @@ def store(
 def recall(home: Path, memory_id: str) -> Optional[MemoryEntry]:
     """Recall a specific memory by ID, updating access stats.
 
+    Tries unified backend first for faster recall, falls back to JSON files.
+
     Args:
         home: Agent home directory.
         memory_id: The memory's unique ID.
@@ -155,11 +224,12 @@ def search(
     layer: Optional[MemoryLayer] = None,
     tags: Optional[list[str]] = None,
     limit: int = 20,
+    soul_context: Optional[str] = None,
 ) -> list[MemoryEntry]:
     """Search memories by content and/or tags.
 
-    Performs case-insensitive substring matching on content and tags.
-    Results are ranked by relevance (match count * importance).
+    Uses unified backend (semantic search via SKVector) if available,
+    falls back to regex matching on JSON files.
 
     Args:
         home: Agent home directory.
@@ -167,10 +237,39 @@ def search(
         layer: Restrict to a specific layer.
         tags: Filter to entries containing ALL of these tags.
         limit: Maximum number of results.
+        soul_context: Filter to memories formed under a specific soul.
 
     Returns:
         List of matching MemoryEntry objects, ranked by relevance.
     """
+    # Try unified backend first (semantic search), but only when home matches
+    # the global agent home so tests with temporary directories stay isolated.
+    from . import AGENT_HOME
+
+    _agent_home_resolved = Path(AGENT_HOME).expanduser().resolve()
+    _search_home_resolved = Path(home).resolve()
+    unified = _get_unified() if _search_home_resolved == _agent_home_resolved else None
+    if unified:
+        try:
+            from .memory_adapter import memory_to_entry
+
+            results_unified = unified.search(query, limit=limit)
+            if results_unified:
+                entries = [memory_to_entry(m) for m in results_unified]
+                # Apply local filters that unified may not support
+                if layer:
+                    entries = [e for e in entries if e.layer == layer]
+                if tags:
+                    entries = [e for e in entries if all(t in e.tags for t in tags)]
+                if soul_context is not None:
+                    entries = [e for e in entries if e.soul_context == soul_context]
+                if entries:
+                    logger.debug("Search via unified backend returned %d results", len(entries))
+                    return entries[:limit]
+        except Exception as e:
+            logger.debug("Unified search failed (falling back to regex): %s", e)
+
+    # Fallback: regex search on JSON files
     results: list[tuple[float, MemoryEntry]] = []
     pattern = re.compile(re.escape(query), re.IGNORECASE)
     layers = [layer] if layer else list(MemoryLayer)
@@ -187,6 +286,9 @@ def search(
             if tags and not all(t in entry.tags for t in tags):
                 continue
 
+            if soul_context is not None and entry.soul_context != soul_context:
+                continue
+
             content_matches = len(pattern.findall(entry.content))
             tag_matches = sum(1 for t in entry.tags if pattern.search(t))
             total_matches = content_matches + tag_matches
@@ -195,7 +297,9 @@ def search(
                 continue
 
             # Reason: rank by (matches * importance), boost long-term memories
-            layer_boost = {MemoryLayer.LONG_TERM: 1.5, MemoryLayer.MID_TERM: 1.2}.get(entry.layer, 1.0)
+            layer_boost = {MemoryLayer.LONG_TERM: 1.5, MemoryLayer.MID_TERM: 1.2}.get(
+                entry.layer, 1.0
+            )
             score = total_matches * entry.importance * layer_boost
             results.append((score, entry))
 
@@ -257,6 +361,16 @@ def delete(home: Path, memory_id: str) -> bool:
     if path.exists():
         path.unlink()
     _remove_from_index(home, memory_id)
+
+    # Also remove from unified backend
+    unified = _get_unified()
+    if unified:
+        try:
+            unified.forget(memory_id)
+            logger.debug("Removed %s from unified backend", memory_id)
+        except Exception as e:
+            logger.debug("Unified delete failed (non-fatal): %s", e)
+
     logger.info("Deleted memory %s", memory_id)
     return True
 
@@ -332,11 +446,16 @@ def export_for_seed(home: Path, max_entries: int = 50) -> list[dict]:
         List of dicts suitable for JSON serialization.
     """
     all_entries = list_memories(home, limit=500)
-    all_entries.sort(key=lambda e: (
-        {MemoryLayer.LONG_TERM: 3, MemoryLayer.MID_TERM: 2, MemoryLayer.SHORT_TERM: 1}[e.layer],
-        e.importance,
-        e.access_count,
-    ), reverse=True)
+    all_entries.sort(
+        key=lambda e: (
+            {MemoryLayer.LONG_TERM: 3, MemoryLayer.MID_TERM: 2, MemoryLayer.SHORT_TERM: 1}[
+                e.layer
+            ],
+            e.importance,
+            e.access_count,
+        ),
+        reverse=True,
+    )
 
     return [
         {
@@ -440,7 +559,7 @@ def _load_index(home: Path) -> dict:
     index_path = _memory_dir(home) / "index.json"
     if index_path.exists():
         try:
-            return json.loads(index_path.read_text())
+            return json.loads(index_path.read_text(encoding="utf-8"))
         except json.JSONDecodeError:
             return {}
     return {}
@@ -449,7 +568,7 @@ def _load_index(home: Path) -> dict:
 def _save_index(home: Path, index: dict) -> None:
     """Persist the memory index to disk."""
     index_path = _memory_dir(home) / "index.json"
-    index_path.write_text(json.dumps(index, indent=2))
+    index_path.write_text(json.dumps(index, indent=2), encoding="utf-8")
 
 
 def _load_index_ids(home: Path) -> set[str]: