nexo-brain 7.20.11 → 7.20.13

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.20.11",
+  "version": "7.20.13",
   "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,11 @@
 
 [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.11` is the current packaged-runtime line. Patch release over v7.20.10 — Local Context now starts from real system volume roots plus mounted/removable/network volumes, filters system/cache/app/product artifacts, and injects relevant local evidence automatically into heartbeat, task-open and pre-action context.
+Version `7.20.13` is the current packaged-runtime line. Patch release over v7.20.12 — Brain recovery now pauses all known DB writers before restoring `nexo.db`, and Doctor can repair the zero-byte/locked database state that made Desktop Local Memory show zero files.
+
+Previously in `7.20.12`: patch release over v7.20.11 — Local Context now keeps the first index pass separate from live change tracking, persists the current indexing start time, caps compact context payloads for agents, and installs the Windows host scheduler needed to keep WSL indexing alive after reboots.
+
+Previously in `7.20.11`: patch release over v7.20.10 — Local Context now starts from real system volume roots plus mounted/removable/network volumes, filters system/cache/app/product artifacts, and injects relevant local evidence automatically into heartbeat, task-open and pre-action context.
 
 Previously in `7.20.10`: patch release over v7.20.9 — Local Context manual refreshes now reconcile automatic roots every time, so newly mounted disks and upgraded default roots are picked up immediately from Desktop's "comprobar cambios" path.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.20.11",
+  "version": "7.20.13",
   "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

@@ -1412,7 +1412,8 @@ def _self_heal_if_wiped() -> dict | None:
             db_looks_wiped,
             db_row_counts,
             find_latest_hourly_backup,
-            kill_nexo_mcp_servers,
+            quiesce_nexo_db_writers,
+            resume_nexo_launchagents,
             safe_sqlite_backup,
             validate_backup_matches_source,
         )
@@ -1467,11 +1468,29 @@ def _self_heal_if_wiped() -> dict | None:
         f"(reference={reference.name}, {ref_total} critical rows). Restoring..."
     )
 
-    # Kill any live MCP servers so they cannot overwrite the restored DB.
-    kill_report = kill_nexo_mcp_servers(dry_run=False)
-    if kill_report.get("terminated"):
-        _log(f"self-heal: terminated {kill_report['terminated']} live MCP server(s).")
-        time.sleep(0.5)
+    # Pause any live DB writers so they cannot overwrite the restored DB or
+    # keep stale handles open. Desktop installs have more writers than the MCP
+    # server: local-index, email-monitor, followup-runner, watchdog and catchup.
+    quiesce_report = quiesce_nexo_db_writers(dry_run=False)
+    stopped_launchagents = list((quiesce_report.get("launchagents") or {}).get("stopped") or [])
+    if quiesce_report.get("terminated") or stopped_launchagents:
+        _log(
+            "self-heal: quiesced DB writers "
+            f"(terminated={quiesce_report.get('terminated', 0)}, "
+            f"launchagents={len(stopped_launchagents)})."
+        )
+    if quiesce_report.get("errors"):
+        _log(f"self-heal: DB writer quiesce warnings: {quiesce_report.get('errors')}")
+
+    def _resume_quiesced() -> dict | None:
+        if not stopped_launchagents:
+            return None
+        report = resume_nexo_launchagents(stopped_launchagents)
+        if report.get("started"):
+            _log(f"self-heal: resumed {len(report['started'])} launchagent(s).")
+        if report.get("errors"):
+            _log(f"self-heal: launchagent resume warnings: {report.get('errors')}")
+        return report
 
     # Snapshot the current (wiped) state so the heal is reversible.
     pre_heal_dir = paths.backups_dir() / f"pre-heal-{time.strftime('%Y-%m-%d-%H%M%S')}"
@@ -1497,27 +1516,34 @@ def _self_heal_if_wiped() -> dict | None:
     ok, err = safe_sqlite_backup(reference, primary)
     if not ok:
         _log(f"self-heal: restore copy failed: {err}")
+        resume_report = _resume_quiesced()
         return {
             "action": "failed",
             "reason": "restore_copy_failed",
             "error": err,
             "reference": str(reference),
             "pre_heal_dir": str(pre_heal_dir),
+            "quiesce": quiesce_report,
+            "resume": resume_report,
         }
     valid, valid_err = validate_backup_matches_source(reference, primary, CRITICAL_TABLES)
     if not valid:
         _log(f"self-heal: post-restore validation failed: {valid_err}")
+        resume_report = _resume_quiesced()
         return {
             "action": "failed",
             "reason": "validation_failed",
             "error": valid_err,
             "reference": str(reference),
             "pre_heal_dir": str(pre_heal_dir),
+            "quiesce": quiesce_report,
+            "resume": resume_report,
         }
 
     final_counts = db_row_counts(primary, CRITICAL_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()
     try:
         SELF_HEAL_STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
         SELF_HEAL_STATE_FILE.write_text(json.dumps({
@@ -1525,6 +1551,7 @@ def _self_heal_if_wiped() -> dict | None:
             "reference": str(reference),
             "critical_rows_restored": final_total,
             "pre_heal_dir": str(pre_heal_dir),
+            "quiesced_launchagents": stopped_launchagents,
         }))
     except Exception as e:
         _log(f"self-heal: state write warning: {e}")
@@ -1535,7 +1562,9 @@ def _self_heal_if_wiped() -> dict | None:
         "reference_rows": ref_total,
         "restored_rows": final_total,
         "pre_heal_dir": str(pre_heal_dir),
-        "terminated_servers": kill_report.get("terminated", 0),
+        "terminated_servers": int((quiesce_report.get("mcp") or {}).get("terminated") or 0),
+        "quiesce": quiesce_report,
+        "resume": resume_report,
     }
 
 

package/src/cli.py

@@ -1361,6 +1361,10 @@ def _local_context_query(args) -> int:
             limit=int(getattr(args, "limit", 12) or 12),
             evidence_required=not bool(getattr(args, "no_evidence_required", False)),
             current_context=getattr(args, "current_context", "") or "",
+            mode=getattr(args, "mode", "compact") or "compact",
+            max_chars=int(getattr(args, "max_chars", 20000) or 0),
+            include_entities=bool(getattr(args, "include_entities", False)),
+            include_relations=bool(getattr(args, "include_relations", False)),
         ),
         args,
     )
@@ -3211,6 +3215,10 @@ def main():
     local_context_query_p.add_argument("--intent", default="answer", help="Intent label stored with the query audit row")
     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.")
+    local_context_query_p.add_argument("--max-chars", type=int, default=20000, help="Maximum JSON payload size before truncation. Use 0 to disable.")
+    local_context_query_p.add_argument("--include-entities", action="store_true", help="Include matched entities in the JSON payload.")
+    local_context_query_p.add_argument("--include-relations", action="store_true", help="Include graph relations in the JSON payload.")
     local_context_query_p.add_argument("--no-evidence-required", action="store_true", help="Allow empty evidence results")
     local_context_query_p.add_argument("--json", action="store_true", help="JSON output")
 

package/src/crons/sync.py

@@ -35,6 +35,14 @@ if str(_runtime_root) not in sys.path:
 
 import paths
 from cron_recovery import is_cron_enabled, resolve_declared_schedule, should_run_at_load
+try:
+    from windows_runtime import resolve_windows_host_binary, running_inside_wsl
+except ImportError:
+    def resolve_windows_host_binary(command: str) -> str:
+        return ""
+
+    def running_inside_wsl() -> bool:
+        return False
 try:
     from runtime_power import (
         launchctl_side_effects_allowed,
@@ -548,6 +556,65 @@ def _install_linux_crontab_fallback(entries: list[str]) -> dict:
     return {"ok": True, "entries": len(entries)}
 
 
+def _powershell_single_quote(value: str | os.PathLike[str]) -> str:
+    return "'" + str(value).replace("'", "''") + "'"
+
+
+def _windows_argument_quote(value: str | os.PathLike[str]) -> str:
+    text = str(value)
+    return '"' + text.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def _sync_wsl_windows_host_local_index_task(dry_run: bool = False) -> dict:
+    if not running_inside_wsl():
+        return {"ok": True, "skipped": True, "reason": "not_wsl"}
+    powershell = resolve_windows_host_binary("powershell.exe")
+    if not powershell:
+        log("WARNING: Windows host PowerShell not available; local-index host task not installed.")
+        return {"ok": False, "skipped": True, "reason": "powershell_missing"}
+
+    distro = str(os.environ.get("WSL_DISTRO_NAME", "")).strip()
+    if not distro:
+        log("WARNING: WSL_DISTRO_NAME missing; local-index host task not installed.")
+        return {"ok": False, "skipped": True, "reason": "wsl_distro_missing"}
+
+    python_bin = "/usr/bin/python3" if Path("/usr/bin/python3").exists() else "python3"
+    script_path = _runtime_code_dir() / "scripts" / "nexo-local-index.py"
+    command = (
+        f"cd {shlex.quote(str(Path.home()))} && "
+        f"NEXO_HOME={shlex.quote(str(NEXO_HOME))} "
+        f"NEXO_CODE={shlex.quote(str(_runtime_code_dir()))} "
+        f"{shlex.quote(python_bin)} {shlex.quote(str(script_path))}"
+    )
+    wsl_args = " ".join(
+        _windows_argument_quote(arg)
+        for arg in ("-d", distro, "--exec", "/bin/bash", "-lc", command)
+    )
+    task_name = "NEXO Local Memory"
+    ps_script = (
+        f"$action = New-ScheduledTaskAction -Execute 'wsl.exe' -Argument {_powershell_single_quote(wsl_args)}; "
+        "$trigger = New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes(1) "
+        "-RepetitionInterval (New-TimeSpan -Minutes 1) -RepetitionDuration (New-TimeSpan -Days 3650); "
+        "$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries "
+        "-StartWhenAvailable -MultipleInstances IgnoreNew; "
+        f"Register-ScheduledTask -TaskName {_powershell_single_quote(task_name)} -Action $action -Trigger $trigger "
+        "-Settings $settings -Description 'NEXO Local Memory background indexing' -Force | Out-Null; "
+        f"Start-ScheduledTask -TaskName {_powershell_single_quote(task_name)}"
+    )
+
+    if dry_run:
+        log(f"  DRY-RUN: would install Windows host task: {task_name}")
+        return {"ok": True, "dry_run": True, "task_name": task_name, "argument": wsl_args}
+
+    result = subprocess.run([powershell, "-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", ps_script], capture_output=True, text=True, timeout=45)
+    if result.returncode != 0:
+        error = (result.stderr or result.stdout or "windows_host_task_install_failed").strip()
+        log(f"WARNING: Windows host local-index task install failed: {error}")
+        return {"ok": False, "task_name": task_name, "error": error}
+    log(f"Windows host task installed: {task_name}")
+    return {"ok": True, "task_name": task_name, "argument": wsl_args}
+
+
 def _enable_systemd_user_units(units: list[str]) -> dict:
     errors: list[str] = []
     daemon = subprocess.run(["systemctl", "--user", "daemon-reload"], capture_output=True, text=True)
@@ -699,6 +766,7 @@ def sync(dry_run: bool = False):
     system = platform.system()
     if system == "Linux":
         sync_linux(dry_run)
+        _sync_wsl_windows_host_local_index_task(dry_run)
         return
     if system != "Darwin":
         log(f"Unsupported platform: {system}. Skipping.")

package/src/db_guard.py

@@ -27,6 +27,8 @@ auto_update.py):
     safe_sqlite_backup(source, dest) -> tuple[bool, str | None]
     validate_backup_matches_source(source, dest, tables) -> tuple[bool, str | None]
     kill_nexo_mcp_servers(dry_run) -> dict
+    quiesce_nexo_db_writers(dry_run) -> dict
+    resume_nexo_launchagents(labels, dry_run) -> dict
 """
 
 from __future__ import annotations
@@ -80,6 +82,27 @@ HOURLY_BACKUP_GLOB = "nexo-*.db"
 # as an automatic self-heal source. 48h matches nexo-backup.sh retention.
 HOURLY_BACKUP_MAX_AGE = 48 * 3600
 
+# Long-lived NEXO services that can keep ``nexo.db`` open while recovery tries
+# to replace it. Keep this list conservative: only product-owned background
+# processes that are safe to stop and restart.
+NEXO_DB_WRITER_LAUNCHAGENTS: tuple[str, ...] = (
+    "com.nexo.local-index",
+    "com.nexo.email-monitor",
+    "com.nexo.followup-runner",
+    "com.nexo.watchdog",
+    "com.nexo.catchup",
+    "com.nexo.immune",
+)
+
+NEXO_DB_WRITER_MARKERS: tuple[str, ...] = (
+    "nexo-local-index.py",
+    "nexo-email-monitor.py",
+    "nexo-followup-runner.py",
+    "nexo-catchup.py",
+    "nexo-watchdog.sh",
+    "nexo-immune.py",
+)
+
 
 # ── Types ───────────────────────────────────────────────────────────────
 
@@ -447,3 +470,252 @@ def _looks_like_nexo_mcp(cmd: str) -> bool:
     if "nexo_sdk" in lowered or "nexo-mcp" in lowered:
         return True
     return False
+
+
+# ── DB writer quiescence ────────────────────────────────────────────────
+
+def quiesce_nexo_db_writers(
+    dry_run: bool = False,
+    *,
+    stop_launchagents: bool = True,
+    settle_seconds: float = 0.75,
+) -> dict:
+    """Stop known NEXO background writers before replacing ``nexo.db``.
+
+    ``kill_nexo_mcp_servers`` is not enough for Desktop installs: local-index,
+    email monitor, followup-runner and catchup can keep a stale DB handle open
+    even after the MCP server exits. This helper is intentionally narrow and
+    only targets product-owned long-lived writers.
+    """
+    result: dict = {
+        "dry_run": dry_run,
+        "mcp": {},
+        "launchagents": {"stopped": [], "errors": [], "unsupported": False},
+        "processes": {"scanned": 0, "terminated": 0, "pids": [], "errors": []},
+        "terminated": 0,
+        "errors": [],
+    }
+
+    mcp_report = kill_nexo_mcp_servers(dry_run=dry_run)
+    result["mcp"] = mcp_report
+    result["terminated"] += int(mcp_report.get("terminated") or 0)
+    result["errors"].extend(mcp_report.get("errors") or [])
+
+    if stop_launchagents:
+        la_report = _stop_nexo_launchagents(dry_run=dry_run)
+        result["launchagents"] = la_report
+        result["errors"].extend(la_report.get("errors") or [])
+
+    process_report = _terminate_nexo_db_writer_processes(dry_run=dry_run)
+    result["processes"] = process_report
+    result["terminated"] += int(process_report.get("terminated") or 0)
+    result["errors"].extend(process_report.get("errors") or [])
+
+    if not dry_run and (result["terminated"] or result["launchagents"].get("stopped")):
+        time.sleep(max(settle_seconds, 0.0))
+    return result
+
+
+def resume_nexo_launchagents(labels: list[str] | tuple[str, ...] | None = None, dry_run: bool = False) -> dict:
+    """Best-effort restart of LaunchAgents stopped by DB recovery."""
+    result: dict = {"dry_run": dry_run, "started": [], "errors": [], "unsupported": False}
+    if os.name != "posix" or sys_platform() != "darwin":
+        result["unsupported"] = True
+        return result
+    uid = os.getuid()
+    launch_agents_dir = Path.home() / "Library" / "LaunchAgents"
+    chosen = tuple(labels or NEXO_DB_WRITER_LAUNCHAGENTS)
+    for label in chosen:
+        plist = launch_agents_dir / f"{label}.plist"
+        if not plist.is_file():
+            continue
+        target = f"gui/{uid}/{label}"
+        if dry_run:
+            result["started"].append(label)
+            continue
+        try:
+            subprocess.run(
+                ["launchctl", "bootstrap", f"gui/{uid}", str(plist)],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            subprocess.run(
+                ["launchctl", "kickstart", "-k", target],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            result["started"].append(label)
+        except Exception as exc:
+            result["errors"].append(f"{label}: {exc}")
+    return result
+
+
+def sys_platform() -> str:
+    # Small indirection makes tests easy to monkeypatch without importing sys at
+    # module import time in older runtimes.
+    import sys
+    return sys.platform
+
+
+def _stop_nexo_launchagents(dry_run: bool = False) -> dict:
+    result: dict = {"stopped": [], "errors": [], "unsupported": False}
+    if os.name != "posix" or sys_platform() != "darwin":
+        result["unsupported"] = True
+        return result
+    uid = os.getuid()
+    launch_agents_dir = Path.home() / "Library" / "LaunchAgents"
+    for label in NEXO_DB_WRITER_LAUNCHAGENTS:
+        plist = launch_agents_dir / f"{label}.plist"
+        if not plist.is_file():
+            continue
+        if dry_run:
+            result["stopped"].append(label)
+            continue
+        try:
+            proc = subprocess.run(
+                ["launchctl", "bootout", f"gui/{uid}", str(plist)],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+        except Exception as exc:
+            result["errors"].append(f"{label}: {exc}")
+            continue
+        if proc.returncode == 0:
+            result["stopped"].append(label)
+        else:
+            stderr = (proc.stderr or "").strip()
+            # launchctl returns non-zero when an agent is already unloaded. That
+            # is not a recovery blocker, so keep it as quiet evidence.
+            if stderr and "No such process" not in stderr and "not found" not in stderr:
+                result["errors"].append(f"{label}: {stderr[:200]}")
+    return result
+
+
+def _terminate_nexo_db_writer_processes(dry_run: bool = False) -> dict:
+    result: dict = {"scanned": 0, "terminated": 0, "pids": [], "errors": [], "dry_run": dry_run}
+    if os.name == "posix":
+        return _terminate_posix_db_writer_processes(dry_run=dry_run)
+    if os.name == "nt":
+        return _terminate_windows_db_writer_processes(dry_run=dry_run)
+    result["errors"].append("unsupported platform")
+    return result
+
+
+def _terminate_posix_db_writer_processes(dry_run: bool = False) -> dict:
+    result: dict = {"scanned": 0, "terminated": 0, "pids": [], "errors": [], "dry_run": dry_run}
+    try:
+        proc = subprocess.run(
+            ["ps", "-axo", "pid=,command="],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except Exception as exc:
+        result["errors"].append(f"ps failed: {exc}")
+        return result
+    if proc.returncode != 0:
+        result["errors"].append(f"ps exit {proc.returncode}: {proc.stderr.strip()[:200]}")
+        return result
+
+    my_pid = os.getpid()
+    for raw in proc.stdout.splitlines():
+        line = raw.strip()
+        if not line:
+            continue
+        head, _, rest = line.partition(" ")
+        if not head.isdigit():
+            continue
+        pid = int(head)
+        if pid == my_pid:
+            continue
+        cmd = rest.strip()
+        if not _looks_like_nexo_db_writer(cmd):
+            continue
+        result["scanned"] += 1
+        result["pids"].append({"pid": pid, "command": cmd[:180]})
+        if dry_run:
+            continue
+        try:
+            os.kill(pid, signal.SIGTERM)
+            result["terminated"] += 1
+        except ProcessLookupError:
+            pass
+        except Exception as exc:
+            result["errors"].append(f"kill {pid} failed: {exc}")
+    return result
+
+
+def _terminate_windows_db_writer_processes(dry_run: bool = False) -> dict:
+    result: dict = {"scanned": 0, "terminated": 0, "pids": [], "errors": [], "dry_run": dry_run}
+    ps_script = (
+        "Get-CimInstance Win32_Process | "
+        "Select-Object ProcessId,CommandLine | ConvertTo-Json -Compress"
+    )
+    try:
+        proc = subprocess.run(
+            ["powershell", "-NoProfile", "-Command", ps_script],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+    except Exception as exc:
+        result["errors"].append(f"powershell process scan failed: {exc}")
+        return result
+    if proc.returncode != 0:
+        result["errors"].append(f"powershell exit {proc.returncode}: {proc.stderr.strip()[:200]}")
+        return result
+    try:
+        import json
+        rows = json.loads(proc.stdout or "[]")
+    except Exception as exc:
+        result["errors"].append(f"process json parse failed: {exc}")
+        return result
+    if isinstance(rows, dict):
+        rows = [rows]
+    my_pid = os.getpid()
+    for row in rows if isinstance(rows, list) else []:
+        try:
+            pid = int(row.get("ProcessId"))
+        except Exception:
+            continue
+        if pid == my_pid:
+            continue
+        cmd = str(row.get("CommandLine") or "")
+        if not _looks_like_nexo_db_writer(cmd):
+            continue
+        result["scanned"] += 1
+        result["pids"].append({"pid": pid, "command": cmd[:180]})
+        if dry_run:
+            continue
+        try:
+            subprocess.run(
+                ["taskkill", "/PID", str(pid), "/T", "/F"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            result["terminated"] += 1
+        except Exception as exc:
+            result["errors"].append(f"taskkill {pid} failed: {exc}")
+    return result
+
+
+def _looks_like_nexo_db_writer(cmd: str) -> bool:
+    if not cmd:
+        return False
+    lowered = cmd.lower()
+    if _looks_like_nexo_mcp(cmd):
+        return True
+    if "nexo-cron-wrapper.sh" in lowered and any(label in lowered for label in (
+        "local-index",
+        "email-monitor",
+        "followup-runner",
+        "watchdog",
+        "catchup",
+        "immune",
+    )):
+        return True
+    return any(marker in lowered for marker in NEXO_DB_WRITER_MARKERS)