nexo-brain 7.9.14 → 7.9.17

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.9.13",
+  "version": "7.9.17",
   "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,7 @@
 
 [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.9.14` is the current packaged-runtime line. Patch release over `7.9.13`: `task_close(done)` now hard-blocks missing verify/change-log/cortex evidence instead of silently degrading to debt-only closes, self-audit auto-drains stale `protocol_debt` every day, and Codex session parity now flags partial bootstrap/startup/heartbeat drift instead of passing as healthy when only one recent session behaved correctly. Coordinated Desktop release remains v0.28.14.
+Version `7.9.17` is the current packaged-runtime line. Patch release over `7.9.16`: continuity snapshot idempotency now marks its SHA-1 digest as non-security usage, keeping the high-severity Bandit gate green while preserving stable idempotency keys. It includes the v7.9.16 restart-marker deadlock fix.
 
 Previously in `7.9.5`: patch release that fixes canonical diary confirmation for Desktop: Brain resolves the Desktop/Claude session UUID through NEXO SID aliases before checking `session_diary`, so archive/delete/app-exit can confirm diaries written by `nexo_session_diary_write` under the active `nexo-...` SID. Verification: `pytest tests/test_lifecycle_events.py` (28 passing) plus coordinated Desktop v0.28.6 shutdown/archive/delete/app-exit checks.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.9.14",
+  "version": "7.9.17",
   "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/cognitive/_core.py

@@ -558,8 +558,9 @@ def _get_model():
     """Lazy-load fastembed TextEmbedding model."""
     global _model
     if _model is None:
-        from fastembed import TextEmbedding
-        _model = TextEmbedding("BAAI/bge-base-en-v1.5")
+        from local_models import build_fastembed_embedding
+
+        _model = build_fastembed_embedding("bge-base-embeddings")
     return _model
 
 
@@ -568,8 +569,9 @@ def _get_reranker():
     global _reranker
     if _reranker is None:
         try:
-            from fastembed.rerank.cross_encoder import TextCrossEncoder
-            _reranker = TextCrossEncoder("Xenova/ms-marco-MiniLM-L-6-v2")
+            from local_models import build_fastembed_reranker
+
+            _reranker = build_fastembed_reranker("cross-encoder-reranker")
         except Exception:
             _reranker = False  # Mark as unavailable
     return _reranker if _reranker is not False else None

package/src/db/_continuity.py

@@ -46,7 +46,7 @@ def build_snapshot_idempotency_key(
             normalized,
         ]
     )
-    return hashlib.sha1(seed.encode("utf-8")).hexdigest()
+    return hashlib.sha1(seed.encode("utf-8"), usedforsecurity=False).hexdigest()
 
 
 def write_continuity_snapshot(

package/src/db/_protocol.py

@@ -195,6 +195,10 @@ def create_cortex_evaluation(
     goal_profile_id: str = "",
     goal_profile_labels=None,
     goal_profile_weights=None,
+    heuristic_choice: str = "",
+    heuristic_reasoning: str = "",
+    critique_payload=None,
+    decision_mode: str = "heuristic",
     selected_choice: str = "",
     selection_reason: str = "",
     selection_source: str = "recommended",
@@ -206,8 +210,9 @@ def create_cortex_evaluation(
                session_id, task_id, goal, task_type, area, impact_level, context_hint,
                alternatives, scores, recommended_choice, recommended_reasoning, linked_outcome_id,
                goal_profile_id, goal_profile_labels, goal_profile_weights,
+               heuristic_choice, heuristic_reasoning, critique_payload, decision_mode,
                selected_choice, selection_reason, selection_source
-           ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+           ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
         (
             session_id.strip(),
             task_id.strip(),
@@ -224,6 +229,10 @@ def create_cortex_evaluation(
             goal_profile_id.strip(),
             _as_json(goal_profile_labels or []),
             _as_json(goal_profile_weights or {}),
+            (heuristic_choice or recommended_choice).strip(),
+            (heuristic_reasoning or recommended_reasoning).strip(),
+            _as_json(critique_payload or {}),
+            (decision_mode or "heuristic").strip(),
             (selected_choice or recommended_choice).strip(),
             (selection_reason or recommended_reasoning).strip(),
             (selection_source or "recommended").strip(),

package/src/db/_schema.py

@@ -909,6 +909,20 @@ def _m38_evolution_log_proposal_payload(conn):
     _migrate_add_column(conn, "evolution_log", "proposal_payload", "TEXT DEFAULT NULL")
 
 
+def _m55_cortex_critique_trace(conn):
+    """Persist heuristic-vs-LLM critique traces for Cortex decisions."""
+    # Some legacy/minimal runtimes have schema_migrations backfilled through
+    # v48 without the optional Cortex table present. Repair the dependency
+    # before adding v55 columns so update never bricks those installs.
+    _m34_cortex_evaluations(conn)
+    _m35_cortex_evaluation_outcome_link(conn)
+    _m37_cortex_goal_profile_trace(conn)
+    _migrate_add_column(conn, "cortex_evaluations", "heuristic_choice", "TEXT DEFAULT ''")
+    _migrate_add_column(conn, "cortex_evaluations", "heuristic_reasoning", "TEXT DEFAULT ''")
+    _migrate_add_column(conn, "cortex_evaluations", "critique_payload", "TEXT DEFAULT '{}'")
+    _migrate_add_column(conn, "cortex_evaluations", "decision_mode", "TEXT DEFAULT 'heuristic'")
+
+
 def _m39_hook_runs(conn):
     """Persist hook lifecycle observability — closes Fase 3 item 7.
 
@@ -1479,6 +1493,7 @@ MIGRATIONS = [
     (52, "lifecycle_canonical_plan", _m52_lifecycle_canonical_plan),
     (53, "session_conversation_identity", _m53_session_conversation_identity),
     (54, "continuity_snapshots", _m54_continuity_snapshots),
+    (55, "cortex_critique_trace", _m55_cortex_critique_trace),
 ]
 
 

package/src/local_model_manifest.json

@@ -0,0 +1,113 @@
+{
+  "version": 1,
+  "models": [
+    {
+      "name": "bge-base-embeddings",
+      "kind": "fastembed_embedding",
+      "model_id": "BAAI/bge-base-en-v1.5",
+      "source_repo": "qdrant/bge-base-en-v1.5-onnx-q",
+      "revision": "738cad1c108e2f23649db9e44b2eab988626493b",
+      "model_file": "model_optimized.onnx",
+      "source": "src/cognitive/_core.py",
+      "required_files": [
+        {
+          "path": "config.json",
+          "size": 740,
+          "sha256": "86f84a5285de7f1ee673f712387219ef1e261ec27dcd870e793a80f9da1aaa3b"
+        },
+        {
+          "path": "model_optimized.onnx",
+          "size": 217824172,
+          "sha256": "4e556722bc4f65716c544c8a931f1e90fb3f866e5741fd93a96f051d673339c7"
+        },
+        {
+          "path": "special_tokens_map.json",
+          "size": 695,
+          "sha256": "5d5b662e421ea9fac075174bb0688ee0d9431699900b90662acd44b2a350503a"
+        },
+        {
+          "path": "tokenizer.json",
+          "size": 711396,
+          "sha256": "d241a60d5e8f04cc1b2b3e9ef7a4921b27bf526d9f6050ab90f9267a1f9e5c66"
+        },
+        {
+          "path": "tokenizer_config.json",
+          "size": 1242,
+          "sha256": "0b29c7bfc889e53b36d9dd3e686dd4300f6525110eaa98c76a5dafceb2029f53"
+        }
+      ]
+    },
+    {
+      "name": "bge-small-embeddings",
+      "kind": "fastembed_embedding",
+      "model_id": "BAAI/bge-small-en-v1.5",
+      "source_repo": "qdrant/bge-small-en-v1.5-onnx-q",
+      "revision": "52398278842ec682c6f32300af41344b1c0b0bb2",
+      "model_file": "model_optimized.onnx",
+      "source": "src/migrate_embeddings.py",
+      "required_files": [
+        {
+          "path": "config.json",
+          "size": 706,
+          "sha256": "13582bcf2effc85b7bf3d3f5532e686bc1c9ce86bb009d10f0ec33cbe92299dd"
+        },
+        {
+          "path": "model_optimized.onnx",
+          "size": 66465124,
+          "sha256": "51f1bd0addd6e859e42c2c8021a5e5461385bb676a649f4b269aa445449f2431"
+        },
+        {
+          "path": "special_tokens_map.json",
+          "size": 695,
+          "sha256": "5d5b662e421ea9fac075174bb0688ee0d9431699900b90662acd44b2a350503a"
+        },
+        {
+          "path": "tokenizer.json",
+          "size": 711396,
+          "sha256": "d241a60d5e8f04cc1b2b3e9ef7a4921b27bf526d9f6050ab90f9267a1f9e5c66"
+        },
+        {
+          "path": "tokenizer_config.json",
+          "size": 1242,
+          "sha256": "0b29c7bfc889e53b36d9dd3e686dd4300f6525110eaa98c76a5dafceb2029f53"
+        }
+      ]
+    },
+    {
+      "name": "cross-encoder-reranker",
+      "kind": "fastembed_reranker",
+      "model_id": "Xenova/ms-marco-MiniLM-L-6-v2",
+      "source_repo": "Xenova/ms-marco-MiniLM-L-6-v2",
+      "revision": "a09144355adeed5f58c8ed011d209bf8ee5a1fec",
+      "model_file": "onnx/model.onnx",
+      "source": "src/cognitive/_core.py",
+      "required_files": [
+        {
+          "path": "config.json",
+          "size": 824,
+          "sha256": "d827779a72d27ae68cf878a6fc2e954542663fe21ca515d9f4783fc96be2d37e"
+        },
+        {
+          "path": "onnx/model.onnx",
+          "size": 90992115,
+          "sha256": "c623d0bcb99f4622beb413eaef00cfbe5db20df9f1dd982da4b4f26022881870"
+        },
+        {
+          "path": "special_tokens_map.json",
+          "size": 125,
+          "sha256": "b6d346be366a7d1d48332dbc9fdf3bf8960b5d879522b7799ddba59e76237ee3"
+        },
+        {
+          "path": "tokenizer.json",
+          "size": 711396,
+          "sha256": "d241a60d5e8f04cc1b2b3e9ef7a4921b27bf526d9f6050ab90f9267a1f9e5c66"
+        },
+        {
+          "path": "tokenizer_config.json",
+          "size": 1242,
+          "sha256": "0b29c7bfc889e53b36d9dd3e686dd4300f6525110eaa98c76a5dafceb2029f53"
+        }
+      ]
+    }
+  ]
+}

package/src/local_models.py

@@ -0,0 +1,247 @@
+"""Pinned local model management for Brain embeddings + reranker.
+
+FastEmbed's built-in registry resolves supported models by friendly name, but
+its downloader tracks the current upstream repo head unless the caller builds a
+stronger contract around it. This module provides that stronger contract:
+
+- source repo pinned by immutable revision SHA
+- required files + sha256 checksums stored in-repo
+- deterministic materialization under ``~/.nexo/runtime/models``
+- FastEmbed instantiated via ``specific_model_path`` so runtime loads the exact
+  downloaded artifacts instead of following a floating registry download
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import shutil
+import tempfile
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+import paths
+
+
+MANIFEST_PATH = Path(__file__).resolve().with_name("local_model_manifest.json")
+MODEL_LOCK_FILENAME = ".nexo-model-lock.json"
+
+
+@dataclass(frozen=True)
+class LocalModelFile:
+    path: str
+    size: int
+    sha256: str
+
+
+@dataclass(frozen=True)
+class LocalModelSpec:
+    name: str
+    kind: str
+    model_id: str
+    source_repo: str
+    revision: str
+    model_file: str
+    source: str
+    required_files: tuple[LocalModelFile, ...]
+
+
+def _slugify(value: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", value.strip().lower()).strip("-")
+
+
+def _hash_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _lock_payload(spec: LocalModelSpec) -> dict[str, Any]:
+    return {
+        "name": spec.name,
+        "kind": spec.kind,
+        "model_id": spec.model_id,
+        "source_repo": spec.source_repo,
+        "revision": spec.revision,
+        "model_file": spec.model_file,
+        "required_files": [
+            {"path": item.path, "size": item.size, "sha256": item.sha256}
+            for item in spec.required_files
+        ],
+    }
+
+
+@lru_cache(maxsize=1)
+def _load_manifest() -> dict[str, LocalModelSpec]:
+    payload = json.loads(MANIFEST_PATH.read_text(encoding="utf-8"))
+    specs: dict[str, LocalModelSpec] = {}
+    for raw in payload.get("models", []) or []:
+        files = tuple(LocalModelFile(**item) for item in raw.get("required_files", []) or [])
+        spec = LocalModelSpec(
+            name=str(raw["name"]),
+            kind=str(raw["kind"]),
+            model_id=str(raw["model_id"]),
+            source_repo=str(raw["source_repo"]),
+            revision=str(raw["revision"]),
+            model_file=str(raw["model_file"]),
+            source=str(raw["source"]),
+            required_files=files,
+        )
+        specs[spec.name] = spec
+    return specs
+
+
+def get_local_model_spec(name: str) -> LocalModelSpec:
+    try:
+        return _load_manifest()[name]
+    except KeyError as exc:  # pragma: no cover - defensive
+        raise KeyError(f"unknown local model spec: {name}") from exc
+
+
+def list_local_model_specs(kind: str | None = None) -> list[LocalModelSpec]:
+    specs = list(_load_manifest().values())
+    if kind:
+        specs = [spec for spec in specs if spec.kind == kind]
+    return specs
+
+
+def models_dir() -> Path:
+    root = paths.models_dir()
+    root.mkdir(parents=True, exist_ok=True)
+    return root
+
+
+def managed_model_dir(spec: LocalModelSpec) -> Path:
+    return models_dir() / _slugify(spec.name) / spec.revision
+
+
+def verify_local_model_dir(spec: LocalModelSpec, root: Path | None = None) -> dict[str, Any]:
+    target = root or managed_model_dir(spec)
+    problems: list[str] = []
+    if not target.exists():
+        problems.append("missing directory")
+    for file_spec in spec.required_files:
+        file_path = target / file_spec.path
+        if not file_path.exists():
+            problems.append(f"missing file:{file_spec.path}")
+            continue
+        size = file_path.stat().st_size
+        if size != file_spec.size:
+            problems.append(f"size mismatch:{file_spec.path}:{size}!={file_spec.size}")
+            continue
+        actual_hash = _hash_file(file_path)
+        if actual_hash != file_spec.sha256:
+            problems.append(f"sha256 mismatch:{file_spec.path}:{actual_hash}!={file_spec.sha256}")
+    lock_path = target / MODEL_LOCK_FILENAME
+    if lock_path.exists():
+        try:
+            payload = json.loads(lock_path.read_text(encoding="utf-8"))
+            if payload.get("revision") != spec.revision or payload.get("source_repo") != spec.source_repo:
+                problems.append("lock metadata mismatch")
+        except Exception:
+            problems.append("invalid lock metadata")
+    return {"ok": not problems, "path": str(target), "problems": problems}
+
+
+def _copy_required_files(snapshot_dir: Path, target_dir: Path, spec: LocalModelSpec) -> None:
+    for file_spec in spec.required_files:
+        source_path = snapshot_dir / file_spec.path
+        if not source_path.exists():
+            raise FileNotFoundError(f"snapshot missing required file: {file_spec.path}")
+        destination = target_dir / file_spec.path
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source_path, destination)
+    (target_dir / MODEL_LOCK_FILENAME).write_text(
+        json.dumps(_lock_payload(spec), indent=2, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+
+
+def ensure_local_model(
+    name: str,
+    *,
+    local_files_only: bool = False,
+    force_redownload: bool = False,
+) -> Path:
+    spec = get_local_model_spec(name)
+    target_dir = managed_model_dir(spec)
+    verification = verify_local_model_dir(spec, target_dir)
+    if verification["ok"] and not force_redownload:
+        return target_dir
+    if target_dir.exists():
+        shutil.rmtree(target_dir, ignore_errors=True)
+
+    from huggingface_hub import snapshot_download
+
+    cache_dir = models_dir() / "_hf-cache"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    snapshot_dir = Path(
+        snapshot_download(
+            repo_id=spec.source_repo,
+            revision=spec.revision,
+            allow_patterns=[item.path for item in spec.required_files],
+            cache_dir=str(cache_dir),
+            local_files_only=local_files_only,
+        )
+    )
+
+    target_parent = target_dir.parent
+    target_parent.mkdir(parents=True, exist_ok=True)
+    tmp_dir = Path(
+        tempfile.mkdtemp(
+            prefix=f".{_slugify(spec.name)}-{spec.revision[:12]}.",
+            dir=str(target_parent),
+        )
+    )
+    try:
+        _copy_required_files(snapshot_dir, tmp_dir, spec)
+        verification = verify_local_model_dir(spec, tmp_dir)
+        if not verification["ok"]:
+            raise ValueError("; ".join(verification["problems"]))
+        os.replace(tmp_dir, target_dir)
+    except Exception:
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+        raise
+    return target_dir
+
+
+def build_fastembed_embedding(name: str):
+    spec = get_local_model_spec(name)
+    if spec.kind != "fastembed_embedding":
+        raise ValueError(f"{name} is not a fastembed embedding model")
+    from fastembed import TextEmbedding
+
+    target_dir = ensure_local_model(name)
+    return TextEmbedding(spec.model_id, specific_model_path=str(target_dir))
+
+
+def build_fastembed_reranker(name: str):
+    spec = get_local_model_spec(name)
+    if spec.kind != "fastembed_reranker":
+        raise ValueError(f"{name} is not a fastembed reranker")
+    from fastembed.rerank.cross_encoder import TextCrossEncoder
+
+    target_dir = ensure_local_model(name)
+    return TextCrossEncoder(spec.model_id, specific_model_path=str(target_dir))
+
+
+__all__ = [
+    "LocalModelFile",
+    "LocalModelSpec",
+    "MODEL_LOCK_FILENAME",
+    "MANIFEST_PATH",
+    "build_fastembed_embedding",
+    "build_fastembed_reranker",
+    "ensure_local_model",
+    "get_local_model_spec",
+    "list_local_model_specs",
+    "managed_model_dir",
+    "models_dir",
+    "verify_local_model_dir",
+]

package/src/migrate_embeddings.py

@@ -16,6 +16,7 @@ import time
 import numpy as np
 
 import paths
+from local_models import build_fastembed_embedding, get_local_model_spec
 
 NEXO_HOME = os.environ.get("NEXO_HOME", os.path.expanduser("~/.nexo"))
 _cognitive_dir = paths.cognitive_dir()
@@ -24,8 +25,8 @@ DB_PATH = str(_cognitive_dir / "cognitive.db")
 BACKUP_PATH = DB_PATH + ".bak-384dims-pre-upgrade"
 
 MODELS = {
-    "small": ("BAAI/bge-small-en-v1.5", 384),
-    "base": ("BAAI/bge-base-en-v1.5", 768),
+    "small": ("bge-small-embeddings", 384),
+    "base": ("bge-base-embeddings", 768),
 }
 
 
@@ -47,8 +48,6 @@ def verify():
 
 def upgrade():
     """Re-embed all memories from bge-small (384) to bge-base (768)."""
-    from fastembed import TextEmbedding
-
     # Verify current state
     print("Current state:")
     verify()
@@ -62,8 +61,9 @@ def upgrade():
 
     # Load new model
     model_name, expected_dim = MODELS["base"]
-    print(f"\nLoading {model_name}...")
-    model = TextEmbedding(model_name)
+    spec = get_local_model_spec(model_name)
+    print(f"\nLoading {spec.model_id}@{spec.revision}...")
+    model = build_fastembed_embedding(model_name)
 
     conn = sqlite3.connect(DB_PATH)
     try:

package/src/model_warmup.py

@@ -28,40 +28,37 @@ class WarmupTarget:
     kind: str
     model_id: str
     source: str
+    source_repo: str | None = None
     revision: str | None = None
     required: bool = True
 
 
 def warmup_targets() -> list[WarmupTarget]:
     from classifier_local import MODEL_ID, MODEL_REVISION
+    from local_models import list_local_model_specs
 
-    return [
+    targets = [
         WarmupTarget(
             name="local-zero-shot-classifier",
             kind="transformers_sequence_classifier",
             model_id=MODEL_ID,
             revision=MODEL_REVISION,
             source="src/classifier_local.py",
-        ),
-        WarmupTarget(
-            name="bge-base-embeddings",
-            kind="fastembed_embedding",
-            model_id="BAAI/bge-base-en-v1.5",
-            source="src/cognitive/_core.py",
-        ),
-        WarmupTarget(
-            name="bge-small-embeddings",
-            kind="fastembed_embedding",
-            model_id="BAAI/bge-small-en-v1.5",
-            source="src/migrate_embeddings.py",
-        ),
-        WarmupTarget(
-            name="cross-encoder-reranker",
-            kind="fastembed_reranker",
-            model_id="Xenova/ms-marco-MiniLM-L-6-v2",
-            source="src/cognitive/_core.py",
+            source_repo=MODEL_ID,
         ),
     ]
+    for spec in list_local_model_specs():
+        targets.append(
+            WarmupTarget(
+                name=spec.name,
+                kind=spec.kind,
+                model_id=spec.model_id,
+                revision=spec.revision,
+                source=spec.source,
+                source_repo=spec.source_repo,
+            )
+        )
+    return targets
 
 
 def _state_path() -> Path:
@@ -86,16 +83,16 @@ def _warm_transformers(target: WarmupTarget) -> None:
 
 
 def _warm_fastembed_embedding(target: WarmupTarget) -> None:
-    from fastembed import TextEmbedding
+    from local_models import build_fastembed_embedding
 
-    model = TextEmbedding(target.model_id)
+    model = build_fastembed_embedding(target.name)
     list(model.embed(["NEXO model warmup"]))
 
 
 def _warm_fastembed_reranker(target: WarmupTarget) -> None:
-    from fastembed.rerank.cross_encoder import TextCrossEncoder
+    from local_models import build_fastembed_reranker
 
-    TextCrossEncoder(target.model_id)
+    build_fastembed_reranker(target.name)
 
 
 def warm_target(target: WarmupTarget) -> None:

package/src/paths.py

@@ -336,6 +336,14 @@ def cognitive_dir() -> Path:
     return new
 
 
+def models_dir() -> Path:
+    new = runtime_dir() / "models"
+    legacy = home() / "models"
+    if not new.exists() and legacy.exists():
+        return legacy
+    return new
+
+
 def coordination_dir() -> Path:
     new = runtime_dir() / "coordination"
     legacy = home() / "coordination"
@@ -488,6 +496,7 @@ __all__ = [
     "backups_dir",
     "memory_dir",
     "cognitive_dir",
+    "models_dir",
     "coordination_dir",
     "exports_dir",
     "nexo_email_dir",

package/src/plugins/cortex.py

@@ -23,6 +23,7 @@ from datetime import datetime, timedelta
 from pathlib import Path
 
 from db import VALID_IMPACT_LEVELS, VALID_TASK_TYPES, validate_impact_level, validate_task_type
+from db._semantic_similarity import hybrid_similarity_score
 
 
 def _get_db():
@@ -89,6 +90,10 @@ STOP_WORDS = {
 }
 HISTORICAL_OUTCOME_MIN_RESOLVED = 2
 HISTORICAL_OUTCOME_LOOKBACK = 12
+SEMANTIC_HISTORY_LOOKBACK = 24
+SEMANTIC_HISTORY_MATCH_THRESHOLD = 0.58
+CRITIQUE_TOP_CANDIDATES = 3
+CRITIQUE_MAX_MARGIN = 0.45
 
 
 def _term_hits(text: str, terms: set[str]) -> int:
@@ -279,50 +284,80 @@ def _constraint_penalty(text: str, constraints: list[str]) -> tuple[float, list[
 
 def _history_signal(text: str, *, area: str = "", goal: str = "") -> dict:
     conn = _get_db()
-    tokens = _tokenize(" ".join(part for part in [text, area, goal] if part), limit=6)
-    if not tokens:
+    query_text = " ".join(part for part in [text, area, goal] if part).strip()
+    if not query_text:
         return {"positive": 0.0, "negative": 0.0, "matched_decisions": 0, "matched_outcomes": 0}
 
-    decision_positive = 0
-    decision_negative = 0
+    def _keyword_extractor(value: str) -> list[str]:
+        return _tokenize(value, limit=8)
+
+    decision_positive = 0.0
+    decision_negative = 0.0
     matched_decisions = 0
-    for token in tokens[:3]:
+    if conn.execute("SELECT 1 FROM sqlite_master WHERE type='table' AND name='decisions'").fetchone():
         rows = conn.execute(
-            """SELECT outcome FROM decisions
-               WHERE lower(decision) LIKE ? OR lower(alternatives) LIKE ? OR lower(based_on) LIKE ?
-               ORDER BY created_at DESC LIMIT 6""",
-            tuple(f"%{token}%" for _ in range(3)),
+            """SELECT decision, alternatives, based_on, outcome
+               FROM decisions
+               ORDER BY created_at DESC LIMIT ?""",
+            (SEMANTIC_HISTORY_LOOKBACK,),
         ).fetchall()
         for row in rows:
+            candidate_text = " ".join(
+                str(row[key] or "")
+                for key in ("decision", "alternatives", "based_on")
+            ).strip()
+            similarity = hybrid_similarity_score(
+                query_text,
+                candidate_text,
+                keyword_extractor=_keyword_extractor,
+                strong_semantic_threshold=0.82,
+                moderate_semantic_threshold=0.74,
+                moderate_keyword_floor=0.12,
+            )
+            if similarity < SEMANTIC_HISTORY_MATCH_THRESHOLD:
+                continue
             matched_decisions += 1
             outcome = (row["outcome"] or "").lower()
             if _contains_any(outcome, NEGATIVE_OUTCOME_TERMS):
-                decision_negative += 1
+                decision_negative += min(1.0, similarity)
             elif _contains_any(outcome, POSITIVE_OUTCOME_TERMS):
-                decision_positive += 1
+                decision_positive += min(1.0, similarity)
 
-    outcome_positive = 0
-    outcome_negative = 0
+    outcome_positive = 0.0
+    outcome_negative = 0.0
     matched_outcomes = 0
     if conn.execute("SELECT 1 FROM sqlite_master WHERE type='table' AND name='outcomes'").fetchone():
-        for token in tokens[:3]:
-            rows = conn.execute(
-                """SELECT status FROM outcomes
-                   WHERE lower(description) LIKE ? OR lower(expected_result) LIKE ? OR lower(action_type) LIKE ?
-                   ORDER BY created_at DESC LIMIT 6""",
-                tuple(f"%{token}%" for _ in range(3)),
-            ).fetchall()
-            for row in rows:
-                matched_outcomes += 1
-                status = (row["status"] or "").lower()
-                if status == "met":
-                    outcome_positive += 1
-                elif status in {"missed", "expired"}:
-                    outcome_negative += 1
+        rows = conn.execute(
+            """SELECT description, expected_result, action_type, status
+               FROM outcomes
+               ORDER BY created_at DESC LIMIT ?""",
+            (SEMANTIC_HISTORY_LOOKBACK,),
+        ).fetchall()
+        for row in rows:
+            candidate_text = " ".join(
+                str(row[key] or "")
+                for key in ("description", "expected_result", "action_type")
+            ).strip()
+            similarity = hybrid_similarity_score(
+                query_text,
+                candidate_text,
+                keyword_extractor=_keyword_extractor,
+                strong_semantic_threshold=0.82,
+                moderate_semantic_threshold=0.74,
+                moderate_keyword_floor=0.12,
+            )
+            if similarity < SEMANTIC_HISTORY_MATCH_THRESHOLD:
+                continue
+            matched_outcomes += 1
+            status = (row["status"] or "").lower()
+            if status == "met":
+                outcome_positive += min(1.0, similarity)
+            elif status in {"missed", "expired"}:
+                outcome_negative += min(1.0, similarity)
 
     return {
-        "positive": min(2.5, (decision_positive * 0.4) + (outcome_positive * 0.5)),
-        "negative": min(3.0, (decision_negative * 0.6) + (outcome_negative * 0.7)),
+        "positive": round(min(2.5, (decision_positive * 0.9) + (outcome_positive * 1.0)), 2),
+        "negative": round(min(3.0, (decision_negative * 1.1) + (outcome_negative * 1.2)), 2),
         "matched_decisions": matched_decisions,
         "matched_outcomes": matched_outcomes,
     }
@@ -702,6 +737,172 @@ def _format_decision_summary(recommended: dict, alternatives_scored: list[dict])
     return f"Recomendada por el mejor balance entre impacto, éxito, riesgo y huella somática; {notes}."
 
 
+def _parse_json_object_response(raw: str) -> dict:
+    text = (raw or "").strip()
+    if not text:
+        return {}
+    try:
+        parsed = json.loads(text)
+        return parsed if isinstance(parsed, dict) else {}
+    except json.JSONDecodeError:
+        match = re.search(r"\{.*\}", text, re.DOTALL)
+        if not match:
+            return {}
+        try:
+            parsed = json.loads(match.group(0))
+            return parsed if isinstance(parsed, dict) else {}
+        except json.JSONDecodeError:
+            return {}
+
+
+def _critique_tier(
+    *,
+    impact_level: str,
+    scored: list[dict],
+    constraints: list[str],
+    evidence_refs: list[str],
+) -> str:
+    if impact_level != "critical":
+        return "alto"
+    gap = 99.0
+    if len(scored) > 1:
+        gap = scored[0]["total_score"] - scored[1]["total_score"]
+    if gap <= CRITIQUE_MAX_MARGIN or len(constraints) >= 3 or len(evidence_refs) <= 1:
+        return "maximo"
+    return "alto"
+
+
+def _run_llm_critique(
+    *,
+    goal: str,
+    task_type: str,
+    impact_level: str,
+    area: str,
+    context_hint: str,
+    constraints: list[str],
+    evidence_refs: list[str],
+    goal_profile: dict,
+    scored: list[dict],
+) -> dict:
+    if impact_level not in {"high", "critical"} or len(scored) < 2:
+        return {"active": False}
+
+    try:
+        from call_model_raw import call_model_raw, ClassifierUnavailableError
+        from core_prompts import render_core_prompt
+        from operator_language import append_operator_language_contract
+    except Exception as exc:
+        return {"active": True, "ok": False, "error": f"critic_unavailable:{exc}"}
+
+    tier = _critique_tier(
+        impact_level=impact_level,
+        scored=scored,
+        constraints=constraints,
+        evidence_refs=evidence_refs,
+    )
+    payload = {
+        "goal": goal,
+        "task_type": task_type,
+        "impact_level": impact_level,
+        "area": area,
+        "context_hint": context_hint,
+        "constraints": constraints,
+        "evidence_refs": evidence_refs,
+        "goal_profile": {
+            "profile_id": goal_profile.get("profile_id", ""),
+            "profile_name": goal_profile.get("profile_name", ""),
+            "goal_labels": goal_profile.get("goal_labels", []),
+            "weights": goal_profile.get("weights", {}),
+        },
+        "heuristic_recommendation": scored[0]["name"],
+        "candidates": [
+            {
+                "name": item["name"],
+                "impact": item["impact"],
+                "success_probability": item["success_probability"],
+                "risk_level": item["risk_level"],
+                "somatic_penalty": item["somatic_penalty"],
+                "total_score": item["total_score"],
+                "notes": item.get("notes") or [],
+                "historical_signal": item.get("historical_signal") or {},
+                "pattern_learning_signal": item.get("pattern_learning_signal") or {},
+            }
+            for item in scored[:CRITIQUE_TOP_CANDIDATES]
+        ],
+    }
+    prompt = render_core_prompt(
+        "cortex-decision-critic",
+        payload_json=json.dumps(payload, ensure_ascii=False, indent=2),
+    )
+    prompt = append_operator_language_contract(prompt)
+    try:
+        raw = call_model_raw(
+            prompt,
+            caller="cortex_decision_critic",
+            tier=tier,
+            system=render_core_prompt("json-object-only"),
+            max_tokens=500,
+            temperature=0.0,
+            stop_sequences=[],
+            timeout=20.0,
+        )
+    except ClassifierUnavailableError as exc:
+        return {"active": True, "ok": False, "tier": tier, "error": str(exc)}
+
+    parsed = _parse_json_object_response(raw)
+    candidate_names = [item["name"] for item in scored]
+    recommended_choice = str(parsed.get("recommended_choice") or "").strip()
+    if recommended_choice not in candidate_names:
+        return {
+            "active": True,
+            "ok": False,
+            "tier": tier,
+            "error": "invalid_recommended_choice",
+            "raw_response": raw[:1200],
+        }
+
+    ranking = parsed.get("confirmed_ranking")
+    clean_ranking: list[str] = []
+    if isinstance(ranking, list):
+        for item in ranking:
+            name = str(item or "").strip()
+            if name in candidate_names and name not in clean_ranking:
+                clean_ranking.append(name)
+    for name in candidate_names:
+        if name not in clean_ranking:
+            clean_ranking.append(name)
+
+    try:
+        confidence = float(parsed.get("confidence"))
+    except (TypeError, ValueError):
+        confidence = 0.0
+    confidence = max(0.0, min(1.0, confidence))
+    risk_flags = parsed.get("risk_flags")
+    if not isinstance(risk_flags, list):
+        risk_flags = []
+    reasoning_summary = str(parsed.get("reasoning_summary") or "").strip()
+    disagreement = bool(parsed.get("disagreement_with_heuristic"))
+    return {
+        "active": True,
+        "ok": True,
+        "tier": tier,
+        "recommended_choice": recommended_choice,
+        "confirmed_ranking": clean_ranking,
+        "confidence": round(confidence, 3),
+        "risk_flags": [str(item).strip() for item in risk_flags if str(item).strip()][:5],
+        "reasoning_summary": reasoning_summary,
+        "disagreement_with_heuristic": disagreement or (recommended_choice != scored[0]["name"]),
+    }
+
+
+def _reorder_scores_by_names(scored: list[dict], ranking: list[str]) -> list[dict]:
+    order = {name: idx for idx, name in enumerate(ranking)}
+    return sorted(
+        scored,
+        key=lambda item: (order.get(item["name"], len(order)), -item["total_score"]),
+    )
+
+
 def handle_cortex_check(
     goal: str,
     task_type: str = "answer",
@@ -858,6 +1059,7 @@ def handle_cortex_decide(
     linked_outcome_id: int = 0,
     goal_profile_id: str = "",
     goal_id: str = "",
+    auto_create_outcome: bool = False,
 ) -> str:
     """Evaluate concrete alternatives for a high-impact task using the existing Cortex."""
     clean_goal = (goal or "").strip()
@@ -927,16 +1129,39 @@ def handle_cortex_decide(
         for item in parsed_alternatives
     ]
     scored.sort(key=lambda item: item["total_score"], reverse=True)
-    recommended = scored[0]
-    reasoning = _format_decision_summary(recommended, scored)
+    heuristic_recommended = scored[0]
+    heuristic_reasoning = _format_decision_summary(heuristic_recommended, scored)
+    critique = _run_llm_critique(
+        goal=clean_goal,
+        task_type=clean_type,
+        impact_level=clean_level,
+        area=area.strip(),
+        context_hint=context_hint.strip(),
+        constraints=parsed_constraints,
+        evidence_refs=parsed_evidence,
+        goal_profile=resolved_goal_profile,
+        scored=scored,
+    )
+    decision_mode = "heuristic"
+    if critique.get("ok"):
+        scored = _reorder_scores_by_names(scored, critique.get("confirmed_ranking") or [])
+        recommended = next(
+            (item for item in scored if item["name"] == critique["recommended_choice"]),
+            heuristic_recommended,
+        )
+        reasoning = (critique.get("reasoning_summary") or "").strip() or heuristic_reasoning
+        decision_mode = "heuristic_plus_llm"
+    else:
+        recommended = heuristic_recommended
+        reasoning = heuristic_reasoning
     resolved_outcome_id = _resolve_linked_outcome_id(
         linked_outcome_id=linked_outcome_id,
         task_id=task_id,
     )
 
-    # Auto-create outcome when none exists, so cortex decisions
-    # get verified by outcome-checker and close the feedback loop.
-    if resolved_outcome_id is None and clean_goal and task_id:
+    # Outcome auto-creation is opt-in so analytics can distinguish
+    # persisted decisions from explicitly tracked outcomes.
+    if auto_create_outcome and resolved_outcome_id is None and clean_goal and task_id:
         try:
             from db import create_outcome
 
@@ -974,6 +1199,10 @@ def handle_cortex_decide(
             goal_profile_id=resolved_goal_profile.get("profile_id", ""),
             goal_profile_labels=resolved_goal_profile.get("goal_labels", []),
             goal_profile_weights=resolved_goal_profile.get("weights", {}),
+            heuristic_choice=heuristic_recommended["name"],
+            heuristic_reasoning=heuristic_reasoning,
+            critique_payload=critique,
+            decision_mode=decision_mode,
             selected_choice=recommended["name"],
             selection_reason=reasoning,
             selection_source="recommended",
@@ -997,6 +1226,10 @@ def handle_cortex_decide(
             "impact_level": clean_level,
             "recommendation": recommended["name"],
             "reasoning": reasoning,
+            "heuristic_recommendation": heuristic_recommended["name"],
+            "heuristic_reasoning": heuristic_reasoning,
+            "decision_mode": decision_mode,
+            "critique": critique,
             "selected_choice": record.get("selected_choice"),
             "selection_source": record.get("selection_source"),
             "linked_outcome_id": record.get("linked_outcome_id"),

package/src/resonance_map.py

@@ -219,6 +219,8 @@ SYSTEM_OWNED_CALLERS: dict[str, str] = {
     "learning_validator":               "medio",
     "outcome_checker":                  "medio",
     "check_context":                    "medio",
+    "semantic_reasoner":                "muy_bajo",
+    "cortex_decision_critic":           "alto",
 
     # ---- Agent orchestration ----------------------------------------------
     "agent_run/generic":                "alto",

package/src/runtime_versioning.py

@@ -16,7 +16,13 @@ import paths
 CONTINUITY_API_LEVEL = 1
 MCP_STATUS_SCHEMA_VERSION = 1
 PROCESS_VERSION = ""
+RESTART_CLIENT_ACTIONS = {
+    "claude_desktop": "restart_client_required",
+    "claude_code": "restart_session_required",
+    "codex": "restart_session_required",
+}
 RESTART_ALLOWLIST = {
+    "nexo_startup",
     "nexo_status",
     "nexo_system_catalog",
     "nexo_tool_explain",
@@ -48,6 +54,61 @@ def _write_json_atomic(path: Path, payload: dict) -> None:
     tmp.replace(path)
 
 
+def _normalize_restart_client(value: str | None) -> str:
+    candidate = str(value or "").strip().lower().replace("-", "_").replace(" ", "_")
+    aliases = {
+        "claude": "claude_code",
+        "claudecode": "claude_code",
+        "claude_code": "claude_code",
+        "claude_desktop": "claude_desktop",
+        "claude_desktop_app": "claude_desktop",
+        "desktop": "claude_desktop",
+        "codex": "codex",
+    }
+    resolved = aliases.get(candidate, candidate)
+    if resolved in RESTART_CLIENT_ACTIONS:
+        return resolved
+    return ""
+
+
+def _enabled_flag(value) -> bool:
+    if isinstance(value, str):
+        return value.strip().lower() not in {"", "0", "false", "no", "off", "disabled", "none"}
+    return bool(value)
+
+
+def _restart_clients_from_preferences() -> dict[str, str]:
+    try:
+        from runtime_power import load_schedule_config
+
+        prefs = load_schedule_config()
+    except Exception:
+        prefs = {}
+
+    raw_clients = prefs.get("interactive_clients") if isinstance(prefs, dict) else {}
+    clients: dict[str, str] = {}
+    if isinstance(raw_clients, dict):
+        for raw_key, raw_enabled in raw_clients.items():
+            key = _normalize_restart_client(str(raw_key or ""))
+            if key and _enabled_flag(raw_enabled):
+                clients[key] = RESTART_CLIENT_ACTIONS[key]
+    return clients
+
+
+def _restart_clients_for_marker(*, client: str = "") -> dict[str, str]:
+    explicit_client = _normalize_restart_client(client or os.environ.get("NEXO_MCP_CLIENT", ""))
+    if explicit_client:
+        return {explicit_client: RESTART_CLIENT_ACTIONS[explicit_client]}
+
+    clients = _restart_clients_from_preferences()
+    if clients:
+        return clients
+
+    # Safe default for fresh/legacy installs: Claude Code is the primary
+    # terminal client, and avoiding absent clients prevents permanent markers.
+    return {"claude_code": RESTART_CLIENT_ACTIONS["claude_code"]}
+
+
 def core_container_dir() -> Path:
     return paths.home() / "core"
 
@@ -135,6 +196,7 @@ def write_restart_required_marker(
     from_version: str,
     to_version: str,
     reason: str = "brain_update",
+    client: str = "",
 ) -> dict:
     path = restart_required_marker_path()
     payload = {
@@ -144,11 +206,7 @@ def write_restart_required_marker(
         "to_version": str(to_version or "").strip(),
         "reason": str(reason or "brain_update"),
         "updated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
-        "clients": {
-            "claude_desktop": "restart_client_required",
-            "claude_code": "restart_session_required",
-            "codex": "restart_session_required",
-        },
+        "clients": _restart_clients_for_marker(client=client),
     }
     _write_json_atomic(path, payload)
     payload["path"] = str(path)
@@ -206,6 +264,7 @@ def activate_versioned_runtime_snapshot(*, source_root: Path | None = None, vers
 
 
 def clear_restart_required_marker(*, client: str = "", installed_version: str = "", process_version: str = "") -> dict:
+    client = _normalize_restart_client(client)
     path = restart_required_marker_path()
     marker = read_restart_required_marker()
     if not marker.get("required"):
@@ -244,6 +303,7 @@ def clear_restart_required_marker(*, client: str = "", installed_version: str =
 
 
 def resolve_restart_required(*, client: str = "", installed_version: str = "", process_version: str = "") -> dict:
+    client = _normalize_restart_client(client)
     marker = read_restart_required_marker()
     installed = str(installed_version or installed_runtime_version() or "").strip()
     process = str(process_version or PROCESS_VERSION or installed).strip()
@@ -277,6 +337,7 @@ def resolve_restart_required(*, client: str = "", installed_version: str = "", p
 
 
 def build_mcp_status(*, client: str = "") -> dict:
+    client = _normalize_restart_client(client)
     state = resolve_restart_required(client=client)
     marker = state["marker"]
     return {
@@ -319,6 +380,28 @@ def prime_process_version() -> str:
 class RestartRequiredMiddleware(Middleware):
     client: str = ""
 
+    def __post_init__(self) -> None:
+        self.client = _normalize_restart_client(self.client)
+
+    def _ack_current_client_if_restarted(self, state: dict) -> dict:
+        if not self.client or not state.get("restart_required"):
+            return state
+        installed = str(state.get("installed_version") or "").strip()
+        process = str(state.get("process_version") or "").strip()
+        if not installed or not process or installed != process:
+            return state
+
+        clear_restart_required_marker(
+            client=self.client,
+            installed_version=installed,
+            process_version=process,
+        )
+        return resolve_restart_required(
+            client=self.client,
+            installed_version=installed,
+            process_version=process,
+        )
+
     async def _tool_result_for_restart_required(self, context, payload: dict) -> ToolResult:
         payload_text = json.dumps(payload, ensure_ascii=False)
         tool = None
@@ -344,6 +427,7 @@ class RestartRequiredMiddleware(Middleware):
     async def on_call_tool(self, context, call_next):
         tool_name = str(getattr(context.message, "name", "") or "").strip()
         state = resolve_restart_required(client=self.client)
+        state = self._ack_current_client_if_restarted(state)
         if not state["restart_required"] or tool_name in RESTART_ALLOWLIST:
             return await call_next(context)
 

package/src/scripts/nexo-learning-housekeep.py

@@ -145,8 +145,8 @@ def detect_duplicates(conn):
     """Find semantically similar learnings using fastembed."""
     ts = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
     try:
-        from fastembed import TextEmbedding
         import numpy as np
+        from local_models import build_fastembed_embedding
     except ImportError:
         print(f"[{ts}] Dedup skipped: fastembed not available")
         return []
@@ -158,7 +158,7 @@ def detect_duplicates(conn):
     if len(learnings) < 2:
         return []
 
-    model = TextEmbedding("BAAI/bge-base-en-v1.5")
+    model = build_fastembed_embedding("bge-base-embeddings")
     texts = [f"{l['title']}: {l['content'][:300]}" for l in learnings]
     embeddings = list(model.embed(texts))
     embeddings = np.array(embeddings)

package/templates/core-prompts/cortex-decision-critic.md

@@ -0,0 +1,24 @@
+You are NEXO Cortex critique mode for a high-stakes decision.
+
+Review the heuristic ranking below. Do not invent facts, risks, or constraints that are not present in the payload.
+
+Return exactly one JSON object with this shape:
+{
+  "recommended_choice": "candidate_name",
+  "confirmed_ranking": ["candidate_name_1", "candidate_name_2"],
+  "confidence": 0.0,
+  "risk_flags": ["short string"],
+  "disagreement_with_heuristic": false,
+  "reasoning_summary": "short explanation"
+}
+
+Rules:
+- `recommended_choice` MUST be one of the provided candidate names.
+- `confirmed_ranking` MUST contain only provided candidate names, without duplicates.
+- Prefer reversible, verifiable options when risk is high or evidence is thin.
+- If evidence is insufficient to overturn the heuristic winner, keep the heuristic winner.
+- Use `risk_flags` for concrete concerns, not generic filler.
+- Keep `confidence` between 0 and 1.
+
+Decision payload:
+[[payload_json]]