nexo-brain 7.20.21 → 7.20.23

package/src/local_context/db.py

@@ -0,0 +1,336 @@
+from __future__ import annotations
+
+import os
+import sqlite3
+import time
+from pathlib import Path
+from typing import Iterable
+from urllib.parse import quote
+
+import paths
+from db._schema import _m63_local_context_layer, _m64_local_context_live_dirs
+
+LOCAL_CONTEXT_DB_NAME = "local-context.db"
+MIGRATION_STATE_KEY = "local_context_db_migrated_from_main"
+MIGRATION_SKIPPED_KEY = "local_context_db_migration_skipped"
+MAIN_CLEANUP_STATE_KEY = "local_context_main_tables_drained"
+
+LOCAL_CONTEXT_TABLES: tuple[str, ...] = (
+    "local_index_roots",
+    "local_index_exclusions",
+    "local_index_jobs",
+    "local_index_checkpoints",
+    "local_index_state",
+    "local_index_errors",
+    "local_index_logs",
+    "local_assets",
+    "local_asset_versions",
+    "local_chunks",
+    "local_entities",
+    "local_relations",
+    "local_embeddings",
+    "local_context_queries",
+    "local_index_dirs",
+)
+
+_CONN: sqlite3.Connection | None = None
+_CONN_PATH: Path | None = None
+_READY = False
+_LAST_MIGRATION_ATTEMPT = 0.0
+_MIGRATION_RETRY_INTERVAL_SECONDS = 300.0
+
+
+def local_context_db_path() -> Path:
+    override = os.environ.get("NEXO_LOCAL_CONTEXT_DB", "").strip()
+    if override:
+        return Path(override).expanduser()
+    test_db = os.environ.get("NEXO_TEST_DB", "").strip()
+    if test_db:
+        return Path(test_db).expanduser().with_name("test_local_context.db")
+    return paths.memory_dir() / LOCAL_CONTEXT_DB_NAME
+
+
+def _main_db_path_for_migration() -> Path:
+    override = os.environ.get("NEXO_LOCAL_CONTEXT_MAIN_DB", "").strip()
+    if override:
+        return Path(override).expanduser()
+    test_db = os.environ.get("NEXO_TEST_DB", "").strip()
+    if test_db:
+        return Path(test_db).expanduser()
+    return paths.db_path()
+
+
+def _busy_timeout_ms() -> int:
+    raw = os.environ.get("NEXO_LOCAL_CONTEXT_DB_BUSY_TIMEOUT_MS", "15000")
+    try:
+        value = int(raw)
+    except Exception:
+        value = 15000
+    return max(1000, min(value, 60000))
+
+
+def _connect(db_path: Path) -> sqlite3.Connection:
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(db_path), timeout=max(_busy_timeout_ms() / 1000.0, 1.0), check_same_thread=False)
+    conn.row_factory = sqlite3.Row
+    conn.execute(f"PRAGMA busy_timeout={_busy_timeout_ms()}")
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA synchronous=NORMAL")
+    conn.execute("PRAGMA temp_store=MEMORY")
+    return conn
+
+
+def connect_local_context_db_readonly(*, timeout_ms: int = 1200) -> sqlite3.Connection:
+    db_path = local_context_db_path()
+    if not db_path.is_file():
+        raise FileNotFoundError(str(db_path))
+    timeout = max(float(timeout_ms) / 1000.0, 0.1)
+    uri_path = quote(db_path.resolve().as_posix(), safe="/:")
+    uri_params = "mode=ro"
+    if not db_path.with_name(db_path.name + "-wal").exists() and not db_path.with_name(db_path.name + "-shm").exists():
+        uri_params += "&immutable=1"
+    uri = f"file:{uri_path}?{uri_params}"
+    conn = sqlite3.connect(uri, uri=True, timeout=timeout, check_same_thread=False)
+    conn.row_factory = sqlite3.Row
+    conn.execute(f"PRAGMA busy_timeout={max(100, int(timeout_ms))}")
+    conn.execute("PRAGMA query_only=ON")
+    return conn
+
+
+def _ensure_schema(conn: sqlite3.Connection) -> None:
+    _m63_local_context_layer(conn)
+    _m64_local_context_live_dirs(conn)
+    conn.execute("PRAGMA user_version=64")
+    conn.commit()
+
+
+def _table_exists(conn: sqlite3.Connection, table: str, *, schema: str = "main") -> bool:
+    row = conn.execute(
+        f"SELECT 1 FROM {schema}.sqlite_master WHERE type='table' AND name=? LIMIT 1",
+        (table,),
+    ).fetchone()
+    return bool(row)
+
+
+def _table_count(conn: sqlite3.Connection, table: str, *, schema: str = "main") -> int:
+    if not _table_exists(conn, table, schema=schema):
+        return 0
+    row = conn.execute(f"SELECT COUNT(*) AS total FROM {schema}.{_quoted(table)}").fetchone()
+    return int(row["total"] or 0)
+
+
+def _state(conn: sqlite3.Connection, key: str) -> str:
+    row = conn.execute("SELECT value FROM local_index_state WHERE key=?", (key,)).fetchone()
+    return str(row["value"] or "") if row else ""
+
+
+def _set_state(conn: sqlite3.Connection, key: str, value: str) -> None:
+    conn.execute(
+        """
+        INSERT INTO local_index_state(key, value, updated_at)
+        VALUES (?, ?, strftime('%s','now'))
+        ON CONFLICT(key) DO UPDATE SET value=excluded.value, updated_at=excluded.updated_at
+        """,
+        (key, value),
+    )
+
+
+def _quoted(name: str) -> str:
+    return '"' + name.replace('"', '""') + '"'
+
+
+def _table_columns(conn: sqlite3.Connection, table: str, *, schema: str = "main") -> list[str]:
+    try:
+        rows = conn.execute(f"PRAGMA {schema}.table_info({_quoted(table)})").fetchall()
+    except sqlite3.OperationalError:
+        return []
+    return [str(row["name"]) for row in rows if row["name"]]
+
+
+def _primary_key_columns(conn: sqlite3.Connection, table: str, *, schema: str = "main") -> list[str]:
+    try:
+        rows = conn.execute(f"PRAGMA {schema}.table_info({_quoted(table)})").fetchall()
+    except sqlite3.OperationalError:
+        return []
+    ordered = sorted(
+        (
+            (int(row["pk"] or 0), str(row["name"]))
+            for row in rows
+            if int(row["pk"] or 0) > 0 and row["name"]
+        ),
+        key=lambda item: item[0],
+    )
+    return [name for _order, name in ordered]
+
+
+def _source_rows_missing_in_target(conn: sqlite3.Connection, table: str) -> int:
+    target_pk = _primary_key_columns(conn, table)
+    source_columns = set(_table_columns(conn, table, schema="source"))
+    pk_columns = [column for column in target_pk if column in source_columns]
+    if not pk_columns:
+        raise RuntimeError(f"cannot verify local context migration for {table}: missing primary key")
+    join_sql = " AND ".join(f"s.{_quoted(column)} = t.{_quoted(column)}" for column in pk_columns)
+    null_check = f"t.{_quoted(pk_columns[0])} IS NULL"
+    row = conn.execute(
+        f"SELECT COUNT(*) AS total "
+        f"FROM source.{_quoted(table)} s "
+        f"LEFT JOIN {_quoted(table)} t ON {join_sql} "
+        f"WHERE {null_check}"
+    ).fetchone()
+    return int(row["total"] or 0)
+
+
+def _copy_local_tables(conn: sqlite3.Connection, tables: Iterable[str]) -> dict[str, int]:
+    copied: dict[str, int] = {}
+    for table in tables:
+        if not _table_exists(conn, table, schema="source"):
+            continue
+        target_columns = _table_columns(conn, table)
+        source_columns = set(_table_columns(conn, table, schema="source"))
+        columns = [column for column in target_columns if column in source_columns]
+        if not columns:
+            continue
+        before = _table_count(conn, table)
+        column_sql = ", ".join(_quoted(column) for column in columns)
+        conn.execute(
+            f"INSERT OR IGNORE INTO {_quoted(table)} ({column_sql}) "
+            f"SELECT {column_sql} FROM source.{_quoted(table)}"
+        )
+        after = _table_count(conn, table)
+        copied[table] = max(0, after - before)
+    return copied
+
+
+def _source_table_counts(conn: sqlite3.Connection, tables: Iterable[str]) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for table in tables:
+        if _table_exists(conn, table, schema="source"):
+            counts[table] = _table_count(conn, table, schema="source")
+    return counts
+
+
+def _drain_source_local_tables_if_verified(
+    conn: sqlite3.Connection,
+    source_counts: dict[str, int],
+) -> dict[str, int]:
+    """Clear old local-memory rows from main DB after verifying the copy.
+
+    We keep the table schema in ``nexo.db`` for backward compatibility with
+    older binaries, but empty the rows after the new DB has at least the same
+    number of records per table. This prevents two sources of truth and stops
+    the main DB from carrying the huge local-memory payload.
+    """
+    drained: dict[str, int] = {}
+    if not source_counts:
+        return drained
+
+    for table, source_count in source_counts.items():
+        local_count = _table_count(conn, table)
+        missing = _source_rows_missing_in_target(conn, table)
+        if local_count < source_count or missing:
+            raise RuntimeError(
+                f"local context migration verification failed for {table}: "
+                f"local={local_count} source={source_count} missing={missing}"
+            )
+
+    for table, source_count in source_counts.items():
+        if source_count <= 0:
+            continue
+        conn.execute(f"DELETE FROM source.{_quoted(table)}")
+        drained[table] = source_count
+
+    if drained:
+        _set_state(conn, MAIN_CLEANUP_STATE_KEY, ",".join(sorted(drained)))
+    return drained
+
+
+def migrate_from_main_if_needed(conn: sqlite3.Connection) -> dict:
+    if os.environ.get("NEXO_LOCAL_CONTEXT_DISABLE_MAIN_MIGRATION", "").strip().lower() in {"1", "true", "yes"}:
+        return {"ok": True, "skipped": "disabled"}
+
+    main_db = _main_db_path_for_migration()
+    if not main_db.is_file():
+        _set_state(conn, MIGRATION_SKIPPED_KEY, "main_db_missing")
+        conn.commit()
+        return {"ok": True, "skipped": "main_db_missing"}
+
+    source = str(main_db).replace("'", "''")
+    try:
+        conn.execute("PRAGMA busy_timeout=1000")
+        conn.execute(f"ATTACH DATABASE '{source}' AS source")
+        if not _table_exists(conn, "local_assets", schema="source") and not _table_exists(conn, "local_index_roots", schema="source"):
+            _set_state(conn, MIGRATION_SKIPPED_KEY, "main_local_tables_missing")
+            if _table_count(conn, "local_assets") > 0 or _table_count(conn, "local_index_jobs") > 0:
+                _set_state(conn, MIGRATION_STATE_KEY, "already_has_local_data")
+            conn.commit()
+            return {"ok": True, "skipped": "main_local_tables_missing"}
+        source_counts = _source_table_counts(conn, LOCAL_CONTEXT_TABLES)
+        if not any(source_counts.values()):
+            _set_state(conn, MIGRATION_STATE_KEY, "main_local_tables_empty")
+            _set_state(conn, MAIN_CLEANUP_STATE_KEY, "empty")
+            conn.commit()
+            return {"ok": True, "skipped": "main_local_tables_empty"}
+        copied = _copy_local_tables(conn, LOCAL_CONTEXT_TABLES)
+        drained = _drain_source_local_tables_if_verified(conn, source_counts)
+        _set_state(conn, MIGRATION_STATE_KEY, str(main_db))
+        _set_state(conn, "local_context_db_migrated_rows", str(sum(copied.values())))
+        if drained:
+            _set_state(conn, "local_context_main_tables_drained_rows", str(sum(drained.values())))
+        conn.commit()
+        return {"ok": True, "migrated_from": str(main_db), "copied": copied, "drained": drained}
+    except sqlite3.OperationalError as exc:
+        message = str(exc)
+        _set_state(conn, MIGRATION_SKIPPED_KEY, message[:240])
+        _set_state(conn, "local_context_db_drain_pending", "main_db_busy_or_unavailable")
+        conn.commit()
+        return {"ok": True, "skipped": "main_db_busy_or_unavailable", "error": message, "retry_pending": True}
+    finally:
+        try:
+            conn.execute("DETACH DATABASE source")
+        except Exception:
+            pass
+        conn.execute(f"PRAGMA busy_timeout={_busy_timeout_ms()}")
+
+
+def ensure_local_context_db() -> None:
+    global _CONN, _CONN_PATH, _READY, _LAST_MIGRATION_ATTEMPT
+    db_path = local_context_db_path()
+    if _CONN is not None and _CONN_PATH != db_path:
+        close_local_context_db()
+    if _CONN is None:
+        _CONN = _connect(db_path)
+        _CONN_PATH = db_path
+    now = time.monotonic()
+    if _READY:
+        if now - _LAST_MIGRATION_ATTEMPT >= _MIGRATION_RETRY_INTERVAL_SECONDS:
+            _LAST_MIGRATION_ATTEMPT = now
+            try:
+                migrate_from_main_if_needed(_CONN)
+            except Exception:
+                # Sidecar data is still usable; cleanup from the old main DB is
+                # best-effort and will retry on later service cycles.
+                pass
+        return
+    _ensure_schema(_CONN)
+    _LAST_MIGRATION_ATTEMPT = now
+    migration = migrate_from_main_if_needed(_CONN)
+    _READY = True
+
+
+def get_local_context_db() -> sqlite3.Connection:
+    ensure_local_context_db()
+    assert _CONN is not None
+    return _CONN
+
+
+def close_local_context_db() -> None:
+    global _CONN, _CONN_PATH, _READY, _LAST_MIGRATION_ATTEMPT
+    if _CONN is not None:
+        try:
+            _CONN.close()
+        except Exception:
+            pass
+    _CONN = None
+    _CONN_PATH = None
+    _READY = False
+    _LAST_MIGRATION_ATTEMPT = 0.0

package/src/local_context/logging.py

@@ -1,12 +1,11 @@
 from __future__ import annotations
 
-from db import get_db
-
+from .db import get_local_context_db
 from .util import json_dumps, now
 
 
 def log_event(level: str, event: str, message: str, **metadata) -> None:
-    conn = get_db()
+    conn = get_local_context_db()
     conn.execute(
         """
         INSERT INTO local_index_logs(created_at, level, event, message, metadata_json)
@@ -18,7 +17,7 @@ def log_event(level: str, event: str, message: str, **metadata) -> None:
 
 
 def tail(limit: int = 100) -> list[dict]:
-    conn = get_db()
+    conn = get_local_context_db()
     rows = conn.execute(
         """
         SELECT created_at, level, event, message, metadata_json

package/src/mcp_required_tools.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+"""Required MCP tool contract shared by Brain and Desktop probes.
+
+These tools are the minimum bootstrap surface NEXO Desktop needs before a
+conversation can be considered healthy. Dynamic plugin loading may still add
+more tools, but these names must always be present.
+"""
+
+BOOTSTRAP_REQUIRED_MCP_TOOLS: tuple[str, ...] = (
+    "nexo_startup",
+    "nexo_heartbeat",
+    "nexo_session_diary_read",
+    "nexo_reminders",
+    "nexo_smart_startup",
+    "nexo_task_open",
+    "nexo_task_close",
+    "nexo_task_acknowledge_guard",
+    "nexo_guard_check",
+    "nexo_learning_add",
+    "nexo_confidence_check",
+    "nexo_followup_create",
+    "nexo_protocol_debt_resolve",
+    "nexo_card_match",
+    "nexo_skill_match",
+)
+
+
+def missing_required_tools(tool_names: list[str] | tuple[str, ...] | set[str]) -> list[str]:
+    available = {str(name) for name in tool_names}
+    return [name for name in BOOTSTRAP_REQUIRED_MCP_TOOLS if name not in available]

package/src/plugins/episodic_memory.py

@@ -10,6 +10,7 @@ from db import (
     log_change, search_changes, update_change_commit,
     recall, get_db, set_linked_outcomes_met,
 )
+from interactive_db import interactive_db_timeout, is_db_busy
 
 REPO_ROOT = Path(__file__).resolve().parents[2]
 _REPO_ABS_PREFIX = str(REPO_ROOT) + "/"
@@ -377,6 +378,23 @@ def handle_session_diary_read(session_id: str = '', last_n: int = 3, last_day: b
         brief: If true, returns ONLY the last diary entry with summary + mental_state + context_next.
                Use this at startup for fast context loading (~1K chars instead of full dump).
     """
+    with interactive_db_timeout():
+        try:
+            return _handle_session_diary_read_inner(session_id, last_n, last_day, domain, brief)
+        except Exception as exc:
+            if is_db_busy(exc):
+                return (
+                    "SESSION DIARY DEGRADED:\n"
+                    "  local brain database is busy; continue with the user request and retry shortly."
+                )
+            return (
+                "SESSION DIARY DEGRADED:\n"
+                f"  skipped ({type(exc).__name__}); continue with the user request and retry shortly."
+            )
+
+
+def _handle_session_diary_read_inner(session_id: str = '', last_n: int = 3, last_day: bool = False,
+                                     domain: str = '', brief: bool = False) -> str:
     if brief:
         # Fast path: only the most recent diary entry, compact format
         results = read_session_diary(session_id, 1, last_day=False, domain=domain)

package/src/plugins/recover.py

@@ -35,6 +35,7 @@ from db_guard import (
     CRITICAL_TABLES,
     EMPTY_DB_SIZE_BYTES,
     HOURLY_BACKUP_GLOB,
+    LOCAL_CONTEXT_TABLES,
     MIN_REFERENCE_ROWS,
     PROTECTED_TABLES,
     WIPE_THRESHOLD_PCT,
@@ -48,6 +49,8 @@ from db_guard import (
     validate_backup_matches_source,
 )
 
+RECOVERY_TABLES = PROTECTED_TABLES + LOCAL_CONTEXT_TABLES
+
 # Path resolution moved to lazy helpers (AUDITOR-V700-PASS2 §11, B10 item 3)
 # to keep monkeypatched NEXO_HOME / paths.* fixtures honoured. PEP 562
 # ``__getattr__`` below preserves the legacy constant names for any caller
@@ -139,7 +142,7 @@ def _describe_backup(path: Path, kind: str) -> dict:
     counts: dict[str, int | None] = {}
     critical_rows = 0
     if size > EMPTY_DB_SIZE_BYTES:
-        counts = db_row_counts(path, PROTECTED_TABLES)
+        counts = db_row_counts(path, RECOVERY_TABLES)
         critical_rows = sum(v for v in counts.values() if isinstance(v, int))
     return {
         "path": str(path),
@@ -240,7 +243,7 @@ def recover(
     result["source"] = str(chosen)
     result["steps"].append(f"chose source: {chosen}")
 
-    source_counts = db_row_counts(chosen, PROTECTED_TABLES)
+    source_counts = db_row_counts(chosen, RECOVERY_TABLES)
     result["source_row_counts"] = {k: v for k, v in source_counts.items() if v is not None}
     source_total = sum(v for v in source_counts.values() if isinstance(v, int))
     if source_total < MIN_REFERENCE_ROWS:
@@ -317,7 +320,7 @@ def recover(
         return result
     result["steps"].append(f"restored {chosen.name} -> {target_path}")
 
-    valid, valid_err = validate_backup_matches_source(chosen, target_path, PROTECTED_TABLES)
+    valid, valid_err = validate_backup_matches_source(chosen, target_path, RECOVERY_TABLES)
     if not valid:
         result["errors"].append(f"post-restore validation failed: {valid_err}")
         if stopped_launchagents:
@@ -325,7 +328,7 @@ def recover(
         return result
     result["steps"].append("validated post-restore row counts")
 
-    final_counts = db_row_counts(target_path, PROTECTED_TABLES)
+    final_counts = db_row_counts(target_path, RECOVERY_TABLES)
     result["final_row_counts"] = {k: v for k, v in final_counts.items() if v is not None}
     if stopped_launchagents:
         result["resume"] = resume_nexo_launchagents(stopped_launchagents)

package/src/plugins/skills.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import json
 
+from interactive_db import interactive_db_timeout, is_db_busy
 from db import (
     create_skill,
     delete_skill,
@@ -85,12 +86,22 @@ def handle_skill_create(
 
 
 def handle_skill_match(task: str, level: str = "") -> str:
-    sync_skills()
-    matches = match_skills(task, level=level)
+    sync_warning = ""
+    with interactive_db_timeout():
+        try:
+            sync_skills()
+        except Exception as exc:
+            if is_db_busy(exc):
+                sync_warning = "SKILL SYNC DEGRADED: local brain database is busy; using existing skill index."
+            else:
+                raise
+        matches = match_skills(task, level=level)
     if not matches:
-        return f"No skills found for: '{task}'"
+        return f"{sync_warning + chr(10) if sync_warning else ''}No skills found for: '{task}'"
 
     lines = [f"SKILLS MATCHED ({len(matches)}) for '{task}':"]
+    if sync_warning:
+        lines.insert(0, sync_warning)
     for match in matches:
         match_method = match.pop("_match", "unknown")
         lines.append(

package/src/plugins/update.py

@@ -39,6 +39,7 @@ try:
     from db_guard import (
         CRITICAL_TABLES,
         HOURLY_BACKUP_MAX_AGE,
+        LOCAL_CONTEXT_TABLES,
         MIN_REFERENCE_ROWS,
         PROTECTED_TABLES,
         WIPE_THRESHOLD_PCT,
@@ -56,6 +57,7 @@ except Exception as exc:  # pragma: no cover - exercised only during stale insta
     _DB_GUARD_AVAILABLE = False
     _DB_GUARD_IMPORT_ERROR = str(exc)
     CRITICAL_TABLES = ()
+    LOCAL_CONTEXT_TABLES = ()
     PROTECTED_TABLES = ()
     HOURLY_BACKUP_MAX_AGE = 48 * 3600
     MIN_REFERENCE_ROWS = 50
@@ -98,6 +100,14 @@ REQUIRED_LOCAL_MEMORY_TABLES: tuple[str, ...] = (
     "local_index_dirs",
 )
 
+
+def _backup_validation_tables(db_file: Path) -> tuple[str, ...]:
+    if db_file.name == "nexo.db":
+        return tuple(PROTECTED_TABLES)
+    if db_file.name == "local-context.db":
+        return tuple(LOCAL_CONTEXT_TABLES)
+    return ()
+
 # Code root is the parent of plugins/:
 # - source checkout: <repo>/src
 # - packaged runtime: <NEXO_HOME>
@@ -404,11 +414,11 @@ def _db_guard_integrity_error() -> str | None:
             f"  import error: {_DB_GUARD_IMPORT_ERROR or 'unknown'}\n"
             "Restart Desktop so it can sync the bundled Brain guard, then retry the update."
         )
-    protected = set(PROTECTED_TABLES)
-    missing = [table for table in REQUIRED_LOCAL_MEMORY_TABLES if table not in protected]
+    local_tables = set(LOCAL_CONTEXT_TABLES)
+    missing = [table for table in REQUIRED_LOCAL_MEMORY_TABLES if table not in local_tables]
     if missing:
         return (
-            "DB protection module is stale; refusing to update because local memory tables are not protected.\n"
+            "DB protection module is stale; refusing to update because local memory tables are not known.\n"
             f"  missing tables: {', '.join(missing)}\n"
             "Restart Desktop so it can sync the bundled Brain guard, then retry the update."
         )
@@ -475,8 +485,14 @@ def _row_count_regression(pre: dict[str, int | None], post: dict[str, int | None
     drop >= WIPE_THRESHOLD_PCT across CRITICAL_TABLES, is treated as a wipe.
     """
     regressions: list[str] = []
-    pre_total = sum(v for v in pre.values() if isinstance(v, int))
-    post_total = sum(v for v in post.values() if isinstance(v, int))
+    pre_total = sum(
+        pre.get(table) for table in PROTECTED_TABLES
+        if isinstance(pre.get(table), int)
+    )
+    post_total = sum(
+        post.get(table) for table in PROTECTED_TABLES
+        if isinstance(post.get(table), int)
+    )
     for table in PROTECTED_TABLES:
         pre_v = pre.get(table)
         post_v = post.get(table)
@@ -505,6 +521,9 @@ def _backup_databases() -> tuple[str, str | None]:
     backup_dir = BACKUP_BASE / f"pre-update-{timestamp}"
 
     db_files = list(DATA_DIR.glob("*.db")) if DATA_DIR.is_dir() else []
+    local_context_db = paths.memory_dir() / "local-context.db"
+    if local_context_db.is_file():
+        db_files.append(local_context_db)
     # Also check NEXO_HOME root for legacy db location
     db_files += [f for f in NEXO_HOME.glob("*.db") if f.is_file()]
     # And check src/ dir for nexo.db (dev mode)
@@ -522,10 +541,9 @@ def _backup_databases() -> tuple[str, str | None]:
         ok, err = safe_sqlite_backup(db_file, dest)
         if not ok:
             return str(backup_dir), f"Failed to backup {db_file.name}: {err}"
-        # Only validate row counts for the primary DB — the other sidecar DBs
-        # (cognitive.db, cron-runs.db) do not share CRITICAL_TABLES.
-        if db_file.name == "nexo.db":
-            valid, valid_err = validate_backup_matches_source(db_file, dest, PROTECTED_TABLES)
+        tables = _backup_validation_tables(db_file)
+        if tables:
+            valid, valid_err = validate_backup_matches_source(db_file, dest, tables)
             if not valid:
                 return str(backup_dir), (
                     f"Backup of {db_file.name} did not preserve critical tables: {valid_err}"
@@ -544,12 +562,19 @@ def _restore_databases(backup_dir: str):
     if not bdir.is_dir():
         return
     for db_backup in bdir.glob("*.db"):
-        # Try to find original location
-        for candidate in [DATA_DIR / db_backup.name, NEXO_HOME / db_backup.name, SRC_DIR / db_backup.name]:
-            if candidate.is_file():
+        # Try to find original location. local-context.db lives outside the
+        # operational DB directory and must be restored even if the target was
+        # missing after a failed update.
+        if db_backup.name == "local-context.db":
+            candidates = [paths.memory_dir() / db_backup.name]
+        else:
+            candidates = [DATA_DIR / db_backup.name, NEXO_HOME / db_backup.name, SRC_DIR / db_backup.name]
+        for candidate in candidates:
+            if candidate.is_file() or db_backup.name == "local-context.db":
                 src_conn = None
                 dst_conn = None
                 try:
+                    candidate.parent.mkdir(parents=True, exist_ok=True)
                     src_conn = sqlite3.connect(str(db_backup))
                     dst_conn = sqlite3.connect(str(candidate))
                     src_conn.backup(dst_conn)