superlocalmemory 3.8.7 → 3.8.9

package/src/superlocalmemory/core/ollama_embedder.py

@@ -90,6 +90,8 @@ class OllamaEmbedder:
         """
         if not text or not text.strip():
             raise ValueError("Cannot embed empty text")
+        from superlocalmemory.core.recall_gate import wait_for_foreground_idle
+        wait_for_foreground_idle()
 
         # V3.3.27: Check cache first
         cache_key = text.strip()
@@ -119,6 +121,9 @@ class OllamaEmbedder:
         """
         if not texts:
             raise ValueError("Cannot embed empty batch")
+        from superlocalmemory.core.recall_gate import is_background_work
+        if is_background_work():
+            return [self.embed(text) for text in texts]
 
         # V3.3.27: Split into cached and uncached
         results: list[list[float] | None] = [None] * len(texts)

package/src/superlocalmemory/core/recall_gate.py

@@ -14,23 +14,82 @@ recall.
 from __future__ import annotations
 
 import threading
+from contextlib import contextmanager
+from typing import Callable, Iterator
 
-_lock = threading.Lock()
+_condition = threading.Condition(threading.Lock())
 _active = 0
+_work_context = threading.local()
 
 
 def begin_recall() -> None:
     global _active
-    with _lock:
+    with _condition:
         _active += 1
 
 
 def end_recall() -> None:
     global _active
-    with _lock:
+    with _condition:
         _active = max(0, _active - 1)
+        if _active == 0:
+            _condition.notify_all()
 
 
 def in_flight() -> int:
-    with _lock:
+    with _condition:
         return _active
+
+
+@contextmanager
+def background_work(
+    *,
+    preempt_requested: Callable[[], bool] | None = None,
+) -> Iterator[None]:
+    """Mark best-effort work that must yield shared inference to recall.
+
+    The marker is thread-local because materialization, health probes, and
+    interactive handlers all share one resident engine and one embedder.
+    Nested callers restore the previous marker on exit.  A daemon-owned
+    materializer may also provide a preemption callback for a profile/runtime
+    reconfigure.  Inference clients use that callback to cut a bounded
+    background request short instead of holding the transition drain lease.
+    """
+    previous = bool(getattr(_work_context, "background", False))
+    previous_preempt = getattr(_work_context, "preempt_requested", None)
+    _work_context.background = True
+    _work_context.preempt_requested = (
+        preempt_requested if preempt_requested is not None else previous_preempt
+    )
+    try:
+        yield
+    finally:
+        _work_context.background = previous
+        _work_context.preempt_requested = previous_preempt
+
+
+def is_background_work() -> bool:
+    """Return whether the current thread is running best-effort work."""
+    return bool(getattr(_work_context, "background", False))
+
+
+def background_preempt_requested() -> bool:
+    """Return whether daemon-owned background work must release its lease."""
+    callback = getattr(_work_context, "preempt_requested", None)
+    if not callable(callback):
+        return False
+    try:
+        return bool(callback())
+    except Exception:
+        # A status read is advisory.  It must not crash a materializer or turn
+        # a valid recall into an ingestion failure.
+        return False
+
+
+def wait_for_foreground_idle() -> None:
+    """Block background inference while an interactive recall is active."""
+    if not is_background_work():
+        return
+    with _condition:
+        while _active > 0:
+            _condition.wait(timeout=0.1)

package/src/superlocalmemory/core/recall_pipeline.py

@@ -100,6 +100,45 @@ def _apply_markers_to_response(response: RecallResponse) -> None:
         r.marker = _emit_marker(r.fact.fact_id)
 
 
+def _preserve_exact_lexical_evidence(
+    response: RecallResponse,
+    query: str,
+) -> None:
+    """Keep a deterministic exact BM25 hit ahead of learned refinements.
+
+    Adaptive and bandit ranking are valuable for ambiguous candidates, but
+    they must not demote a fact containing the caller's exact query behind
+    semantically similar noise. This guard runs after every learned layer and
+    changes only ordering; it does not introduce or bypass evidence.
+    """
+    normalized_query = " ".join(query.casefold().split())
+    if len(normalized_query) < 3 or len(response.results) < 2:
+        return
+    exact = [
+        result
+        for result in response.results
+        if (
+            float((result.channel_scores or {}).get("bm25", 0.0) or 0.0) > 0.0
+            and normalized_query
+            in " ".join(result.fact.content.casefold().split())
+        )
+    ]
+    if not exact:
+        return
+    strongest = max(
+        exact,
+        key=lambda result: float(
+            (result.channel_scores or {}).get("bm25", 0.0) or 0.0,
+        ),
+    )
+    if response.results[0] is strongest:
+        return
+    response.results = [
+        strongest,
+        *(result for result in response.results if result is not strongest),
+    ]
+
+
 # ---------------------------------------------------------------------------
 # Stage 8 SB-1 — feed shadow_router from recall-settled signals.
 #
@@ -854,6 +893,7 @@ def run_recall(
     except Exception as exc:
         logger.debug("Ranking pipeline skipped: %s", exc)
 
+    _preserve_exact_lexical_evidence(response, query)
     _mark("learning+ranking")
     # Deliberately no trust, Fisher, retention, lifecycle, popularity, or graph
     # mutation here.  Those state transitions require a separately authenticated

package/src/superlocalmemory/core/store_pipeline.py

@@ -34,6 +34,14 @@ logger = logging.getLogger(__name__)
 _INIT_LANGEVIN_RADIUS = 0.05
 
 
+def _reraise_materialization_deferral(exc: Exception) -> None:
+    """Keep explicit runtime preemption out of best-effort fallbacks."""
+    from superlocalmemory.core.materialization_control import MaterializationDeferred
+
+    if isinstance(exc, MaterializationDeferred):
+        raise exc
+
+
 def _ingestion_effect_id(operation_id: str, *parts: object) -> str:
     """Return a stable ID for a relational effect owned by one ingestion."""
     if not operation_id:
@@ -247,6 +255,7 @@ def _upsert_fact_vectors(fact, profile_id, ann_index, vector_store, embedder=Non
         try:
             fact.embedding = embedder.embed(fact.content)
         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
     if not getattr(fact, "embedding", None):
@@ -429,6 +438,7 @@ def run_store(
         )
         extraction_complete = facts is not None
     except Exception as _extract_exc:
+        _reraise_materialization_deferral(_extract_exc)
         # P0-1 (remember-write-04): an extractor EXCEPTION (transient LLM/embed
         # backend error) must NOT orphan the already-committed memory. The None
         # guard below only handled a None *return*, not a raise. Treat a raise

package/src/superlocalmemory/encoding/scene_builder.py

@@ -38,6 +38,8 @@ class SceneBuilder:
     def __init__(self, db, embedder=None) -> None:
         self._db = db
         self._embedder = embedder
+        # Key by scene ID, never theme. Themes are deliberately non-unique,
+        # while eligibility and durable anchor membership are scene-specific.
         self._scene_embeddings_cache: dict[str, list[float]] = {}
 
     def assign_to_scene(
@@ -53,8 +55,12 @@ class SceneBuilder:
         if self._embedder is None:
             return self._create_scene(new_fact, profile_id)
 
-        # Always compute fact embedding first — needed for comparisons
-        fact_emb = self._embedder.embed(new_fact.content)
+        # Canonical ingestion already embeds the fact before scene assignment.
+        # Reuse that vector so scene clustering does not issue a duplicate model
+        # request for every remembered fact.
+        fact_emb = new_fact.embedding
+        if fact_emb is None:
+            fact_emb = self._embedder.embed(new_fact.content)
 
         # v3.4.38: Defensive None guard. embedder.embed() returns None when
         # the embedding worker is unavailable (timeout, crash). Without this
@@ -69,30 +75,58 @@ class SceneBuilder:
         if not scenes:
             return self._create_scene(new_fact, profile_id)
 
+        live_scene_embeddings = self._load_live_scene_embeddings(profile_id)
+        live_scene_ids = set(live_scene_embeddings)
+        self._scene_embeddings_cache.update({
+            scene_id: embedding
+            for scene_id, embedding in live_scene_embeddings.items()
+            if embedding is not None
+        })
+        # Old consolidation/deletion paths left scene rows whose fact IDs no
+        # longer exist. They are not evidence and must not trigger thousands of
+        # replacement model calls after restart. A cache hit cannot prove that
+        # a scene still has a surviving fact, so eligibility is always derived
+        # from the current database state.
+        scenes = [
+            scene for scene in scenes if scene.scene_id in live_scene_ids
+        ]
+        if not scenes:
+            return self._create_scene(new_fact, profile_id)
+
         # Find best matching scene
         best_scene: MemoryScene | None = None
         best_sim = -1.0
 
-        # V3.3.27: Batch-embed all uncached scene themes in ONE call.
+        # A scene's theme is derived from its first (anchor) fact. On daemon
+        # restart the in-memory cache is empty, but the anchor embeddings remain
+        # durable in atomic_facts. Prime from those vectors before calling the
+        # model; otherwise a mature database re-embeds thousands of themes and
+        # repeatedly recycles the shared foreground worker.
+        # V3.3.27: Batch-embed all still-uncached scene themes in ONE call.
         # Previously: 200+ individual embed() calls per fact (30s on Mode B).
         # Now: 1 batch call for all uncached themes, then cache hits for the rest.
-        uncached_themes = [s.theme for s in scenes if s.theme not in self._scene_embeddings_cache]
-        if uncached_themes and hasattr(self._embedder, 'embed_batch'):
+        uncached_scenes = [
+            scene for scene in scenes
+            if scene.scene_id not in self._scene_embeddings_cache
+        ]
+        if uncached_scenes and hasattr(self._embedder, 'embed_batch'):
             try:
-                batch_embs = self._embedder.embed_batch(uncached_themes)
-                for theme, emb in zip(uncached_themes, batch_embs):
+                batch_embs = self._embedder.embed_batch(
+                    [scene.theme for scene in uncached_scenes]
+                )
+                for scene, emb in zip(uncached_scenes, batch_embs):
                     if emb is not None:
-                        self._scene_embeddings_cache[theme] = emb
+                        self._scene_embeddings_cache[scene.scene_id] = emb
             except Exception:
                 pass  # Fall through to individual embeds below
 
         for scene in scenes:
-            if scene.theme in self._scene_embeddings_cache:
-                theme_emb = self._scene_embeddings_cache[scene.theme]
+            if scene.scene_id in self._scene_embeddings_cache:
+                theme_emb = self._scene_embeddings_cache[scene.scene_id]
             else:
                 theme_emb = self._embedder.embed(scene.theme)
                 if theme_emb is not None:
-                    self._scene_embeddings_cache[scene.theme] = theme_emb
+                    self._scene_embeddings_cache[scene.scene_id] = theme_emb
             if theme_emb is None:
                 continue
             sim = _cosine(fact_emb, theme_emb)
@@ -130,10 +164,6 @@ class SceneBuilder:
         comparisons in assign_to_scene.
         """
         theme = fact.content[:200]
-        # Pre-compute theme embedding for future comparisons
-        if self._embedder is not None:
-            self._scene_embeddings_cache[theme] = self._embedder.embed(theme)
-
         scene = MemoryScene(
             profile_id=profile_id,
             theme=theme,
@@ -142,6 +172,14 @@ class SceneBuilder:
             created_at=datetime.now(UTC).isoformat(),
             last_updated=datetime.now(UTC).isoformat(),
         )
+        # Pre-compute theme embedding for future comparisons. The canonical fact
+        # vector represents this exact theme and avoids a duplicate model call.
+        if self._embedder is not None:
+            theme_embedding = fact.embedding
+            if theme_embedding is None:
+                theme_embedding = self._embedder.embed(theme)
+            if theme_embedding is not None:
+                self._scene_embeddings_cache[scene.scene_id] = theme_embedding
         self._save_scene(scene)
         return scene
 
@@ -171,6 +209,58 @@ class SceneBuilder:
         )
         return [self._row_to_scene(dict(r)) for r in rows]
 
+    def _load_live_scene_embeddings(
+        self,
+        profile_id: str,
+    ) -> dict[str, list[float] | None]:
+        """Load one durable anchor embedding for every live scene.
+
+        ``json_each`` resolves the first still-existing fact in each scene, so
+        scenes whose original anchor was consolidated away can still reuse a
+        surviving member. The result also identifies fully stale scene rows,
+        which are ignored by assignment instead of being re-embedded.
+        """
+        try:
+            rows = self._db.execute(
+                """
+                WITH live_scene_facts AS (
+                    SELECT
+                        ms.scene_id,
+                        ms.theme,
+                        af.embedding,
+                        ROW_NUMBER() OVER (
+                            PARTITION BY ms.scene_id
+                            ORDER BY CAST(member.key AS INTEGER)
+                        ) AS member_rank
+                    FROM memory_scenes AS ms
+                    JOIN json_each(ms.fact_ids_json) AS member
+                    JOIN atomic_facts AS af
+                      ON af.fact_id = member.value
+                     AND af.profile_id = ms.profile_id
+                    WHERE ms.profile_id = ?
+                )
+                SELECT scene_id, embedding
+                FROM live_scene_facts
+                WHERE member_rank = 1
+                """,
+                (profile_id,),
+            )
+        except Exception:
+            return {}
+
+        result: dict[str, list[float] | None] = {}
+        for row in rows:
+            data = dict(row)
+            raw_embedding = data.get("embedding")
+            embedding = None
+            if raw_embedding:
+                try:
+                    embedding = json.loads(raw_embedding)
+                except (TypeError, ValueError, json.JSONDecodeError):
+                    embedding = None
+            result[str(data["scene_id"])] = embedding
+        return result
+
     def _save_scene(self, scene: MemoryScene) -> None:
         """Upsert scene to DB."""
         self._db.execute(

package/src/superlocalmemory/mcp/tools_core.py

@@ -282,7 +282,6 @@ def register_core_tools(server, get_engine: Callable) -> None:
         import asyncio
         try:
             from superlocalmemory.mcp._daemon_proxy import choose_pool
-            pool = choose_pool()
             # S9-DASH-10: priority for session_id, so engagement
             # signals land on the right pending_outcome:
             #   1. Explicit ``session_id`` tool-call argument.
@@ -322,15 +321,25 @@ def register_core_tools(server, get_engine: Callable) -> None:
                     pass
             if not effective_sid:
                 effective_sid = f"mcp:{agent_id}"
-            # V3.3.19: Run in thread pool to avoid blocking MCP event loop.
+            # Resolve the daemon proxy inside the worker too. ``choose_pool``
+            # verifies daemon ownership through a synchronous /health request;
+            # when this tool is served by the daemon's mounted HTTP MCP app,
+            # resolving it on Uvicorn's event-loop thread makes that loop wait
+            # on its own health response forever. Stdio did not exhibit this
+            # because its MCP process is external to the daemon.
+            #
             # V3.4.26: WorkerPool now concurrent — parallel calls no longer
             # block behind a single threading.Lock. See worker_pool.py.
+            def _recall_via_daemon_pool():
+                pool = choose_pool()
+                return pool.recall(
+                    query, limit=limit, session_id=effective_sid,
+                    fast=fast, include_global=include_global,
+                    include_shared=include_shared, window=window or None,
+                )
+
             result = await asyncio.to_thread(
-                pool.recall, query, limit=limit, session_id=effective_sid,
-                fast=fast,
-                include_global=include_global,
-                include_shared=include_shared,
-                window=window or None,
+                _recall_via_daemon_pool,
             )
             if result.get("ok"):
                 return {