nexo-brain 7.32.0 → 7.34.0

package/src/db/_memory_v2.py

@@ -24,6 +24,103 @@ def _core():
     return module
 
 
+def _cognitive():
+    """Lazy import of the cognitive embedding core.
+
+    Imported lazily so the DB layer never hard-depends on the (heavy) cognitive
+    stack and so importing db._memory_v2 cannot fail when numpy/fastembed are
+    unavailable in a stripped environment.
+    """
+    module = sys.modules.get("cognitive._core")
+    if module is None:
+        module = importlib.import_module("cognitive._core")
+    return module
+
+
+# Identifier persisted alongside each precomputed observation vector so the
+# fusion path can refuse to compare vectors produced by an incompatible model.
+OBSERVATION_EMBEDDING_MODEL = "bge-base-embeddings"
+
+
+def _model_is_warm() -> bool:
+    """Return True only when embedding will NOT trigger a cold model load.
+
+    Two safe cases:
+      * the deterministic offline fallback is active
+        (NEXO_SKIP_COGNITIVE_MODEL_DOWNLOAD) — fast and dependency-free, so it is
+        always safe to embed; and
+      * the real fastembed model is already loaded in this process.
+
+    A cold real model returns False so the latency path degrades to FTS instead
+    of paying a download/load cost on a single query.
+    """
+    try:
+        cog = _cognitive()
+    except Exception:
+        return False
+    try:
+        if cog._model_download_disabled():
+            return True
+    except Exception:
+        return False
+    return getattr(cog, "_model", None) is not None
+
+
+def _embedding_columns_present(conn) -> bool:
+    try:
+        cols = {row[1] for row in conn.execute("PRAGMA table_info(memory_observations)").fetchall()}
+    except Exception:
+        return False
+    return "embedding" in cols and "embedding_model" in cols
+
+
+def _embed_text_blob(text: str):
+    """Embed text into (blob, model_name). Returns (None, '') on any failure.
+
+    Never raises; never blocks indefinitely on a cold model — callers gate on
+    _model_is_warm() before calling on the latency path.
+    """
+    clean = str(text or "").strip()
+    if not clean:
+        return None, ""
+    try:
+        cog = _cognitive()
+        vector = cog.embed(clean)
+        blob = cog._array_to_blob(vector)
+        if not blob:
+            return None, ""
+        return blob, OBSERVATION_EMBEDDING_MODEL
+    except Exception:
+        return None, ""
+
+
+def _write_observation_embedding(uid: str, *, summary: str = "", subject: str = "") -> bool:
+    """Precompute and store an observation embedding. Guarded; never raises.
+
+    Called AFTER the observation row is committed. A failure here must never
+    surface to the write path — the observation is already durable; the vector
+    is a shadow optimisation that the bounded backfill can fill in later.
+    """
+    try:
+        conn = _core().get_db()
+        if not _table_exists(conn, "memory_observations") or not _embedding_columns_present(conn):
+            return False
+        if not _model_is_warm():
+            return False
+        text = " ".join(part for part in [str(subject or "").strip(), str(summary or "").strip()] if part).strip()
+        blob, model_name = _embed_text_blob(text)
+        if blob is None:
+            return False
+        conn.execute(
+            "UPDATE memory_observations SET embedding = ?, embedding_model = ? WHERE observation_uid = ?",
+            (blob, model_name, uid),
+        )
+        conn.commit()
+        return True
+    except Exception:
+        return False
+
+
 _REDACT_PATTERNS = (
     re.compile(r"sk-[a-zA-Z0-9_\-]{20,}"),
     re.compile(r"ghp_[a-zA-Z0-9]{20,}"),
@@ -254,6 +351,12 @@ def _row_to_observation(row) -> dict:
     item["evidence_refs"] = _parse_json(item.pop("evidence_refs_json", "[]"), [])
     item["entities"] = _parse_json(item.pop("entities_json", "[]"), [])
     item["metadata"] = _parse_json(item.pop("metadata_json", "{}"), {})
+    # The shadow embedding BLOB is an internal optimisation, not user-facing
+    # payload. Drop the raw bytes (they are not JSON-serialisable) but expose a
+    # cheap boolean so callers/tests can assert it was precomputed.
+    embedding_blob = item.pop("embedding", None)
+    item.pop("embedding_model", None)
+    item["has_embedding"] = bool(embedding_blob)
     return item
 
 
@@ -671,6 +774,11 @@ def upsert_memory_observation(observation: dict) -> dict:
         ),
     )
     conn.commit()
+    # Precompute the semantic embedding AFTER the write is durable. This is a
+    # shadow optimisation: it is guarded, never blocks the write, and skips
+    # entirely when the model is cold/unavailable (the bounded backfill fills
+    # those rows later). The summary/subject already passed redaction above.
+    _write_observation_embedding(uid, summary=clean_summary, subject=clean_subject)
     row = conn.execute("SELECT * FROM memory_observations WHERE observation_uid = ?", (uid,)).fetchone()
     result = _row_to_observation(row) if row else {"observation_uid": uid}
     result["ok"] = True
@@ -898,6 +1006,174 @@ def search_memory_observations_fts(
     return [_row_to_observation(row) for row in rows]
 
 
+def backfill_observation_embeddings(*, limit: int = 200) -> dict:
+    """Bounded, idempotent backfill of precomputed observation embeddings.
+
+    Only touches rows whose ``embedding IS NULL`` (idempotent — re-running after
+    a full pass is a no-op). Bounded by ``limit`` so it never scans the whole
+    table in one call; callers loop until ``remaining == 0``. Skips entirely
+    when the model is cold so it never triggers a download on a hot path.
+    """
+    conn = _core().get_db()
+    if not _table_exists(conn, "memory_observations"):
+        return {"ok": True, "updated": 0, "skipped": True, "reason": "memory_observations table unavailable"}
+    if not _embedding_columns_present(conn):
+        return {"ok": True, "updated": 0, "skipped": True, "reason": "embedding columns unavailable"}
+    if not _model_is_warm():
+        return {"ok": True, "updated": 0, "skipped": True, "reason": "embedding model cold"}
+
+    max_rows = max(1, min(int(limit or 200), 1000))
+    try:
+        rows = conn.execute(
+            """
+            SELECT id, observation_uid, subject, summary
+              FROM memory_observations
+             WHERE embedding IS NULL
+             ORDER BY created_at DESC, id DESC
+             LIMIT ?
+            """,
+            (max_rows,),
+        ).fetchall()
+    except Exception as exc:
+        return {"ok": False, "updated": 0, "error": _truncate(str(exc), 300)}
+
+    updated = 0
+    failed = 0
+    for row in rows:
+        item = dict(row)
+        text = " ".join(
+            part for part in [str(item.get("subject") or "").strip(), str(item.get("summary") or "").strip()] if part
+        ).strip()
+        blob, model_name = _embed_text_blob(text)
+        if blob is None:
+            failed += 1
+            continue
+        try:
+            conn.execute(
+                "UPDATE memory_observations SET embedding = ?, embedding_model = ? WHERE id = ?",
+                (blob, model_name, item.get("id")),
+            )
+            updated += 1
+        except Exception:
+            failed += 1
+    if updated:
+        conn.commit()
+
+    try:
+        remaining = int(
+            conn.execute("SELECT COUNT(*) FROM memory_observations WHERE embedding IS NULL").fetchone()[0]
+        )
+    except Exception:
+        remaining = 0
+    return {
+        "ok": failed == 0,
+        "updated": updated,
+        "failed": failed,
+        "seen": len(rows),
+        "remaining": remaining,
+    }
+
+
+def vector_scan_observations(
+    query_vector,
+    *,
+    limit: int = 50,
+    scan_limit: int = 400,
+    start_ts: float | None = None,
+    end_ts: float | None = None,
+    project_key: str = "",
+    min_score: float = 0.0,
+) -> list[dict]:
+    """Bounded cosine scan over precomputed observation embeddings.
+
+    ``scan_limit`` caps how many embedded rows are deserialised/compared so a
+    single query can never walk an unbounded table. Returns the top ``limit``
+    matches as ``{observation_uid, vector_score}`` dicts. Never raises — any
+    failure yields an empty list so the caller degrades to FTS.
+    """
+    if query_vector is None:
+        return []
+    conn = _core().get_db()
+    if not _table_exists(conn, "memory_observations") or not _embedding_columns_present(conn):
+        return []
+    try:
+        cog = _cognitive()
+    except Exception:
+        return []
+
+    clauses = ["embedding IS NOT NULL"]
+    params: list[Any] = []
+    if start_ts is not None:
+        clauses.append("created_at >= ?")
+        params.append(float(start_ts))
+    if end_ts is not None:
+        clauses.append("created_at < ?")
+        params.append(float(end_ts))
+    if project_key.strip():
+        clauses.append("project_key = ?")
+        params.append(project_key.strip())
+
+    bounded_scan = max(1, min(int(scan_limit or 400), 2000))
+    bounded_limit = max(1, min(int(limit or 50), 200))
+    try:
+        rows = conn.execute(
+            f"""
+            SELECT observation_uid, embedding
+              FROM memory_observations
+             WHERE {' AND '.join(clauses)}
+             ORDER BY salience DESC, created_at DESC, id DESC
+             LIMIT ?
+            """,
+            params + [bounded_scan],
+        ).fetchall()
+    except Exception:
+        return []
+
+    scored: list[dict] = []
+    for row in rows:
+        blob = row["embedding"]
+        if not blob:
+            continue
+        try:
+            candidate_vector = cog._blob_to_array(blob)
+            score = cog.cosine_similarity(query_vector, candidate_vector)
+        except Exception:
+            continue
+        if score <= min_score:
+            continue
+        scored.append({"observation_uid": row["observation_uid"], "vector_score": float(score)})
+
+    scored.sort(key=lambda item: item["vector_score"], reverse=True)
+    return scored[:bounded_limit]
+
+
+def get_memory_observations_by_uids(uids: list[str]) -> dict[str, dict]:
+    """Fetch observation rows by uid (bounded). Returns {uid: observation}.
+
+    Used by the retrieval fusion path to materialise semantic-only matches that
+    the lexical/FTS scan did not surface. Bounded to a small batch; never raises.
+    """
+    conn = _core().get_db()
+    if not _table_exists(conn, "memory_observations"):
+        return {}
+    clean = [str(uid).strip() for uid in (uids or []) if str(uid).strip()][:200]
+    if not clean:
+        return {}
+    placeholders = ",".join("?" for _ in clean)
+    try:
+        rows = conn.execute(
+            f"SELECT * FROM memory_observations WHERE observation_uid IN ({placeholders})",
+            clean,
+        ).fetchall()
+    except Exception:
+        return {}
+    result: dict[str, dict] = {}
+    for row in rows:
+        item = _row_to_observation(row)
+        result[item.get("observation_uid")] = item
+    return result
+
+
 def memory_observation_stats(days: int = 7) -> dict:
     conn = _core().get_db()
     if not _table_exists(conn, "memory_observations"):

package/src/db/_protocol.py

@@ -436,6 +436,41 @@ def close_protocol_task(
     return get_protocol_task(task_id) or {}
 
 
+def list_recent_closed_tasks(
+    *,
+    outcome: str = "done",
+    exclude_task_id: str = "",
+    limit: int = 200,
+    within_days: int = 0,
+) -> list[dict]:
+    """Return recently CLOSED protocol tasks for self-error detection.
+
+    Read-only. Ordered most-recent-first by ``closed_at``. The self-error
+    detector compares the just-closed task against these prior closures to
+    spot a later action that corrects something a previous task already
+    claimed as ``done``. Kept deliberately narrow (status filter + small
+    limit) so it never scans the whole history on every close.
+    """
+    conn = get_db()
+    clauses = ["status = ?", "closed_at IS NOT NULL"]
+    params: list[object] = [str(outcome).strip() or "done"]
+    if exclude_task_id:
+        clauses.append("task_id != ?")
+        params.append(exclude_task_id.strip())
+    if within_days and within_days > 0:
+        clauses.append("closed_at >= datetime('now', ?)")
+        params.append(f"-{int(within_days)} days")
+    where = " AND ".join(clauses)
+    rows = conn.execute(
+        f"""SELECT * FROM protocol_tasks
+            WHERE {where}
+            ORDER BY closed_at DESC
+            LIMIT ?""",
+        (*params, max(1, int(limit))),
+    ).fetchall()
+    return [dict(row) for row in rows]
+
+
 def create_protocol_debt(
     session_id: str,
     debt_type: str,

package/src/db/_schema.py

@@ -2119,6 +2119,81 @@ def _m64_local_context_live_dirs(conn):
     )
 
 
+def _m84_local_chunks_fts(conn):
+    """FTS5 keyword index over local_chunks for semantic-keyword local-file recall.
+
+    Additive + idempotent + reversible. Creates an FTS5 virtual table
+    ``local_chunks_fts`` keyed by ``local_chunks.rowid`` (local_chunks is NOT
+    WITHOUT ROWID, so its implicit rowid is stable and usable as the FTS key)
+    plus triggers that mirror local_chunks insert/delete/update. The FTS row
+    stores a denormalized snapshot of the owning asset's ``privacy_class`` /
+    ``status`` so privacy can be coarse-prefiltered INSIDE the FTS query without
+    a heavy join. The authoritative privacy check stays on the real
+    local_assets join + is_queryable_path in the retrieval path.
+
+    NOTE: no bulk INSERT...SELECT backfill here (that would scan/lock the live
+    19GB DB at schema time). The incremental, resumable backfill runs in the
+    cron tick (local_context/api.py:_backfill_fts_rows). No vector_blob column,
+    no VACUUM — explicitly out of scope.
+    """
+    try:
+        conn.execute(
+            """
+            CREATE VIRTUAL TABLE IF NOT EXISTS local_chunks_fts USING fts5(
+                text,
+                privacy_class UNINDEXED,
+                asset_status UNINDEXED,
+                tokenize='unicode61 remove_diacritics 2'
+            )
+            """
+        )
+    except Exception:
+        # Hosts without FTS5 support: fall back to a plain shadow table so the
+        # triggers below still succeed and the dual-read simply never flips on
+        # (FTS MATCH would raise OperationalError -> retrieval stays on LIKE).
+        conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS local_chunks_fts (
+                rowid INTEGER PRIMARY KEY,
+                text TEXT DEFAULT '',
+                privacy_class TEXT DEFAULT '',
+                asset_status TEXT DEFAULT ''
+            )
+            """
+        )
+    conn.executescript(
+        """
+        CREATE TRIGGER IF NOT EXISTS local_chunks_fts_insert
+        AFTER INSERT ON local_chunks BEGIN
+            INSERT INTO local_chunks_fts(rowid, text, privacy_class, asset_status)
+            VALUES (
+                new.rowid,
+                new.text,
+                COALESCE((SELECT privacy_class FROM local_assets WHERE asset_id=new.asset_id), 'normal'),
+                COALESCE((SELECT status FROM local_assets WHERE asset_id=new.asset_id), 'active')
+            );
+        END;
+
+        CREATE TRIGGER IF NOT EXISTS local_chunks_fts_delete
+        AFTER DELETE ON local_chunks BEGIN
+            DELETE FROM local_chunks_fts WHERE rowid = old.rowid;
+        END;
+
+        CREATE TRIGGER IF NOT EXISTS local_chunks_fts_update
+        AFTER UPDATE OF text, asset_id ON local_chunks BEGIN
+            DELETE FROM local_chunks_fts WHERE rowid = old.rowid;
+            INSERT INTO local_chunks_fts(rowid, text, privacy_class, asset_status)
+            VALUES (
+                new.rowid,
+                new.text,
+                COALESCE((SELECT privacy_class FROM local_assets WHERE asset_id=new.asset_id), 'normal'),
+                COALESCE((SELECT status FROM local_assets WHERE asset_id=new.asset_id), 'active')
+            );
+        END;
+        """
+    )
+
+
 def _backfill_diary_quality(conn):
     for table in ("session_diary", "diary_archive"):
         conn.execute(f"""
@@ -3112,6 +3187,134 @@ def _m82_confidence_checks(conn):
     )
 
 
+def _m83_observation_embeddings(conn):
+    """Shadow embedding columns for semantic retrieval over observations.
+
+    Additive + reversible: two nullable columns on memory_observations. The
+    embedding is precomputed at write time (after the row is committed) and by a
+    bounded backfill. memory_search fuses the precomputed vector with the
+    existing FTS/token score so paraphrases retrieve the right observation.
+
+    The query/latency path never triggers a cold model load — it embeds the
+    query once only when a model is already warm (or the deterministic offline
+    fallback is active) and otherwise degrades to today's FTS-only behaviour.
+    """
+    # Ensure the base table exists before ALTER: partial-DB upgrade paths (which
+    # mark earlier migrations applied without materializing every table) would
+    # otherwise hit "no such table: memory_observations". m60 is idempotent.
+    _m60_memory_observations(conn)
+    _migrate_add_column(conn, "memory_observations", "embedding", "BLOB")
+    _migrate_add_column(conn, "memory_observations", "embedding_model", "TEXT DEFAULT ''")
+    # Partial index so the bounded backfill can find un-embedded rows cheaply.
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_memory_obs_embedding_pending "
+        "ON memory_observations(id) WHERE embedding IS NULL"
+    )
+    conn.commit()
+
+
+def _m85_eval_runs(conn):
+    """Time series for the memory eval bench (recall@k / MRR / semantic gain).
+
+    One row per (run, metric) so the table is queryable as a series: the
+    before/after delta of an Ola 1 change is just two rows for the same metric
+    with different ``ola1_enabled``. ``model_warm`` distinguishes numbers from
+    the real embedding model (1) vs the deterministic offline fallback (0), so
+    a CI run (fallback, pipeline check) is never confused with a Deep Sleep run
+    (real model, semantic quality). Append-only and additive — re-running the
+    harness inserts new rows, never mutates old ones.
+
+    Mirrors the existing _m28_automation_runs / _m34_cortex_evaluations shape.
+    """
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS eval_runs (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            suite TEXT NOT NULL DEFAULT '',
+            case_set_id TEXT DEFAULT '',
+            case_set_version TEXT DEFAULT '',
+            fixture_hash TEXT DEFAULT '',
+            metric TEXT NOT NULL DEFAULT '',
+            value REAL NOT NULL DEFAULT 0.0,
+            ola1_enabled INTEGER NOT NULL DEFAULT 1,
+            model_warm INTEGER NOT NULL DEFAULT 0,
+            created_at TEXT DEFAULT (datetime('now'))
+        )
+        """
+    )
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_eval_runs_suite ON eval_runs(suite)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_eval_runs_metric ON eval_runs(suite, metric)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_eval_runs_created ON eval_runs(created_at)")
+    conn.commit()
+
+
+def _m86_resolution_cache(conn):
+    """Working-memory / resolution cache for the pre-answer router and repo maps.
+
+    Non-authoritative, like semantic_layers (_m76): the canonical facts still
+    live in diary/workflows/tasks/evidence/memory/learnings/change_log and in
+    the git repos themselves. This table only caches the FINAL organized
+    result of a retrieval (a ``PreAnswerRoute.to_dict()`` for ``kind='route'``)
+    or a lightweight repo snapshot (``kind='repo_map'``), keyed by a
+    deterministic ``cache_key`` (route_cache_key | ``repo:{project_key}``).
+
+    The anti-stale contract (Francisco's rule of gold) lives in the read path
+    (``resolution_cache.is_valid``): a HIT is only valid when ALL hold —
+    (1) now() < expires_at, (2) status=='fresh',
+    (3) source_fingerprint recomputed == stored, (4) change_watermark global ==
+    stored. The columns below exist to support exactly that check. The
+    ``instant`` tier (ttl=0) never writes here.
+    """
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS resolution_cache (
+            cache_key          TEXT PRIMARY KEY,
+            kind               TEXT NOT NULL DEFAULT 'route',
+            intent             TEXT NOT NULL DEFAULT '',
+            area               TEXT NOT NULL DEFAULT '',
+            sid                TEXT NOT NULL DEFAULT '',
+            result_json        TEXT NOT NULL,
+            source_fingerprint TEXT NOT NULL,
+            source_refs_json   TEXT NOT NULL DEFAULT '[]',
+            change_watermark   INTEGER NOT NULL DEFAULT 0,
+            status             TEXT NOT NULL DEFAULT 'fresh',
+            policy_version     TEXT NOT NULL DEFAULT '',
+            resolved_at        REAL NOT NULL,
+            expires_at         REAL NOT NULL DEFAULT 0,
+            hit_count          INTEGER NOT NULL DEFAULT 0,
+            CHECK(kind IN ('route', 'repo_map')),
+            CHECK(status IN ('fresh', 'stale', 'expired', 'invalid'))
+        )
+        """
+    )
+    _migrate_add_index(conn, "idx_resolution_cache_status_exp", "resolution_cache", "status, expires_at")
+    _migrate_add_index(conn, "idx_resolution_cache_kind", "resolution_cache", "kind, sid")
+    _migrate_add_index(conn, "idx_resolution_cache_fingerprint", "resolution_cache", "source_fingerprint")
+    conn.commit()
+
+
+def _m87_resolution_cache_content_snapshot(conn):
+    """Per-row content snapshot for the resolution cache's anti-stale check.
+
+    The fingerprint (``source_fingerprint``) is a single opaque digest over the
+    versions of the consulted refs. It proved the AGGREGATE changed but could
+    not by itself say WHICH ref moved, and — more importantly — it relied on
+    ``semantic_layers.source_version_for`` keyed by CANONICAL prefixes
+    (``followup:``), while the pre-answer router emits its own SOURCE-NAME refs
+    (``followups:``). Those source-name refs resolved to an ``unsupported``
+    namespace → empty version → an inert fingerprint, so a followup completed by
+    a plain UPDATE (no change_log write → watermark unmoved) was served stale.
+
+    This column stores an explicit ``{ref: version}`` map captured from the REAL
+    rows at write time (``resolution_cache.row_version_snapshot``). On read we
+    re-read those same rows by id and compare — the snapshot is now the PRIMARY
+    freshness guarantee; TTL and the global watermark remain cheap fast-fails.
+    Idempotent, append-only ALTER (non-destructive).
+    """
+    _migrate_add_column(conn, "resolution_cache", "content_snapshot_json", "TEXT NOT NULL DEFAULT '{}'")
+    conn.commit()
+
+
 MIGRATIONS = [
     (1, "learnings_columns", _m1_learnings_columns),
     (2, "followups_reasoning", _m2_followups_reasoning),
@@ -3195,6 +3398,10 @@ MIGRATIONS = [
     (80, "opportunity_orchestrator", _m80_opportunity_orchestrator),
     (81, "core_rules_product_metadata", _m81_core_rules_product_metadata),
     (82, "confidence_checks", _m82_confidence_checks),
+    (83, "observation_embeddings", _m83_observation_embeddings),
+    (85, "eval_runs", _m85_eval_runs),
+    (86, "resolution_cache", _m86_resolution_cache),
+    (87, "resolution_cache_content_snapshot", _m87_resolution_cache_content_snapshot),
 ]
 
 

package/src/hooks/auto_capture.py

@@ -288,37 +288,69 @@ def _content_hash(fact_type: str, content: str) -> str:
 # ---------------------------------------------------------------------------
 
 
-def _auto_learning_add(title: str, content: str) -> bool:
-    """Best-effort call to tools_learnings.handle_learning_add.
+def _get_auto_capture_logger():
+    """Lazy, guarded logger so capture failures are observable, never silent.
 
-    Returns True when the learning was stored, False otherwise. Failures
-    are silent so the hook itself never breaks the user's prompt flow.
+    Import must never raise (tmp/read-only homes in tests) — falls back to a
+    NullHandler. Mirrors the enforcement_engine logger pattern.
     """
+    import logging
+    log = logging.getLogger("nexo.auto_capture")
+    if log.handlers:
+        return log
     try:
-        import tools_learnings  # type: ignore
+        import paths
+        d = paths.logs_dir()
+        d.mkdir(parents=True, exist_ok=True)
+        handler = logging.FileHandler(d / "auto_capture.log")
+        handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
+        log.addHandler(handler)
+        log.setLevel(logging.INFO)
     except Exception:
-        return False
+        log.addHandler(logging.NullHandler())
+    return log
 
+
+def _auto_learning_add(title: str, content: str) -> bool:
+    """Persist a correction-derived learning via tools_learnings.handle_learning_add.
+
+    Failures are LOGGED (never silently swallowed) and retried once with a tiny
+    backoff so a transient DB-lock contention on the shared Brain self-heals
+    within the same prompt. Never raises and never breaks the prompt flow
+    (returns bool); all logging/retry stays inside the hook's exit-0 contract.
+    """
+    import time
+    log = _get_auto_capture_logger()
     try:
-        # The public symbol is handle_learning_add. A prior call to a
-        # non-existent tools_learnings.add_learning raised AttributeError that
-        # was swallowed below, so EVERY auto-captured correction silently
-        # failed to persist a learning (error-capture / never-repeat broken).
-        result = tools_learnings.handle_learning_add(
-            category="auto",
-            title=title,
-            content=content,
-            priority="medium",
-            reasoning="auto-captured from correction pattern in UserPromptSubmit/PostToolUse hook",
-        )
-        if isinstance(result, str):
-            return not result.strip().upper().startswith("ERROR")
-        if isinstance(result, dict):
-            return bool(result.get("ok") or result.get("id") or result.get("learning_id"))
-        return bool(result)
-    except Exception:
+        import tools_learnings  # type: ignore
+    except Exception as exc:
+        log.info("auto_capture: tools_learnings unavailable (%s)", exc.__class__.__name__)
         return False
 
+    for attempt in range(2):
+        try:
+            result = tools_learnings.handle_learning_add(
+                category="auto",
+                title=title,
+                content=content,
+                priority="medium",
+                reasoning="auto-captured from correction pattern in UserPromptSubmit/PostToolUse hook",
+            )
+            if isinstance(result, str):
+                ok = not result.strip().upper().startswith("ERROR")
+            elif isinstance(result, dict):
+                ok = bool(result.get("ok") or result.get("id") or result.get("learning_id"))
+            else:
+                ok = bool(result)
+            if ok:
+                return True
+            log.warning("auto_capture learning_add failed (attempt %d/2): %r", attempt + 1, result)
+        except Exception as exc:
+            log.warning("auto_capture learning_add error (attempt %d/2): %s", attempt + 1, exc)
+        if attempt == 0:
+            time.sleep(0.05)
+    return False
+
 
 # ---------------------------------------------------------------------------
 # Core processing
@@ -408,7 +440,11 @@ def process_conversation(messages: list[str]) -> dict:
                 learning_added = True
                 learnings_added += 1
 
-        _dedup_record(dedup_conn, content_hash, fact_type)
+        # A FAILED correction-learning must stay retryable on the next identical
+        # prompt, so only arm the 1h dedup gate for a correction once its learning
+        # actually persisted. Non-correction facts dedup as before.
+        if not (fact_type == "correction" and not learning_added):
+            _dedup_record(dedup_conn, content_hash, fact_type)
 
         extracted_details.append({
             "type": fact_type,