nexo-brain 7.20.13 → 7.20.15

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.20.13",
+  "version": "7.20.14",
   "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.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.
+Version `7.20.15` is the current packaged-runtime line. Patch release over v7.20.14 — Brain update/recovery paths now fail closed when the DB guard is missing or stale, and backup validation rejects any replacement that loses Local Memory tables.
+
+Previously in `7.20.14`: patch release over v7.20.13 — Brain protects Local Memory during update/recovery paths, rotates runtime backup families to the latest 5 entries, keeps first-indexing status stable, and exposes bounded indexing speed profiles for Desktop.
+
+Previously in `7.20.13`: 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.
 

package/package.json

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

@@ -82,6 +82,23 @@ TEMPLATE_FILE = _RESOLVED_REPO_DIR / "templates" / "CLAUDE.md.template"
 CHECK_COOLDOWN_SECONDS = 3600  # 1 hour
 GIT_TIMEOUT_SECONDS = 4  # stay well under the 5s total budget
 CRITICAL_BACKUP_TABLES = ("learnings", "session_diary", "guard_checks", "protocol_debt")
+LOCAL_CONTEXT_BACKUP_TABLES = (
+    "local_index_roots",
+    "local_index_exclusions",
+    "local_index_jobs",
+    "local_index_checkpoints",
+    "local_index_state",
+    "local_index_errors",
+    "local_assets",
+    "local_asset_versions",
+    "local_chunks",
+    "local_entities",
+    "local_relations",
+    "local_embeddings",
+    "local_context_queries",
+    "local_index_dirs",
+)
+PROTECTED_BACKUP_TABLES = CRITICAL_BACKUP_TABLES + LOCAL_CONTEXT_BACKUP_TABLES
 CLASSIFIER_INSTALL_TIMEOUT_SECONDS = 1800
 CLASSIFIER_INSTALL_JOIN_SECONDS = 1500
 CLASSIFIER_INSTALL_LOG = paths.logs_dir() / "classifier-install.log"
@@ -321,7 +338,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 CRITICAL_BACKUP_TABLES:
+    for table in PROTECTED_BACKUP_TABLES:
         source_count = _critical_table_count(source_db, table)
         backup_count = _critical_table_count(backup_db, table)
         report["source_counts"][table] = source_count
@@ -1336,7 +1353,7 @@ def _reload_launch_agents_after_bump() -> dict:
     return result
 
 
-AUTO_UPDATE_BACKUP_KEEP = 10
+AUTO_UPDATE_BACKUP_KEEP = 5
 """Maximum number of auto-update backups to keep per prefix.
 
 Both `pre-autoupdate-*/` (DB snapshots) and `runtime-tree-*/` (code mirrors)
@@ -1409,8 +1426,10 @@ def _self_heal_if_wiped() -> dict | None:
             CRITICAL_TABLES,
             HOURLY_BACKUP_MAX_AGE,
             MIN_REFERENCE_ROWS,
+            PROTECTED_TABLES,
             db_looks_wiped,
             db_row_counts,
+            find_best_hourly_backup,
             find_latest_hourly_backup,
             quiesce_nexo_db_writers,
             resume_nexo_launchagents,
@@ -1424,11 +1443,16 @@ def _self_heal_if_wiped() -> dict | None:
     primary = DATA_DIR / "nexo.db"
     if not primary.is_file():
         return None
-    if not db_looks_wiped(primary, CRITICAL_TABLES):
+    if not db_looks_wiped(primary, PROTECTED_TABLES):
         return None
-    reference = find_latest_hourly_backup(
+    reference = find_best_hourly_backup(
+        paths.backups_dir(),
+        max_age_seconds=HOURLY_BACKUP_MAX_AGE,
+        tables=PROTECTED_TABLES,
+    ) or find_latest_hourly_backup(
         paths.backups_dir(),
         max_age_seconds=HOURLY_BACKUP_MAX_AGE,
+        tables=PROTECTED_TABLES,
     )
     if reference is None:
         _log("self-heal: nexo.db looks wiped but no usable hourly backup found — skipping.")
@@ -1437,7 +1461,7 @@ def _self_heal_if_wiped() -> dict | None:
             "reason": "no_usable_hourly_backup",
             "primary_db": str(primary),
         }
-    ref_counts = db_row_counts(reference, CRITICAL_TABLES)
+    ref_counts = db_row_counts(reference, PROTECTED_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}")
@@ -1526,7 +1550,7 @@ def _self_heal_if_wiped() -> dict | None:
             "quiesce": quiesce_report,
             "resume": resume_report,
         }
-    valid, valid_err = validate_backup_matches_source(reference, primary, CRITICAL_TABLES)
+    valid, valid_err = validate_backup_matches_source(reference, primary, PROTECTED_TABLES)
     if not valid:
         _log(f"self-heal: post-restore validation failed: {valid_err}")
         resume_report = _resume_quiesced()
@@ -1540,7 +1564,7 @@ def _self_heal_if_wiped() -> dict | None:
             "resume": resume_report,
         }
 
-    final_counts = db_row_counts(primary, CRITICAL_TABLES)
+    final_counts = db_row_counts(primary, PROTECTED_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()

package/src/db_guard.py

@@ -17,15 +17,19 @@ Public surface (stable for use by plugins/update.py, plugins/recover.py,
 auto_update.py):
 
     CRITICAL_TABLES
+    LOCAL_CONTEXT_TABLES
+    PROTECTED_TABLES
     WIPE_THRESHOLD_PCT
     MIN_REFERENCE_ROWS
 
     db_row_counts(path, tables) -> dict[str, int | None]
     db_looks_wiped(path, tables, min_reference_rows) -> bool
     find_latest_hourly_backup(backups_dir, max_age_seconds) -> Path | None
+    find_best_hourly_backup(backups_dir, max_age_seconds) -> Path | None
     diff_row_counts(current, reference, tables) -> WipeReport
     safe_sqlite_backup(source, dest) -> tuple[bool, str | None]
     validate_backup_matches_source(source, dest, tables) -> tuple[bool, str | None]
+    restore_tables_from_backup(source, target, tables) -> dict
     kill_nexo_mcp_servers(dry_run) -> dict
     quiesce_nexo_db_writers(dry_run) -> dict
     resume_nexo_launchagents(labels, dry_run) -> dict
@@ -61,6 +65,31 @@ CRITICAL_TABLES: tuple[str, ...] = (
     "decisions",
 )
 
+# The local memory index is not a disposable cache. A full-disk first pass can
+# take days, and losing these tables silently makes NEXO look "healthy" while
+# the user's local memory has actually been reset.
+LOCAL_CONTEXT_TABLES: tuple[str, ...] = (
+    "local_index_roots",
+    "local_index_exclusions",
+    "local_index_jobs",
+    "local_index_checkpoints",
+    "local_index_state",
+    "local_index_errors",
+    "local_assets",
+    "local_asset_versions",
+    "local_chunks",
+    "local_entities",
+    "local_relations",
+    "local_embeddings",
+    "local_context_queries",
+    "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
+
 # 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".
 # Otherwise we cannot distinguish a fresh install from a wipe.
@@ -180,7 +209,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, ...] = CRITICAL_TABLES) -> dict[str, int | None]:
+def db_row_counts(path: str | Path, tables: tuple[str, ...] = PROTECTED_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}
@@ -206,7 +235,7 @@ def db_row_counts(path: str | Path, tables: tuple[str, ...] = CRITICAL_TABLES) -
 
 def db_looks_wiped(
     path: str | Path,
-    tables: tuple[str, ...] = CRITICAL_TABLES,
+    tables: tuple[str, ...] = PROTECTED_TABLES,
     min_reference_rows: int = MIN_REFERENCE_ROWS,
 ) -> bool:
     """Heuristic: the file exists AND either all critical tables exist with 0 rows,
@@ -247,6 +276,7 @@ def find_latest_hourly_backup(
     max_age_seconds: int = HOURLY_BACKUP_MAX_AGE,
     glob: str = HOURLY_BACKUP_GLOB,
     min_critical_rows: int = 1,
+    tables: tuple[str, ...] = PROTECTED_TABLES,
 ) -> Path | None:
     """Return the newest hourly backup that contains at least ``min_critical_rows``
     across CRITICAL_TABLES and is not older than ``max_age_seconds``.
@@ -281,19 +311,58 @@ def find_latest_hourly_backup(
     # the row-count floor. A production NEXO_HOME can accumulate 40+ hourly
     # backups, so opening every file would add seconds to the CLI startup.
     for _, candidate in stat_candidates:
-        counts = db_row_counts(candidate)
+        counts = db_row_counts(candidate, tables)
         total = sum(v for v in counts.values() if isinstance(v, int))
         if total >= min_critical_rows:
             return candidate
     return None
 
 
+def find_best_hourly_backup(
+    backups_dir: str | Path,
+    max_age_seconds: int = HOURLY_BACKUP_MAX_AGE,
+    glob: str = HOURLY_BACKUP_GLOB,
+    min_critical_rows: int = 1,
+    tables: tuple[str, ...] = PROTECTED_TABLES,
+) -> Path | None:
+    """Return the usable hourly backup with the most protected rows.
+
+    Newest is not always safest: if an update/reset starts reindexing from
+    scratch, the next hourly backups are recent but degraded. For local memory
+    recovery we prefer the richest backup and use mtime only as a tie-breaker.
+    """
+    base = Path(backups_dir)
+    if not base.is_dir():
+        return None
+    now = time.time()
+    best: tuple[int, float, Path] | None = None
+    for entry in base.glob(glob):
+        if not entry.is_file():
+            continue
+        try:
+            stat = entry.stat()
+        except OSError:
+            continue
+        if now - stat.st_mtime > max_age_seconds:
+            continue
+        if stat.st_size <= EMPTY_DB_SIZE_BYTES:
+            continue
+        counts = db_row_counts(entry, tables)
+        total = sum(v for v in counts.values() if isinstance(v, int))
+        if total < min_critical_rows:
+            continue
+        candidate = (int(total), float(stat.st_mtime), entry)
+        if best is None or candidate[:2] > best[:2]:
+            best = candidate
+    return best[2] if best else None
+
+
 # ── Diff & wipe detection ───────────────────────────────────────────────
 
 def diff_row_counts(
     current: str | Path,
     reference: str | Path,
-    tables: tuple[str, ...] = CRITICAL_TABLES,
+    tables: tuple[str, ...] = PROTECTED_TABLES,
 ) -> WipeReport:
     """Compare row counts between two SQLite DBs and return a WipeReport."""
     source_counts = db_row_counts(current, tables)
@@ -363,7 +432,7 @@ def safe_sqlite_backup(source: str | Path, dest: str | Path) -> tuple[bool, str
 def validate_backup_matches_source(
     source: str | Path,
     dest: str | Path,
-    tables: tuple[str, ...] = CRITICAL_TABLES,
+    tables: tuple[str, ...] = PROTECTED_TABLES,
 ) -> tuple[bool, str | None]:
     """After a backup, verify that every critical table in the copy has at
     least as many rows as the source — i.e. we did not lose data in transit.
@@ -393,6 +462,94 @@ def validate_backup_matches_source(
     return True, None
 
 
+def _quote_identifier(identifier: str) -> str:
+    if identifier not in PROTECTED_TABLES:
+        raise ValueError(f"refusing unsafe table identifier: {identifier!r}")
+    return '"' + identifier.replace('"', '""') + '"'
+
+
+def restore_tables_from_backup(
+    source: str | Path,
+    target: str | Path,
+    tables: tuple[str, ...] = LOCAL_CONTEXT_TABLES,
+) -> dict:
+    """Replace selected tables in ``target`` with the copy from ``source``.
+
+    This is intentionally table-scoped. It lets Doctor/repair recover days of
+    local indexing from a backup without rolling back newer conversations,
+    credentials, followups, or other Brain state created after that backup.
+    """
+    src = Path(source)
+    dst = Path(target)
+    result: dict = {
+        "ok": False,
+        "source": str(src),
+        "target": str(dst),
+        "tables": {},
+        "errors": [],
+    }
+    if not src.is_file():
+        result["errors"].append(f"source missing: {src}")
+        return result
+    if not dst.is_file():
+        result["errors"].append(f"target missing: {dst}")
+        return result
+
+    conn = None
+    try:
+        conn = sqlite3.connect(str(dst), timeout=30)
+        conn.execute("PRAGMA foreign_keys=OFF")
+        conn.execute("ATTACH DATABASE ? AS backup_db", (str(src),))
+        for table in tables:
+            quoted = _quote_identifier(table)
+            src_exists = conn.execute(
+                "SELECT sql FROM backup_db.sqlite_master WHERE type='table' AND name=?",
+                (table,),
+            ).fetchone()
+            if src_exists is None:
+                result["tables"][table] = {"status": "missing_in_source"}
+                continue
+            dst_exists = conn.execute(
+                "SELECT name FROM main.sqlite_master WHERE type='table' AND name=?",
+                (table,),
+            ).fetchone()
+            if dst_exists is None:
+                create_sql = str(src_exists[0] or "").strip()
+                if not create_sql:
+                    result["tables"][table] = {"status": "schema_missing_in_source"}
+                    continue
+                conn.execute(create_sql)
+            before = _table_count(conn, table) or 0
+            conn.execute(f"DELETE FROM main.{quoted}")
+            conn.execute(f"INSERT INTO main.{quoted} SELECT * FROM backup_db.{quoted}")
+            after = _table_count(conn, table) or 0
+            result["tables"][table] = {
+                "status": "restored",
+                "before": int(before),
+                "after": int(after),
+            }
+        conn.commit()
+        result["ok"] = not result["errors"]
+    except Exception as exc:
+        result["errors"].append(f"{type(exc).__name__}: {exc}")
+        try:
+            if conn is not None:
+                conn.rollback()
+        except Exception:
+            pass
+    finally:
+        if conn is not None:
+            try:
+                conn.execute("DETACH DATABASE backup_db")
+            except Exception:
+                pass
+            try:
+                conn.close()
+            except Exception:
+                pass
+    return result
+
+
 # ── MCP server discovery / kill ─────────────────────────────────────────
 
 def kill_nexo_mcp_servers(dry_run: bool = False) -> dict:

package/src/doctor/providers/boot.py

@@ -45,9 +45,13 @@ def check_db_integrity(fix: bool = False) -> DoctorCheck:
         CRITICAL_TABLES,
         EMPTY_DB_SIZE_BYTES,
         MIN_REFERENCE_ROWS,
+        PROTECTED_TABLES,
         db_looks_wiped,
         db_row_counts,
+        diff_row_counts,
+        find_best_hourly_backup,
         find_latest_hourly_backup,
+        restore_tables_from_backup,
     )
 
     db_path = paths.db_path()
@@ -81,13 +85,25 @@ def check_db_integrity(fix: bool = False) -> DoctorCheck:
     except Exception as exc:
         quick_error = f"{type(exc).__name__}: {exc}"
 
-    looks_wiped = db_looks_wiped(db_path, CRITICAL_TABLES)
-    reference = find_latest_hourly_backup(
+    looks_wiped = db_looks_wiped(db_path, PROTECTED_TABLES)
+    reference = find_best_hourly_backup(
         paths.backups_dir(),
         min_critical_rows=MIN_REFERENCE_ROWS,
+        tables=PROTECTED_TABLES,
+    ) or find_latest_hourly_backup(
+        paths.backups_dir(),
+        min_critical_rows=MIN_REFERENCE_ROWS,
+        tables=PROTECTED_TABLES,
     )
-    reference_counts = db_row_counts(reference, CRITICAL_TABLES) if reference else {}
+    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
+    recoverable_regression = bool(
+        reference
+        and protected_regression
+        and protected_regression.is_wipe()
+        and not looks_wiped
+    )
     lower_error = quick_error.lower()
     corrupt_error = any(token in lower_error for token in (
         "database disk image is malformed",
@@ -105,7 +121,7 @@ def check_db_integrity(fix: bool = False) -> DoctorCheck:
         )
     )
 
-    if quick_ok and not recoverable_wipe:
+    if quick_ok and not recoverable_wipe and not recoverable_regression:
         if looks_wiped and not reference:
             return DoctorCheck(
                 id="boot.db_integrity",
@@ -131,7 +147,37 @@ def check_db_integrity(fix: bool = False) -> DoctorCheck:
         f"looks_wiped: {looks_wiped}",
     ]
     if reference:
-        evidence.append(f"Reference backup: {reference} ({reference_rows} critical rows)")
+        evidence.append(f"Reference backup: {reference} ({reference_rows} protected rows)")
+    if protected_regression:
+        evidence.extend(protected_regression.summary_lines())
+
+    if fix and recoverable_regression:
+        report = restore_tables_from_backup(reference, db_path)
+        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 restored from backup ({restored_rows} protected rows)",
+                evidence=evidence + [f"Restored local-memory tables: {len(restored)}"],
+                fixed=True,
+            )
+        return DoctorCheck(
+            id="boot.db_integrity",
+            tier="boot",
+            status="critical",
+            severity="error",
+            summary="Local memory 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 fix and recoverable_wipe:
         from plugins.recover import recover
@@ -145,7 +191,7 @@ def check_db_integrity(fix: bool = False) -> DoctorCheck:
                 tier="boot",
                 status="healthy",
                 severity="info",
-                summary=f"Database restored from backup ({restored_rows} critical rows)",
+                summary=f"Database restored from backup ({restored_rows} protected rows)",
                 evidence=evidence + [f"Pre-recover snapshot: {report.get('pre_recover_dir', '')}"],
                 fixed=True,
             )
@@ -159,13 +205,13 @@ def check_db_integrity(fix: bool = False) -> DoctorCheck:
             repair_plan=["Run nexo recover --force --yes, then restart Desktop"],
         )
 
-    if recoverable_wipe:
+    if recoverable_wipe or recoverable_regression:
         return DoctorCheck(
             id="boot.db_integrity",
             tier="boot",
             status="critical",
             severity="error",
-            summary="Database appears wiped or corrupt but a valid backup exists",
+            summary="Database or local memory appears degraded but a valid backup exists",
             evidence=evidence,
             repair_plan=["Run nexo doctor --tier boot --plane database_real --fix"],
             escalation_prompt="NEXO database needs automatic recovery from backup.",

package/src/local_context/__init__.py

@@ -20,12 +20,14 @@ from .api import (
     local_index_hygiene,
     model_status,
     pause,
+    performance_config,
     purge_asset,
     reconcile_live_changes,
     remove_exclusion,
     remove_root,
     resume,
     run_once,
+    set_performance_profile,
     status,
     warmup_models,
 )
@@ -45,12 +47,14 @@ __all__ = [
     "local_index_hygiene",
     "model_status",
     "pause",
+    "performance_config",
     "purge_asset",
     "reconcile_live_changes",
     "remove_exclusion",
     "remove_root",
     "resume",
     "run_once",
+    "set_performance_profile",
     "status",
     "warmup_models",
 ]

package/src/local_context/api.py

@@ -36,7 +36,55 @@ DEFAULT_ROUTER_MAX_CHARS = int(os.environ.get("NEXO_LOCAL_CONTEXT_ROUTER_MAX_CHA
 DEFAULT_MAX_JOB_ATTEMPTS = int(os.environ.get("NEXO_LOCAL_INDEX_MAX_JOB_ATTEMPTS", "3") or "3")
 INITIAL_INDEX_COMPLETE_KEY = "initial_index_complete"
 INITIAL_INDEX_STARTED_AT_KEY = "initial_index_started_at"
+PERFORMANCE_PROFILE_KEY = "performance_profile"
+DEFAULT_PERFORMANCE_PROFILE = os.environ.get("NEXO_LOCAL_INDEX_PERFORMANCE_PROFILE", "medium").strip().lower() or "medium"
 VALID_CONTEXT_MODES = {"compact", "full"}
+PERFORMANCE_PROFILES: dict[str, dict[str, Any]] = {
+    "low": {
+        "profile": "low",
+        "label": "Bajo",
+        "scan_limit": 250,
+        "process_limit": 50,
+        "live_asset_limit": 500,
+        "live_dir_limit": 100,
+        "live_file_limit": 250,
+        "cycles_per_run": 1,
+        "warning": False,
+    },
+    "medium": {
+        "profile": "medium",
+        "label": "Medio",
+        "scan_limit": 1000,
+        "process_limit": 200,
+        "live_asset_limit": DEFAULT_LIVE_ASSET_LIMIT,
+        "live_dir_limit": DEFAULT_LIVE_DIR_LIMIT,
+        "live_file_limit": DEFAULT_LIVE_FILE_LIMIT,
+        "cycles_per_run": 1,
+        "warning": False,
+    },
+    "high": {
+        "profile": "high",
+        "label": "Alto",
+        "scan_limit": 3000,
+        "process_limit": 600,
+        "live_asset_limit": 5000,
+        "live_dir_limit": 800,
+        "live_file_limit": 2500,
+        "cycles_per_run": 2,
+        "warning": True,
+    },
+    "extreme": {
+        "profile": "extreme",
+        "label": "Extremo",
+        "scan_limit": 8000,
+        "process_limit": 1500,
+        "live_asset_limit": 10000,
+        "live_dir_limit": 2000,
+        "live_file_limit": 6000,
+        "cycles_per_run": 3,
+        "warning": True,
+    },
+}
 
 
 def ensure_ready() -> None:
@@ -545,6 +593,53 @@ def _get_state(key: str, default: str = "") -> str:
     return _get_state_conn(conn, key, default)
 
 
+def _normalize_performance_profile(profile: str | None) -> str:
+    value = str(profile or "").strip().lower()
+    aliases = {
+        "slow": "low",
+        "bajo": "low",
+        "normal": "medium",
+        "balanced": "medium",
+        "medio": "medium",
+        "fast": "high",
+        "alto": "high",
+        "max": "extreme",
+        "maximum": "extreme",
+        "extremo": "extreme",
+    }
+    value = aliases.get(value, value)
+    return value if value in PERFORMANCE_PROFILES else "medium"
+
+
+def performance_config(profile: str | None = None, *, conn=None) -> dict:
+    active_profile = profile
+    if active_profile is None:
+        if conn is None:
+            active_profile = _get_state(PERFORMANCE_PROFILE_KEY, DEFAULT_PERFORMANCE_PROFILE)
+        else:
+            active_profile = _get_state_conn(conn, PERFORMANCE_PROFILE_KEY, DEFAULT_PERFORMANCE_PROFILE)
+    normalized = _normalize_performance_profile(active_profile)
+    config = dict(PERFORMANCE_PROFILES[normalized])
+    config["available_profiles"] = [dict(PERFORMANCE_PROFILES[key]) for key in ("low", "medium", "high", "extreme")]
+    config["interval_seconds"] = 60
+    return config
+
+
+def set_performance_profile(profile: str) -> dict:
+    normalized = _normalize_performance_profile(profile)
+    _set_state(PERFORMANCE_PROFILE_KEY, normalized)
+    config = performance_config(normalized)
+    log_event(
+        "info",
+        "performance_profile_updated",
+        "Local memory performance profile updated",
+        profile=normalized,
+        scan_limit=config["scan_limit"],
+        process_limit=config["process_limit"],
+    )
+    return {"ok": True, "profile": normalized, "performance": config}
+
+
 def _root_initial_scan_key(root_id: int) -> str:
     return f"root:{int(root_id)}:initial_scan_complete"
 
@@ -1679,10 +1774,10 @@ def run_once(
     *,
     root: str | None = None,
     limit: int | None = None,
-    process_limit: int = 100,
-    live_asset_limit: int = DEFAULT_LIVE_ASSET_LIMIT,
-    live_dir_limit: int = DEFAULT_LIVE_DIR_LIMIT,
-    live_file_limit: int = DEFAULT_LIVE_FILE_LIMIT,
+    process_limit: int | None = None,
+    live_asset_limit: int | None = None,
+    live_dir_limit: int | None = None,
+    live_file_limit: int | None = None,
 ) -> dict:
     if _get_state("privacy_hygiene_v2", "0") != "1":
         local_index_privacy_hygiene(fix=True)
@@ -1694,14 +1789,20 @@ def run_once(
         ensure_default_roots()
     if root:
         add_root(root)
+    config = performance_config()
+    effective_scan_limit = int(limit if limit is not None else config["scan_limit"])
+    effective_process_limit = int(process_limit if process_limit is not None else config["process_limit"])
+    effective_live_asset_limit = int(live_asset_limit if live_asset_limit is not None else config["live_asset_limit"])
+    effective_live_dir_limit = int(live_dir_limit if live_dir_limit is not None else config["live_dir_limit"])
+    effective_live_file_limit = int(live_file_limit if live_file_limit is not None else config["live_file_limit"])
     conn = _conn()
     initial_before = _initial_scan_status(conn, list_roots())
     initial_index_before = _refresh_initial_index_complete(conn, initial_before)
     if initial_index_before:
         live_result = reconcile_live_changes(
-            asset_limit=live_asset_limit,
-            dir_limit=live_dir_limit,
-            file_limit=live_file_limit,
+            asset_limit=effective_live_asset_limit,
+            dir_limit=effective_live_dir_limit,
+            file_limit=effective_live_file_limit,
         )
     else:
         live_result = {
@@ -1711,8 +1812,8 @@ def run_once(
             "assets": {},
             "dirs": {},
         }
-    scan_result = scan_once(limit=limit)
-    job_result = process_jobs(limit=process_limit)
+    scan_result = scan_once(limit=effective_scan_limit)
+    job_result = process_jobs(limit=effective_process_limit)
     conn_after = _conn()
     initial_after = _initial_scan_status(conn_after, list_roots())
     active_after = _active_job_count(conn_after)
@@ -1724,6 +1825,14 @@ def run_once(
         "live": live_result,
         "scan": scan_result,
         "jobs": job_result,
+        "performance": {
+            "profile": config["profile"],
+            "scan_limit": effective_scan_limit,
+            "process_limit": effective_process_limit,
+            "live_asset_limit": effective_live_asset_limit,
+            "live_dir_limit": effective_live_dir_limit,
+            "live_file_limit": effective_live_file_limit,
+        },
     }
 
 
@@ -2083,6 +2192,7 @@ def status() -> dict:
     problem = _service_problem(service)
     service["healthy"] = problem is None
     service["state"] = "paused" if paused else ("attention" if problem else ("idle" if active_jobs == 0 and initial_index_complete else "indexing"))
+    performance = performance_config(conn=conn)
     problems = _problem_rows(conn)
     if problem:
         problems.insert(0, {
@@ -2098,10 +2208,10 @@ def status() -> dict:
         })
     if paused:
         phase = "paused"
-    elif problem:
-        phase = "service_attention"
     elif not initial_index_complete:
         phase = "initial_indexing"
+    elif problem:
+        phase = "service_attention"
     elif active_jobs == 0:
         phase = "idle"
     else:
@@ -2125,7 +2235,9 @@ def status() -> dict:
             "initial_discovery_complete": bool(initial_scan["complete"]),
             "initial_index_complete": bool(initial_index_complete),
             "index_mode": "watching_changes" if initial_index_complete else "initial_indexing",
+            "performance_profile": performance["profile"],
         },
+        "performance": performance,
         "initial_scan": initial_scan,
         "initial_index_complete": bool(initial_index_complete),
         "volumes": volumes,

package/src/plugins/recover.py

@@ -36,6 +36,7 @@ from db_guard import (
     EMPTY_DB_SIZE_BYTES,
     HOURLY_BACKUP_GLOB,
     MIN_REFERENCE_ROWS,
+    PROTECTED_TABLES,
     WIPE_THRESHOLD_PCT,
     db_looks_wiped,
     db_row_counts,
@@ -138,7 +139,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, CRITICAL_TABLES)
+        counts = db_row_counts(path, PROTECTED_TABLES)
         critical_rows = sum(v for v in counts.values() if isinstance(v, int))
     return {
         "path": str(path),
@@ -147,6 +148,7 @@ def _describe_backup(path: Path, kind: str) -> dict:
         "mtime": mtime,
         "size_bytes": size,
         "critical_rows": critical_rows,
+        "protected_rows": critical_rows,
         "row_counts": {k: v for k, v in counts.items() if v is not None},
         "is_usable": size > EMPTY_DB_SIZE_BYTES and critical_rows >= MIN_REFERENCE_ROWS,
     }
@@ -167,9 +169,16 @@ def _pick_source(entries: list[dict], explicit: str | None) -> tuple[Path | None
 
     if not entries:
         return None, "no backups found under NEXO_HOME/backups/"
-    for entry in entries:
-        if entry["is_usable"]:
-            return Path(entry["path"]), None
+    usable = [entry for entry in entries if entry["is_usable"]]
+    if usable:
+        best = max(
+            usable,
+            key=lambda entry: (
+                int(entry.get("protected_rows") or entry.get("critical_rows") or 0),
+                float(entry.get("mtime") or 0),
+            ),
+        )
+        return Path(best["path"]), None
     return None, "no usable backup with critical rows found"
 
 
@@ -206,8 +215,8 @@ def recover(
         "steps": [],
         "warnings": [],
         "errors": [],
-        "current_looks_wiped": db_looks_wiped(target_path),
-        "current_row_counts": {k: v for k, v in db_row_counts(target_path).items() if v is not None},
+        "current_looks_wiped": db_looks_wiped(target_path, PROTECTED_TABLES),
+        "current_row_counts": {k: v for k, v in db_row_counts(target_path, PROTECTED_TABLES).items() if v is not None},
     }
 
     # Step 1: pick source
@@ -231,7 +240,7 @@ def recover(
     result["source"] = str(chosen)
     result["steps"].append(f"chose source: {chosen}")
 
-    source_counts = db_row_counts(chosen)
+    source_counts = db_row_counts(chosen, PROTECTED_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:
@@ -308,7 +317,7 @@ def recover(
         return result
     result["steps"].append(f"restored {chosen.name} -> {target_path}")
 
-    valid, valid_err = validate_backup_matches_source(chosen, target_path)
+    valid, valid_err = validate_backup_matches_source(chosen, target_path, PROTECTED_TABLES)
     if not valid:
         result["errors"].append(f"post-restore validation failed: {valid_err}")
         if stopped_launchagents:
@@ -316,7 +325,7 @@ def recover(
         return result
     result["steps"].append("validated post-restore row counts")
 
-    final_counts = db_row_counts(target_path)
+    final_counts = db_row_counts(target_path, PROTECTED_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/update.py

@@ -32,27 +32,31 @@ except ModuleNotFoundError as exc:
     def is_duplicate_artifact_name(_path) -> bool:
         return False
 
-# db_guard landed in v5.5.5. When plugins/update.py is imported from a runtime
-# that still ships the v5.5.4 tree (e.g. mid-upgrade), the import will fail —
-# we fall back to no-op guards so the update can still complete and bring in
-# the fixed module on its own.
+# db_guard must be available before any DB-touching update runs. Desktop syncs
+# this file plus db_guard.py as a pair; if a stale runtime imports update.py
+# without a current guard, we abort instead of risking a local-memory wipe.
 try:
     from db_guard import (
         CRITICAL_TABLES,
         HOURLY_BACKUP_MAX_AGE,
         MIN_REFERENCE_ROWS,
+        PROTECTED_TABLES,
         WIPE_THRESHOLD_PCT,
         db_looks_wiped,
         db_row_counts,
         diff_row_counts,
+        find_best_hourly_backup,
         find_latest_hourly_backup,
         safe_sqlite_backup,
         validate_backup_matches_source,
     )
     _DB_GUARD_AVAILABLE = True
-except Exception:  # pragma: no cover - exercised only during mid-upgrade installs
+    _DB_GUARD_IMPORT_ERROR = ""
+except Exception as exc:  # pragma: no cover - exercised only during stale installs
     _DB_GUARD_AVAILABLE = False
+    _DB_GUARD_IMPORT_ERROR = str(exc)
     CRITICAL_TABLES = ()
+    PROTECTED_TABLES = ()
     HOURLY_BACKUP_MAX_AGE = 48 * 3600
     MIN_REFERENCE_ROWS = 50
     WIPE_THRESHOLD_PCT = 80
@@ -66,6 +70,9 @@ except Exception:  # pragma: no cover - exercised only during mid-upgrade instal
     def diff_row_counts(*_args, **_kwargs):  # type: ignore[misc]
         return None
 
+    def find_best_hourly_backup(*_args, **_kwargs):  # type: ignore[misc]
+        return None
+
     def find_latest_hourly_backup(*_args, **_kwargs):  # type: ignore[misc]
         return None
 
@@ -84,6 +91,13 @@ except Exception:  # pragma: no cover - exercised only during mid-upgrade instal
     def validate_backup_matches_source(*_args, **_kwargs):  # type: ignore[misc]
         return True, None
 
+REQUIRED_LOCAL_MEMORY_TABLES: tuple[str, ...] = (
+    "local_assets",
+    "local_chunks",
+    "local_embeddings",
+    "local_index_dirs",
+)
+
 # Code root is the parent of plugins/:
 # - source checkout: <repo>/src
 # - packaged runtime: <NEXO_HOME>
@@ -121,6 +135,7 @@ def _is_packaged_install() -> bool:
 NEXO_HOME = export_resolved_nexo_home()
 DATA_DIR = paths.data_dir()
 BACKUP_BASE = paths.backups_dir()
+TECHNICAL_BACKUP_KEEP = 5
 
 # In packaged installs, update.py lives at <NEXO_HOME>/plugins/update.py.
 _PACKAGED_INSTALL = _is_packaged_install()
@@ -129,6 +144,38 @@ SRC_DIR = CODE_ROOT
 PACKAGE_JSON = REPO_DIR / "package.json"
 
 
+def _rotate_backup_family(prefix: str, keep: int = TECHNICAL_BACKUP_KEEP) -> int:
+    """Rotate technical rollback directories for one backup prefix.
+
+    Cleanup is best-effort: update/rollback safety must never depend on
+    deleting old snapshots successfully.
+    """
+    if keep <= 0:
+        return 0
+    base = BACKUP_BASE
+    if not base.is_dir():
+        return 0
+    try:
+        candidates = [p for p in base.iterdir() if p.is_dir() and p.name.startswith(prefix)]
+    except Exception:
+        return 0
+    if len(candidates) <= keep:
+        return 0
+    try:
+        candidates.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+    except Exception:
+        return 0
+
+    removed = 0
+    for old in candidates[keep:]:
+        try:
+            shutil.rmtree(old)
+            removed += 1
+        except Exception:
+            continue
+    return removed
+
+
 def _venv_python_path(runtime_root: Path | None = None) -> Path:
     root = runtime_root or _nexo_home()
     if sys.platform == "win32":
@@ -344,6 +391,30 @@ def _check_dirty() -> str | None:
     return None
 
 
+def _db_guard_integrity_error() -> str | None:
+    """Return why DB protection is unsafe, or None when current guard is usable."""
+    if os.environ.get("NEXO_SKIP_WIPE_GUARD") == "1":
+        return None
+    primary_db = DATA_DIR / "nexo.db"
+    if not primary_db.is_file():
+        return None
+    if not _DB_GUARD_AVAILABLE:
+        return (
+            "DB protection module is not available; refusing to update while local memory may exist.\n"
+            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]
+    if missing:
+        return (
+            "DB protection module is stale; refusing to update because local memory tables are not protected.\n"
+            f"  missing tables: {', '.join(missing)}\n"
+            "Restart Desktop so it can sync the bundled Brain guard, then retry the update."
+        )
+    return None
+
+
 def _preflight_wipe_check() -> str | None:
     """Abort the update early if the primary DB already looks wiped.
 
@@ -360,25 +431,40 @@ def _preflight_wipe_check() -> str | None:
     """
     if os.environ.get("NEXO_SKIP_WIPE_GUARD") == "1":
         return None
+    guard_err = _db_guard_integrity_error()
+    if guard_err:
+        return guard_err
     primary_db = DATA_DIR / "nexo.db"
     if not primary_db.is_file():
         return None  # Nothing to protect; fresh install path.
-    if not db_looks_wiped(primary_db):
-        return None  # Populated DB — proceed.
-    reference = find_latest_hourly_backup(BACKUP_BASE)
+    reference = find_best_hourly_backup(
+        BACKUP_BASE,
+        tables=PROTECTED_TABLES,
+    ) or find_latest_hourly_backup(BACKUP_BASE, tables=PROTECTED_TABLES)
     if reference is None:
         return None  # No reference to compare against; cannot distinguish wipe from fresh install.
-    reference_counts = db_row_counts(reference)
+    reference_counts = db_row_counts(reference, PROTECTED_TABLES)
     reference_total = sum(v for v in reference_counts.values() if isinstance(v, int))
     if reference_total < MIN_REFERENCE_ROWS:
         return None  # Reference itself is near-empty; likely fresh install.
-    return (
-        "Primary DB appears wiped while a recent hourly backup still has real data.\n"
-        f"  nexo.db: {primary_db} (empty)\n"
-        f"  hourly backup: {reference} ({reference_total} critical rows)\n"
-        "Run `nexo recover` to restore from backup, then retry the update.\n"
-        "Set NEXO_SKIP_WIPE_GUARD=1 to override (only recommended during a deliberate reinstall)."
-    )
+    if db_looks_wiped(primary_db, PROTECTED_TABLES):
+        return (
+            "Primary DB appears wiped while a recent hourly backup still has real data.\n"
+            f"  nexo.db: {primary_db} (empty)\n"
+            f"  hourly backup: {reference} ({reference_total} protected rows)\n"
+            "Run `nexo recover` to restore from backup, then retry the update.\n"
+            "Set NEXO_SKIP_WIPE_GUARD=1 to override (only recommended during a deliberate reinstall)."
+        )
+    report = diff_row_counts(primary_db, reference, PROTECTED_TABLES)
+    if report.is_wipe():
+        return (
+            "Primary DB has lost protected data compared with the latest usable backup.\n"
+            f"  nexo.db: {primary_db}\n"
+            f"  backup: {reference} ({reference_total} protected rows)\n"
+            + "\n".join(report.summary_lines())
+            + "\nRun `nexo doctor --tier boot --plane database_real --fix` before updating."
+        )
+    return None
 
 
 def _row_count_regression(pre: dict[str, int | None], post: dict[str, int | None]) -> str | None:
@@ -391,7 +477,7 @@ def _row_count_regression(pre: dict[str, int | None], post: dict[str, int | None
     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))
-    for table in CRITICAL_TABLES:
+    for table in PROTECTED_TABLES:
         pre_v = pre.get(table)
         post_v = post.get(table)
         if pre_v is None or pre_v < 10:
@@ -439,12 +525,16 @@ def _backup_databases() -> tuple[str, str | None]:
         # 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, CRITICAL_TABLES)
+            valid, valid_err = validate_backup_matches_source(db_file, dest, PROTECTED_TABLES)
             if not valid:
                 return str(backup_dir), (
                     f"Backup of {db_file.name} did not preserve critical tables: {valid_err}"
                 )
 
+    try:
+        _rotate_backup_family("pre-update-")
+    except Exception:
+        pass
     return str(backup_dir), None
 
 
@@ -846,6 +936,10 @@ def _backup_code_tree() -> tuple[str | None, str | None]:
             shutil.copy2(vf, backup_dir / "version.json")
     except Exception as e:
         return None, f"Code tree backup failed: {e}"
+    try:
+        _rotate_backup_family("code-tree-")
+    except Exception:
+        pass
     return str(backup_dir), None
 
 

package/src/scripts/backfill_task_owner.py

@@ -43,6 +43,7 @@ from pathlib import Path
 
 DEFAULT_DB_PATH = Path.home() / ".nexo" / "runtime" / "data" / "nexo.db"
 DEFAULT_CALIBRATION = Path.home() / ".nexo" / "brain" / "calibration.json"
+BACKFILL_OWNER_BACKUP_KEEP = 5
 
 _WAITING_PHRASES = (
     r"esperando (?:respuesta|a\s+\w+|confirmaci[oó]n)",
@@ -256,9 +257,42 @@ def _backup_db(db_path: Path) -> Path:
     backup = db_path.parent.parent / "backups" / f"pre-backfill-owner-{ts}" / db_path.name
     backup.parent.mkdir(parents=True, exist_ok=True)
     shutil.copy2(db_path, backup)
+    _rotate_backup_family(backup.parent.parent)
     return backup
 
 
+def _rotate_backup_family(
+    backups_dir: Path,
+    prefix: str = "pre-backfill-owner-",
+    keep: int = BACKFILL_OWNER_BACKUP_KEEP,
+) -> int:
+    """Keep the newest technical backfill backups and prune older ones."""
+    if keep <= 0:
+        return 0
+    backups_dir = Path(backups_dir)
+    if not backups_dir.is_dir():
+        return 0
+    try:
+        candidates = [p for p in backups_dir.iterdir() if p.is_dir() and p.name.startswith(prefix)]
+    except Exception:
+        return 0
+    if len(candidates) <= keep:
+        return 0
+    try:
+        candidates.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+    except Exception:
+        return 0
+
+    removed = 0
+    for old in candidates[keep:]:
+        try:
+            shutil.rmtree(old)
+            removed += 1
+        except Exception:
+            continue
+    return removed
+
+
 def run(
     db_path: Path,
     calibration_path: Path,

package/src/scripts/nexo-local-index.py

@@ -37,11 +37,18 @@ LOG_DIR.mkdir(parents=True, exist_ok=True)
 LOG_FILE = LOG_DIR / "local-index.log"
 LOCK_FILE = LOG_DIR / "local-index.lock"
 LOCK_STALE_SECONDS = int(os.environ.get("NEXO_LOCAL_INDEX_LOCK_STALE_SECONDS", "1800") or "1800")
-SCAN_LIMIT = int(os.environ.get("NEXO_LOCAL_INDEX_SCAN_LIMIT", "1000") or "1000")
-PROCESS_LIMIT = int(os.environ.get("NEXO_LOCAL_INDEX_PROCESS_LIMIT", "200") or "200")
-LIVE_ASSET_LIMIT = int(os.environ.get("NEXO_LOCAL_INDEX_LIVE_ASSET_LIMIT", "2000") or "2000")
-LIVE_DIR_LIMIT = int(os.environ.get("NEXO_LOCAL_INDEX_LIVE_DIR_LIMIT", "300") or "300")
-LIVE_FILE_LIMIT = int(os.environ.get("NEXO_LOCAL_INDEX_LIVE_FILE_LIMIT", "1000") or "1000")
+
+
+def _optional_env_int(name: str) -> int | None:
+    value = os.environ.get(name, "").strip()
+    if not value:
+        return None
+    try:
+        parsed = int(value)
+    except ValueError:
+        log(f"Ignoring invalid integer env {name}={value!r}.")
+        return None
+    return parsed if parsed > 0 else None
 
 
 def log(message: str) -> None:
@@ -114,14 +121,19 @@ def release_lock() -> None:
         pass
 
 
-def _run_index_cycle() -> dict:
+def _run_single_index_cycle(config: dict) -> dict:
+    scan_limit = _optional_env_int("NEXO_LOCAL_INDEX_SCAN_LIMIT") or int(config["scan_limit"])
+    process_limit = _optional_env_int("NEXO_LOCAL_INDEX_PROCESS_LIMIT") or int(config["process_limit"])
+    live_asset_limit = _optional_env_int("NEXO_LOCAL_INDEX_LIVE_ASSET_LIMIT") or int(config["live_asset_limit"])
+    live_dir_limit = _optional_env_int("NEXO_LOCAL_INDEX_LIVE_DIR_LIMIT") or int(config["live_dir_limit"])
+    live_file_limit = _optional_env_int("NEXO_LOCAL_INDEX_LIVE_FILE_LIMIT") or int(config["live_file_limit"])
     try:
         return api.run_once(
-            limit=SCAN_LIMIT,
-            process_limit=PROCESS_LIMIT,
-            live_asset_limit=LIVE_ASSET_LIMIT,
-            live_dir_limit=LIVE_DIR_LIMIT,
-            live_file_limit=LIVE_FILE_LIMIT,
+            limit=scan_limit,
+            process_limit=process_limit,
+            live_asset_limit=live_asset_limit,
+            live_dir_limit=live_dir_limit,
+            live_file_limit=live_file_limit,
         )
     except TypeError as exc:
         message = str(exc)
@@ -135,7 +147,28 @@ def _run_index_cycle() -> dict:
             error=message,
         )
         log(f"Compatibility fallback: api.run_once does not accept live reconcile limits ({message}).")
-        return api.run_once(limit=SCAN_LIMIT, process_limit=PROCESS_LIMIT)
+        return api.run_once(limit=scan_limit, process_limit=process_limit)
+
+
+def _run_index_cycle() -> dict:
+    config = api.performance_config()
+    cycles = _optional_env_int("NEXO_LOCAL_INDEX_CYCLES_PER_RUN") or int(config.get("cycles_per_run") or 1)
+    results = []
+    ok = True
+    for _index in range(max(1, cycles)):
+        result = _run_single_index_cycle(config)
+        results.append(result)
+        ok = ok and bool(result.get("ok"))
+        paused = bool(result.get("paused") or result.get("scan", {}).get("paused") or result.get("jobs", {}).get("paused"))
+        if paused or not result.get("ok"):
+            break
+    return {
+        "ok": ok,
+        "profile": config["profile"],
+        "cycles": len(results),
+        "result": results[-1] if results else {},
+        "results": results,
+    }
 
 
 def main() -> int:

package/src/scripts/prune_runtime_backups.py

@@ -33,7 +33,7 @@ Class taxonomy (prefix-based) and retention policy:
       retired-personal-scripts-*, retired-personal-skills-*,
       runtime-core-sync-*, pre-freshinstall-*
     Retention (per prefix family): keep last N_RECENT + 1 per month for
-    MONTHLY_WINDOW_DAYS. Older than that and outside the 10 most recent
+    MONTHLY_WINDOW_DAYS. Older than that and outside the recent window
     are eligible for deletion.
 
   HOURLY_DB (sqlite dumps, managed by nexo-backup.sh):
@@ -51,7 +51,7 @@ Usage:
   prune_runtime_backups.py                 # dry-run summary
   prune_runtime_backups.py --apply         # actually delete
   prune_runtime_backups.py --json          # machine-readable report
-  prune_runtime_backups.py --recent 10     # override N_RECENT
+  prune_runtime_backups.py --recent 5      # override N_RECENT
   prune_runtime_backups.py --window-days 90
   prune_runtime_backups.py --only pre-backfill-owner  # restrict family
 
@@ -361,7 +361,7 @@ def main() -> int:
     ap.add_argument("--root", help="override runtime/backups path")
     ap.add_argument("--apply", action="store_true", help="actually delete (default is dry-run)")
     ap.add_argument("--json", action="store_true", help="machine-readable report")
-    ap.add_argument("--recent", type=int, default=10, help="N most recent per family to always keep (default: 10)")
+    ap.add_argument("--recent", type=int, default=5, help="N most recent per family to always keep (default: 5)")
     ap.add_argument("--window-days", type=int, default=90, help="month-spaced retention window (default: 90)")
     ap.add_argument("--only", help="restrict to one technical family (e.g. 'pre-backfill-owner')")
     args = ap.parse_args()

package/src/server.py

@@ -629,14 +629,21 @@ def nexo_local_index_status() -> str:
 
 
 @mcp.tool
-def nexo_local_index_control(action: str = "run_once", root: str = "", limit: int = 0, process_limit: int = 100) -> str:
+def nexo_local_index_control(
+    action: str = "run_once",
+    root: str = "",
+    limit: int = 0,
+    process_limit: int = 0,
+    performance_profile: str = "",
+) -> str:
     """Control the local memory index.
 
     Args:
-        action: one of run_once, pause, resume, clear_index.
+        action: one of run_once, pause, resume, clear_index, set_performance.
         root: optional folder to add and scan when action=run_once.
         limit: optional per-root scan limit for cooperative background cycles.
         process_limit: max pending jobs to process in this cycle.
+        performance_profile: low, medium, high or extreme when action=set_performance.
     """
     normalized = str(action or "run_once").strip().lower()
     if normalized == "pause":
@@ -645,10 +652,12 @@ def nexo_local_index_control(action: str = "run_once", root: str = "", limit: in
         result = local_context_api.resume()
     elif normalized == "clear_index":
         result = local_context_api.clear_index()
+    elif normalized == "set_performance":
+        result = local_context_api.set_performance_profile(performance_profile)
     elif normalized == "run_once":
-        result = local_context_api.run_once(root=root or None, limit=limit or None, process_limit=process_limit)
+        result = local_context_api.run_once(root=root or None, limit=limit or None, process_limit=process_limit or None)
     else:
-        result = {"ok": False, "error": "unknown_action", "allowed": ["run_once", "pause", "resume", "clear_index"]}
+        result = {"ok": False, "error": "unknown_action", "allowed": ["run_once", "pause", "resume", "clear_index", "set_performance"]}
     return json.dumps(result, ensure_ascii=False)