nexo-brain 5.0.4 → 5.1.0

package/.claude-plugin/plugin.json

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

@@ -87,6 +87,18 @@ Versions `3.1.7` through `3.2.0` close the recent-memory gap:
 - when even that misses, NEXO now exposes raw transcript fallback tools for Claude Code and Codex session stores
 - NEXO can now inspect itself through a live system catalog derived from canonical sources instead of relying only on stale docs or operator memory
 
+Version `5.1.0` lands the full NEXO-AUDIT-2026-04-11 roadmap as a single minor bump — every open evolution / adaptive / cognitive / skills loop now closes under itself, the knowledge graph exports cleanly, OpenTelemetry spans can be turned on without a hard dependency, and every PR has to clear lint, security, coverage, and release-readiness gates before it can merge:
+
+- Evolution cycle now auto-applies user-approved proposals on the next run (backed by the new idempotent migration `m38`), adaptive learned-weight rollbacks surface as visible followups, outcome patterns auto-promote to draft skills, and a Voyager-style detector exposes co-occurring skill pairs as composite-skill candidates via `nexo_skill_compose_candidates`.
+- `cognitive._search.search()` now accepts `dream_weight` and reranks dream-insights through it, somatic markers fold into the same reranking path (max +0.10 boost), state watchers open and auto-resolve deterministic `NF-WATCHER-{id}` followups, and correction fatigue opens a visible followup instead of only decaying memory.
+- A new Cortex quality cron (every 6h) watches accept rate / linked-success / override gap and opens `NF-CORTEX-QUALITY-DROP` idempotently when the decision engine starts drifting between cycles.
+- Adding a new learning now walks recent decisions through `retroactive_learnings.apply_learning_retroactively()` and opens deterministic `NF-RETRO-L<id>-D<id>` followups for every decision the learning would have changed (exposed via `nexo_learning_apply_retroactively`).
+- Hook lifecycle observability: new `hook_runs` table (migration `m39`) + `nexo_hook_runs` tool expose recent hook runs, failure streaks, and a health summary. Hook drops are no longer invisible.
+- Knowledge graph bitemporal export: `nexo_kg_export` emits JSON-LD (with an `nexo:*` vocabulary) or GraphML, and accepts an `as_of` ISO timestamp that replays the historical snapshot through `kg_edges.valid_from / valid_until` for igraph, Gephi, NetworkX, and Cytoscape.
+- OpenTelemetry integration: new `src/observability.py` soft-imports `opentelemetry` and only activates when `OTEL_EXPORTER_OTLP_ENDPOINT` or `OTEL_SERVICE_NAME` is set. `tool_span()` becomes a real span when enabled and stays a no-op context manager when disabled.
+- CI gates on every PR: new workflows enforce ruff (`E9 / F63 / F7 / F82 / F821`), bandit at high severity / high confidence, coverage baselines, and `verify_release_readiness.py --ci`. A PR that breaks the release contract fails loudly instead of waiting until tag push.
+- Safer update path: `auto_update` is guarded by a POSIX `flock` with stale-steal at 10 minutes, and on macOS it now `launchctl unload`s and reloads every `com.nexo.*.plist` after a version bump so long-lived crons pick up the new codebase immediately.
+
 Version `5.0.4` tightens the local runtime bridge and trims false-positive doctor noise:
 
 - vendorable `nexo_helper.py` now resolves `NEXO_HOME` and the `nexo` CLI path robustly, so personal scripts and subprocess flows stop depending on a lucky PATH

package/package.json

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

@@ -355,6 +355,137 @@ def _sync_crons():
         _log(f"Cron sync warning: {e}")
 
 
+def _reload_launch_agents_after_bump() -> dict:
+    """Unload+load NEXO LaunchAgents so they pick up the new code on next fire.
+
+    Closes Bloque D of NEXO-AUDIT-2026-04-11 (learning #186 from Fase 1).
+    Until this helper, `nexo update` would `git pull` the new code into
+    NEXO_CODE but the 40+ LaunchAgents already running held the old
+    Python modules in memory until macOS happened to restart them. With
+    a single function call we explicitly tell launchd to reload the
+    plist files so the next fire reads the fresh code.
+
+    Best-effort throughout — a failure here must NEVER block the update
+    that just succeeded. Returns a dict with what was attempted so the
+    caller can log a single summary line.
+
+    Returns:
+        {
+          "scanned": N,        # plists found in ~/Library/LaunchAgents
+          "reloaded": N,       # plists where unload+load both succeeded
+          "skipped_missing": N, # plist file vanished mid-scan
+          "errors": [{plist, stderr}],
+        }
+
+    Linux equivalent: systemctl --user daemon-reload + restart of timer
+    units. Implemented as a no-op stub on Linux for now (the macOS
+    LaunchAgent path is the production target — Linux users running
+    `nexo update` get the cron sync but not the per-timer restart yet).
+    Captured as a TODO for the next round.
+    """
+    result: dict = {
+        "scanned": 0,
+        "reloaded": 0,
+        "skipped_missing": 0,
+        "errors": [],
+        "platform": sys.platform,
+    }
+
+    if sys.platform != "darwin":
+        # macOS-only for now. systemd path tracked separately.
+        return result
+
+    launch_agents_dir = Path.home() / "Library" / "LaunchAgents"
+    if not launch_agents_dir.is_dir():
+        return result
+
+    try:
+        plists = sorted(launch_agents_dir.glob("com.nexo.*.plist"))
+    except Exception as e:
+        result["errors"].append({"plist": "*", "stderr": f"glob failed: {e}"})
+        return result
+
+    result["scanned"] = len(plists)
+    for plist in plists:
+        try:
+            if not plist.is_file():
+                result["skipped_missing"] += 1
+                continue
+            # launchctl bootout / bootstrap is the modern API but requires
+            # the GUI session id ($UID/Background or gui/$UID). The legacy
+            # unload + load -w pair still works on every macOS NEXO supports
+            # and does not need a session id, so we use it here.
+            unload_proc = subprocess.run(
+                ["launchctl", "unload", str(plist)],
+                capture_output=True, text=True, timeout=10,
+            )
+            # unload returns non-zero if the agent was not loaded — that
+            # is fine, we still try to load fresh.
+            load_proc = subprocess.run(
+                ["launchctl", "load", "-w", str(plist)],
+                capture_output=True, text=True, timeout=10,
+            )
+            if load_proc.returncode == 0:
+                result["reloaded"] += 1
+            else:
+                result["errors"].append({
+                    "plist": plist.name,
+                    "stderr": (load_proc.stderr or load_proc.stdout or "load failed")[:300],
+                })
+        except subprocess.TimeoutExpired:
+            result["errors"].append({"plist": plist.name, "stderr": "launchctl timeout"})
+        except Exception as e:
+            result["errors"].append({"plist": plist.name, "stderr": str(e)[:300]})
+
+    return result
+
+
+AUTO_UPDATE_BACKUP_KEEP = 10
+"""Maximum number of auto-update backups to keep per prefix.
+
+Both `pre-autoupdate-*/` (DB snapshots) and `runtime-tree-*/` (code mirrors)
+were accumulating indefinitely, growing to tens of GB on long-running
+installs. Rotating to the N most recent keeps a meaningful rollback window
+without unbounded disk use."""
+
+
+def _rotate_auto_update_backups(prefix: str, keep: int = AUTO_UPDATE_BACKUP_KEEP) -> int:
+    """Delete old auto-update backup directories matching a prefix, keeping `keep` most recent.
+
+    Silent on failures — cleanup must never interrupt the auto-update flow.
+    Returns number of entries removed (0 on failure or nothing to prune).
+    """
+    if keep <= 0:
+        return 0
+    base = NEXO_HOME / "backups"
+    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 as e:
+        _log(f"Backup rotation scan warning ({prefix}): {e}")
+        return 0
+    if len(candidates) <= keep:
+        return 0
+    # Newest first by modification time, then delete everything beyond `keep`
+    try:
+        candidates.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+    except Exception as e:
+        _log(f"Backup rotation sort warning ({prefix}): {e}")
+        return 0
+    removed = 0
+    import shutil as _shutil
+    for old in candidates[keep:]:
+        try:
+            _shutil.rmtree(str(old))
+            removed += 1
+        except Exception as e:
+            _log(f"Backup rotation remove warning ({old.name}): {e}")
+    if removed:
+        _log(f"Rotated {removed} old {prefix}* backup(s), kept {keep} most recent")
+    return removed
+
+
 def _backup_dbs() -> str | None:
     """Snapshot all .db files before migration. Returns backup dir or None."""
     import sqlite3
@@ -388,6 +519,14 @@ def _backup_dbs() -> str | None:
                         conn.close()
                     except Exception:
                         pass
+    # Opportunistic rotation: keep only the N most recent pre-autoupdate dirs.
+    # Failures here must never bubble up — the caller depends on the backup
+    # path string for rollback and should not see spurious exceptions from
+    # housekeeping of older entries.
+    try:
+        _rotate_auto_update_backups("pre-autoupdate-")
+    except Exception as e:
+        _log(f"Backup rotation warning (pre-autoupdate): {e}")
     return str(backup_dir)
 
 
@@ -531,6 +670,28 @@ def _check_git_updates() -> str | None:
     # Sync cron definitions with manifest
     _sync_crons()
 
+    # Bloque D / learning #186: when the package version actually
+    # changed, reload the LaunchAgents so the 40+ background crons
+    # pick up the new code on their next fire instead of holding the
+    # old Python modules in memory until macOS happens to restart them.
+    # Best-effort — never blocks the update flow.
+    if old_version != new_version:
+        try:
+            reload_summary = _reload_launch_agents_after_bump()
+            if reload_summary.get("reloaded"):
+                _log(
+                    f"Reloaded {reload_summary['reloaded']}/{reload_summary['scanned']} "
+                    f"NEXO LaunchAgents after version bump"
+                    + (f" ({len(reload_summary['errors'])} errors)" if reload_summary["errors"] else "")
+                )
+            elif reload_summary.get("scanned"):
+                _log(
+                    f"LaunchAgent reload after bump: scanned {reload_summary['scanned']}, "
+                    f"reloaded 0, errors {len(reload_summary['errors'])}"
+                )
+        except Exception as e:
+            _log(f"LaunchAgent reload after bump failed: {e}")
+
     msg = f"Auto-updated: {old_version} -> {new_version}" if old_version != new_version else f"Auto-updated (v{new_version}, new commits)"
     _log(msg)
     return msg
@@ -873,6 +1034,101 @@ def _sync_client_bootstraps(preferences: dict | None = None) -> list[str]:
 
 # ── Main entry point ─────────────────────────────────────────────────
 
+_AUTO_UPDATE_LOCK_FILE = NEXO_HOME / "operations" / ".auto_update.lock"
+_AUTO_UPDATE_LOCK_STALE_SECONDS = 600  # 10 minutes
+
+
+def _acquire_auto_update_lock() -> tuple[bool, object | None, str]:
+    """Acquire an exclusive non-blocking lock on the auto_update lockfile.
+
+    Closes NF-AUDIT-2026-04-11-UPDATE-LOCK. Two NEXO terminals starting at
+    the same moment after a version bump used to race on
+    auto_update_check(): they would both run run_migrations(),
+    _check_git_updates(), and the file/hooks sync, occasionally tripping
+    UNIQUE constraints on schema_migrations or producing torn writes on
+    shared files.
+
+    The lock uses fcntl.flock(LOCK_EX | LOCK_NB) so the second caller
+    returns instantly with a clean "skipped_reason=locked_by_other_process"
+    rather than blocking the server startup. The lock file persists across
+    crashes — we treat any lock older than 10 minutes as stale and steal
+    it, so a hard kill mid-update never wedges future runs forever.
+
+    Returns:
+        (acquired, fh, reason)
+        - acquired: True if we now hold the lock, False otherwise.
+        - fh: the open file handle (caller MUST close it after release).
+        - reason: human-readable explanation when not acquired.
+    """
+    try:
+        _AUTO_UPDATE_LOCK_FILE.parent.mkdir(parents=True, exist_ok=True)
+    except Exception as e:
+        return False, None, f"cannot create lock directory: {e}"
+
+    # Steal stale locks: if the lockfile exists and was last modified more
+    # than 10 minutes ago, assume the previous holder crashed and reset it.
+    try:
+        if _AUTO_UPDATE_LOCK_FILE.exists():
+            age = time.time() - _AUTO_UPDATE_LOCK_FILE.stat().st_mtime
+            if age > _AUTO_UPDATE_LOCK_STALE_SECONDS:
+                try:
+                    _AUTO_UPDATE_LOCK_FILE.unlink()
+                except Exception:
+                    pass  # Will fall through to the open below
+    except Exception:
+        pass
+
+    try:
+        fh = open(_AUTO_UPDATE_LOCK_FILE, "a+")
+    except Exception as e:
+        return False, None, f"cannot open lock file: {e}"
+
+    try:
+        import fcntl
+        fcntl.flock(fh.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except ImportError:
+        # Non-POSIX platform. Best-effort: write a PID stamp and proceed.
+        try:
+            fh.seek(0)
+            fh.truncate()
+            fh.write(f"{os.getpid()}:{time.time()}\n")
+            fh.flush()
+        except Exception:
+            pass
+        return True, fh, ""
+    except (OSError, BlockingIOError):
+        try:
+            fh.close()
+        except Exception:
+            pass
+        return False, None, "locked_by_other_process"
+
+    # We have the lock. Stamp PID + timestamp so observers can see who.
+    try:
+        fh.seek(0)
+        fh.truncate()
+        fh.write(f"{os.getpid()}:{time.time()}\n")
+        fh.flush()
+    except Exception:
+        pass
+    return True, fh, ""
+
+
+def _release_auto_update_lock(fh: object | None) -> None:
+    """Release the lock acquired by _acquire_auto_update_lock and close the fd."""
+    if fh is None:
+        return
+    try:
+        import fcntl
+        fcntl.flock(fh.fileno(), fcntl.LOCK_UN)  # type: ignore[attr-defined]
+    except Exception:
+        pass
+    try:
+        fh.close()  # type: ignore[attr-defined]
+    except Exception:
+        pass
+
+
 def auto_update_check() -> dict:
     """Run the full auto-update check at server startup.
 
@@ -887,6 +1143,12 @@ def auto_update_check() -> dict:
         - git fetch/pull (if git repo)
         - npm version check (if non-git install)
 
+    Concurrency:
+        Wrapped in a non-blocking exclusive flock so a second concurrent
+        terminal returns instantly with skipped_reason='locked_by_other_process'
+        instead of racing on run_migrations / git pull / file sync. Stale
+        locks (>10 minutes) are auto-stolen.
+
     Returns a dict with:
         - checked: bool — whether a network check was actually performed
         - git_update: str|None — git update status message
@@ -895,9 +1157,30 @@ def auto_update_check() -> dict:
         - client_bootstrap_updates: list[str] — Codex/Claude bootstrap sync statuses
         - migrations: list — file-based migration results
         - db_migrations: int — number of DB schema migrations applied
-        - skipped_reason: str|None — why the network check was skipped (cooldown, etc.)
+        - skipped_reason: str|None — why the network check was skipped (cooldown, locked, etc.)
         - error: str|None — error message if something failed (informational only)
     """
+    acquired, lock_fh, lock_reason = _acquire_auto_update_lock()
+    if not acquired:
+        return {
+            "checked": False,
+            "git_update": None,
+            "npm_notice": None,
+            "claude_md_update": None,
+            "client_bootstrap_updates": [],
+            "migrations": [],
+            "db_migrations": 0,
+            "skipped_reason": lock_reason or "locked_by_other_process",
+            "error": None,
+        }
+    try:
+        return _auto_update_check_locked()
+    finally:
+        _release_auto_update_lock(lock_fh)
+
+
+def _auto_update_check_locked() -> dict:
+    """Inner body of auto_update_check, executed while holding the lockfile."""
     result = {
         "checked": False,
         "git_update": None,
@@ -1315,6 +1598,13 @@ def _backup_runtime_tree(dest: Path = NEXO_HOME) -> str:
     if (dest / "bin").is_dir():
         import shutil
         shutil.copytree(str(dest / "bin"), str(backup_dir / "bin"), dirs_exist_ok=True)
+    # Opportunistic rotation: runtime-tree snapshots were accumulating forever
+    # because nothing ever pruned them. Keep only the N most recent; failures
+    # must never block the runtime-tree caller's rollback flow.
+    try:
+        _rotate_auto_update_backups("runtime-tree-")
+    except Exception as e:
+        _log(f"Backup rotation warning (runtime-tree): {e}")
     return str(backup_dir)
 
 

package/src/cognitive/_ingest.py

@@ -353,8 +353,10 @@ def prediction_error_gate(
 
     if best_score > threshold:
         # Check for siblings before rejecting -- if discriminating entities differ,
-        # this is NOT a duplicate, it's a sibling (same fix for different platforms)
+        # this is NOT a duplicate, it's a sibling (same fix for different platforms).
+        # Lazy import to avoid the cognitive._memory <-> cognitive._ingest cycle.
         if best_match:
+            from cognitive._memory import _memories_are_siblings
             is_sibling, discriminators = _memories_are_siblings(content, best_match["content"])
             if is_sibling:
                 _gate_stats["accepted_novel"] += 1

package/src/cognitive/_memory.py

@@ -1,4 +1,5 @@
 """NEXO Cognitive — Memory operations: format, stats, consolidation, somatic."""
+import base64
 import json, math, re
 import numpy as np
 from datetime import datetime, timedelta, timezone
@@ -9,7 +10,10 @@ def _utcnow_naive() -> datetime:
     the legacy ``datetime.utcnow()`` string format on disk.
     """
     return datetime.now(timezone.utc).replace(tzinfo=None)
-from cognitive._core import _get_db, embed, cosine_similarity, _blob_to_array, _array_to_blob, EMBEDDING_DIM, DISCRIMINATING_ENTITIES
+from cognitive._core import (
+    _get_db, embed, cosine_similarity, _blob_to_array, _array_to_blob,
+    EMBEDDING_DIM, DISCRIMINATING_ENTITIES, redact_secrets,
+)
 from cognitive._ingest import _sanitize_memory_content
 
 

package/src/cognitive/_search.py

@@ -278,6 +278,82 @@ def _result_confidence(score: float) -> str:
 # (structural) worlds.
 # ============================================================================
 
+def _somatic_boost_results(results: list[dict], max_boost: float = 0.10) -> list[dict]:
+    """Boost search results that touch high-risk somatic targets.
+
+    Closes Fase 3 item 2 of NEXO-AUDIT-2026-04-11. The somatic_markers table
+    is populated by guard hits, error_repetition events, and learning_add
+    side effects (see _memory.py:somatic_*). Until this function existed,
+    that risk signal was never used to influence retrieval — a memory
+    touching a known-painful area got no extra surfacing.
+
+    Now any retrieved memory whose `domain` matches an area-type marker
+    with risk_score > 0.1 receives a positive boost proportional to the
+    risk_score. The intent is positive (not penalizing): a high-risk area
+    is exactly the context where the agent benefits from extra reminders.
+
+    Boost formula: min(max_boost, 0.10 * risk_score)
+    - risk_score 0.2 -> +0.020
+    - risk_score 0.5 -> +0.050
+    - risk_score 1.0 -> +0.100 (capped)
+
+    Result rows that received a boost carry `somatic_boost` (the actual
+    boost) and `somatic_risk` (the source risk_score) so dashboards and
+    downstream rerankers can identify them.
+
+    The boost gate matches `_kg_boost_results`: only results already at
+    score >= 0.45 receive the boost, so noise from very weak matches is
+    not amplified.
+    """
+    if not results:
+        return results
+
+    try:
+        db = _get_db()
+    except Exception:
+        return results
+
+    # Collect distinct domains across the result set so we can do a single
+    # batched query against somatic_markers instead of one per result.
+    domains = {(r.get("domain") or "").strip() for r in results if (r.get("domain") or "").strip()}
+    if not domains:
+        return results
+
+    try:
+        placeholders = ",".join(["?"] * len(domains))
+        rows = db.execute(
+            f"SELECT target, risk_score FROM somatic_markers "
+            f"WHERE target_type = 'area' AND risk_score > 0.1 "
+            f"AND target IN ({placeholders})",
+            list(domains),
+        ).fetchall()
+    except Exception:
+        return results
+
+    if not rows:
+        return results
+
+    risk_by_domain = {row["target"]: float(row["risk_score"] or 0.0) for row in rows}
+
+    for r in results:
+        domain = (r.get("domain") or "").strip()
+        if not domain:
+            continue
+        risk = risk_by_domain.get(domain, 0.0)
+        if risk <= 0.1:
+            continue
+        if r.get("score", 0) < 0.45:  # Same relevance gate as KG and temporal
+            continue
+        boost = min(max_boost, 0.10 * risk)
+        if boost <= 0:
+            continue
+        r["score"] = min(0.95, r["score"] + boost)
+        r["somatic_boost"] = round(boost, 4)
+        r["somatic_risk"] = round(risk, 4)
+
+    return results
+
+
 def _kg_boost_results(results: list[dict], max_boost: float = 0.08) -> list[dict]:
     """Boost search results based on Knowledge Graph connectivity.
 
@@ -726,6 +802,7 @@ def search(
     spreading_depth: int | None = None,
     decompose: bool = True,
     exclude_dreams: bool = True,
+    dream_weight: float = 0.0,
 ) -> list[dict]:
     """Full vector search across STM and/or LTM with rehearsal and dormant reactivation.
 
@@ -735,10 +812,29 @@ def search(
         exclude_dreams: If True (default), exclude dream_insight memories from results.
                         Dream insights are 21% of LTM and dilute search precision.
                         Set to False only when explicitly looking for cross-domain patterns.
+        dream_weight: Float in [0.0, 1.0]. Closes Fase 3 item 1 of NEXO-AUDIT-2026-04-11.
+                      When > 0, dream_insight memories are INCLUDED in retrieval even
+                      if exclude_dreams=True, but their cosine score is multiplied by
+                      this weight before the min_score gate. The default 0.0 keeps
+                      the historical behavior (dreams excluded). Set to 0.5 for
+                      "include dreams at half importance" or 1.0 for "treat dreams
+                      like any other memory". When dream_weight > 0, the result rows
+                      that came from dream_insight carry a `dream_weighted=True` flag
+                      so dashboards and downstream rerankers can identify them.
         hybrid: If True, boost results with BM25 keyword matches (default True)
         hybrid_alpha: Weight for vector vs BM25. Higher = more vector. (default 0.6)
         decompose: If True, decompose complex queries into sub-queries for better multi-hop (default True)
     """
+    # Normalize dream_weight to [0.0, 1.0]; >0 effectively overrides exclude_dreams.
+    try:
+        dream_weight = float(dream_weight or 0.0)
+    except (TypeError, ValueError):
+        dream_weight = 0.0
+    if dream_weight < 0.0:
+        dream_weight = 0.0
+    elif dream_weight > 1.0:
+        dream_weight = 1.0
+    _include_dreams_with_weight = dream_weight > 0.0
     # Multi-query decomposition: for complex questions, search sub-parts and merge
     if decompose and query_text:
         _connectors = [" after ", " before ", " because ", " and then ", " when ", " while "]
@@ -856,7 +952,8 @@ def search(
         if source_type_filter:
             where += " AND source_type = ?"
             params.append(source_type_filter)
-        if exclude_dreams and not source_type_filter:
+        # Fase 3 item 1: dream_weight > 0 lets dreams in even when exclude_dreams=True.
+        if exclude_dreams and not source_type_filter and not _include_dreams_with_weight:
             where += " AND source_type != 'dream_insight'"
         rows = db.execute(f"SELECT * FROM ltm_memories {where}", params).fetchall()
 
@@ -869,8 +966,14 @@ def search(
             lifecycle = row["lifecycle_state"] or "active"
             if lifecycle == "pinned":
                 score = min(1.0, score + 0.2)
+            # Fase 3 item 1: dream_insight rows get their score scaled by dream_weight.
+            # The weight applies BEFORE the min_score gate, so a low weight naturally
+            # suppresses dreams without requiring a separate filter step.
+            is_dream = row["source_type"] == "dream_insight"
+            if is_dream and _include_dreams_with_weight:
+                score = score * dream_weight
             if score >= min_score:
-                results.append({
+                entry = {
                     "store": "ltm",
                     "id": row["id"],
                     "content": row["content"],
@@ -884,7 +987,11 @@ def search(
                     "score": score,
                     "tags": row["tags"],
                     "lifecycle_state": lifecycle,
-                })
+                }
+                if is_dream and _include_dreams_with_weight:
+                    entry["dream_weighted"] = True
+                    entry["dream_weight_applied"] = dream_weight
+                results.append(entry)
 
     # Check dormant LTM for reactivation
     if stores in ("both", "ltm") and not exclude_dormant:
@@ -936,6 +1043,11 @@ def search(
     # Knowledge Graph structural boost: connected memories rank higher
     results = _kg_boost_results(results)
 
+    # Fase 3 item 2: somatic risk boost — memories whose domain matches a
+    # high-risk area marker get a small positive lift so the agent surfaces
+    # warnings about painful areas more aggressively.
+    results = _somatic_boost_results(results)
+
     # Sort by score descending, take top-20 for reranking
     results.sort(key=lambda x: x.get("score", 0), reverse=True)
 

package/src/crons/manifest.json

@@ -16,6 +16,18 @@
       "run_on_boot": true,
       "run_on_wake": true
     },
+    {
+      "id": "cortex-cycle",
+      "script": "scripts/nexo-cortex-cycle.py",
+      "interval_seconds": 21600,
+      "description": "Continuous Cortex quality validation — every 6h. Persists snapshot and opens NF-CORTEX-QUALITY-DROP followup on degradation",
+      "core": true,
+      "recovery_policy": "catchup",
+      "idempotent": true,
+      "max_catchup_age": 86400,
+      "run_on_boot": false,
+      "run_on_wake": false
+    },
     {
       "id": "sleep",
       "script": "scripts/nexo-sleep.py",

package/src/db/_core.py

@@ -53,7 +53,7 @@ def get_db() -> sqlite3.Connection:
         raw.execute("PRAGMA journal_mode=WAL")
         raw.execute("PRAGMA busy_timeout=30000")
         raw.execute("PRAGMA foreign_keys=ON")
-        raw.execute("PRAGMA wal_autocheckpoint=100")
+        raw.execute("PRAGMA wal_autocheckpoint=1000")
         raw.row_factory = sqlite3.Row
         _shared_conn = _SerializedConnection(raw)
     return _shared_conn

package/src/db/_reminders.py

@@ -14,6 +14,35 @@ from db._hot_context import capture_context_event
 ACTIVE_EXCLUDED_STATUSES = {"DELETED", "archived", "blocked", "waiting"}
 READ_TOKEN_TTL_SECONDS = 30 * 60
 
+# Opportunistic cleanup of expired item_read_tokens: runs at most once every
+# _READ_TOKEN_PURGE_INTERVAL seconds from inside _issue_item_read_token. This
+# avoids unbounded growth of expired tokens without adding a new cron or
+# relying on maintenance_schedule (which is currently not wired up — its
+# runner check_and_run_overdue is defined but never invoked from anywhere).
+_READ_TOKEN_PURGE_INTERVAL = 3600  # 1 hour
+_last_read_token_purge: float = 0.0
+
+
+def _purge_expired_read_tokens_if_due(conn: sqlite3.Connection, now: float) -> None:
+    """Delete expired item_read_tokens in-band with a 1h throttle.
+
+    Called from _issue_item_read_token so cleanup rides on normal activity and
+    does not require a separate scheduler. Failures are swallowed because
+    token issuance must never be blocked by cleanup problems.
+    """
+    global _last_read_token_purge
+    if now - _last_read_token_purge < _READ_TOKEN_PURGE_INTERVAL:
+        return
+    _last_read_token_purge = now
+    try:
+        conn.execute(
+            "DELETE FROM item_read_tokens WHERE expires_at < ?",
+            (now,),
+        )
+    except Exception:
+        # Cleanup must never block token issuance. Swallow and move on.
+        pass
+
 
 def _table_exists(conn: sqlite3.Connection, table_name: str) -> bool:
     row = conn.execute(
@@ -133,6 +162,13 @@ def get_item_history(item_type: str, item_id: str, limit: int = 20) -> list[dict
 def _issue_item_read_token(item_type: str, item_id: str, ttl_seconds: int = READ_TOKEN_TTL_SECONDS) -> str:
     conn = get_db()
     now = now_epoch()
+    # Opportunistic cleanup of expired tokens so the table does not grow
+    # unbounded. Throttled to once per hour. Wrapped defensively: any
+    # failure inside the cleanup helper must never block token issuance.
+    try:
+        _purge_expired_read_tokens_if_due(conn, now)
+    except Exception:
+        pass
     token = "IRT-" + secrets.token_hex(12)
     history_seq = _latest_history_seq(conn, item_type, item_id)
     conn.execute(