nexo-brain 7.20.21 → 7.20.23

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.20.19",
+  "version": "7.20.23",
   "description": "Local cognitive runtime for Claude Code \u2014 persistent memory, overnight learning, doctor diagnostics, personal scripts, recovery-aware jobs, startup preflight, and optional dashboard/power helper.",
   "author": {
     "name": "NEXO Brain",

package/README.md

@@ -18,7 +18,9 @@
 
 [Watch the overview video](https://nexo-brain.com/watch/) · [Watch on YouTube](https://www.youtube.com/watch?v=i2lkGhKyVqI) · [Open the infographic](https://nexo-brain.com/assets/nexo-brain-infographic-v5.png)
 
-Version `7.20.19` is the current packaged-runtime line. Patch release over v7.20.18 — Local Memory status and long first-indexing runs stay stable during Desktop-managed updates; stale macOS Full Disk Access denials are cleared after a live access probe succeeds.
+Version `7.20.23` is the current packaged-runtime line. Patch release over v7.20.22 — Local Memory status reads the real split sidecar database read-only, reports retryable keyed failures without false zeroes, and keeps Desktop Spanish/English copy localized.
+
+Previously in `7.20.22`: patch release over v7.20.19 — Local Memory moved out of the main Brain database, MCP readiness verifies required tools, and split-aware Desktop backups validate the main DB and Local Memory sidecar separately.
 
 Previously in `7.20.18`: patch release over v7.20.17 — Desktop-managed setup now preserves a completed onboarding flag when Brain is later invoked with the non-interactive `--skip` bootstrap path.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.20.21",
+  "version": "7.20.23",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO Brain — Shared brain for AI agents. Persistent memory, semantic RAG, natural forgetting, metacognitive guard, trust scoring, 150+ MCP tools. Works with Claude Code, Codex, Claude Desktop & any MCP client. 100% local, free.",
   "homepage": "https://nexo-brain.com",

package/src/auto_update.py

@@ -89,6 +89,7 @@ LOCAL_CONTEXT_BACKUP_TABLES = (
     "local_index_checkpoints",
     "local_index_state",
     "local_index_errors",
+    "local_index_logs",
     "local_assets",
     "local_asset_versions",
     "local_chunks",
@@ -99,6 +100,14 @@ LOCAL_CONTEXT_BACKUP_TABLES = (
     "local_index_dirs",
 )
 PROTECTED_BACKUP_TABLES = CRITICAL_BACKUP_TABLES + LOCAL_CONTEXT_BACKUP_TABLES
+
+
+def _backup_validation_tables(db_file: Path) -> tuple[str, ...]:
+    if db_file.name == "local-context.db":
+        return LOCAL_CONTEXT_BACKUP_TABLES
+    return PROTECTED_BACKUP_TABLES
+
+
 CLASSIFIER_INSTALL_TIMEOUT_SECONDS = 1800
 CLASSIFIER_INSTALL_JOIN_SECONDS = 1500
 CLASSIFIER_INSTALL_LOG = paths.logs_dir() / "classifier-install.log"
@@ -338,7 +347,7 @@ def _validate_db_backup(source_db: Path, backup_db: Path) -> dict:
         report["errors"].append(f"backup db missing: {backup_db}")
         return report
 
-    for table in PROTECTED_BACKUP_TABLES:
+    for table in _backup_validation_tables(source_db):
         source_count = _critical_table_count(source_db, table)
         backup_count = _critical_table_count(backup_db, table)
         report["source_counts"][table] = source_count
@@ -373,18 +382,29 @@ def _create_validated_db_backup() -> tuple[str | None, dict | None]:
     if not backup_dir:
         return None, None
 
-    source_db = _find_primary_db_path()
-    if source_db is None:
+    source_dbs: list[Path] = []
+    primary_db = _find_primary_db_path()
+    if primary_db is not None:
+        source_dbs.append(primary_db)
+    local_context_db = paths.memory_dir() / "local-context.db"
+    if local_context_db.is_file():
+        source_dbs.append(local_context_db)
+    if not source_dbs:
         return backup_dir, None
 
-    report = _validate_db_backup(source_db, Path(backup_dir) / source_db.name)
-    if not report["ok"]:
-        details = ", ".join(
-            f"{item['table']} {item['source']}->{item['backup']}"
-            for item in report["regressions"]
-        ) or "; ".join(report["errors"])
-        _log(f"DB backup validation failed: {details}")
-    return backup_dir, report
+    reports = []
+    ok = True
+    for source_db in source_dbs:
+        report = _validate_db_backup(source_db, Path(backup_dir) / source_db.name)
+        reports.append(report)
+        if not report["ok"]:
+            ok = False
+            details = ", ".join(
+                f"{item['table']} {item['source']}->{item['backup']}"
+                for item in report["regressions"]
+            ) or "; ".join(report["errors"])
+            _log(f"DB backup validation failed ({source_db.name}): {details}")
+    return backup_dir, {"ok": ok, "reports": reports}
 
 
 def _read_last_check() -> dict:
@@ -1425,6 +1445,7 @@ def _self_heal_if_wiped() -> dict | None:
         from db_guard import (
             CRITICAL_TABLES,
             HOURLY_BACKUP_MAX_AGE,
+            LOCAL_CONTEXT_TABLES,
             MIN_REFERENCE_ROWS,
             PROTECTED_TABLES,
             db_looks_wiped,
@@ -1445,14 +1466,15 @@ def _self_heal_if_wiped() -> dict | None:
         return None
     if not db_looks_wiped(primary, PROTECTED_TABLES):
         return None
+    recovery_tables = PROTECTED_TABLES + LOCAL_CONTEXT_TABLES
     reference = find_best_hourly_backup(
         paths.backups_dir(),
         max_age_seconds=HOURLY_BACKUP_MAX_AGE,
-        tables=PROTECTED_TABLES,
+        tables=recovery_tables,
     ) or find_latest_hourly_backup(
         paths.backups_dir(),
         max_age_seconds=HOURLY_BACKUP_MAX_AGE,
-        tables=PROTECTED_TABLES,
+        tables=recovery_tables,
     )
     if reference is None:
         _log("self-heal: nexo.db looks wiped but no usable hourly backup found — skipping.")
@@ -1461,7 +1483,7 @@ def _self_heal_if_wiped() -> dict | None:
             "reason": "no_usable_hourly_backup",
             "primary_db": str(primary),
         }
-    ref_counts = db_row_counts(reference, PROTECTED_TABLES)
+    ref_counts = db_row_counts(reference, recovery_tables)
     ref_total = sum(v for v in ref_counts.values() if isinstance(v, int))
     if ref_total < MIN_REFERENCE_ROWS:
         _log(f"self-heal: reference backup {reference.name} has {ref_total} rows, below floor {MIN_REFERENCE_ROWS}")
@@ -1550,7 +1572,7 @@ def _self_heal_if_wiped() -> dict | None:
             "quiesce": quiesce_report,
             "resume": resume_report,
         }
-    valid, valid_err = validate_backup_matches_source(reference, primary, PROTECTED_TABLES)
+    valid, valid_err = validate_backup_matches_source(reference, primary, recovery_tables)
     if not valid:
         _log(f"self-heal: post-restore validation failed: {valid_err}")
         resume_report = _resume_quiesced()
@@ -1564,7 +1586,7 @@ def _self_heal_if_wiped() -> dict | None:
             "resume": resume_report,
         }
 
-    final_counts = db_row_counts(primary, PROTECTED_TABLES)
+    final_counts = db_row_counts(primary, recovery_tables)
     final_total = sum(v for v in final_counts.values() if isinstance(v, int))
     _log(f"self-heal: restored {final_total} critical rows from {reference.name}.")
     resume_report = _resume_quiesced()
@@ -2047,6 +2069,9 @@ def _backup_dbs() -> str | None:
     backup_dir = paths.backups_dir() / f"pre-autoupdate-{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)
     db_files += [f for f in NEXO_HOME.glob("*.db") if f.is_file()]
     src_db = SRC_DIR / "nexo.db"
     if src_db.is_file() and src_db not in db_files:
@@ -2090,11 +2115,16 @@ def _restore_dbs(backup_dir: str):
     if not bdir.is_dir():
         return
     for db_backup in bdir.glob("*.db"):
-        for candidate in [DATA_DIR / db_backup.name, NEXO_HOME / db_backup.name, SRC_DIR / db_backup.name]:
-            if candidate.is_file():
+        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)
@@ -3958,7 +3988,7 @@ def _auto_update_check_locked() -> dict:
 
     # Backfill runtime CLI modules for existing installs
     try:
-        for fname in ("cli.py", "script_registry.py", "skills_runtime.py", "cron_recovery.py", "client_preferences.py", "claude_cli.py", "agent_runner.py", "bootstrap_docs.py"):
+        for fname in ("cli.py", "script_registry.py", "skills_runtime.py", "cron_recovery.py", "client_preferences.py", "claude_cli.py", "agent_runner.py", "bootstrap_docs.py", "mcp_required_tools.py"):
             src_file = SRC_DIR / fname
             dest_file = NEXO_HOME / fname
             if src_file.is_file() and (not dest_file.exists() or src_file.stat().st_mtime > dest_file.stat().st_mtime):

package/src/cli.py

@@ -52,6 +52,17 @@ from pathlib import Path
 
 from runtime_home import export_resolved_nexo_home
 from runtime_versioning import build_mcp_status, clear_restart_required_marker
+try:
+    from mcp_required_tools import BOOTSTRAP_REQUIRED_MCP_TOOLS, missing_required_tools
+except ModuleNotFoundError as exc:
+    if getattr(exc, "name", "") != "mcp_required_tools":
+        raise
+    # Older installed runtimes can be missing modules added after their CLI was
+    # copied. Keep `nexo update` bootable so the sync can repair the runtime.
+    BOOTSTRAP_REQUIRED_MCP_TOOLS: tuple[str, ...] = ()
+
+    def missing_required_tools(_tool_names):
+        return []
 
 NEXO_HOME = export_resolved_nexo_home()
 NEXO_CODE = Path(os.environ.get("NEXO_CODE", str(Path(__file__).resolve().parent)))
@@ -200,8 +211,11 @@ def _mcp_probe(args) -> int:
     server_path = NEXO_CODE / "server.py"
     env = os.environ.copy()
     env["NEXO_MCP_PROBE"] = "1"
-    env.setdefault("NEXO_MCP_PLUGIN_MODE", getattr(args, "plugin_mode", None) or "none")
-    env.setdefault("NEXO_MCP_RUN_STARTUP_PREFLIGHT", "0")
+    # Probe must be deterministic: inherited env from an older Desktop/runtime
+    # must not force plugin loading or startup preflight and turn this into a
+    # slow/false-negative health check.
+    env["NEXO_MCP_PLUGIN_MODE"] = getattr(args, "plugin_mode", None) or "none"
+    env["NEXO_MCP_RUN_STARTUP_PREFLIGHT"] = "0"
     client = str(getattr(args, "client", "") or "").strip()
     if client:
         env["NEXO_MCP_CLIENT"] = client
@@ -256,8 +270,8 @@ def _mcp_probe(args) -> int:
             for tool in tools
             if isinstance(tool, dict) and tool.get("name")
         ]
-        required = ["nexo_startup", "nexo_heartbeat", "nexo_task_open", "nexo_guard_check"]
-        missing = [name for name in required if name not in tool_names]
+        required = list(BOOTSTRAP_REQUIRED_MCP_TOOLS)
+        missing = missing_required_tools(tool_names)
         ok = not missing and len(tool_names) > 0
         payload = {
             "ok": ok,
@@ -265,6 +279,8 @@ def _mcp_probe(args) -> int:
             "probe_ok": ok,
             "tools_available": len(tool_names) > 0,
             "tool_count": len(tool_names),
+            "required_tools": required,
+            "required_tool_count": len(required),
             "required_tools_present": not missing,
             "missing_required_tools": missing,
             "client": client,
@@ -3383,7 +3399,7 @@ def main():
 
     local_context_query_p = local_context_sub.add_parser("query", help="Query local memory evidence")
     local_context_query_p.add_argument("query", help="Question or search phrase")
-    local_context_query_p.add_argument("--intent", default="answer", help="Intent label stored with the query audit row")
+    local_context_query_p.add_argument("--intent", default="answer", help="Intent label included with the query result")
     local_context_query_p.add_argument("--limit", type=int, default=12, help="Maximum evidence rows")
     local_context_query_p.add_argument("--current-context", default="", help="Optional current conversation/task context")
     local_context_query_p.add_argument("--mode", choices=["compact", "full"], default="compact", help="Payload shape. Compact is safe for chat clients; full is for debugging.")

package/src/db_guard.py

@@ -75,6 +75,7 @@ LOCAL_CONTEXT_TABLES: tuple[str, ...] = (
     "local_index_checkpoints",
     "local_index_state",
     "local_index_errors",
+    "local_index_logs",
     "local_assets",
     "local_asset_versions",
     "local_chunks",
@@ -85,10 +86,16 @@ LOCAL_CONTEXT_TABLES: tuple[str, ...] = (
     "local_index_dirs",
 )
 
-# Everything an updater/recovery path must preserve. Keep CRITICAL_TABLES as a
-# public legacy name for older callers, but new guards should use
-# PROTECTED_TABLES so local indexing cannot regress unnoticed.
-PROTECTED_TABLES: tuple[str, ...] = CRITICAL_TABLES + LOCAL_CONTEXT_TABLES
+# Tables protected inside the operational Brain DB. Keep this core-only:
+# callers that need local memory checks must request LOCAL_CONTEXT_TABLES or
+# RECOVERY_TABLES explicitly so normal Brain wipe detection is not skewed by
+# split local-memory databases.
+PROTECTED_TABLES: tuple[str, ...] = CRITICAL_TABLES
+
+# Recovery must still inspect legacy backups that carried local memory tables
+# inside nexo.db. This wider set is safe for row counts and restore validation,
+# but should not replace PROTECTED_TABLES in core wipe-diff callers.
+RECOVERY_TABLES: tuple[str, ...] = CRITICAL_TABLES + LOCAL_CONTEXT_TABLES
 
 # A reference backup must contain at least this many rows (summed across
 # CRITICAL_TABLES) before we will treat it as "proof the user has real data".
@@ -209,7 +216,7 @@ def _table_count(conn: sqlite3.Connection, table: str) -> int | None:
     return int(result[0]) if result is not None else 0
 
 
-def db_row_counts(path: str | Path, tables: tuple[str, ...] = PROTECTED_TABLES) -> dict[str, int | None]:
+def db_row_counts(path: str | Path, tables: tuple[str, ...] = RECOVERY_TABLES) -> dict[str, int | None]:
     """Return {table: count} for a SQLite DB. Missing DB / missing tables map to None."""
     p = Path(path)
     counts: dict[str, int | None] = {t: None for t in tables}
@@ -251,11 +258,22 @@ def db_looks_wiped(
         size = p.stat().st_size
     except OSError:
         return False
+    counts = db_row_counts(p, tables)
     if size <= EMPTY_DB_SIZE_BYTES:
         # Small but not necessarily wiped — confirm via row counts.
-        counts = db_row_counts(p, tables)
-        return _all_tables_empty_or_missing(counts)
-    counts = db_row_counts(p, tables)
+        return _counts_look_wiped(counts)
+    return _counts_look_wiped(counts)
+
+
+def _counts_look_wiped(counts: dict[str, int | None]) -> bool:
+    """Treat Brain table loss as a wipe even if legacy local tables remain."""
+    critical_present = {
+        table: counts.get(table)
+        for table in CRITICAL_TABLES
+        if counts.get(table) is not None
+    }
+    if critical_present:
+        return _all_tables_empty_or_missing(critical_present)
     return _all_tables_empty_or_missing(counts)
 
 
@@ -478,7 +496,7 @@ def _backup_drift_is_safe(source_count: int, backup_count: int) -> bool:
 
 
 def _quote_identifier(identifier: str) -> str:
-    if identifier not in PROTECTED_TABLES:
+    if identifier not in PROTECTED_TABLES and identifier not in LOCAL_CONTEXT_TABLES:
         raise ValueError(f"refusing unsafe table identifier: {identifier!r}")
     return '"' + identifier.replace('"', '""') + '"'
 

package/src/doctor/providers/boot.py

@@ -44,6 +44,7 @@ def check_db_integrity(fix: bool = False) -> DoctorCheck:
     from db_guard import (
         CRITICAL_TABLES,
         EMPTY_DB_SIZE_BYTES,
+        LOCAL_CONTEXT_TABLES,
         MIN_REFERENCE_ROWS,
         PROTECTED_TABLES,
         db_looks_wiped,
@@ -98,6 +99,47 @@ def check_db_integrity(fix: bool = False) -> DoctorCheck:
     reference_counts = db_row_counts(reference, PROTECTED_TABLES) if reference else {}
     reference_rows = sum(v for v in reference_counts.values() if isinstance(v, int))
     protected_regression = diff_row_counts(db_path, reference, PROTECTED_TABLES) if reference else None
+    local_context_db = paths.memory_dir() / "local-context.db"
+    local_needs_reference = (
+        not local_context_db.is_file()
+        or db_looks_wiped(local_context_db, LOCAL_CONTEXT_TABLES)
+    )
+    local_reference = None
+    if local_needs_reference:
+        local_reference = (
+            find_best_hourly_backup(
+                paths.backups_dir(),
+                glob="local-context-*.db",
+                min_critical_rows=MIN_REFERENCE_ROWS,
+                tables=LOCAL_CONTEXT_TABLES,
+            )
+            or find_latest_hourly_backup(
+                paths.backups_dir(),
+                glob="local-context-*.db",
+                min_critical_rows=MIN_REFERENCE_ROWS,
+                tables=LOCAL_CONTEXT_TABLES,
+            )
+            or find_best_hourly_backup(
+                paths.backups_dir(),
+                glob="nexo-*.db",
+                min_critical_rows=MIN_REFERENCE_ROWS,
+                tables=LOCAL_CONTEXT_TABLES,
+            )
+            or find_latest_hourly_backup(
+                paths.backups_dir(),
+                glob="nexo-*.db",
+                min_critical_rows=MIN_REFERENCE_ROWS,
+                tables=LOCAL_CONTEXT_TABLES,
+            )
+        )
+    local_reference_counts = db_row_counts(local_reference, LOCAL_CONTEXT_TABLES) if local_reference else {}
+    local_reference_rows = sum(v for v in local_reference_counts.values() if isinstance(v, int))
+    local_regression = diff_row_counts(local_context_db, local_reference, LOCAL_CONTEXT_TABLES) if local_reference else None
+    recoverable_local_regression = bool(
+        local_reference
+        and local_regression
+        and local_regression.is_wipe()
+    )
     recoverable_regression = bool(
         reference
         and protected_regression
@@ -121,7 +163,7 @@ def check_db_integrity(fix: bool = False) -> DoctorCheck:
         )
     )
 
-    if quick_ok and not recoverable_wipe and not recoverable_regression:
+    if quick_ok and not recoverable_wipe and not recoverable_regression and not recoverable_local_regression:
         if looks_wiped and not reference:
             return DoctorCheck(
                 id="boot.db_integrity",
@@ -150,6 +192,11 @@ def check_db_integrity(fix: bool = False) -> DoctorCheck:
         evidence.append(f"Reference backup: {reference} ({reference_rows} protected rows)")
     if protected_regression:
         evidence.extend(protected_regression.summary_lines())
+    if local_reference:
+        evidence.append(f"Local memory DB: {local_context_db}")
+        evidence.append(f"Local memory reference: {local_reference} ({local_reference_rows} rows)")
+    if local_regression:
+        evidence.extend(["Local memory regression:", *local_regression.summary_lines()])
 
     if fix and recoverable_regression:
         report = restore_tables_from_backup(reference, db_path)
@@ -205,7 +252,49 @@ def check_db_integrity(fix: bool = False) -> DoctorCheck:
             repair_plan=["Run nexo recover --force --yes, then restart Desktop"],
         )
 
-    if recoverable_wipe or recoverable_regression:
+    if fix and recoverable_local_regression:
+        try:
+            local_context_db.parent.mkdir(parents=True, exist_ok=True)
+            if not local_context_db.exists():
+                sqlite3.connect(str(local_context_db)).close()
+        except Exception as exc:
+            return DoctorCheck(
+                id="boot.db_integrity",
+                tier="boot",
+                status="critical",
+                severity="error",
+                summary="Local memory sidecar repair failed",
+                evidence=evidence + [f"Cannot create local memory DB: {type(exc).__name__}: {exc}"],
+                repair_plan=["Close NEXO Desktop and run nexo doctor --tier boot --plane database_real --fix"],
+            )
+        report = restore_tables_from_backup(local_reference, local_context_db, tables=LOCAL_CONTEXT_TABLES)
+        if report.get("ok"):
+            restored = {
+                table: payload
+                for table, payload in (report.get("tables") or {}).items()
+                if isinstance(payload, dict) and payload.get("status") == "restored"
+            }
+            restored_rows = sum(int(payload.get("after") or 0) for payload in restored.values())
+            return DoctorCheck(
+                id="boot.db_integrity",
+                tier="boot",
+                status="healthy",
+                severity="info",
+                summary=f"Local memory sidecar restored from backup ({restored_rows} rows)",
+                evidence=evidence + [f"Restored local-memory sidecar tables: {len(restored)}"],
+                fixed=True,
+            )
+        return DoctorCheck(
+            id="boot.db_integrity",
+            tier="boot",
+            status="critical",
+            severity="error",
+            summary="Local memory sidecar repair failed",
+            evidence=evidence + [f"Restore errors: {report.get('errors') or []}"],
+            repair_plan=["Close NEXO Desktop and run nexo doctor --tier boot --plane database_real --fix"],
+        )
+
+    if recoverable_wipe or recoverable_regression or recoverable_local_regression:
         return DoctorCheck(
             id="boot.db_integrity",
             tier="boot",

package/src/interactive_db.py

@@ -0,0 +1,59 @@
+"""Helpers for interactive MCP tools that must not block on SQLite locks."""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+from contextlib import contextmanager
+
+from db import get_db
+
+
+def interactive_db_timeout_ms() -> int:
+    """Return the max SQLite busy wait for user-facing MCP calls."""
+    try:
+        return max(50, min(int(os.environ.get("NEXO_MCP_DB_BUSY_TIMEOUT_MS", "250")), 10000))
+    except Exception:
+        return 250
+
+
+def set_interactive_db_timeout() -> None:
+    """Make the shared connection fail fast when a background writer owns the DB."""
+    try:
+        get_db().execute(f"PRAGMA busy_timeout={interactive_db_timeout_ms()}")
+    except Exception:
+        pass
+
+
+@contextmanager
+def interactive_db_timeout():
+    """Temporarily reduce SQLite busy wait for a user-facing MCP call."""
+    conn = None
+    previous = None
+    try:
+        conn = get_db()
+        row = conn.execute("PRAGMA busy_timeout").fetchone()
+        previous = int(row[0]) if row and row[0] is not None else None
+        conn.execute(f"PRAGMA busy_timeout={interactive_db_timeout_ms()}")
+    except Exception:
+        conn = None
+    try:
+        yield
+    finally:
+        if conn is not None and previous is not None:
+            try:
+                conn.execute(f"PRAGMA busy_timeout={previous}")
+            except Exception:
+                pass
+
+
+def is_db_busy(exc: BaseException) -> bool:
+    msg = str(exc).lower()
+    return (
+        isinstance(exc, sqlite3.OperationalError)
+        and (
+            "database is locked" in msg
+            or "database is busy" in msg
+            or "database table is locked" in msg
+        )
+    ) or "database is locked" in msg or "database is busy" in msg