superlocalmemory 3.8.1 → 3.8.3

package/src/superlocalmemory/server/unified_daemon.py

@@ -453,6 +453,61 @@ def _emit_event(
 import asyncio as _asyncio
 _recall_semaphore = _asyncio.Semaphore(3)
 
+
+def _recall_budget_s() -> float:
+    """Generous latency budget for a recall before the keyword fallback (v3.8.3).
+
+    SLM's value is quality recall under heavy multi-agent load, so semantic
+    recall is given ample time; the keyword fallback is a LAST-RESORT safety
+    net for a genuine hang (e.g. a wedged embedder), not a speed cutoff. Tune
+    with SLM_SEARCH_RECALL_TIMEOUT_S (shared with the dashboard search route).
+    """
+    import os
+    try:
+        v = float(os.environ.get("SLM_SEARCH_RECALL_TIMEOUT_S", ""))
+        return v if v > 0 else 25.0
+    except (TypeError, ValueError):
+        return 25.0
+
+
+def _recall_keyword_fallback(engine, query: str, limit: int) -> dict:
+    """Fast profile-scoped keyword (LIKE) fallback for /recall.
+
+    Used only when semantic recall exceeds its budget, so CLI/MCP callers get
+    a bounded response instead of hanging. Mirrors the dashboard /api/search
+    fallback shape (retrieval_mode=degraded_lexical).
+    """
+    results = []
+    try:
+        rows = engine._db.execute(
+            "SELECT fact_id, content, confidence FROM atomic_facts "
+            "WHERE profile_id = ? AND content LIKE ? "
+            "ORDER BY confidence DESC LIMIT ?",
+            (engine.profile_id, f"%{query}%", limit),
+        )
+        for pos, r in enumerate(rows, start=1):
+            d = dict(r)
+            results.append({
+                "fact_id": d.get("fact_id"),
+                "content": (d.get("content") or "")[:2400],
+                "score": None, "relevance_score": None, "ranking_score": None,
+                "confidence": d.get("confidence"),
+                "rank_position": pos,
+            })
+    except Exception as exc:
+        logger.warning("recall keyword fallback failed (non-fatal): %s", exc)
+    return {
+        "ok": True,
+        "query": query,
+        "query_type": "text_search",
+        "retrieval_mode": "degraded_lexical",
+        "degraded_reason": "recall_budget_exceeded",
+        "result_count": len(results),
+        "results": results,
+        "count": len(results),
+        "no_confident_match": True,
+    }
+
 # 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.
@@ -1068,6 +1123,21 @@ async def _source_quality_repair_loop(
                     state="retrying",
                     last_error="storage_temporarily_unavailable",
                 )
+            except Exception as exc:  # F6 fix: broad catch keeps loop alive
+                # Any unexpected exception in a single tick (e.g. malformed JSON
+                # blob, AttributeError from a half-migrated schema) must not kill
+                # the entire repair loop.  Log and continue to next iteration.
+                logger.warning(
+                    "source-quality repair tick failed unexpectedly: %s — "
+                    "loop continues",
+                    exc,
+                    exc_info=True,
+                )
+                _set_source_quality_repair_status(
+                    application,
+                    state="retrying",
+                    last_error=type(exc).__name__,
+                )
             else:
                 successful_ticks += 1
             if pending == []:
@@ -1448,9 +1518,186 @@ async def lifespan(application: FastAPI):
             except Exception as exc:
                 logger.warning("Vector store backfill failed (non-fatal): %s", exc)
 
+        def _self_heal():
+            """v3.8.2 zero-pain self-heal.
+
+            On daemon start (especially right after a pip/npm upgrade of a
+            months-old database), silently restore full retrieval capability
+            with ZERO user action:
+              1. embed facts that were never embedded (NULL embedding column),
+              2. backfill key-expansion alt-keys (BM25 recall aid) via one
+                 bounded maintenance pass per profile,
+              3. index everything (including the just-embedded facts) into the
+                 sqlite-vec store.
+            Fully non-blocking (daemon thread) — recall keeps serving throughout.
+            Every step is bounded + idempotent, so on an already-complete DB the
+            whole pass is a fast no-op. Progress is exposed at /status.self_heal
+            so the dashboard can show a plain-language "Optimizing memory…" line.
+            """
+            import time as _t
+            global _SELF_HEAL_STATUS
+            _SELF_HEAL_STATUS = {
+                "state": "checking_components", "embeddings_backfilled": 0,
+                "expansion_backfilled": 0, "null_remaining": None,
+                "components": None,
+                "started_at": _t.time(), "finished_at": None,
+            }
+            # Step 0 (v3.8.2 "whole self-healer"): repair components that
+            # silently failed to install from the internet — BEFORE waiting on
+            # the embedder, since a missing embedding model would make that wait
+            # pointless. Downloads missing HF models (embedder/reranker, only
+            # when torch is present) and pip-installs sqlite-vec when the
+            # interpreter is user-writable. Bounded, fail-open, never sudo,
+            # never auto-pulls Ollama. Manual-only items are recorded for the
+            # dashboard "what's missing" report (GET /api/v3/components), not
+            # acted on here.
+            try:
+                from superlocalmemory.core import component_healer
+                heal_res = component_healer.heal_missing(
+                    config,
+                    on_progress=lambda k, m: logger.info(
+                        "Self-heal component[%s]: %s", k, m,
+                    ),
+                )
+                _SELF_HEAL_STATUS["components"] = heal_res
+                if heal_res["attempted"]:
+                    logger.info("Self-heal components: %s", heal_res)
+            except Exception as exc:
+                logger.warning(
+                    "Self-heal component check failed (non-fatal): %s", exc,
+                )
+            _SELF_HEAL_STATUS["state"] = "waiting_embedder"
+            for _ in range(120):  # up to ~60s for the embedder to warm
+                if _embedding_warm:
+                    break
+                _t.sleep(0.5)
+            try:
+                embedder = getattr(retrieval_eng, "_embedder", None) if retrieval_eng else None
+                db = engine._db
+                if embedder is None or db is None:
+                    _SELF_HEAL_STATUS["state"] = "skipped_no_embedder"
+                    return
+                # 1) Embed never-embedded facts (all profiles, the upgrade
+                #    headline). Looped: backfill is idempotent + bounded, and the
+                #    shared embedding worker can transiently return None under
+                #    startup contention (concurrent recall-warmup). Retrying until
+                #    the NULL count stops shrinking makes the heal converge
+                #    robustly rather than abandoning on one transient miss.
+                #    Facts that never embed (e.g. a document far over the model's
+                #    token limit) are left as-is after a bounded number of no-progress
+                #    attempts. No-op when there are no NULLs.
+                _SELF_HEAL_STATUS["state"] = "backfilling_embeddings"
+                try:
+                    from superlocalmemory.storage.embedding_migrator import (
+                        backfill_missing_embeddings,
+                    )
+                    # RECALL-PRIORITY THROTTLE: the embedding worker is a single
+                    # serialized subprocess shared with foreground recall. A
+                    # continuous backfill starves interactive query-embedding and
+                    # recalls time out. So: (a) tiny batches (short worker holds),
+                    # and (b) before each batch, defer while ANY user recall is in
+                    # flight — reusing the same recall_gate the pending materializer
+                    # uses. This keeps recall responsive throughout the heal (the
+                    # zero-pain requirement); the heal just takes a little longer.
+                    from superlocalmemory.core import recall_gate
+                    total_embedded = 0
+                    no_progress = 0
+                    for _attempt in range(500):
+                        # Absolute priority to user recalls: pause the heal while
+                        # a recall is active (bounded wait so we never wedge).
+                        _waited = 0.0
+                        while recall_gate.in_flight() > 0 and _waited < 30.0:
+                            _t.sleep(0.5)
+                            _waited += 0.5
+                        r = backfill_missing_embeddings(
+                            config, db, embedder, limit=5, all_profiles=True,
+                        )
+                        got = r.get("embedded", 0)
+                        total_embedded += got
+                        _SELF_HEAL_STATUS["embeddings_backfilled"] = total_embedded
+                        _SELF_HEAL_STATUS["null_remaining"] = r.get("remaining_null", 0)
+                        if r.get("remaining_null", 0) == 0:
+                            break
+                        if got == 0:
+                            no_progress += 1
+                            if no_progress >= 5:  # transient recovery exhausted
+                                break
+                            _t.sleep(3)  # let the worker settle, then retry
+                        else:
+                            no_progress = 0
+                            _t.sleep(0.5)  # brief pause between bursts
+                    if total_embedded:
+                        logger.info(
+                            "Self-heal: embedded %d previously-unembedded facts "
+                            "(%d remaining)", total_embedded,
+                            _SELF_HEAL_STATUS["null_remaining"],
+                        )
+                except Exception as exc:
+                    logger.warning("Self-heal embedding backfill failed (non-fatal): %s", exc)
+                # 2) Math/key-expansion maintenance is intentionally NOT run here:
+                #    run_maintenance triggers a full Langevin backfill over every
+                #    fact, which on a large legacy DB takes minutes and its CPU
+                #    burst inflates foreground recall latency during the heal
+                #    window. The startup heal stays lean (embeddings + vector
+                #    index — what makes facts findable again). Langevin/Sheaf/
+                #    key-expansion continue to converge on the periodic
+                #    MaintenanceScheduler exactly as before — unchanged behavior.
+                # 3) Index everything (incl. newly-embedded) into the vector store.
+                _SELF_HEAL_STATUS["state"] = "indexing_vectors"
+                try:
+                    _backfill_vector_store()
+                except Exception as exc:
+                    logger.warning("Self-heal vector index failed (non-fatal): %s", exc)
+                _SELF_HEAL_STATUS["state"] = "complete"
+                _SELF_HEAL_STATUS["finished_at"] = _t.time()
+                logger.info("Self-heal complete: %s", _SELF_HEAL_STATUS)
+            except Exception as exc:
+                _SELF_HEAL_STATUS["state"] = "error"
+                logger.warning("Self-heal failed (non-fatal): %s", exc)
+
+        def _component_recheck_loop():
+            """Periodic component re-check (v3.8.2 "whole self-healer").
+
+            The startup heal (_self_heal Step 0) runs once. This keeps the
+            self-healer promise for a long-running daemon: it re-probes
+            components on a slow cadence and auto-repairs any that regress
+            (a cache eviction, a half-finished install). No-op on a healthy
+            machine — nothing is auto-fixable-missing, so it is just a cheap
+            probe. Disable with SLM_COMPONENT_RECHECK_SEC=0.
+            """
+            import os as _os
+            import time as _t
+            try:
+                cadence = int(_os.environ.get("SLM_COMPONENT_RECHECK_SEC", "1800"))
+            except ValueError:
+                cadence = 1800
+            if cadence <= 0:
+                return
+            # Let the startup heal + warmup settle before the first re-check.
+            _t.sleep(max(cadence, 300))
+            while True:
+                try:
+                    from superlocalmemory.core import component_healer
+                    res = component_healer.heal_missing(
+                        config,
+                        on_progress=lambda k, m: logger.info(
+                            "Component re-check[%s]: %s", k, m,
+                        ),
+                    )
+                    if res["attempted"]:
+                        logger.info("Component re-check repaired: %s", res)
+                except Exception as exc:
+                    logger.debug("Component re-check failed (non-fatal): %s", exc)
+                _t.sleep(cadence)
+
         threading.Thread(target=_warmup_embedder, daemon=True, name="embed-warmup").start()
         threading.Thread(target=_warmup_recall, daemon=True, name="recall-warmup").start()
-        threading.Thread(target=_backfill_vector_store, daemon=True, name="vs-backfill").start()
+        # v3.8.2: self-heal supersedes the bare vector-store backfill (it calls
+        # _backfill_vector_store itself, after embedding + expansion heal).
+        threading.Thread(target=_self_heal, daemon=True, name="self-heal").start()
+        threading.Thread(
+            target=_component_recheck_loop, daemon=True, name="component-recheck",
+        ).start()
 
         # v3.6.8: Runtime recall-health monitor. The three warmups above run
         # ONCE at boot; on a long-running daemon the graph page cache gets
@@ -2761,7 +3008,15 @@ def _register_daemon_routes(application: FastAPI) -> None:
         request: Request,
         q: str = "", query: str = "", limit: int = CANONICAL_RECALL_LIMIT,
         session_id: str = "",
-        fast: bool = True,
+        # v3.8.2 client-driven agentic: ``fast`` is left UNSET (None) by default
+        # so the daemon resolves the configured policy (retrieval.client_driven_agentic,
+        # ships True). The agent hot path is consumed by a frontier LLM that
+        # reformulates queries far better than the local Ollama model, so it
+        # skips the internal agentic round and returns fast local retrieval (all
+        # six channels + reranker) plus confidence signals; the client re-queries
+        # on low confidence. An explicit ?fast=true / ?fast=false always wins.
+        # See recall_pipeline.resolve_hot_path_fast.
+        fast: bool | None = None,
         full: bool = False,
         include_source: bool = False,
         include_global: bool | None = None,
@@ -2773,6 +3028,10 @@ def _register_daemon_routes(application: FastAPI) -> None:
         engine = _get_engine_or_503()
         if not search_query:
             return {"results": [], "count": 0, "query_type": "none", "retrieval_time_ms": 0}
+        # v3.8.2: resolve the client-driven-agentic default now so the concrete
+        # bool drives BOTH the full-recall semaphore below and engine.recall().
+        from superlocalmemory.core.recall_pipeline import resolve_hot_path_fast
+        fast = resolve_hot_path_fast(fast, engine._config)
         # S9-DASH-02: session_id for the outcome-queue producer.
         # Priority: ?session_id= > X-SLM-Session-Id header > synthetic
         # "http:<ts>". Without a session_id the recall still works
@@ -2809,15 +3068,35 @@ def _register_daemon_routes(application: FastAPI) -> None:
         if not fast:
             await _recall_semaphore.acquire()
         try:
-            response = await asyncio.to_thread(
-                engine.recall,
-                search_query, limit=limit, session_id=effective_sid,
-                agent_id=recall_actor,
-                fast=fast,
-                include_global=include_global,
-                include_shared=include_shared,
-                window=window or None,
+            # v3.8.3: bound the recall so CLI/MCP callers never hang on a
+            # wedged embedder. Poll the executor future (which cannot be
+            # cancelled) without blocking the loop, and give quality recall a
+            # GENEROUS budget; only if it is exceeded do we serve the fast
+            # keyword fallback. The orphaned recall finishes in the background.
+            loop = asyncio.get_running_loop()
+            _rf = loop.run_in_executor(
+                None,
+                lambda: engine.recall(
+                    search_query, limit=limit, session_id=effective_sid,
+                    agent_id=recall_actor,
+                    fast=fast,
+                    include_global=include_global,
+                    include_shared=include_shared,
+                    window=window or None,
+                ),
             )
+            _budget = _recall_budget_s()
+            _deadline = loop.time() + _budget
+            while not _rf.done() and loop.time() < _deadline:
+                await asyncio.sleep(0.05)
+            if not _rf.done():
+                _rf.add_done_callback(lambda f: (f.cancelled() or f.exception()))
+                logger.warning(
+                    "recall: semantic recall exceeded %.0fs budget for %r — "
+                    "serving keyword fallback", _budget, (search_query or "")[:80],
+                )
+                return _recall_keyword_fallback(engine, search_query, limit)
+            response = _rf.result()
             # v3.4.26: return the same field shape as recall_worker so
             # MCP processes proxying through the daemon get recall_trace-
             # compatible data without a second round trip.
@@ -3178,8 +3457,68 @@ def _register_daemon_routes(application: FastAPI) -> None:
             "legacy_port": _LEGACY_PORT,
             "profile": profile_snapshot.profile_id,
             "profile_generation": profile_snapshot.generation,
+            # F2 fix: expose M028 backfill progress so operators can monitor
+            # the post-upgrade fact/entity association repair state.
+            "m028_backfill": getattr(
+                application.state,
+                "fact_entity_association_repair_status",
+                None,
+            ),
+            # v3.8.2: zero-pain self-heal progress (embeddings/expansion/vector
+            # index backfill after an upgrade). Dashboard renders a plain
+            # "Optimizing memory…" line from this. Defaults to idle before start.
+            "self_heal": globals().get("_SELF_HEAL_STATUS", {"state": "idle"}),
         }
 
+    @application.get("/api/v3/components")
+    async def components():
+        """Component / dependency health (v3.8.2).
+
+        Read-only snapshot from the central registry (core.component_registry)
+        — the same source the self-heal thread acts on. Powers the dashboard
+        'what's missing' report and `slm doctor`. Includes live 'retrying'
+        overlays while a background repair is in flight. Never mutates state.
+        """
+        _update_activity()
+        try:
+            from superlocalmemory.core import component_registry
+            cfg = getattr(application.state, "config", None)
+            return component_registry.snapshot(cfg)
+        except Exception as exc:
+            raise HTTPException(500, detail=str(exc))
+
+    @application.post("/api/v3/components/heal")
+    async def heal_components(request: Request):
+        """Trigger a component self-heal pass (dashboard 'Retry now').
+
+        Repairs auto-fixable missing components (re-download missing models,
+        install sqlite-vec). Runs in a background thread and returns
+        immediately so the HTTP request never blocks on a multi-minute
+        download; the dashboard polls GET /api/v3/components to watch the
+        'retrying' → 'ok' transition. Safe to call repeatedly (no-op when
+        healthy). Requires the dashboard write principal, like other
+        dashboard mutations.
+        """
+        _require_write_actor(request)
+        _update_activity()
+        cfg = getattr(application.state, "config", None)
+
+        def _run():
+            try:
+                from superlocalmemory.core import component_healer
+                res = component_healer.heal_missing(
+                    cfg,
+                    on_progress=lambda k, m: logger.info(
+                        "Manual heal[%s]: %s", k, m,
+                    ),
+                )
+                logger.info("Manual component heal: %s", res)
+            except Exception as exc:
+                logger.warning("Manual component heal failed (non-fatal): %s", exc)
+
+        threading.Thread(target=_run, daemon=True, name="manual-heal").start()
+        return {"status": "started"}
+
     @application.get("/list")
     async def list_facts(limit: int = 50):
         _update_activity()

package/src/superlocalmemory/storage/embedding_migrator.py

@@ -26,6 +26,23 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
+# ---------------------------------------------------------------------------
+# Backfill constants
+# ---------------------------------------------------------------------------
+
+#: Default batch size for backfill_missing_embeddings.
+_BACKFILL_BATCH_SIZE = 50
+
+#: Max characters embedded per fact during backfill. The embedding model
+#: (nomic-embed-text-v1.5) truncates at ~8192 tokens anyway, but a raw
+#: oversized document (observed up to 107 KB on a real DB) makes the shared
+#: single-worker embedder busy for 15-20s on ONE fact — starving foreground
+#: recall during a self-heal pass. Bounding the input keeps every fact's embed
+#: fast and the worker responsive; the leading slice captures the fact's gist
+#: for semantic recall. Facts this large are documents that were almost
+#: certainly NULL because they failed to embed at ingestion for the same reason.
+_MAX_EMBED_CHARS = 8000
+
 # Sentinel stored in config.json when no model has been set yet.
 _NO_MODEL = ""
 
@@ -44,6 +61,24 @@ def _model_signature(config: SLMConfig) -> str:
     return f"{emb.model_name}::{emb.dimension}"
 
 
+def _normalize_signature(signature: str) -> str:
+    """Normalize a signature for equivalence comparison.
+
+    v3.8.2 self-healing: the SAME embedding model has been recorded under
+    different name strings across releases — notably the HuggingFace org
+    prefix drifted (``nomic-ai/nomic-embed-text-v1.5`` vs the bare
+    ``nomic-embed-text-v1.5``). A prefix-only difference does NOT change the
+    embedding vector space, so it must not trigger a full multi-hour re-embed
+    when a non-technical user upgrades. This collapses the model name to its
+    basename (segment after the last ``/``) while keeping the ``::dimension``
+    suffix — a genuine model change (different basename OR dimension) still
+    differs and still triggers migration.
+    """
+    model, sep, dim = signature.partition("::")
+    model = model.rsplit("/", 1)[-1].strip()
+    return f"{model}{sep}{dim}" if sep else model
+
+
 def _read_stored_signature(config_dir: Path) -> str:
     """Read the last-used embedding model signature from config.json."""
     config_path = config_dir / "config.json"
@@ -88,6 +123,19 @@ def check_embedding_migration(config: SLMConfig) -> bool:
     if stored_sig == current_sig:
         return False
 
+    # v3.8.2 self-healing: a prefix-only model-name drift (e.g. the nomic-ai/
+    # org prefix appearing/disappearing between releases) is the SAME vector
+    # space — absorb the transition by refreshing the stored signature to the
+    # current form, with NO re-embed. This spares non-technical users a
+    # multi-hour full re-index on a cosmetic upgrade.
+    if _normalize_signature(stored_sig) == _normalize_signature(current_sig):
+        _write_stored_signature(config.base_dir, current_sig)
+        logger.info(
+            "Embedding signature normalized (no re-embed): %s ~= %s",
+            stored_sig, current_sig,
+        )
+        return False
+
     logger.warning(
         "Embedding model changed: %s -> %s. Re-indexing required.",
         stored_sig, current_sig,
@@ -177,3 +225,190 @@ def run_embedding_migration(
         reindexed, total,
     )
     return reindexed
+
+
+# ---------------------------------------------------------------------------
+# Backfill: embed facts that were NEVER embedded (embedding IS NULL)
+# ---------------------------------------------------------------------------
+
+def _count_null_embeddings(
+    db: Any,
+    profile_id: str,
+    all_profiles: bool,
+) -> int:
+    """Return count of atomic_facts rows with NULL embedding."""
+    if all_profiles:
+        rows = db.execute(
+            "SELECT count(*) AS c FROM atomic_facts WHERE embedding IS NULL",
+        )
+    else:
+        rows = db.execute(
+            "SELECT count(*) AS c FROM atomic_facts "
+            "WHERE embedding IS NULL AND profile_id = ?",
+            (profile_id,),
+        )
+    return int(rows[0]["c"]) if rows else 0
+
+
+def backfill_missing_embeddings(
+    config: "SLMConfig",
+    db: Any,
+    embedder: Any,
+    batch_size: int = _BACKFILL_BATCH_SIZE,
+    limit: int | None = None,
+    all_profiles: bool = False,
+) -> dict[str, int]:
+    """Embed atomic_facts rows whose ``embedding`` column is NULL.
+
+    Unlike :func:`run_embedding_migration` (which re-embeds on model-signature
+    change), this function handles facts that were *never* embedded — for
+    example facts stored while the embedder was unavailable.
+
+    Resumable and idempotent: re-running after a partial run only processes
+    the remaining NULLs.  Fail-open per-fact: a single bad fact logs a warning
+    and is skipped; the batch continues.
+
+    Writes mirror :func:`run_embedding_migration` exactly:
+    * ``atomic_facts.embedding`` ← ``json.dumps(vector)``
+    * ``embedding_metadata`` ← upserted row with current model name + dimension
+
+    Args:
+        config: Active SLMConfig (provides profile_id, model name, dimension).
+        db: DatabaseManager (or duck-compatible object with ``.execute()``).
+        embedder: Object implementing ``embed_batch(texts) -> list[vec|None]``
+            and (optionally) ``embed(text) -> vec|None``.  Pass ``None`` to
+            make this a no-op (returns zero counts).
+        batch_size: Facts per embed_batch() call.  Defaults to 50.
+        limit: Maximum facts to embed in this call.  ``None`` means no cap —
+            all NULL-embedding facts are processed.  Use a bounded limit for
+            the maintenance self-healing path so each pass is quick.
+        all_profiles: When ``True``, processes facts from every profile in the
+            database.  When ``False`` (default), scopes to
+            ``config.active_profile``.
+
+    Returns:
+        ``{"scanned": int, "embedded": int, "remaining_null": int}``
+
+        *scanned*: total NULL-embedding facts found before applying *limit*.
+        *embedded*: facts successfully written in this call.
+        *remaining_null*: NULL count after the call (includes facts not yet
+            reached because of *limit*).
+    """
+    profile_id = config.active_profile
+
+    if embedder is None:
+        logger.warning(
+            "backfill_missing_embeddings: no embedder available — skipping."
+        )
+        return {"scanned": 0, "embedded": 0, "remaining_null": 0}
+
+    # ------------------------------------------------------------------
+    # 1. Fetch all NULL-embedding facts (cheap query; only reads IDs + content)
+    # ------------------------------------------------------------------
+    if all_profiles:
+        rows = db.execute(
+            "SELECT fact_id, content, profile_id FROM atomic_facts "
+            "WHERE embedding IS NULL ORDER BY created_at",
+        )
+    else:
+        rows = db.execute(
+            "SELECT fact_id, content, profile_id FROM atomic_facts "
+            "WHERE embedding IS NULL AND profile_id = ? ORDER BY created_at",
+            (profile_id,),
+        )
+
+    facts: list[tuple[str, str, str]] = [
+        (dict(r)["fact_id"], dict(r)["content"], dict(r)["profile_id"])
+        for r in rows
+    ]
+    scanned = len(facts)
+
+    if scanned == 0:
+        return {"scanned": 0, "embedded": 0, "remaining_null": 0}
+
+    # Apply call-level limit (resumability: next call picks up where this left off)
+    if limit is not None:
+        facts = facts[:limit]
+
+    current_model = config.embedding.model_name
+    current_dim = config.embedding.dimension
+    embedded = 0
+
+    # ------------------------------------------------------------------
+    # 2. Batch embed and write back
+    # ------------------------------------------------------------------
+    for batch_start in range(0, len(facts), batch_size):
+        batch = facts[batch_start : batch_start + batch_size]
+        # Bound per-fact input so an oversized document doesn't monopolize the
+        # shared embedding worker (starving foreground recall during self-heal).
+        texts = [(content or "")[:_MAX_EMBED_CHARS] for _, content, _ in batch]
+        fact_ids = [fid for fid, _, _ in batch]
+        prof_ids = [pid for _, _, pid in batch]
+
+        # Attempt batch embed; fall back to per-fact on batch failure.
+        try:
+            vectors: list[Any] = embedder.embed_batch(texts)
+        except Exception as exc:
+            logger.warning(
+                "backfill: batch embed failed for facts %d-%d: %s — "
+                "retrying per-fact.",
+                batch_start,
+                batch_start + len(batch),
+                exc,
+            )
+            vectors = []
+            for text in texts:
+                try:
+                    vec = embedder.embed(text)
+                    vectors.append(vec)
+                except Exception as per_fact_exc:
+                    logger.warning(
+                        "backfill: per-fact embed failed for '%s...': %s",
+                        text[:40],
+                        per_fact_exc,
+                    )
+                    vectors.append(None)
+
+        # Write each successfully-embedded fact back to the DB.
+        for fid, vec, pid in zip(fact_ids, vectors, prof_ids):
+            if vec is None:
+                logger.warning(
+                    "backfill: null vector for fact %s — skipping.", fid[:16]
+                )
+                continue
+            try:
+                embedding_json = json.dumps(vec)
+                # Mirror run_embedding_migration's write path exactly.
+                db.execute(
+                    "UPDATE atomic_facts SET embedding = ? WHERE fact_id = ?",
+                    (embedding_json, fid),
+                )
+                # Upsert embedding_metadata.  NULL-embedding facts have no row
+                # here yet, so we INSERT; if a row somehow exists, update it.
+                db.execute(
+                    "INSERT INTO embedding_metadata"
+                    "    (fact_id, profile_id, model_name, dimension)"
+                    " VALUES (?, ?, ?, ?)"
+                    " ON CONFLICT(fact_id) DO UPDATE SET"
+                    "    model_name = excluded.model_name",
+                    (fid, pid, current_model, current_dim),
+                )
+                embedded += 1
+            except Exception as exc:
+                logger.warning(
+                    "backfill: failed to write fact %s: %s", fid[:16], exc
+                )
+
+    # ------------------------------------------------------------------
+    # 3. Count remaining NULLs (accounts for the limit; tells caller how
+    #    many passes remain before full convergence).
+    # ------------------------------------------------------------------
+    remaining = _count_null_embeddings(db, profile_id, all_profiles)
+
+    logger.info(
+        "Embedding backfill: %d/%d facts embedded, %d remaining NULL.",
+        embedded,
+        scanned,
+        remaining,
+    )
+    return {"scanned": scanned, "embedded": embedded, "remaining_null": remaining}