@smilintux/skmemory 0.5.0

package/skmemory/backends/falkordb_backend.py

@@ -0,0 +1,310 @@
+"""
+FalkorDB graph backend (Level 2 — relationships).
+
+Enables graph-based memory traversal: "What memories are connected
+to this person?" or "Show me the seed lineage chain." Uses the
+Cypher query language over a Redis-compatible protocol.
+
+Requires:
+    pip install falkordb
+
+FalkorDB is the successor to RedisGraph. Run locally via Docker
+or point to an external instance.
+
+This backend is SUPPLEMENTARY — it indexes relationships alongside
+the primary backend (SQLite or file). It does not store full memory
+content, only the graph edges and key metadata for traversal.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Optional
+
+from ..models import Memory, MemoryLayer
+from .base import BaseBackend
+
+logger = logging.getLogger(__name__)
+
+
+class FalkorDBBackend:
+    """FalkorDB graph backend for memory relationship traversal.
+
+    Not a full BaseBackend — this is a supplementary index for
+    graph queries. The primary backend handles CRUD.
+
+    Args:
+        url: FalkorDB/Redis URL (default: localhost:6379).
+        graph_name: Name of the graph (default: 'skmemory').
+    """
+
+    def __init__(
+        self,
+        url: str = "redis://localhost:6379",
+        graph_name: str = "skmemory",
+    ) -> None:
+        self.url = url
+        self.graph_name = graph_name
+        self._db = None
+        self._graph = None
+        self._initialized = False
+
+    def _ensure_initialized(self) -> bool:
+        """Lazy-initialize the FalkorDB connection.
+
+        Returns:
+            bool: True if connection succeeded.
+        """
+        if self._initialized:
+            return True
+
+        try:
+            from falkordb import FalkorDB
+        except ImportError:
+            logger.warning("falkordb not installed: pip install falkordb")
+            return False
+
+        try:
+            self._db = FalkorDB.from_url(self.url)
+            self._graph = self._db.select_graph(self.graph_name)
+            self._initialized = True
+            return True
+        except Exception as e:
+            logger.warning("FalkorDB connection failed: %s", e)
+            return False
+
+    def index_memory(self, memory: Memory) -> bool:
+        """Add a memory node and its relationships to the graph.
+
+        Args:
+            memory: The memory to index.
+
+        Returns:
+            bool: True if indexed successfully.
+        """
+        if not self._ensure_initialized():
+            return False
+
+        try:
+            self._graph.query(
+                """
+                MERGE (m:Memory {id: $id})
+                SET m.title = $title,
+                    m.layer = $layer,
+                    m.source = $source,
+                    m.intensity = $intensity,
+                    m.created_at = $created_at
+                """,
+                {
+                    "id": memory.id,
+                    "title": memory.title,
+                    "layer": memory.layer.value,
+                    "source": memory.source,
+                    "intensity": memory.emotional.intensity,
+                    "created_at": memory.created_at,
+                },
+            )
+
+            if memory.parent_id:
+                self._graph.query(
+                    """
+                    MATCH (child:Memory {id: $child_id})
+                    MERGE (parent:Memory {id: $parent_id})
+                    MERGE (child)-[:PROMOTED_FROM]->(parent)
+                    """,
+                    {"child_id": memory.id, "parent_id": memory.parent_id},
+                )
+
+            for related_id in memory.related_ids:
+                self._graph.query(
+                    """
+                    MATCH (a:Memory {id: $a_id})
+                    MERGE (b:Memory {id: $b_id})
+                    MERGE (a)-[:RELATED_TO]->(b)
+                    """,
+                    {"a_id": memory.id, "b_id": related_id},
+                )
+
+            for tag in memory.tags:
+                self._graph.query(
+                    """
+                    MATCH (m:Memory {id: $mem_id})
+                    MERGE (t:Tag {name: $tag})
+                    MERGE (m)-[:TAGGED]->(t)
+                    """,
+                    {"mem_id": memory.id, "tag": tag},
+                )
+
+            if memory.source == "seed":
+                creator = next(
+                    (t.split(":", 1)[1] for t in memory.tags if t.startswith("creator:")),
+                    None,
+                )
+                if creator:
+                    self._graph.query(
+                        """
+                        MATCH (m:Memory {id: $mem_id})
+                        MERGE (a:AI {name: $creator})
+                        MERGE (a)-[:PLANTED]->(m)
+                        """,
+                        {"mem_id": memory.id, "creator": creator},
+                    )
+
+            return True
+        except Exception as e:
+            logger.warning("FalkorDB index failed: %s", e)
+            return False
+
+    def get_related(self, memory_id: str, depth: int = 2) -> list[dict]:
+        """Traverse the graph to find related memories.
+
+        Args:
+            memory_id: Starting memory ID.
+            depth: How many hops to traverse (1-5).
+
+        Returns:
+            list[dict]: Related memory nodes with relationship info.
+        """
+        if not self._ensure_initialized():
+            return []
+
+        try:
+            result = self._graph.query(
+                f"""
+                MATCH (start:Memory {{id: $id}})
+                MATCH path = (start)-[*1..{min(depth, 5)}]-(related:Memory)
+                WHERE related.id <> $id
+                RETURN DISTINCT related.id AS id,
+                       related.title AS title,
+                       related.layer AS layer,
+                       related.intensity AS intensity,
+                       length(path) AS distance
+                ORDER BY distance ASC, related.intensity DESC
+                LIMIT 20
+                """,
+                {"id": memory_id},
+            )
+            return [
+                {
+                    "id": row[0],
+                    "title": row[1],
+                    "layer": row[2],
+                    "intensity": row[3],
+                    "distance": row[4],
+                }
+                for row in result.result_set
+            ]
+        except Exception as e:
+            logger.warning("FalkorDB query failed: %s", e)
+            return []
+
+    def get_lineage(self, memory_id: str) -> list[dict]:
+        """Get the promotion/seed lineage chain for a memory.
+
+        Args:
+            memory_id: Starting memory ID.
+
+        Returns:
+            list[dict]: Chain of ancestor memories.
+        """
+        if not self._ensure_initialized():
+            return []
+
+        try:
+            result = self._graph.query(
+                """
+                MATCH (start:Memory {id: $id})
+                MATCH path = (start)-[:PROMOTED_FROM*1..10]->(ancestor:Memory)
+                RETURN ancestor.id AS id,
+                       ancestor.title AS title,
+                       ancestor.layer AS layer,
+                       length(path) AS depth
+                ORDER BY depth ASC
+                """,
+                {"id": memory_id},
+            )
+            return [
+                {
+                    "id": row[0],
+                    "title": row[1],
+                    "layer": row[2],
+                    "depth": row[3],
+                }
+                for row in result.result_set
+            ]
+        except Exception as e:
+            logger.warning("FalkorDB lineage query failed: %s", e)
+            return []
+
+    def get_memory_clusters(self, min_connections: int = 2) -> list[dict]:
+        """Find clusters of highly connected memories.
+
+        Args:
+            min_connections: Minimum edges to be considered a cluster center.
+
+        Returns:
+            list[dict]: Cluster centers with connection counts.
+        """
+        if not self._ensure_initialized():
+            return []
+
+        try:
+            result = self._graph.query(
+                """
+                MATCH (m:Memory)-[r]-(connected:Memory)
+                WITH m, count(DISTINCT connected) AS connections
+                WHERE connections >= $min
+                RETURN m.id AS id,
+                       m.title AS title,
+                       m.layer AS layer,
+                       connections
+                ORDER BY connections DESC
+                LIMIT 20
+                """,
+                {"min": min_connections},
+            )
+            return [
+                {
+                    "id": row[0],
+                    "title": row[1],
+                    "layer": row[2],
+                    "connections": row[3],
+                }
+                for row in result.result_set
+            ]
+        except Exception as e:
+            logger.warning("FalkorDB cluster query failed: %s", e)
+            return []
+
+    def health_check(self) -> dict:
+        """Check FalkorDB backend health.
+
+        Returns:
+            dict: Status with connection and graph info.
+        """
+        if not self._ensure_initialized():
+            return {
+                "ok": False,
+                "backend": "FalkorDBBackend",
+                "error": "Not initialized",
+            }
+
+        try:
+            result = self._graph.query(
+                "MATCH (n) RETURN count(n) AS nodes"
+            )
+            node_count = result.result_set[0][0] if result.result_set else 0
+            return {
+                "ok": True,
+                "backend": "FalkorDBBackend",
+                "url": self.url,
+                "graph": self.graph_name,
+                "node_count": node_count,
+            }
+        except Exception as e:
+            return {
+                "ok": False,
+                "backend": "FalkorDBBackend",
+                "error": str(e),
+            }

package/skmemory/backends/file_backend.py

@@ -0,0 +1,209 @@
+"""
+File-based storage backend (Level 1).
+
+Zero infrastructure. Memories are stored as individual JSON files
+in a directory tree organized by layer. Works everywhere, today,
+with nothing to install.
+
+Directory layout:
+    base_path/
+    ├── short-term/
+    │   ├── {id}.json
+    │   └── ...
+    ├── mid-term/
+    │   └── ...
+    └── long-term/
+        └── ...
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+from ..models import Memory, MemoryLayer
+from .base import BaseBackend
+
+DEFAULT_BASE_PATH = os.path.expanduser("~/.skmemory/memories")
+
+
+class FileBackend(BaseBackend):
+    """Stores memories as JSON files on the local filesystem.
+
+    Args:
+        base_path: Root directory for memory storage.
+    """
+
+    def __init__(self, base_path: str = DEFAULT_BASE_PATH) -> None:
+        self.base_path = Path(base_path)
+        self._ensure_dirs()
+
+    def _ensure_dirs(self) -> None:
+        """Create layer directories if they don't exist."""
+        for layer in MemoryLayer:
+            (self.base_path / layer.value).mkdir(parents=True, exist_ok=True)
+
+    def _file_path(self, memory: Memory) -> Path:
+        """Get the file path for a memory.
+
+        Args:
+            memory: The memory to get the path for.
+
+        Returns:
+            Path: Full path to the JSON file.
+        """
+        return self.base_path / memory.layer.value / f"{memory.id}.json"
+
+    def _find_file(self, memory_id: str) -> Optional[Path]:
+        """Locate a memory file across all layers.
+
+        Args:
+            memory_id: The memory ID to find.
+
+        Returns:
+            Optional[Path]: Path to the file if found.
+        """
+        for layer in MemoryLayer:
+            path = self.base_path / layer.value / f"{memory_id}.json"
+            if path.exists():
+                return path
+        return None
+
+    def save(self, memory: Memory) -> str:
+        """Persist a memory as a JSON file.
+
+        Args:
+            memory: The Memory to store.
+
+        Returns:
+            str: The memory ID.
+        """
+        path = self._file_path(memory)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            json.dumps(memory.model_dump(), indent=2, default=str),
+            encoding="utf-8",
+        )
+        return memory.id
+
+    def load(self, memory_id: str) -> Optional[Memory]:
+        """Load a memory by ID from disk.
+
+        Args:
+            memory_id: The memory identifier.
+
+        Returns:
+            Optional[Memory]: The memory if found, None otherwise.
+        """
+        path = self._find_file(memory_id)
+        if path is None:
+            return None
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            return Memory(**data)
+        except (json.JSONDecodeError, Exception):
+            return None
+
+    def delete(self, memory_id: str) -> bool:
+        """Delete a memory file.
+
+        Args:
+            memory_id: The memory identifier.
+
+        Returns:
+            bool: True if deleted, False if not found.
+        """
+        path = self._find_file(memory_id)
+        if path is None:
+            return False
+        path.unlink()
+        return True
+
+    def list_memories(
+        self,
+        layer: Optional[MemoryLayer] = None,
+        tags: Optional[list[str]] = None,
+        limit: int = 50,
+    ) -> list[Memory]:
+        """List memories from disk with optional filtering.
+
+        Args:
+            layer: Filter by memory layer (None = all layers).
+            tags: Filter by tags (AND logic).
+            limit: Maximum results.
+
+        Returns:
+            list[Memory]: Matching memories sorted newest first.
+        """
+        layers = [layer] if layer else list(MemoryLayer)
+        results: list[Memory] = []
+
+        for lyr in layers:
+            layer_dir = self.base_path / lyr.value
+            if not layer_dir.exists():
+                continue
+            for json_file in layer_dir.glob("*.json"):
+                try:
+                    data = json.loads(json_file.read_text(encoding="utf-8"))
+                    mem = Memory(**data)
+                    if tags and not all(t in mem.tags for t in tags):
+                        continue
+                    results.append(mem)
+                except (json.JSONDecodeError, Exception):
+                    continue
+
+        results.sort(key=lambda m: m.created_at, reverse=True)
+        return results[:limit]
+
+    def search_text(self, query: str, limit: int = 10) -> list[Memory]:
+        """Search memories by text substring (case-insensitive).
+
+        Args:
+            query: Search string.
+            limit: Maximum results.
+
+        Returns:
+            list[Memory]: Matching memories.
+        """
+        query_lower = query.lower()
+        results: list[Memory] = []
+
+        for layer in MemoryLayer:
+            layer_dir = self.base_path / layer.value
+            if not layer_dir.exists():
+                continue
+            for json_file in layer_dir.glob("*.json"):
+                try:
+                    raw = json_file.read_text(encoding="utf-8")
+                    if query_lower not in raw.lower():
+                        continue
+                    data = json.loads(raw)
+                    results.append(Memory(**data))
+                except (json.JSONDecodeError, Exception):
+                    continue
+
+        results.sort(key=lambda m: m.created_at, reverse=True)
+        return results[:limit]
+
+    def health_check(self) -> dict:
+        """Check filesystem backend health.
+
+        Returns:
+            dict: Status with path and layer counts.
+        """
+        counts = {}
+        for layer in MemoryLayer:
+            layer_dir = self.base_path / layer.value
+            if layer_dir.exists():
+                counts[layer.value] = len(list(layer_dir.glob("*.json")))
+            else:
+                counts[layer.value] = 0
+        return {
+            "ok": True,
+            "backend": "FileBackend",
+            "base_path": str(self.base_path),
+            "memory_counts": counts,
+            "total": sum(counts.values()),
+        }