@smilintux/skmemory 0.7.2 → 0.9.2

package/skmemory/backends/file_backend.py

@@ -19,15 +19,13 @@ Directory layout:
 from __future__ import annotations
 
 import json
-import os
 from pathlib import Path
-from typing import Optional
 
 from ..config import SKMEMORY_HOME
 from ..models import Memory, MemoryLayer
 from .base import BaseBackend
 
-DEFAULT_BASE_PATH = str(SKMEMORY_HOME)
+DEFAULT_BASE_PATH = str(SKMEMORY_HOME / "memory")
 
 
 class FileBackend(BaseBackend):
@@ -57,7 +55,7 @@ class FileBackend(BaseBackend):
         """
         return self.base_path / memory.layer.value / f"{memory.id}.json"
 
-    def _find_file(self, memory_id: str) -> Optional[Path]:
+    def _find_file(self, memory_id: str) -> Path | None:
         """Locate a memory file across all layers.
 
         Args:
@@ -89,7 +87,7 @@ class FileBackend(BaseBackend):
         )
         return memory.id
 
-    def load(self, memory_id: str) -> Optional[Memory]:
+    def load(self, memory_id: str) -> Memory | None:
         """Load a memory by ID from disk.
 
         Args:
@@ -124,8 +122,8 @@ class FileBackend(BaseBackend):
 
     def list_memories(
         self,
-        layer: Optional[MemoryLayer] = None,
-        tags: Optional[list[str]] = None,
+        layer: MemoryLayer | None = None,
+        tags: list[str] | None = None,
         limit: int = 50,
     ) -> list[Memory]:
         """List memories from disk with optional filtering.
@@ -168,8 +166,11 @@ class FileBackend(BaseBackend):
         Returns:
             list[Memory]: Matching memories.
         """
-        query_lower = query.lower()
+        words = [w.lower() for w in query.split()]
+        if not words:
+            return []
         results: list[Memory] = []
+        scored: list[tuple[int, Memory]] = []
 
         for layer in MemoryLayer:
             layer_dir = self.base_path / layer.value
@@ -177,15 +178,19 @@ class FileBackend(BaseBackend):
                 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():
+                    data = json.loads(json_file.read_text(encoding="utf-8"))
+                    mem = Memory(**data)
+                    searchable = mem.to_embedding_text().lower()
+                    hits = sum(1 for w in words if w in searchable)
+                    if hits == 0:
                         continue
-                    data = json.loads(raw)
-                    results.append(Memory(**data))
+                    scored.append((hits, mem))
                 except (json.JSONDecodeError, Exception):
                     continue
 
-        results.sort(key=lambda m: m.created_at, reverse=True)
+        # Sort by match count desc, then recency
+        scored.sort(key=lambda t: (t[0], t[1].created_at), reverse=True)
+        results = [m for _, m in scored]
         return results[:limit]
 
     def health_check(self) -> dict:

package/skmemory/backends/skgraph_backend.py

@@ -38,10 +38,9 @@ from __future__ import annotations
 
 import logging
 import os
-from typing import Optional
 
-from ..models import Memory, MemoryLayer
 from .. import graph_queries as Q
+from ..models import Memory
 
 logger = logging.getLogger(__name__)
 
@@ -219,11 +218,7 @@ class SKGraphBackend:
             # PLANTED edge for AI seed memories
             if memory.source == "seed":
                 creator = next(
-                    (
-                        t.split(":", 1)[1]
-                        for t in memory.tags
-                        if t.startswith("creator:")
-                    ),
+                    (t.split(":", 1)[1] for t in memory.tags if t.startswith("creator:")),
                     None,
                 )
                 if creator:
@@ -241,7 +236,7 @@ class SKGraphBackend:
     # Read operations
     # ─────────────────────────────────────────────────────────
 
-    def get(self, memory_id: str) -> Optional[dict]:
+    def get(self, memory_id: str) -> dict | None:
         """Retrieve the graph node properties for a memory by ID.
 
         Returns only the properties stored in the graph (no full content).
@@ -544,24 +539,17 @@ class SKGraphBackend:
 
         try:
             node_result = self._graph.query(Q.COUNT_NODES)
-            node_count = (
-                node_result.result_set[0][0] if node_result.result_set else 0
-            )
+            node_count = node_result.result_set[0][0] if node_result.result_set else 0
 
             edge_result = self._graph.query(Q.COUNT_EDGES)
-            edge_count = (
-                edge_result.result_set[0][0] if edge_result.result_set else 0
-            )
+            edge_count = edge_result.result_set[0][0] if edge_result.result_set else 0
 
             mem_result = self._graph.query(Q.COUNT_MEMORIES)
-            memory_count = (
-                mem_result.result_set[0][0] if mem_result.result_set else 0
-            )
+            memory_count = mem_result.result_set[0][0] if mem_result.result_set else 0
 
             tag_result = self._graph.query(Q.TAG_DISTRIBUTION)
             tag_distribution = [
-                {"tag": row[0], "memory_count": row[1]}
-                for row in tag_result.result_set
+                {"tag": row[0], "memory_count": row[1]} for row in tag_result.result_set
             ]
 
             return {

package/skmemory/backends/skvector_backend.py

@@ -15,9 +15,7 @@ SaaS endpoint: https://cloud.qdrant.io (free cluster available).
 from __future__ import annotations
 
 import hashlib
-import json
 import logging
-from typing import Optional
 
 from ..models import Memory, MemoryLayer
 from .base import BaseBackend
@@ -66,7 +64,7 @@ class SKVectorBackend(BaseBackend):
     def __init__(
         self,
         url: str = "http://localhost:6333",
-        api_key: Optional[str] = None,
+        api_key: str | None = None,
         collection: str = COLLECTION_NAME,
         embedding_model: str = EMBEDDING_MODEL,
     ) -> None:
@@ -98,20 +96,15 @@ class SKVectorBackend(BaseBackend):
         try:
             from sentence_transformers import SentenceTransformer
         except ImportError:
-            logger.warning(
-                "sentence-transformers not installed: "
-                "pip install skmemory[skvector]"
-            )
+            logger.warning("sentence-transformers not installed: pip install skmemory[skvector]")
             return False
 
         try:
             from qdrant_client.http.exceptions import (
-                ResponseHandlingException,
                 UnexpectedResponse,
             )
         except ImportError:
             UnexpectedResponse = None
-            ResponseHandlingException = None
 
         try:
             self._client = QdrantClient(url=self.url, api_key=self.api_key)
@@ -219,7 +212,7 @@ class SKVectorBackend(BaseBackend):
         """Convert a memory ID string to a deterministic Qdrant integer point ID."""
         return int(hashlib.sha256(memory_id.encode()).hexdigest()[:15], 16)
 
-    def load(self, memory_id: str) -> Optional[Memory]:
+    def load(self, memory_id: str) -> Memory | None:
         """Retrieve a memory by ID from Qdrant.
 
         Args:
@@ -275,8 +268,8 @@ class SKVectorBackend(BaseBackend):
 
     def list_memories(
         self,
-        layer: Optional[MemoryLayer] = None,
-        tags: Optional[list[str]] = None,
+        layer: MemoryLayer | None = None,
+        tags: list[str] | None = None,
         limit: int = 50,
     ) -> list[Memory]:
         """List memories from Qdrant with filtering.
@@ -301,9 +294,7 @@ class SKVectorBackend(BaseBackend):
             )
         if tags:
             for tag in tags:
-                must_conditions.append(
-                    FieldCondition(key="tags", match=MatchValue(value=tag))
-                )
+                must_conditions.append(FieldCondition(key="tags", match=MatchValue(value=tag)))
 
         scroll_filter = Filter(must=must_conditions) if must_conditions else None
 
@@ -351,9 +342,7 @@ class SKVectorBackend(BaseBackend):
         memories = []
         for scored_point in results:
             try:
-                mem = Memory.model_validate_json(
-                    scored_point.payload["memory_json"]
-                )
+                mem = Memory.model_validate_json(scored_point.payload["memory_json"])
                 memories.append(mem)
             except Exception:
                 continue

package/skmemory/backends/sqlite_backend.py

@@ -25,16 +25,14 @@ Directory layout (same as FileBackend):
 from __future__ import annotations
 
 import json
-import os
 import sqlite3
 from pathlib import Path
-from typing import Optional
 
 from ..config import SKMEMORY_HOME
-from ..models import EmotionalSnapshot, Memory, MemoryLayer
+from ..models import Memory, MemoryLayer
 from .base import BaseBackend
 
-DEFAULT_BASE_PATH = str(SKMEMORY_HOME)
+DEFAULT_BASE_PATH = str(SKMEMORY_HOME / "memory")
 
 _SCHEMA = """
 CREATE TABLE IF NOT EXISTS memories (
@@ -77,10 +75,10 @@ CREATE INDEX IF NOT EXISTS idx_access_count ON memories(access_count DESC);
 
 -- NEW: View for active context (today + recent summaries)
 CREATE VIEW IF NOT EXISTS active_memories AS
-SELECT 
+SELECT
     id, title, summary, content_preview, tags, layer, created_at,
     importance, access_count,
-    CASE 
+    CASE
         WHEN DATE(created_at) = CURRENT_DATE THEN 'today'
         WHEN DATE(created_at) = DATE('now', '-1 day') THEN 'yesterday'
         WHEN DATE(created_at) >= DATE('now', '-7 days') THEN 'week'
@@ -88,7 +86,7 @@ SELECT
     END as context_tier
 FROM memories
 WHERE created_at >= DATE('now', '-30 days')
-ORDER BY 
+ORDER BY
     context_tier,
     importance DESC,
     access_count DESC;
@@ -109,7 +107,7 @@ class SQLiteBackend(BaseBackend):
         self.base_path = Path(base_path)
         self._ensure_dirs()
         self._db_path = self.base_path / "index.db"
-        self._conn: Optional[sqlite3.Connection] = None
+        self._conn: sqlite3.Connection | None = None
         self._ensure_db()
 
     def _ensure_dirs(self) -> None:
@@ -134,8 +132,36 @@ class SQLiteBackend(BaseBackend):
         return self._conn
 
     def _ensure_db(self) -> None:
-        """Initialize the database schema."""
+        """Initialize the database schema, migrating old tables if needed."""
         conn = self._get_conn()
+
+        # Migrate: add columns that may be missing from older schemas.
+        # We check pragma_table_info first so this is safe on fresh DBs too.
+        row = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name='memories'"
+        ).fetchone()
+        if row is not None:
+            existing = {r[1] for r in conn.execute("PRAGMA table_info(memories)").fetchall()}
+            migrations = [
+                (
+                    "importance",
+                    "ALTER TABLE memories ADD COLUMN importance REAL NOT NULL DEFAULT 0.5",
+                ),
+                (
+                    "access_count",
+                    "ALTER TABLE memories ADD COLUMN access_count INTEGER NOT NULL DEFAULT 0",
+                ),
+                ("last_accessed", "ALTER TABLE memories ADD COLUMN last_accessed TEXT"),
+            ]
+            for col, ddl in migrations:
+                if col not in existing:
+                    conn.execute(ddl)
+            conn.commit()
+
+            # Drop stale view so CREATE VIEW IF NOT EXISTS picks up new columns.
+            conn.execute("DROP VIEW IF EXISTS active_memories")
+            conn.commit()
+
         conn.executescript(_SCHEMA)
         conn.commit()
 
@@ -150,7 +176,7 @@ class SQLiteBackend(BaseBackend):
         """
         return self.base_path / memory.layer.value / f"{memory.id}.json"
 
-    def _find_file(self, memory_id: str) -> Optional[Path]:
+    def _find_file(self, memory_id: str) -> Path | None:
         """Locate a memory file using the index first, then fallback.
 
         Args:
@@ -238,14 +264,14 @@ class SQLiteBackend(BaseBackend):
             "content_preview": row["content_preview"],
             "emotional_intensity": row["emotional_intensity"],
             "emotional_valence": row["emotional_valence"],
-            "emotional_labels": [l for l in row["emotional_labels"].split(",") if l],
+            "emotional_labels": [lbl for lbl in row["emotional_labels"].split(",") if lbl],
             "cloud9_achieved": bool(row["cloud9_achieved"]),
             "created_at": row["created_at"],
             "parent_id": row["parent_id"],
             "related_ids": [r for r in row["related_ids"].split(",") if r],
         }
 
-    def _row_to_memory(self, row: sqlite3.Row) -> Optional[Memory]:
+    def _row_to_memory(self, row: sqlite3.Row) -> Memory | None:
         """Load the full Memory object from disk using the index path.
 
         Args:
@@ -281,7 +307,7 @@ class SQLiteBackend(BaseBackend):
         self._index_memory(memory, path)
         return memory.id
 
-    def load(self, memory_id: str) -> Optional[Memory]:
+    def load(self, memory_id: str) -> Memory | None:
         """Load a memory by ID, using the index for fast lookup.
 
         Args:
@@ -322,8 +348,8 @@ class SQLiteBackend(BaseBackend):
 
     def list_memories(
         self,
-        layer: Optional[MemoryLayer] = None,
-        tags: Optional[list[str]] = None,
+        layer: MemoryLayer | None = None,
+        tags: list[str] | None = None,
         limit: int = 50,
     ) -> list[Memory]:
         """List memories using the index for filtering, loading full objects.
@@ -366,8 +392,8 @@ class SQLiteBackend(BaseBackend):
 
     def list_summaries(
         self,
-        layer: Optional[MemoryLayer] = None,
-        tags: Optional[list[str]] = None,
+        layer: MemoryLayer | None = None,
+        tags: list[str] | None = None,
         limit: int = 50,
         min_intensity: float = 0.0,
         order_by: str = "created_at",
@@ -407,7 +433,19 @@ class SQLiteBackend(BaseBackend):
 
         where = " AND ".join(conditions) if conditions else "1=1"
 
-        if order_by == "emotional_intensity":
+        if order_by == "recency_weighted_intensity":
+            # Combine intensity with recency: recent high-intensity memories
+            # score higher than old high-intensity ones.
+            # julianday('now') - julianday(created_at) gives days ago.
+            # Decay: halve the recency bonus every 7 days.
+            order = (
+                "(emotional_intensity + "
+                "CASE WHEN julianday('now') - julianday(created_at) < 1 THEN 5.0 "
+                "WHEN julianday('now') - julianday(created_at) < 3 THEN 3.0 "
+                "WHEN julianday('now') - julianday(created_at) < 7 THEN 1.5 "
+                "ELSE 0.0 END) DESC"
+            )
+        elif order_by == "emotional_intensity":
             order = "emotional_intensity DESC"
         else:
             order = "created_at DESC"
@@ -424,7 +462,9 @@ class SQLiteBackend(BaseBackend):
     def search_text(self, query: str, limit: int = 10) -> list[Memory]:
         """Search memories using the SQLite index (title, summary, preview).
 
-        Falls back to full file scan only if the index doesn't find matches.
+        For multi-word queries, tries AND first (all words must match).
+        If AND returns nothing, falls back to OR (any word matches),
+        ranked by how many query words each memory contains.
 
         Args:
             query: Search string.
@@ -434,19 +474,63 @@ class SQLiteBackend(BaseBackend):
             list[Memory]: Matching memories.
         """
         conn = self._get_conn()
-        query_param = f"%{query}%"
+        words = query.split()
+
+        if not words:
+            return []
+
+        cols = ["title", "summary", "content_preview", "tags"]
+
+        def _word_clause(word: str) -> str:
+            return "(" + " OR ".join(f"{c} LIKE ?" for c in cols) + ")"
+
+        def _word_params(word: str) -> list[str]:
+            pattern = f"%{word}%"
+            return [pattern] * len(cols)
+
+        # Try AND first: all words must match
+        and_clauses = [_word_clause(w) for w in words]
+        and_params: list[str] = []
+        for w in words:
+            and_params.extend(_word_params(w))
+        and_params.append(str(limit))
 
         rows = conn.execute(
-            """
+            f"""
             SELECT * FROM memories
-            WHERE title LIKE ? OR summary LIKE ? OR content_preview LIKE ?
-                  OR tags LIKE ?
+            WHERE {" AND ".join(and_clauses)}
             ORDER BY created_at DESC
             LIMIT ?
             """,
-            (query_param, query_param, query_param, query_param, limit),
+            and_params,
         ).fetchall()
 
+        if not rows and len(words) > 1:
+            # Fall back to OR: any word matches, ranked by match count
+            or_clauses = [_word_clause(w) for w in words]
+            # Use SUM of CASE expressions to count matching words
+            score_expr = " + ".join(
+                f"CASE WHEN {_word_clause(w)} THEN 1 ELSE 0 END" for w in words
+            )
+            or_params: list[str] = []
+            # params for WHERE (OR)
+            for w in words:
+                or_params.extend(_word_params(w))
+            # params for ORDER BY score (same patterns again)
+            for w in words:
+                or_params.extend(_word_params(w))
+            or_params.append(str(limit))
+
+            rows = conn.execute(
+                f"""
+                SELECT * FROM memories
+                WHERE {" OR ".join(or_clauses)}
+                ORDER BY ({score_expr}) DESC, created_at DESC
+                LIMIT ?
+                """,
+                or_params,
+            ).fetchall()
+
         results = []
         for row in rows:
             mem = self._row_to_memory(row)
@@ -501,7 +585,7 @@ class SQLiteBackend(BaseBackend):
 
         return results
 
-    def list_backups(self, backup_dir: Optional[str] = None) -> list[dict]:
+    def list_backups(self, backup_dir: str | None = None) -> list[dict]:
         """List all skmemory backup files, sorted newest first.
 
         Args:
@@ -512,10 +596,7 @@ class SQLiteBackend(BaseBackend):
             list[dict]: Backup entries, newest first. Each entry has:
                 ``path``, ``name``, ``size_bytes``, ``date``.
         """
-        if backup_dir is None:
-            bdir = self.base_path.parent / "backups"
-        else:
-            bdir = Path(backup_dir)
+        bdir = self.base_path.parent / "backups" if backup_dir is None else Path(backup_dir)
 
         if not bdir.exists():
             return []
@@ -532,7 +613,7 @@ class SQLiteBackend(BaseBackend):
             )
         return entries
 
-    def prune_backups(self, keep: int = 7, backup_dir: Optional[str] = None) -> list[str]:
+    def prune_backups(self, keep: int = 7, backup_dir: str | None = None) -> list[str]:
         """Delete oldest backups, retaining only the N most recent.
 
         Args:
@@ -554,7 +635,7 @@ class SQLiteBackend(BaseBackend):
                 pass
         return deleted
 
-    def export_all(self, output_path: Optional[str] = None) -> str:
+    def export_all(self, output_path: str | None = None) -> str:
         """Export all memories as a single JSON file for backup.
 
         Reads every JSON file on disk and bundles them into one
@@ -591,8 +672,10 @@ class SQLiteBackend(BaseBackend):
                 except (json.JSONDecodeError, Exception):
                     continue
 
+        from datetime import datetime as _dt
+        from datetime import timezone as _tz
+
         from .. import __version__
-        from datetime import datetime as _dt, timezone as _tz
 
         payload = {
             "skmemory_version": __version__,

package/skmemory/backends/vaulted_backend.py

@@ -13,7 +13,7 @@ File format on disk (per memory file):
     SKMV1 || salt(16) || nonce(12) || AES-GCM(json_bytes) || tag(16)
 
 Usage:
-    backend = VaultedSQLiteBackend(passphrase="sovereign-key")
+    backend = VaultedSQLiteBackend(passphrase="EXAMPLE-DO-NOT-USE")
     store = MemoryStore(primary=backend, use_sqlite=False)
     mem = store.snapshot("title", "content")
     recalled = store.recall(mem.id)  # transparent decrypt
@@ -25,12 +25,10 @@ import json
 import sqlite3
 from datetime import date, datetime, timezone
 from pathlib import Path
-from typing import Optional
 
 from ..models import Memory, MemoryLayer
 from ..vault import VAULT_HEADER, MemoryVault
-from .sqlite_backend import SQLiteBackend
-from .sqlite_backend import DEFAULT_BASE_PATH
+from .sqlite_backend import DEFAULT_BASE_PATH, SQLiteBackend
 
 
 class VaultedSQLiteBackend(SQLiteBackend):
@@ -50,7 +48,7 @@ class VaultedSQLiteBackend(SQLiteBackend):
 
     Example::
 
-        backend = VaultedSQLiteBackend(passphrase="my-secret")
+        backend = VaultedSQLiteBackend(passphrase="EXAMPLE-DO-NOT-USE")
         store = MemoryStore(primary=backend, use_sqlite=False)
         m = store.snapshot("Private thought", "End-to-end encrypted on disk")
         r = store.recall(m.id)  # decrypted on the fly
@@ -83,7 +81,7 @@ class VaultedSQLiteBackend(SQLiteBackend):
         self._index_memory(memory, path)
         return memory.id
 
-    def load(self, memory_id: str) -> Optional[Memory]:
+    def load(self, memory_id: str) -> Memory | None:
         """Decrypt and parse a memory file.
 
         Handles both encrypted (``SKMV1`` header) and plaintext files
@@ -100,7 +98,7 @@ class VaultedSQLiteBackend(SQLiteBackend):
             return None
         return self._read_memory_file(path)
 
-    def _row_to_memory(self, row: sqlite3.Row) -> Optional[Memory]:
+    def _row_to_memory(self, row: sqlite3.Row) -> Memory | None:
         """Load a full Memory object, decrypting if needed.
 
         Args:
@@ -143,7 +141,7 @@ class VaultedSQLiteBackend(SQLiteBackend):
                     continue
         return count
 
-    def export_all(self, output_path: Optional[str] = None) -> str:
+    def export_all(self, output_path: str | None = None) -> str:
         """Export all memories (decrypted) to a JSON backup file.
 
         Args:
@@ -267,7 +265,7 @@ class VaultedSQLiteBackend(SQLiteBackend):
     # Internal
     # ------------------------------------------------------------------
 
-    def _read_memory_file(self, path: Path) -> Optional[Memory]:
+    def _read_memory_file(self, path: Path) -> Memory | None:
         """Read a file and parse to Memory, decrypting if needed.
 
         Args: