nexo-brain 5.5.5 → 5.5.6

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.5.5",
+  "version": "5.5.6",
   "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 `5.5.5` is the current packaged-runtime line: data-loss guardrails + automatic self-heal. The updater now refuses to capture an already-wiped `nexo.db` into a `pre-update-*` snapshot (validated `sqlite3.backup` + pre-flight wipe guard + post-migration row-count gate), and an auto-heal restores `data/nexo.db` from the newest hourly backup on the next server boot when a wipe is detected. New `nexo recover` CLI + `nexo_recover` MCP tool.
+Version `5.5.6` is the current packaged-runtime line: same-day follow-up to v5.5.5 that adds in-process rate-limits to `nexo_backup_now` (30 s), `nexo_backup_restore` (60 s), and `export_user_bundle` (120 s) so a runaway MCP client can no longer hammer `sqlite3.Connection.backup()` from a tool-use loop — closing the cause of the 2026-04-16 incident the same day v5.5.5 closed its consequences.
+
+Previously in `5.5.5`: data-loss guardrails + automatic self-heal. The updater now refuses to capture an already-wiped `nexo.db` into a `pre-update-*` snapshot (validated `sqlite3.backup` + pre-flight wipe guard + post-migration row-count gate), and an auto-heal restores `data/nexo.db` from the newest hourly backup on the next server boot when a wipe is detected. New `nexo recover` CLI + `nexo_recover` MCP tool.
 
 Previously in `5.5.4`: Deep Sleep no longer blocks on unparseable sessions — reduced retries, added a JSON escape hatch, and unified the automation subprocess timeout to 3h across all scripts via a single shared constant.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.5.5",
+  "version": "5.5.6",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO Brain \u2014 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/plugins/backup.py

@@ -1,8 +1,20 @@
-"""Backup plugin — hourly SQLite backups with 7-day retention."""
+"""Backup plugin — hourly SQLite backups with 7-day retention.
+
+v5.5.6: all three tools are rate-limited in-process so that a runaway MCP
+client (tool-use loop in Claude Code, buggy Desktop handler, etc.) cannot
+hammer ``sqlite3.Connection.backup()`` hundreds of times in minutes. The
+v5.5.4 incident where an external loop caused ~8.5 GB of file-backed writes
+in 37 minutes and corrupted nexo.db when the OS finally killed the process
+is the exact scenario this limit prevents at the tool boundary — in addition
+to the v5.5.5 self-heal that recovers from that class of wipe.
+"""
+import glob
 import os
 import shutil
+import sqlite3
+import threading
 import time
-import glob
+
 from db import get_db
 
 NEXO_HOME = os.environ.get("NEXO_HOME", os.path.expanduser("~/.nexo"))
@@ -11,15 +23,63 @@ BACKUP_DIR = os.path.join(NEXO_HOME, "backups")
 
 RETENTION_DAYS = 7
 
+# ── Rate limits (v5.5.6) ────────────────────────────────────────────
+# Minimum seconds between successive calls to each destructive/expensive
+# backup tool. Overridable per-tool via env var for tests or deliberate
+# recovery scenarios (NEXO_BACKUP_MIN_INTERVAL_SECS, etc.).
+BACKUP_NOW_MIN_INTERVAL_SECS = int(
+    os.environ.get("NEXO_BACKUP_MIN_INTERVAL_SECS", "30")
+)
+BACKUP_RESTORE_MIN_INTERVAL_SECS = int(
+    os.environ.get("NEXO_BACKUP_RESTORE_MIN_INTERVAL_SECS", "60")
+)
+
+_rate_limit_lock = threading.Lock()
+_last_call_ts: dict[str, float] = {
+    "backup_now": 0.0,
+    "backup_restore": 0.0,
+}
+
+
+def _check_rate_limit(tool: str, min_interval: int) -> str | None:
+    """Return a rate-limit error string if the tool is called too soon, else None."""
+    now = time.time()
+    with _rate_limit_lock:
+        last = _last_call_ts.get(tool, 0.0)
+        elapsed = now - last
+        if last > 0 and elapsed < min_interval:
+            remaining = int(min_interval - elapsed)
+            return (
+                f"Rate-limited: {tool} called {int(elapsed)}s ago "
+                f"(min {min_interval}s between calls). Wait {remaining}s. "
+                "If you are seeing this message repeatedly, a client may be stuck in a "
+                "tool-use loop — check NEXO transcripts and kill the runaway session."
+            )
+        _last_call_ts[tool] = now
+    return None
+
+
+def _reset_rate_limit_state_for_tests() -> None:
+    """Test hook: clear all tracked call timestamps."""
+    with _rate_limit_lock:
+        for key in _last_call_ts:
+            _last_call_ts[key] = 0.0
+
 
 def handle_backup_now() -> str:
-    """Create an immediate backup of the NEXO database."""
+    """Create an immediate backup of the NEXO database.
+
+    Rate-limited to one call every BACKUP_NOW_MIN_INTERVAL_SECS (default 30 s).
+    """
+    err = _check_rate_limit("backup_now", BACKUP_NOW_MIN_INTERVAL_SECS)
+    if err is not None:
+        return err
+
     os.makedirs(BACKUP_DIR, exist_ok=True)
     timestamp = time.strftime("%Y-%m-%d-%H%M")
     dest = os.path.join(BACKUP_DIR, f"nexo-{timestamp}.db")
 
     # Use SQLite backup API for consistency
-    import sqlite3
     src_conn = sqlite3.connect(DB_PATH)
     try:
         dst_conn = sqlite3.connect(dest)
@@ -56,16 +116,23 @@ def handle_backup_list() -> str:
 def handle_backup_restore(filename: str) -> str:
     """Restore database from a backup file. DESTRUCTIVE — replaces current DB.
 
+    Rate-limited to one call every BACKUP_RESTORE_MIN_INTERVAL_SECS (default
+    60 s). A client hammering restore in a loop is the exact shape of the
+    v5.5.4 incident.
+
     Args:
         filename: Backup filename (e.g., 'nexo-2026-03-11-1200.db')
     """
+    err = _check_rate_limit("backup_restore", BACKUP_RESTORE_MIN_INTERVAL_SECS)
+    if err is not None:
+        return err
+
     src = os.path.join(BACKUP_DIR, filename)
     if not os.path.isfile(src):
         return f"Backup not found: {filename}"
 
     # Create safety backup first
     safety = os.path.join(BACKUP_DIR, f"nexo-pre-restore-{time.strftime('%Y%m%d%H%M%S')}.db")
-    import sqlite3
     src_conn = sqlite3.connect(DB_PATH)
     try:
         dst_conn = sqlite3.connect(safety)

package/src/user_data_portability.py

@@ -8,6 +8,8 @@ import shutil
 import sqlite3
 import tarfile
 import tempfile
+import threading
+import time
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -23,6 +25,36 @@ IGNORED_FILENAMES = {".DS_Store"}
 IGNORED_DIRS = {"__pycache__"}
 IGNORED_SUFFIXES = {".pyc", ".pyo"}
 
+# v5.5.6: rate-limit the whole-bundle export so a runaway MCP client cannot
+# loop this tool. Each export snapshots the entire NEXO state through
+# sqlite3.Connection.backup() plus a tree copy — in the v5.5.4 incident a
+# similar loop wrote 8.5 GB in 37 minutes. Overridable for tests / deliberate
+# batch exports via NEXO_EXPORT_MIN_INTERVAL_SECS.
+EXPORT_MIN_INTERVAL_SECS = int(os.environ.get("NEXO_EXPORT_MIN_INTERVAL_SECS", "120"))
+_export_rate_lock = threading.Lock()
+_export_last_call_ts = [0.0]
+
+
+def _check_export_rate_limit() -> str | None:
+    now = time.time()
+    with _export_rate_lock:
+        last = _export_last_call_ts[0]
+        elapsed = now - last
+        if last > 0 and elapsed < EXPORT_MIN_INTERVAL_SECS:
+            remaining = int(EXPORT_MIN_INTERVAL_SECS - elapsed)
+            return (
+                f"Rate-limited: export_user_bundle called {int(elapsed)}s ago "
+                f"(min {EXPORT_MIN_INTERVAL_SECS}s between calls). Wait {remaining}s. "
+                "If you see this repeatedly, a client may be stuck in a tool-use loop."
+            )
+        _export_last_call_ts[0] = now
+    return None
+
+
+def _reset_export_rate_limit_state_for_tests() -> None:
+    with _export_rate_lock:
+        _export_last_call_ts[0] = 0.0
+
 
 def _now_stamp() -> str:
     return datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
@@ -137,6 +169,9 @@ def _load_personal_scripts() -> tuple[list[dict], list[dict]]:
 
 
 def export_user_bundle(output_path: str = "") -> dict:
+    err = _check_export_rate_limit()
+    if err is not None:
+        return {"ok": False, "error": err, "rate_limited": True}
     output = Path(output_path).expanduser() if output_path.strip() else (EXPORTS_DIR / f"nexo-user-data-{_now_stamp()}.tar.gz")
     output.parent.mkdir(parents=True, exist_ok=True)
     STAGING_DIR.mkdir(parents=True, exist_ok=True)