superlocalmemory 4.0.8 → 4.0.10

package/src/superlocalmemory/core/store_pipeline.py

@@ -118,6 +118,54 @@ def _record_correction_candidate(
         logger.warning("Correction candidate not recorded for %s: %s", successor_fact_id, exc)
 
 
+#: Entity id pattern for the per-profile placeholder a dated fact with no
+#: resolved entity points its temporal event at. Per profile, not shared, so
+#: profile deletion cascades it away with everything else.
+_UNRESOLVED_ENTITY_PREFIX = "__slm_unresolved__:"
+
+
+def _ensure_unresolved_entity(db: Any, profile_id: str) -> str | None:
+    """Return the placeholder entity id for ``profile_id``, creating it once.
+
+    ``temporal_events.entity_id`` is NOT NULL with a foreign key to
+    ``canonical_entities``, so an event for a fact with no recognised entity
+    needs something real to reference. This is that something.
+
+    It is deliberately inert as an entity:
+
+      * Its ``canonical_name`` is empty, and the only query that resolves an
+        entity by name (``retrieval/temporal_channel.py``, the "events for
+        entity X" lookup) is driven by names extracted from the user's
+        question, which are never empty.
+      * Nothing derives entity links from ``temporal_events``. The entity
+        channel builds its map from ``atomic_facts.canonical_entities_json``,
+        which this does not touch — so the placeholder cannot become the kind
+        of entity that links a quarter of the store and flattens entity
+        proximity. That failure mode is real (on the author's store 'State'
+        links 1,388 facts) and this is specifically shaped not to add to it.
+      * ``fact_count`` stays 0. It is a hook for a foreign key, not a concept.
+
+    Returns None if the row cannot be created, in which case the caller skips
+    the temporal event rather than failing the write — a missing temporal row
+    is a degraded memory, an aborted remember is a lost one.
+    """
+    entity_id = f"{_UNRESOLVED_ENTITY_PREFIX}{profile_id}"
+    try:
+        db.execute(
+            "INSERT OR IGNORE INTO canonical_entities "
+            "(entity_id, profile_id, canonical_name, entity_type, fact_count) "
+            "VALUES (?, ?, '', 'unresolved', 0)",
+            (entity_id, profile_id),
+        )
+        return entity_id
+    except Exception as exc:  # noqa: BLE001 — never fail a write over this
+        logger.debug(
+            "temporal placeholder entity unavailable for %s: %s",
+            profile_id, exc,
+        )
+        return None
+
+
 def _record_fact_entity_association(
     db: DatabaseManager,
     *,
@@ -311,8 +359,13 @@ def enrich_fact(
 # Vector dual-write helper (P1-2 / embeddings-vector-01)
 # ---------------------------------------------------------------------------
 
-def _upsert_fact_vectors(fact, profile_id, ann_index, vector_store, embedder=None):
-    """Dual-write a fact's embedding to the ANN index + sqlite-vec store.
+def _upsert_fact_vectors(fact, profile_id, ann_index, vector_store, embedder=None) -> bool:
+    """Dual-write a fact's embedding to the sqlite-vec projection and the ANN index.
+
+    Write order mirrors _attach_vector: the sqlite-vec projection is attempted
+    first because that is what a meaning-based search reads.  The ANN index is
+    updated only when the projection accepts the vector.  Returns True when the
+    fact is now findable by meaning (the projection accepted the vector).
 
     Embeds on-demand when the fact has no embedding (e.g. consolidated
     summary facts created without one), so UPDATE/SUPERSEDE and consolidated
@@ -325,18 +378,44 @@ def _upsert_fact_vectors(fact, profile_id, ann_index, vector_store, embedder=Non
         except Exception as _emb_exc:  # pragma: no cover - defensive
             _reraise_materialization_deferral(_emb_exc)
             logger.debug("on-demand embed failed for %s: %s", fact.fact_id, _emb_exc)
-            return
+            return False
     if not getattr(fact, "embedding", None):
-        return
-    if ann_index:
-        ann_index.add(fact.fact_id, fact.embedding)
-    # V3.2: VectorStore upsert (sqlite-vec) -- dual-write (Rule 12)
+        return False
+
+    projected = False
+    # Projection first: what a meaning-based search reads.
     if vector_store and getattr(vector_store, "available", False):
-        vector_store.upsert(
-            fact_id=fact.fact_id,
-            profile_id=profile_id,
-            embedding=fact.embedding,
-        )
+        try:
+            projected = bool(vector_store.upsert(
+                fact_id=fact.fact_id,
+                profile_id=profile_id,
+                embedding=fact.embedding,
+            ))
+            if not projected:
+                logger.warning(
+                    "vector projection refused for %s — stored but not "
+                    "findable by meaning", fact.fact_id[:12],
+                )
+        except Exception as _vs_exc:
+            logger.warning(
+                "vector projection failed for %s (%s: %s) — stored but not "
+                "findable by meaning",
+                fact.fact_id[:12], type(_vs_exc).__name__, _vs_exc,
+            )
+
+    # ANN index only when the projection accepted the vector so both
+    # representations stay consistent.  Writing ANN without a vector-store
+    # entry creates a ghost that disappears on restart (ANN is rebuilt from
+    # the vector store at startup).
+    if projected and ann_index:
+        try:
+            ann_index.add(fact.fact_id, fact.embedding)
+        except Exception:
+            logger.warning(
+                "in-memory index rejected %s", fact.fact_id[:12], exc_info=True,
+            )
+
+    return projected
 
 
 class _TombstoneReadError(Exception):
@@ -741,6 +820,15 @@ def run_store(
             materialization_progress["relational_started"] = True
 
         is_queryable_promotion = fact.fact_id in queryable_ids
+        # When a promoted fact is being materialised the embedding column is
+        # written in a separate step AFTER the projection attempt so that the
+        # two representations stay in the correct order: projection first,
+        # canonical column second (mirroring _attach_vector's invariant).
+        # Writing the column before the projection and then failing the
+        # projection leaves the fact with embedding IS NOT NULL but no entry
+        # in fact_embeddings — invisible to meaning-search and invisible to
+        # every repair pass that selects WHERE embedding IS NULL.
+        _deferred_canonical_embedding = None  # set below if promotion path taken
         if is_queryable_promotion:
             db.update_fact(fact.fact_id, {
                 "content": fact.content,
@@ -757,15 +845,22 @@ def run_store(
                 "access_count": fact.access_count,
                 "source_turn_ids_json": fact.source_turn_ids,
                 "session_id": fact.session_id,
-                "embedding": fact.embedding,
-                "fisher_mean": fact.fisher_mean,
-                "fisher_variance": fact.fisher_variance,
+                # embedding / fisher fields omitted here — written after
+                # the projection attempt below so canonical is never ahead
+                # of the projection.
                 "lifecycle": fact.lifecycle,
                 "langevin_position": fact.langevin_position,
                 "emotional_valence": fact.emotional_valence,
                 "emotional_arousal": fact.emotional_arousal,
                 "signal_type": fact.signal_type,
             })
+            if fact.embedding:
+                _deferred_canonical_embedding = (
+                    fact.fact_id,
+                    fact.embedding,
+                    fact.fisher_mean,
+                    fact.fisher_variance,
+                )
         if consolidator:
             try:
                 action = consolidator.consolidate(
@@ -793,6 +888,9 @@ def run_store(
                     target_id = action.existing_fact_id
                     if is_queryable_promotion and target_id:
                         db.delete_fact(fact.fact_id)
+                        # The original promoted fact was deleted; its deferred
+                        # canonical embedding write must not happen.
+                        _deferred_canonical_embedding = None
                     existing_fact = db.get_fact(target_id) if target_id else None
                     if existing_fact is None:
                         continue
@@ -838,9 +936,31 @@ def run_store(
             if materialization_progress is not None:
                 materialization_progress["fact_ids"] = tuple(stored_ids)
 
-        # Dual-write embedding to ANN index + vector store (embed on-demand if
-        # a consolidated ADD fact arrived without one). See _upsert_fact_vectors.
+        # Projection first (vector store then ANN index, on-demand embed for
+        # consolidated facts that arrived without one).
         _upsert_fact_vectors(fact, profile_id, ann_index, vector_store, embedder)
+
+        # Canonical embedding write: deferred to here from the queryable-
+        # promotion block above so the projection is always attempted first.
+        # The column is written regardless of whether the projection accepted
+        # the vector (the vector is real data; withholding it would force
+        # every repair pass to re-compute a model call that the same
+        # installation condition would refuse again anyway).
+        if _deferred_canonical_embedding is not None:
+            _dc_fid, _dc_emb, _dc_fmean, _dc_fvar = _deferred_canonical_embedding
+            try:
+                db.update_fact(_dc_fid, {
+                    "embedding": _dc_emb,
+                    "fisher_mean": _dc_fmean,
+                    "fisher_variance": _dc_fvar,
+                })
+            except Exception as _dc_exc:
+                logger.warning(
+                    "canonical embedding write failed for %s: %s",
+                    _dc_fid[:12], _dc_exc,
+                )
+            _deferred_canonical_embedding = None
+
         # Phase 2: Generate contextual description (after consolidator, before graph_builder)
         if context_generator:
             try:
@@ -959,12 +1079,39 @@ def run_store(
         if scene_builder:
             scene_builder.assign_to_scene(fact, profile_id)
 
-        # Populate temporal_events for temporal retrieval
+        # Populate temporal_events for temporal retrieval.
+        #
+        # A DATE IS A DATE WHETHER OR NOT AN ENTITY WAS RESOLVED. This used to
+        # read `if fact.canonical_entities and has_dates`, so a fact carrying a
+        # perfectly good date but no recognised entity got no temporal row at
+        # all. Measured on the author's store: 967 of 3,894 genuine facts have
+        # no canonical entity (24.8%), and 958 of those have no temporal event
+        # either — a quarter of the store that the temporal channel could only
+        # reach through its created_at recency fallback, i.e. by being recent
+        # rather than by being about the right time.
+        #
+        # The date-window query does not need the entity: it joins
+        # temporal_events to atomic_facts and nothing else
+        # (retrieval/temporal_channel.py). Only the "events for entity X"
+        # lookup joins canonical_entities, and that lookup is correctly
+        # uninterested in a fact with no entity.
+        #
+        # temporal_events.entity_id is NOT NULL with an FK to
+        # canonical_entities, so an entity-less event needs a row to point at.
+        # It gets a per-profile sentinel rather than a shared one, and the
+        # sentinel is invisible to ranking: the entity channel builds its map
+        # from atomic_facts.canonical_entities_json, which is untouched here, so
+        # this cannot create the kind of entity that links a quarter of the
+        # store and destroys entity proximity.
         has_dates = (fact.observation_date or fact.referenced_date
                      or fact.interval_start)
-        if fact.canonical_entities and has_dates:
+        if has_dates:
             from superlocalmemory.storage.models import TemporalEvent
-            for eid in fact.canonical_entities:
+            entity_ids = list(fact.canonical_entities)
+            if not entity_ids:
+                sentinel = _ensure_unresolved_entity(db, profile_id)
+                entity_ids = [sentinel] if sentinel else []
+            for eid in entity_ids:
                 event = TemporalEvent(
                     event_id=_ingestion_effect_id(
                         ingestion_operation_id,
@@ -1139,15 +1286,11 @@ def run_store_fact_direct(
         )
         fact.canonical_entities = list(canonical.values())
     db.store_fact(fact)
-    if fact.embedding and ann_index:
-        ann_index.add(fact.fact_id, fact.embedding)
-    # V3.2: VectorStore upsert (dual-write)
-    if fact.embedding and vector_store and vector_store.available:
-        vector_store.upsert(
-            fact_id=fact.fact_id,
-            profile_id=profile_id,
-            embedding=fact.embedding,
-        )
+    # Projection first (vector store), ANN only on success — matching
+    # _attach_vector's invariant.  The return value (projected) is not used
+    # here because run_store_fact_direct is a fire-and-forget path with no
+    # receipt to update; the caller is responsible for any enrichment status.
+    _upsert_fact_vectors(fact, profile_id, ann_index, vector_store)
     if graph_builder:
         graph_builder.build_edges(fact, profile_id)
     # The graph projection must run after GraphBuilder: syncing immediately

package/src/superlocalmemory/core/topic_signature.py

@@ -4,8 +4,6 @@
 
 """Topic signature — deterministic, Unicode-safe, ReDoS-resistant 16-char hex.
 
-LLD reference: `.backup/active-brain/lld/LLD-01-context-cache-and-hot-path-hooks.md`
-Section 4.2.
 
 Hot-path contract:
   - stdlib-only imports (no third-party packages).

package/src/superlocalmemory/core/transactions/concrete_owners.py

@@ -15,6 +15,7 @@ from superlocalmemory.core.transactions.owners import (
     OwnerResult,
 )
 from superlocalmemory.core.transactions.service import MemoryTransactionService
+from superlocalmemory.storage.embedding_codec import decode_embedding
 
 REQUIRED_ADMISSION_OWNERS: tuple[str, ...] = ("bm25", "temporal", "vector")
 
@@ -438,10 +439,16 @@ class VectorOwner(_FactScopedOwner):
         for row in rows:
             record = dict(row)
             fid = record.get("fact_id")
-            embedding = record.get("embedding")
-            if fid is None or not embedding:
+            raw_embedding = record.get("embedding")
+            if fid is None or not raw_embedding:
                 continue
-            result[fid] = _fingerprint("vector", str(embedding))
+            # Decode so TEXT and BLOB rows produce the same fingerprint for the
+            # same embedding values.  A ValueError here (corrupt buffer) must
+            # propagate — a bad fingerprint is worse than no fingerprint.
+            decoded = decode_embedding(raw_embedding, fact_id=fid)
+            if decoded is None:
+                continue
+            result[fid] = _fingerprint("vector", str(decoded))
         return result
 
     def _table_present(
@@ -496,11 +503,11 @@ class VectorOwner(_FactScopedOwner):
         raw = dict(rows[0]).get("embedding")
         if not raw:
             return False
-        try:
-            embedding = json.loads(raw)
-        except (TypeError, json.JSONDecodeError):
-            return False
-        if not isinstance(embedding, list) or not embedding:
+        # decode_embedding accepts both TEXT (JSON) and BLOB (float32 binary);
+        # ValueError for corrupt data propagates — a heal that silently
+        # returns False on corruption is indistinguishable from "not present".
+        embedding = decode_embedding(raw, fact_id=fact_id)
+        if not embedding:
             return False
         ok = self._vector_store.upsert(
             fact_id=fact_id, profile_id=context.profile_id, embedding=embedding,

package/src/superlocalmemory/dynamics/eap_scheduler.py

@@ -29,12 +29,14 @@ from __future__ import annotations
 
 import json
 import logging
+import sqlite3
 from typing import TYPE_CHECKING
 
 import numpy as np
 from numpy.typing import NDArray
 
 from superlocalmemory.core.config import QuantizationConfig
+from superlocalmemory.storage.embedding_codec import decode_embedding
 
 if TYPE_CHECKING:
     from superlocalmemory.math.ebbinghaus import EbbinghausCurve
@@ -262,7 +264,13 @@ class EAPScheduler:
         Tries embedding_metadata -> fact_embeddings (vec0 table).
         Falls back to atomic_facts.embedding JSON column.
         """
-        # Try atomic_facts.embedding (JSON column)
+        # Try atomic_facts.embedding (TEXT JSON or BLOB float32).
+        # Two-stage error handling:
+        #   - DB query failures (any exception from execute) → log + return None.
+        #   - Format errors from decode_embedding (ValueError) → propagate.
+        #     A corrupt embedding must NOT be silently collapsed to None because
+        #     the caller cannot distinguish "embedding absent" from "data lost".
+        raw = None
         try:
             rows = self._db.execute(
                 "SELECT embedding FROM atomic_facts WHERE fact_id = ?",
@@ -270,14 +278,17 @@ class EAPScheduler:
             )
             if rows:
                 raw = dict(rows[0]).get("embedding")
-                if raw and raw != "null":
-                    data = json.loads(raw) if isinstance(raw, str) else raw
-                    if data:
-                        return np.array(data, dtype=np.float64)
-        except Exception as exc:
+        except Exception as exc:  # noqa: BLE001 — isolates DB failure from decode failure
             logger.debug(
                 "Could not load embedding from atomic_facts for %s: %s",
                 fact_id, exc,
             )
+            return None
+
+        if raw and raw != "null":
+            # ValueError from decode_embedding propagates intentionally.
+            vec = decode_embedding(raw, fact_id=fact_id)
+            if vec:
+                return np.array(vec, dtype=np.float64)
 
         return None

package/src/superlocalmemory/encoding/cognitive_consolidator.py

@@ -327,6 +327,17 @@ class CognitiveConsolidator:
               AND r.lifecycle_zone IN ('warm', 'cold')
               AND r.retention_score < ?
               AND f.lifecycle != 'forgotten'
+              -- Withheld rows are not candidates, and this is not tidiness.
+              -- 304 of them remain warm/cold in atomic_facts after 4.0.10
+              -- withholds them, and each still carries its cluster's POOLED
+              -- canonical_entities_json. CCQ clusters on entity overlap, so one
+              -- withheld summary naming ten entities joins a cluster of real
+              -- memories, contributes model prose to the gist, and then this
+              -- pass archives every source in the cluster -- including the real
+              -- memories, at scores M043's restore would not bring back.
+              -- Exactly the damage this release exists to stop, on a path the
+              -- release did not otherwise touch.
+              AND COALESCE(f.quarantined, 0) = 0
               AND f.fact_id NOT IN (
                   SELECT je.value
                   FROM ccq_consolidated_blocks ccb,
@@ -494,7 +505,10 @@ class CognitiveConsolidator:
             f"SELECT fact_id, content, importance, confidence, "
             f"       canonical_entities_json "
             f"FROM atomic_facts "
-            f"WHERE fact_id IN ({placeholders}) AND profile_id = ?",
+            f"WHERE fact_id IN ({placeholders}) AND profile_id = ? "
+            # Belt and braces with the identify query above: a cluster assembled
+            # before a row was withheld must not contribute its text to a gist.
+            f"  AND COALESCE(quarantined, 0) = 0",
             (*cluster.fact_ids, profile_id),
         )
 

package/src/superlocalmemory/encoding/graph_builder.py

@@ -9,7 +9,7 @@ last 50 memories; this version searches ALL facts per canonical entity.
 
 Edge types: ENTITY (shared entity, weight 1.0), TEMPORAL (exp-decay,
 1-week window), SEMANTIC (ANN cosine > 0.7), CAUSAL (causal markers,
-weight 0.8). CONTRADICTION exposed for external Sheaf module (Wave 4).
+weight 0.8). CONTRADICTION exposed for external Sheaf module (added in v3.5).
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
 License: AGPL-3.0-or-later
@@ -101,7 +101,7 @@ class GraphBuilder:
         self, fact_id_a: str, fact_id_b: str, profile_id: str,
         severity: float = 1.0,
     ) -> GraphEdge:
-        """Add a contradiction edge. Called by Sheaf module (Wave 4)."""
+        """Add a contradiction edge. Called by the Sheaf module (introduced in v3.5)."""
         edge = GraphEdge(
             profile_id=profile_id,
             source_id=fact_id_a,

package/src/superlocalmemory/encoding/scene_builder.py

@@ -15,6 +15,8 @@ Part of Qualixar | Author: Varun Pratap Bhardwaj
 from __future__ import annotations
 
 import json
+
+from superlocalmemory.storage.embedding_codec import decode_embedding
 import logging
 from datetime import UTC, datetime
 
@@ -357,8 +359,12 @@ class SceneBuilder:
             embedding = None
             if raw_embedding:
                 try:
-                    embedding = json.loads(raw_embedding)
-                except (TypeError, ValueError, json.JSONDecodeError):
+                    embedding = decode_embedding(
+                        raw_embedding, fact_id=str(data.get("scene_id", "<scene>")),
+                    )
+                except ValueError:
+                    # A malformed stored value, not an absent one. Scenes are an
+                    # optimisation, so one bad row must not sink the batch.
                     embedding = None
             result[str(data["scene_id"])] = embedding
         return result

package/src/superlocalmemory/hooks/adapter_base.py

@@ -4,8 +4,6 @@
 
 """Cross-platform adapter base — shared Protocol and atomic write primitive.
 
-LLD reference: ``.backup/active-brain/lld/LLD-05-cross-platform-adapters.md``
-Sections: 2 (component catalog), 4.4 (atomic write), 9.3 (sync log contract).
 
 Every adapter (Cursor, Antigravity, Copilot) implements the ``Adapter``
 Protocol. The shared ``_atomic_write`` primitive enforces the hard-rule

package/src/superlocalmemory/hooks/context_payload.py

@@ -4,8 +4,6 @@
 
 """Shared content builder — single source for every adapter body.
 
-LLD reference: ``.backup/active-brain/lld/LLD-05-cross-platform-adapters.md``
-Section 3 (Content Builder). One builder → five formatters. Every string is
 passed through ``redact_secrets`` before entering the dataclass, so no
 adapter ever writes an unredacted secret.
 

package/src/superlocalmemory/hooks/portable_kit.py

@@ -2,16 +2,16 @@
 # Licensed under AGPL-3.0-or-later - see LICENSE file
 # Part of SuperLocalMemory V3 | https://qualixar.com
 
-"""WP-08 portable kit — ``slm connect <ide>`` MCP-wiring.
+"""Portable kit — ``slm connect <ide>`` MCP-wiring.
 
 Writes SLM's MCP block into the target IDE config via MERGE-NOT-CLOBBER:
 - Only touches the ``superlocalmemory`` server key.
 - All other servers + top-level keys are preserved byte-for-byte.
 - Atomic write (.tmp + os.replace); aborts on parse error (file untouched).
-- claude-code is OUT: short-circuits to a WP-06 plugin pointer, no config written.
+- claude-code is OUT: short-circuits to a plugin pointer, no config written.
 - AGENTS.md is appended with <!-- SLM-START/END --> markers (never overwrite).
 
-IDE_MATRIX verified against ide/configs/* templates (read-only, WP-04 owns).
+IDE_MATRIX verified against ide/configs/* templates (read-only; configs are the authoritative source).
 """
 
 from __future__ import annotations
@@ -39,7 +39,7 @@ SLM_MARKER_END = "<!-- SLM-END -->"
 VALID_TRANSPORTS: frozenset[str] = frozenset({"stdio", "http", "http-mcp-remote"})
 
 CLAUDE_CODE_PLUGIN_POINTER = (
-    "slm connect claude-code: Claude Code is configured via the SLM plugin (WP-06).\n"
+    "slm connect claude-code: Claude Code is configured via the SLM plugin (see plugin/ directory).\n"
     "Run: slm plugin install  OR  see plugin-src/ for manual installation.\n"
     "No MCP config file is written by this command."
 )
@@ -206,17 +206,17 @@ IDE_MATRIX: dict[str, IDEDescriptor] = {
         },
         caveats="contextProviders is a LIST; append+dedupe by serverName",
     ),
-    # --- OUT: claude-code defers to WP-06 ---
+    # --- OUT: claude-code defers to the plugin installer ---
     "claude-code": IDEDescriptor(
         ide_id="claude-code",
-        display="Claude Code (WP-06 plugin)",
+        display="Claude Code (plugin)",
         mcp_path_global="",
         mcp_path_project=None,
         server_key="",
         fmt="",
         agents_md_path=None,
         server_block={},
-        caveats="OUT — WP-06 plugin pointer only; no MCP config written",
+        caveats="OUT — plugin pointer only; no MCP config written",
     ),
     # --- EXPERIMENTAL (gated, not wired by default) ---
     # chatgpt-desktop, perplexity, cody: gated behind --experimental
@@ -702,7 +702,7 @@ if __name__ == "__main__":  # pragma: no cover
         metavar="IDE",
         help=(
             "IDE ids to connect.  Pass 'all' to connect every supported IDE "
-            "(excluding claude-code which uses the WP-06 plugin)."
+            "(excluding claude-code which uses the plugin installer)."
         ),
     )
     _parser.add_argument("--home", help="Override home directory (test hook).")

package/src/superlocalmemory/hooks/post_tool_async_hook.py

@@ -4,8 +4,6 @@
 
 """PostToolUse async:true hook — fire-and-forget prewarm via stdlib urllib.
 
-LLD reference: `.backup/active-brain/lld/LLD-01-context-cache-and-hot-path-hooks.md`
-Section 4.4.
 
 HARD RULES (enforced by tests):
   - stdlib only — ``urllib.request``, NOT ``httpx`` / ``requests``.

package/src/superlocalmemory/hooks/prewarm_auth.py

@@ -4,8 +4,6 @@
 
 """Authentication primitives for the /internal/prewarm daemon route.
 
-LLD reference: `.backup/active-brain/lld/LLD-01-context-cache-and-hot-path-hooks.md`
-Section 4.5.
 
 Four gates, applied in order, BEFORE any engine work:
   1. Loopback-only — client address must be 127.0.0.1 / ::1.

package/src/superlocalmemory/hooks/user_prompt_hook.py

@@ -4,8 +4,6 @@
 
 """UserPromptSubmit hook — Python fallback (compiled binary preferred).
 
-LLD reference: `.backup/active-brain/lld/LLD-01-context-cache-and-hot-path-hooks.md`
-Section 4.3.
 
 HARD RULES (enforced by tests):
   - stdlib-only imports at module load (SLM modules delayed-imported).

package/src/superlocalmemory/infra/backup.py

@@ -16,6 +16,7 @@ import hashlib
 import json
 import logging
 import shutil
+import tempfile
 import sqlite3
 import time
 import uuid
@@ -735,15 +736,50 @@ class BackupManager:
         target = self.db_path.parent / target_name
 
         try:
-            self.create_backup(label="pre-restore")
+            # Stage the source OUTSIDE backup_dir before anything else runs.
+            #
+            # create_backup() below calls _enforce_retention(), which globs this
+            # same directory and unlinks the oldest files — including, when the
+            # backup being restored is the oldest, the source itself. A plain
+            # sqlite3.connect() on that now-missing path RECREATES it as an
+            # empty database, which is then copied over the live store while the
+            # call returns True, leaving a zero-byte file under the original
+            # name so a second attempt also appears to succeed.
+            #
+            # Reproduced before this fix: 11 snapshots, max_backups=10, a
+            # 500-fact store restored to 0 tables, restore_backup() -> True.
+            with tempfile.TemporaryDirectory(prefix="slm-restore-") as staging:
+                staged = Path(staging) / filename
+
+                # mode=ro fails loudly on a missing file instead of creating one.
+                src_ro = sqlite3.connect(f"file:{backup_path}?mode=ro", uri=True)
+                try:
+                    if not [r[0] for r in src_ro.execute(
+                            "SELECT name FROM sqlite_master WHERE type='table'")]:
+                        logger.error(
+                            "Restore rejected: %s contains no tables — refusing to "
+                            "overwrite %s with an empty database",
+                            filename, target_name,
+                        )
+                        return False
+                    staged_dst = sqlite3.connect(str(staged))
+                    try:
+                        src_ro.backup(staged_dst)
+                    finally:
+                        staged_dst.close()
+                finally:
+                    src_ro.close()
 
-            src = sqlite3.connect(str(backup_path))
-            dst = sqlite3.connect(str(target))
-            try:
-                src.backup(dst)
-            finally:
-                dst.close()
-                src.close()
+                self.create_backup(label="pre-restore")
+
+                # Restore from the staged copy, which retention cannot reach.
+                src = sqlite3.connect(f"file:{staged}?mode=ro", uri=True)
+                dst = sqlite3.connect(str(target))
+                try:
+                    src.backup(dst)
+                finally:
+                    dst.close()
+                    src.close()
 
             logger.info("Restored: %s -> %s", filename, target.name)