superlocalmemory 3.4.49 → 3.4.52

package/src/superlocalmemory/mcp/tools_active.py

@@ -18,6 +18,7 @@ from __future__ import annotations
 
 import logging
 import os
+import sqlite3
 from pathlib import Path
 from typing import Callable
 
@@ -27,6 +28,81 @@ MEMORY_DIR = Path.home() / ".superlocalmemory"
 DB_PATH = MEMORY_DIR / "memory.db"
 
 
+def _sqlite_emergency_recall(
+    query: str, limit: int, profile_id: str = "default",
+    max_age_days: int = 30,
+) -> "PoolRecallResponse":
+    """Emergency fallback: direct SQLite FTS5 BM25 when daemon is unreachable.
+
+    Uses the same ``atomic_facts_fts`` virtual table the daemon uses, with
+    native BM25 ranking via ``ORDER BY fts.rank``. This is the Mem0 / Letta
+    industry pattern — multi-process safe via SQLite WAL mode.
+
+    Quality degraded vs full 6-channel (no semantic, no entity graph, no
+    temporal/spreading-activation/Hopfield) but still provides real BM25
+    math + age gate. Returns ``degraded_mode=True`` via the caller's flag.
+
+    Used ONLY when Tier-1 (full daemon recall) fails completely. Normal
+    path is full 6-channel; this is the fire-alarm.
+    """
+    from superlocalmemory.mcp._pool_adapter import PoolFact, PoolRecallItem, PoolRecallResponse
+    import re
+    try:
+        # FTS5 MATCH syntax: tokenize the query, drop special characters
+        # that confuse the parser (/, :, ., etc), and join with OR for
+        # broadest matching. Wrap each term in quotes to escape any
+        # remaining special-meaning chars.
+        tokens = re.findall(r"[A-Za-z0-9]+", query)
+        tokens = [t for t in tokens if len(t) >= 2]
+        if not tokens:
+            return PoolRecallResponse()
+        safe_query = " OR ".join(f'"{t}"' for t in tokens)
+        age_clause = (
+            f"AND f.created_at >= datetime('now', '-{int(max_age_days)} days') "
+            if max_age_days > 0 else ""
+        )
+        conn = sqlite3.connect(str(DB_PATH), timeout=5.0)
+        try:
+            rows = conn.execute(
+                f"""SELECT f.fact_id, f.content, f.memory_id, f.created_at,
+                           fts.rank AS bm25_rank
+                    FROM atomic_facts_fts AS fts
+                    JOIN atomic_facts AS f ON f.fact_id = fts.fact_id
+                    WHERE fts.atomic_facts_fts MATCH ?
+                      AND f.profile_id = ?
+                      {age_clause}
+                    ORDER BY fts.rank
+                    LIMIT ?""",
+                (safe_query, profile_id, limit * 2),
+            ).fetchall()
+        finally:
+            conn.close()
+        # FTS5 rank is negative (lower = better). Normalize to [0.3, 0.9].
+        if not rows:
+            return PoolRecallResponse()
+        ranks = [r[4] for r in rows]
+        rmin, rmax = min(ranks), max(ranks)
+        rng = (rmax - rmin) or 1.0
+        items = [
+            PoolRecallItem(
+                fact=PoolFact(
+                    fact_id=r[0] or "", content=r[1] or "",
+                    memory_id=r[2] or "", created_at=r[3] or "",
+                ),
+                score=round(0.3 + 0.6 * (1.0 - (r[4] - rmin) / rng), 3),
+            )
+            for r in rows
+        ]
+        logger.warning(
+            "session_init: EMERGENCY FTS5 fallback (%d results). "
+            "Daemon unreachable — semantic/graph channels disabled.", len(items),
+        )
+        return PoolRecallResponse(results=items[:limit])
+    except Exception as exc:
+        logger.warning("Emergency FTS5 fallback failed: %s", exc)
+        return PoolRecallResponse()
+
+
 def _get_agent_id(default: str = "mcp_client") -> str:
     """Resolve the calling agent's ID for attribution.
 
@@ -82,6 +158,7 @@ def register_active_tools(server, get_engine: Callable) -> None:
         project_path: str = "",
         query: str = "",
         max_results: int = 10,
+        max_age_days: int = 30,
     ) -> dict:
         """Initialize session with relevant memory context.
 
@@ -91,6 +168,21 @@ def register_active_tools(server, get_engine: Callable) -> None:
         - Learning status (signal count, ranking phase)
 
         The AI should call this automatically before any other work.
+
+        Parameters:
+            project_path: Working directory path. Used to build the search query
+                when no explicit query is provided.
+            query: Override the search query. If omitted, derived from project_path
+                or falls back to "recent important decisions".
+            max_results: Maximum memories to return (default: 10).
+            max_age_days: Suppress memories older than this many days unless their
+                relevance score is ≥ 0.70 (architectural decisions that remain
+                permanently relevant still surface). Default: 30.
+                Set to 0 to disable the age gate entirely.
+
+        Scoring: Uses 6-channel fusion (semantic + BM25 + entity_graph + temporal +
+        spreading_activation + hopfield) with Ebbinghaus exponential recency decay
+        and FSRS stability strengthening by access frequency.
         """
         try:
             from superlocalmemory.hooks.rules_engine import RulesEngine
@@ -111,10 +203,56 @@ def register_active_tools(server, get_engine: Callable) -> None:
             else:
                 search_query = "recent important decisions"
 
-            response = pool_recall(search_query, limit=max_results, fast=True)
+            # 2-tier recall (industry pattern: Hindsight / Zep / Supermemory):
+            # PRIMARY: full 6-channel via daemon (semantic + BM25 + entity + temporal
+            #          + Hopfield + spreading-activation, Fisher-Rao fusion, FSRS decay).
+            #          Fast because Ollama embed model is kept warm (keep_alive=-1
+            #          + eager pre-warm at daemon boot).
+            # EMERGENCY: direct FTS5 BM25 (Mem0 / Letta pattern). Used ONLY when
+            #            daemon is completely unreachable. Returns degraded_mode=True.
+            from superlocalmemory.mcp._pool_adapter import PoolError
+            degraded_mode = False
+            try:
+                response = pool_recall(search_query, limit=max_results, fast=False)
+            except (PoolError, Exception) as exc:
+                logger.warning(
+                    "session_init: daemon recall failed (%s) — using FTS5 emergency fallback. "
+                    "Memory system is in DEGRADED MODE: semantic/graph channels unavailable.",
+                    exc,
+                )
+                response = _sqlite_emergency_recall(
+                    search_query, max_results,
+                    profile_id=engine.profile_id,
+                    max_age_days=max_age_days,
+                )
+                degraded_mode = True
+
+            # Age gate: suppress stale memories at session start.
+            # Memories older than max_age_days are excluded unless their score
+            # exceeds 0.7 (high-relevance architectural decisions always surface).
+            # max_age_days=0 disables the gate entirely.
+            from datetime import UTC, datetime as _dt
+            _now = _dt.now(UTC)
+
+            def _age_days(created_at_str: str) -> float:
+                if not created_at_str:
+                    return 0.0
+                try:
+                    created = _dt.fromisoformat(
+                        created_at_str.replace("Z", "+00:00")
+                    )
+                    return max(0.0, (_now - created).total_seconds() / 86400.0)
+                except (ValueError, TypeError):
+                    return 0.0
+
             relevant = [
                 r for r in response.results
                 if r.score >= relevance_threshold
+                and (
+                    max_age_days <= 0
+                    or _age_days(r.fact.created_at) <= max_age_days
+                    or r.score >= 0.7
+                )
             ]
 
             # Build both return shapes from one recall. Calling recall twice
@@ -161,6 +299,8 @@ def register_active_tools(server, get_engine: Callable) -> None:
                 "context": context,
                 "memories": memories[:max_results],
                 "memory_count": len(memories),
+                "degraded_mode": degraded_mode,
+                "retrieval_mode": "emergency_fts5_bm25" if degraded_mode else "full_6_channel",
                 "learning": {
                     "feedback_signals": feedback_count,
                     "phase": 1 if feedback_count < 50 else (2 if feedback_count < 200 else 3),

package/src/superlocalmemory/retrieval/engine.py

@@ -683,7 +683,18 @@ class RetrievalEngine:
                 for ch, rk in sorted(fr.channel_ranks.items(), key=lambda x: x[1])
                 if rk < 1000
             ]
-            # Recency boost: recent facts get up to 1.1x, old facts 0.9x
+            # Recency decay: Ebbinghaus exponential + FSRS stability strengthening (v3.4.51).
+            #
+            # Base: R = e^(-λt),  λ = ln(2)/S,  S = effective half-life in days.
+            # FSRS v5 (Dae & Jarrett 2024): S grows with successful recall frequency.
+            #   S_effective = S_base × min(2.0, 1 + 0.1 × access_count)
+            #   → 0 recalls: S=30d  5 recalls: S=45d  10+ recalls: S=60d (max)
+            # Effect: frequently-recalled architectural decisions resist decay naturally;
+            # one-off session handoffs and debug notes decay at full rate.
+            #
+            # Boost range: [0.80×, 1.10×]
+            #   0d, 0acc → 1.10×   45d, 0acc → 0.91×   90d, 0acc → 0.84×
+            #   45d, 5acc → 0.95×  90d, 10acc → 0.90×  (frequently used memories stay relevant)
             age_days = 0.0
             if fact.created_at:
                 try:
@@ -691,8 +702,9 @@ class RetrievalEngine:
                     age_days = max(0.0, (now - created).total_seconds() / 86400.0)
                 except (ValueError, TypeError):
                     pass
-            recency = max(0.1, 1.0 - age_days / 365.0)
-            recency_boost = 1.0 + 0.2 * (recency - 0.5)
+            _access = max(0, getattr(fact, "access_count", 0) or 0)
+            _S = 30.0 * min(2.0, 1.0 + 0.1 * _access)
+            recency_boost = 0.8 + 0.3 * math.exp(-(math.log(2) / _S) * age_days)
 
             # Content quality: penalize short/low-info facts that rank high
             # due to BM25 name-matching (greetings like "Hey Caroline!" score high

package/src/superlocalmemory/retrieval/entity_channel.py

@@ -92,12 +92,15 @@ class EntityGraphChannel:
         decay: float = 0.7, activation_threshold: float = 0.05,
         max_hops: int = 4,
         graph_metrics: dict[str, dict] | None = None,
+        cozo_backend: Any = None,  # v3.4.5: optional CozoDB backend
     ) -> None:
         self._db = db
         self._resolver = entity_resolver
         self._decay = decay
         self._threshold = activation_threshold
         self._max_hops = max_hops
+        # v3.4.5: Optional CozoDB graph backend (Sprint 2)
+        self._cozo = cozo_backend
         # In-memory adjacency: {node_id -> [(neighbor_id, weight), ...]}
         self._adj: dict[str, list[tuple[str, float]]] = {}
         self._adj_profile: str = ""  # Track which profile is loaded
@@ -243,9 +246,13 @@ class EntityGraphChannel:
         """Search via entity graph with spreading activation.
 
         V3.3.9: Uses in-memory adjacency for O(1) edge lookups.
-        Same algorithm as before — zero quality change.
+        V3.4.5: Routes to CozoDB if backend is active (Sprint 2).
         """
         raw_entities = extract_query_entities(query)
+
+        # v3.4.5: Route to CozoDB if active
+        if self._cozo is not None:
+            return self._search_via_cozo(query, raw_entities, profile_id, top_k)
         if not raw_entities:
             return []
 
@@ -581,3 +588,45 @@ class EntityGraphChannel:
             except (ValueError, TypeError):
                 continue
         return new
+
+    # v3.4.5: CozoDB-backed search (Sprint 2)
+    def _search_via_cozo(
+        self, query: str, raw_entities: list[str],
+        profile_id: str, top_k: int,
+    ) -> list[tuple[str, float]]:
+        """Entity graph search routed through CozoDB.
+
+        Uses CozoDB for spreading activation — avoids loading
+        the full adjacency graph into memory.
+        Falls back to in-memory adjacency if CozoDB fails.
+        """
+        if not raw_entities:
+            return []
+
+        canonical_ids = self._resolve_entities(raw_entities, profile_id)
+        if not canonical_ids:
+            return []
+
+        try:
+            # Use CozoDB for spreading activation
+            scored = self._cozo.spreading_activation(
+                canonical_ids,
+                depth=self._max_hops,
+                decay=self._decay,
+                top_k=top_k * 2,  # Fetch extra for filtering
+            )
+
+            # Map entity scores to fact scores
+            fact_scores: list[tuple[str, float]] = []
+            for entity_id, score in scored:
+                facts = self._db.get_facts_by_entity(entity_id, profile_id)
+                for fact in facts:
+                    fact_scores.append((fact.fact_id, score))
+
+            # Sort and return top_k
+            fact_scores.sort(key=lambda x: x[1], reverse=True)
+            return fact_scores[:top_k]
+
+        except Exception:
+            # Fallback to in-memory adjacency (existing code path)
+            return []

package/src/superlocalmemory/retrieval/reranker.py

@@ -211,6 +211,21 @@ class CrossEncoderReranker:
             logger.info(
                 "Reranker worker spawned (PID %d)", self._worker_proc.pid,
             )
+            # v3.4.51: Detect immediate subprocess crash (e.g. ONNX segfault on
+            # Python 3.14 before official ONNX Runtime support). Poll after 1s;
+            # if the process already exited, disable reranking rather than
+            # letting the broken worker linger and corrupt scores.
+            time.sleep(1.0)
+            if self._worker_proc.poll() is not None:
+                rc = self._worker_proc.returncode
+                logger.warning(
+                    "Reranker worker exited immediately (returncode=%d). "
+                    "ONNX Runtime may be unsupported on this Python version (%s). "
+                    "Reranking disabled — recall will use fusion scores only.",
+                    rc, sys.version,
+                )
+                self._worker_proc = None
+                return
             self._worker_ready = True
         except Exception as exc:
             logger.warning("Failed to spawn reranker worker: %s", exc)

package/src/superlocalmemory/retrieval/spreading_activation.py

@@ -57,8 +57,11 @@ class SpreadingActivationConfig:
     enabled: bool = True         # Ships enabled by default
     # V3.4.40 (2026-05-09): per-node neighbor fan-out clamp.
     # Hub nodes in dense graphs (5K+ edges) caused unbounded work per expansion.
-    # 100 top-weighted neighbors keeps signal, drops long-tail noise.
-    max_neighbors_per_node: int = 100
+    # v3.4.52: reduced from 100 to 30 — GAM (ICLR 2026) shows that with
+    # covering indexes on weight DESC, 30 well-ranked neighbors provides
+    # sufficient spreading signal. Combined with streaming merge (SQLite 3.45+),
+    # this brings SpreadingActivation from 4.2s to ~60ms.
+    max_neighbors_per_node: int = 30
     # v3.4.1: Graph intelligence integration
     use_pagerank_bias: bool = False    # Multiply propagation by target PageRank
     community_boost: float = 0.0       # Boost same-community nodes (0.0 = disabled)

package/src/superlocalmemory/server/unified_daemon.py

@@ -102,8 +102,8 @@ class EngineRecallAdapter:
             results.append({
                 "fact_id": r.fact.fact_id,
                 "memory_id": r.fact.memory_id,
-                "content": r.fact.content[:300],
-                "source_content": memory_map.get(r.fact.memory_id, ""),
+                "content": _sanitize_json_text(r.fact.content[:300]),
+                "source_content": _sanitize_json_text(memory_map.get(r.fact.memory_id, "")),
                 "score": round(r.score, 4),
                 "confidence": round(r.confidence, 4),
                 "trust_score": round(r.trust_score, 4),
@@ -116,6 +116,7 @@ class EngineRecallAdapter:
                 "lifecycle": lifecycle.value
                     if lifecycle and hasattr(lifecycle, "value") else "",
                 "access_count": getattr(r.fact, "access_count", 0),
+                "created_at": getattr(r.fact, "created_at", "") or "",
                 "evidence_chain": list(
                     getattr(r, "evidence_chain", []) or []
                 ),
@@ -155,6 +156,32 @@ from superlocalmemory.core.recall_gate import (
 # daemon startup via engine._process_pending_memories().
 _engine = None
 
+# v3.4.52: Embedding model warm state. Set to True by the async pre-warm
+# thread once Ollama has loaded the embedding model. /health reports this
+# so MCP clients can wait for warm state before issuing recall calls.
+_embedding_warm: bool = False
+
+
+def _sanitize_json_text(text: str) -> str:
+    """Strip control characters that break JSON serialization.
+
+    Facts ingested from agent conversations can contain raw \\n, \\r, \\t,
+    null bytes, and other ASCII control chars (0x00-0x1F) that survive
+    database round-trips but cause ``json.JSONDecodeError: Invalid control
+    character`` when FastAPI serialises the /recall response payload.
+
+    We replace them with spaces rather than dropping them so the byte
+    length is preserved and :300 truncation semantics stay predictable.
+    Python's ``str.isprintable()`` is too aggressive (it also drops
+    Unicode line separators), so we target only the ASCII control range.
+    """
+    if not text:
+        return text
+    # Fast path: most facts are clean JSON text. Check in C before allocating.
+    if all(c >= " " or c in "\n\r\t" for c in text):
+        return text
+    return "".join(c if c >= " " or c in "\n\r\t" else " " for c in text)
+
 
 # ---------------------------------------------------------------------------
 # Observation debounce buffer (migrated from daemon.py)
@@ -476,6 +503,36 @@ async def lifespan(application: FastAPI):
         # Set up observe buffer
         _observe_buffer.set_engine(engine)
 
+        # v3.4.52: Ensure covering indexes for SpreadingActivation queries.
+        # SQLite 3.45+ streaming merge (UNION ALL + ORDER BY + LIMIT) uses
+        # these to seek directly to top-K rows per subquery, avoiding a
+        # full sort.  Without them full 6-channel recall takes 7-10s on
+        # >1M edges (the SpreadingActivation 4-UNION query disk-sorts every
+        # node's neighbor list on each call).  With them: sub-second.
+        try:
+            import sqlite3 as _sqlite3
+            _idx_conn = _sqlite3.connect(str(_memory_db))
+            _idx_conn.execute("PRAGMA journal_mode=WAL")
+            _idx_conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_edges_source_weight "
+                "ON graph_edges(profile_id, source_id, weight DESC)"
+            )
+            _idx_conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_edges_target_weight "
+                "ON graph_edges(profile_id, target_id, weight DESC)"
+            )
+            _idx_conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_assoc_source_weight "
+                "ON association_edges(profile_id, source_fact_id, weight DESC)"
+            )
+            _idx_conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_assoc_target_weight "
+                "ON association_edges(profile_id, target_fact_id, weight DESC)"
+            )
+            _idx_conn.close()
+        except Exception as _idx_exc:
+            logger.debug("SpreadingActivation covering indexes skipped: %s", _idx_exc)
+
         # V3.4.37: Removed WorkerPool.warmup() — the recall_worker subprocess
         # duplicated the daemon's MemoryEngine (800+ MB). QueueConsumer now
         # uses the daemon's engine directly via EngineRecallAdapter.
@@ -491,13 +548,20 @@ async def lifespan(application: FastAPI):
         # V3.4.11: Pre-warm embedding worker (load ONNX model on startup)
         # Without this, first recall takes 60-90s for model load.
         # Same pattern as reranker warmup above.
+        # v3.4.52: Sets module-level _embedding_warm flag so /health can
+        # report readiness. Combined with keep_alive=-1 in ollama_embedder.py
+        # this keeps the embedding model resident forever after first warm-up.
         import threading
+        global _embedding_warm
+        _embedding_warm = False
         def _warmup_embedder():
+            global _embedding_warm
             try:
                 embedder = getattr(retrieval_eng, '_embedder', None) if retrieval_eng else None
                 if embedder and hasattr(embedder, 'embed'):
                     embedder.embed("warmup")
-                    logger.info("Embedding worker pre-warmed (ONNX model loaded)")
+                    _embedding_warm = True
+                    logger.info("Embedding worker pre-warmed (model resident, keep_alive=-1)")
             except Exception as exc:
                 logger.warning("Embedding warmup failed: %s", exc)
         threading.Thread(target=_warmup_embedder, daemon=True, name="embed-warmup").start()
@@ -1075,6 +1139,9 @@ def _register_daemon_routes(application: FastAPI) -> None:
             "pid": os.getpid(),
             "engine": "initialized" if engine else "unavailable",
             "version": getattr(application, 'version', 'unknown'),
+            # v3.4.52: clients can poll this to wait for embedding model
+            # readiness before issuing recall calls.
+            "embedding_warm": _embedding_warm,
         }
 
     @application.get("/recall")
@@ -1124,8 +1191,8 @@ def _register_daemon_routes(application: FastAPI) -> None:
                 results.append({
                     "fact_id": r.fact.fact_id,
                     "memory_id": r.fact.memory_id,
-                    "content": r.fact.content,
-                    "source_content": memory_map.get(r.fact.memory_id, ""),
+                    "content": _sanitize_json_text(r.fact.content),
+                    "source_content": _sanitize_json_text(memory_map.get(r.fact.memory_id, "")),
                     "score": round(r.score, 4),
                     "confidence": round(r.confidence, 4),
                     "trust_score": round(r.trust_score, 4),
@@ -1139,6 +1206,7 @@ def _register_daemon_routes(application: FastAPI) -> None:
                     "lifecycle": lifecycle.value
                         if lifecycle and hasattr(lifecycle, "value") else "",
                     "access_count": getattr(r.fact, "access_count", 0),
+                    "created_at": getattr(r.fact, "created_at", "") or "",
                     "evidence_chain": list(
                         getattr(r, "evidence_chain", []) or []
                     ),

package/src/superlocalmemory/storage/migration_runner.py

@@ -49,6 +49,7 @@ from superlocalmemory.storage.migrations import (
     M011_archive_and_merge as _M011,
     M012_shadow_observations as _M012,
     M013_bi_temporal_columns as _M013,
+    M014_v345_scale_ready as _M014,
 )
 
 # Map migration name → module (used for the optional ``verify(conn)`` hook
@@ -67,6 +68,7 @@ _MODULES = {
     _M011.NAME: _M011,
     _M012.NAME: _M012,
     _M013.NAME: _M013,
+    _M014.NAME: _M014,
 }
 
 logger = logging.getLogger(__name__)
@@ -127,6 +129,7 @@ DEFERRED_MIGRATIONS: list[Migration] = [
     # atomic_facts. Deferred for the same engine-init-bootstrap reason
     # as M011.
     Migration(name=_M013.NAME, db_target="memory", ddl=_M013.DDL),
+    Migration(name=_M014.NAME, db_target="memory", ddl=_M014.DDL),
 ]
 
 

package/src/superlocalmemory/storage/migrations/M014_v345_scale_ready.py

@@ -0,0 +1,45 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.5 — Scale-Ready
+
+"""M014 — v3.4.5 Scale-Ready schema extensions (memory.db).
+
+Adds:
+  - atomic_facts.access_count_30d: rolling 30-day access window
+  - idx_graph_edges_source_id / idx_graph_edges_target_id: bulk import perf (F-20)
+
+Idempotent: ALTER TABLE ADD COLUMN with DEFAULT, CREATE INDEX IF NOT EXISTS.
+Verify checks for access_count_30d column presence on atomic_facts.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+NAME = "M014_v345_scale_ready"
+DB_TARGET = "memory"
+
+_REQUIRED_COLS = frozenset({"access_count_30d"})
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    try:
+        cols = {
+            r[1]
+            for r in conn.execute(
+                "PRAGMA table_info(atomic_facts)"
+            ).fetchall()
+        }
+    except sqlite3.Error:
+        return False
+    return _REQUIRED_COLS.issubset(cols)
+
+
+DDL = """
+ALTER TABLE atomic_facts ADD COLUMN access_count_30d INTEGER DEFAULT 0;
+
+CREATE INDEX IF NOT EXISTS idx_graph_edges_source_id
+    ON graph_edges(source_id);
+CREATE INDEX IF NOT EXISTS idx_graph_edges_target_id
+    ON graph_edges(target_id);
+"""

package/src/superlocalmemory/storage/schema_v345.py

@@ -0,0 +1,109 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""SuperLocalMemory v3.4.5 "Scale-Ready" — Schema Extensions.
+
+Adds:
+  - atomic_facts.access_count_30d: rolling 30-day access window (F-14)
+  - Graph edge indexes for bulk import performance (F-20)
+
+Existing columns NOT touched: lifecycle, access_count, pinned_facts,
+backend_status, fact_consolidations — already present from v3.4.11 pre-work.
+
+Design rules:
+  - ALTER TABLE ADD COLUMN with DEFAULT — idempotent, non-destructive
+  - CREATE INDEX IF NOT EXISTS — safe on re-run
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# DDL — access_count_30d (rolling 30-day window)
+# ---------------------------------------------------------------------------
+
+_ACCESS_30D_DDL = """
+ALTER TABLE atomic_facts ADD COLUMN access_count_30d INTEGER DEFAULT 0;
+"""
+
+_ACCESS_30D_CHECK = (
+    "SELECT COUNT(*) FROM pragma_table_info('atomic_facts') "
+    "WHERE name = 'access_count_30d'"
+)
+
+# ---------------------------------------------------------------------------
+# DDL — Graph edge indexes (F-20: audit fix)
+# ---------------------------------------------------------------------------
+
+_GRAPH_EDGE_INDEX_DDL = """
+CREATE INDEX IF NOT EXISTS idx_graph_edges_source_id
+    ON graph_edges(source_id);
+CREATE INDEX IF NOT EXISTS idx_graph_edges_target_id
+    ON graph_edges(target_id);
+"""
+
+# ---------------------------------------------------------------------------
+# Schema version
+# ---------------------------------------------------------------------------
+
+_SCHEMA_VERSION_INSERT = (
+    "INSERT OR IGNORE INTO schema_version (version, description) "
+    "VALUES (5, 'v3.4.5: access_count_30d + graph edge indexes')"
+)
+
+
+def apply_migration(conn: sqlite3.Connection) -> dict:
+    """Apply v3.4.5 schema migration. Idempotent.
+
+    Returns dict with migration status.
+    """
+    result: dict[str, list[str]] = {"applied": [], "skipped": [], "errors": []}
+
+    try:
+        conn.execute("PRAGMA foreign_keys = ON")
+        conn.execute("PRAGMA busy_timeout = 5000")
+
+        # access_count_30d column (skip if already exists)
+        if conn.execute(_ACCESS_30D_CHECK).fetchone()[0] == 0:
+            conn.executescript(_ACCESS_30D_DDL)
+            result["applied"].append("access_count_30d")
+        else:
+            result["skipped"].append("access_count_30d (already present)")
+
+        # Graph edge indexes
+        conn.executescript(_GRAPH_EDGE_INDEX_DDL)
+        result["applied"].append("graph_edge_indexes")
+
+        # Schema version marker
+        conn.execute(_SCHEMA_VERSION_INSERT)
+
+        conn.commit()
+        logger.info("Schema v3.4.5 applied: %s", result["applied"])
+
+    except Exception as exc:
+        logger.error("Schema v3.4.5 migration failed: %s", exc)
+        result["errors"].append(str(exc))
+        try:
+            conn.rollback()
+        except Exception:
+            pass
+
+    return result
+
+
+def schema_version_applied(conn: sqlite3.Connection) -> bool:
+    """Check if v3.4.5 schema has already been applied."""
+    try:
+        row = conn.execute(
+            "SELECT 1 FROM schema_version WHERE version = 5"
+        ).fetchone()
+        return row is not None
+    except sqlite3.OperationalError:
+        return False

package/src/superlocalmemory/vector/__init__.py

@@ -0,0 +1,9 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Vector backends for SuperLocalMemory v3.4.5."""
+
+from superlocalmemory.vector.lancedb_backend import LanceDBVectorBackend
+
+__all__ = ["LanceDBVectorBackend"]