nexo-brain 2.6.17 → 2.6.18

package/.claude-plugin/plugin.json

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

@@ -38,11 +38,15 @@ That means NEXO now manages not only the shared runtime and MCP wiring, but also
 - For Codex specifically, `nexo chat` and Codex headless automation inject the current bootstrap explicitly, so Codex starts as NEXO even when plain global Codex startup is inconsistent about global instructions.
 - Deep Sleep now reads both Claude Code and Codex transcript stores, so overnight analysis still works even when the user spends the day in Codex.
 
-Version `2.6.14` closes those parity gaps in practice, `2.6.15` hardens the installed-runtime migration path so existing users actually receive the managed bootstrap updates cleanly, `2.6.16` pushes the system further in three directions, and `2.6.17` finishes the annoying last-mile migration bugs for real existing installs:
+Version `2.6.14` closes those parity gaps in practice, `2.6.15` hardens the installed-runtime migration path so existing users actually receive the managed bootstrap updates cleanly, `2.6.16` pushes the system further in three directions, `2.6.17` finishes the annoying last-mile migration bugs for real existing installs, and `2.6.18` tightens the remaining practical gaps around manual Codex use, Deep Sleep horizon artifacts, and retrieval honesty:
 
 - Codex now gets managed global bootstrap/model sync in `~/.codex/config.toml`, so sessions opened outside `nexo chat` are much less likely to start as plain Codex.
+- Codex config now also persists a managed `mcp_servers.nexo` entry, so the shared brain survives even if ad-hoc Codex MCP state drifts.
+- Runtime doctor now audits recent Codex sessions for real startup discipline and verifies Claude Desktop shared-brain metadata explicitly instead of treating both as invisible best-effort wiring.
 - Retrieval is smarter by default: HyDE and spreading activation now auto-enable when the query shape benefits, while exact lookups remain conservative.
+- Retrieval explanations now surface confidence and the auto-strategy that fired, while associative expansion trims itself back to `top_k` instead of leaking low-signal neighbors.
 - Deep Sleep now blends recent context with older context over a 60-day horizon, and memory decay now tracks per-memory `stability` and `difficulty` instead of relying only on global decay constants.
+- Deep Sleep now also carries project-priority weighting into its long-horizon context and writes reusable weekly/monthly summary artifacts instead of reasoning only day by day.
 - Existing installs that already had NEXO connected to Codex now backfill that client state automatically during update/sync, so the managed Codex bootstrap actually lands without manual cleanup.
 - Bootstrap docs now fall back to the operator name `NEXO` when local metadata is blank, avoiding broken headings in `CLAUDE.md` and `AGENTS.md`.
 
@@ -52,11 +56,12 @@ Version `2.6.14` closes those parity gaps in practice, `2.6.15` hardens the inst
 |------------|-------------|-------|----------------|
 | Shared brain / MCP runtime | Yes | Yes | Yes |
 | Managed bootstrap document | `~/.claude/CLAUDE.md` | `~/.codex/AGENTS.md` | Not applicable |
-| Global startup bootstrap sync | Native via hooks + bootstrap | Managed via bootstrap + Codex config `initial_messages` | MCP only |
+| Global startup bootstrap sync | Native via hooks + bootstrap | Managed via bootstrap + Codex config `initial_messages` + `mcp_servers.nexo` | Managed MCP-only shared-brain metadata |
 | `nexo chat` terminal client | Yes | Yes | No |
 | Background automation backend | Recommended | Supported | No |
 | Raw transcript source for Deep Sleep | Yes | Yes | No |
 | Native hook depth | Deepest | Partial, compensated | None |
+| Runtime doctor parity audit | Yes | Yes | Shared-brain only |
 | Recommended today | Yes | Supported | Shared-brain companion |
 
 ## The Problem
@@ -193,6 +198,9 @@ Deep Sleep now also mixes **recent context with older context across a 60-day ho
 - recurring multi-week themes
 - cross-domain links between older learnings and current failures
 - stale followups and topics that keep being mentioned but never formalized
+- weighted project pressure based on diary activity, followups, learnings, and decision outcomes
+
+It now also writes **weekly and monthly Deep Sleep summaries** so the overnight system can reuse higher-horizon signals instead of rediscovering everything from scratch every day.
 
 ## Cognitive Cortex
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "2.6.17",
+  "version": "2.6.18",
   "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/client_sync.py

@@ -243,10 +243,12 @@ def _sync_codex_managed_config(
     *,
     bootstrap_prompt: str,
     runtime_profile: dict | None,
+    server_config: dict | None,
 ) -> dict:
     payload = _load_toml_object(path)
     action = "updated" if payload else "created"
     runtime_profile = dict(runtime_profile or {})
+    server_config = dict(server_config or {})
 
     if runtime_profile.get("model"):
         payload["model"] = runtime_profile["model"]
@@ -263,10 +265,19 @@ def _sync_codex_managed_config(
     nexo_table = payload.setdefault("nexo", {})
     codex_table = nexo_table.setdefault("codex", {})
     codex_table["bootstrap_managed"] = True
+    codex_table["mcp_managed"] = True
     codex_table["bootstrap_bytes"] = len(bootstrap_prompt.encode("utf-8")) if bootstrap_prompt else 0
     if runtime_profile.get("model"):
         codex_table["managed_model"] = runtime_profile["model"]
     codex_table["managed_reasoning_effort"] = runtime_profile.get("reasoning_effort", "") or ""
+    if server_config:
+        mcp_servers = payload.setdefault("mcp_servers", {})
+        mcp_servers["nexo"] = {
+            "command": server_config.get("command", ""),
+            "args": list(server_config.get("args", []) or []),
+            "env": dict(server_config.get("env", {}) or {}),
+        }
+        codex_table["managed_server_command"] = server_config.get("command", "")
 
     _write_toml_object(path, payload)
     return {
@@ -274,6 +285,7 @@ def _sync_codex_managed_config(
         "action": action,
         "path": str(path),
         "bootstrap_managed": True,
+        "mcp_managed": True,
         "model": runtime_profile.get("model", ""),
         "reasoning_effort": runtime_profile.get("reasoning_effort", "") or "",
     }
@@ -296,7 +308,7 @@ def _write_json_object(path: Path, payload: dict) -> None:
     path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n")
 
 
-def _sync_json_client(path: Path, server_config: dict, label: str) -> dict:
+def _sync_json_client(path: Path, server_config: dict, label: str, *, managed_metadata: dict | None = None) -> dict:
     payload = _load_json_object(path)
     mcp_servers = payload.setdefault("mcpServers", {})
     if not isinstance(mcp_servers, dict):
@@ -304,6 +316,12 @@ def _sync_json_client(path: Path, server_config: dict, label: str) -> dict:
         payload["mcpServers"] = mcp_servers
     action = "updated" if "nexo" in mcp_servers else "created"
     mcp_servers["nexo"] = server_config
+    if managed_metadata is not None:
+        nexo_meta = payload.setdefault("nexo", {})
+        if not isinstance(nexo_meta, dict):
+            nexo_meta = {}
+            payload["nexo"] = nexo_meta
+        nexo_meta.update(managed_metadata)
     _write_json_object(path, payload)
     return {
         "ok": True,
@@ -313,6 +331,18 @@ def _sync_json_client(path: Path, server_config: dict, label: str) -> dict:
     }
 
 
+def _claude_desktop_managed_metadata(server_config: dict, *, operator_name: str) -> dict:
+    return {
+        "claude_desktop": {
+            "shared_brain_managed": True,
+            "shared_brain_mode": "mcp_only",
+            "managed_operator": operator_name or server_config.get("env", {}).get("NEXO_NAME", "") or "NEXO",
+            "managed_runtime_home": server_config.get("env", {}).get("NEXO_HOME", ""),
+            "managed_runtime_root": server_config.get("env", {}).get("NEXO_CODE", ""),
+        }
+    }
+
+
 def sync_claude_code(
     *,
     nexo_home: str | os.PathLike[str] | None = None,
@@ -361,10 +391,15 @@ def sync_claude_desktop(
         python_path=python_path,
         operator_name=operator_name,
     )
+    resolved_name = server_config.get("env", {}).get("NEXO_NAME", "") or _resolve_operator_name(
+        Path(nexo_home).expanduser() if nexo_home else _default_nexo_home(),
+        explicit=operator_name,
+    )
     return _sync_json_client(
         _claude_desktop_config_path(Path(user_home).expanduser() if user_home else None),
         server_config,
         "claude_desktop",
+        managed_metadata=_claude_desktop_managed_metadata(server_config, operator_name=resolved_name),
     )
 
 
@@ -410,6 +445,7 @@ def sync_codex(
                 config_path,
                 bootstrap_prompt=prompt_text,
                 runtime_profile=runtime_profile,
+                server_config=server_config,
             )
         return result
 
@@ -425,29 +461,12 @@ def sync_codex(
         timeout=30,
         env=env,
     )
-    if result.returncode != 0:
-        result = {
-            "ok": False,
-            "client": "codex",
-            "path": str(config_path),
-            "error": (result.stderr or result.stdout or "codex mcp add failed").strip(),
-        }
-        bootstrap_result = sync_client_bootstrap(
-            "codex",
-            nexo_home=nexo_home,
-            operator_name=operator_name,
-            user_home=user_home,
-        )
-        result["bootstrap"] = bootstrap_result
-        if not bootstrap_result.get("ok"):
-            result["error"] = f"{result['error']}; bootstrap: {bootstrap_result.get('error', 'unknown error')}"
-        return result
     sync_result = {
         "ok": True,
         "client": "codex",
         "action": "updated",
         "path": str(config_path),
-        "mode": "cli",
+        "mode": "cli" if result.returncode == 0 else "config_only",
     }
     bootstrap_result = sync_client_bootstrap(
         "codex",
@@ -464,7 +483,10 @@ def sync_codex(
         config_path,
         bootstrap_prompt=bootstrap_result.get("content") or "",
         runtime_profile=runtime_profile,
+        server_config=server_config,
     )
+    if result.returncode != 0:
+        sync_result["warning"] = (result.stderr or result.stdout or "codex mcp add failed").strip()
     return sync_result
 
 

package/src/cognitive/_search.py

@@ -159,6 +159,7 @@ _HISTORICAL_CUES = frozenset({
 _EXACT_LOOKUP_RE = re.compile(
     r"(/|\\|::|\.[A-Za-z0-9]+|#L\d+|line \d+|error[: ]|exception|traceback|0x[0-9a-fA-F]+|[A-Z]{2,}-\d+)"
 )
+_MIN_NEIGHBOR_BOOST = 0.035
 
 
 def _apply_temporal_boost(results: list[dict], query_text: str) -> list[dict]:
@@ -254,6 +255,14 @@ def _auto_spreading_depth(query_text: str, source_type_filter: str = "") -> int:
     return 0
 
 
+def _result_confidence(score: float) -> str:
+    if score >= 0.82:
+        return "high"
+    if score >= 0.66:
+        return "medium"
+    return "low"
+
+
 # ============================================================================
 # FEATURE 0.5: Knowledge Graph Boost
 # Memories connected to more KG nodes (files, areas, other learnings) are
@@ -928,13 +937,23 @@ def search(
                     r["co_activation_boost"] = boost
 
             # Add neighbor memories not already in results
-            new_neighbor_hashes = set(neighbor_boosts.keys()) - existing_hashes
+            new_neighbor_hashes = {
+                nh
+                for nh, boost in neighbor_boosts.items()
+                if nh not in existing_hashes and boost >= _MIN_NEIGHBOR_BOOST
+            }
             if new_neighbor_hashes:
+                ranked_new_neighbors = sorted(
+                    new_neighbor_hashes,
+                    key=lambda nh: neighbor_boosts.get(nh, 0.0),
+                    reverse=True,
+                )[: max(1, min(3, top_k // 3 or 1))]
+                allowed_new_neighbors = set(ranked_new_neighbors)
                 for store_name, table in [("stm", "stm_memories"), ("ltm", "ltm_memories")]:
                     rows = db.execute(f"SELECT * FROM {table}").fetchall()
                     for row in rows:
                         nh = _canonical_co_id(store_name, row["id"])
-                        if nh in new_neighbor_hashes:
+                        if nh in allowed_new_neighbors:
                             boost = neighbor_boosts[nh]
                             results.append({
                                 "store": store_name,
@@ -951,10 +970,11 @@ def search(
                                 "co_activation_boost": boost,
                                 "lifecycle_state": row.get("lifecycle_state", "active"),
                             })
-                            new_neighbor_hashes.discard(nh)
+                            allowed_new_neighbors.discard(nh)
 
             # Re-sort after applying boosts
             results.sort(key=lambda x: x["score"], reverse=True)
+            results = results[:top_k]
 
     # Add rank explanations
     for rank, r in enumerate(results, 1):
@@ -970,6 +990,7 @@ def search(
         if resolved_use_hyde:
             ranking_desc = "hyde_centroid_similarity"
         parts = [f"Ranked #{rank}: {ranking_desc}={score:.3f}"]
+        parts.append(f"confidence={_result_confidence(score)}")
         parts.append(f"store={store}, strength={strength:.2f}, accesses={access_count}")
         if r.get("kg_boost"):
             parts.append(f"kg_boost=+{r['kg_boost']:.3f} ({r.get('kg_connections', 0)} edges)")
@@ -979,6 +1000,12 @@ def search(
             parts.append("hyde=auto")
         if spreading_depth is None and resolved_spreading_depth > 0:
             parts.append(f"spreading=auto:{resolved_spreading_depth}")
+        if use_hyde is None and resolved_use_hyde and spreading_depth is None and resolved_spreading_depth > 0:
+            parts.append("auto_strategy=semantic+associative recall")
+        elif use_hyde is None and resolved_use_hyde:
+            parts.append("auto_strategy=semantic expansion")
+        elif spreading_depth is None and resolved_spreading_depth > 0:
+            parts.append("auto_strategy=associative expansion")
         if created:
             parts.append(f"created={created[:10]}")
         if tags:

package/src/doctor/providers/runtime.py

@@ -54,18 +54,162 @@ def _codex_bootstrap_config_status() -> dict:
             "error": str(exc),
         }
     managed = bool(payload.get("nexo", {}).get("codex", {}).get("bootstrap_managed"))
+    mcp_managed = bool(payload.get("nexo", {}).get("codex", {}).get("mcp_managed"))
     initial_messages = payload.get("initial_messages", [])
     has_initial_messages = bool(initial_messages)
+    mcp_server = payload.get("mcp_servers", {}).get("nexo", {})
     return {
         "exists": True,
         "path": str(path),
         "bootstrap_managed": managed,
+        "mcp_managed": mcp_managed,
         "has_initial_messages": has_initial_messages,
         "model": str(payload.get("model", "") or ""),
         "reasoning_effort": str(payload.get("model_reasoning_effort", "") or ""),
+        "has_mcp_server": isinstance(mcp_server, dict) and bool(mcp_server.get("command")) and bool(mcp_server.get("args")),
+        "mcp_runtime_home": str((mcp_server.get("env") or {}).get("NEXO_HOME", "") or ""),
+        "mcp_runtime_root": str((mcp_server.get("env") or {}).get("NEXO_CODE", "") or ""),
     }
 
 
+def _claude_desktop_shared_brain_status() -> dict:
+    path = Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json"
+    if not path.is_file():
+        return {"exists": False, "path": str(path), "shared_brain_managed": False}
+    try:
+        payload = json.loads(path.read_text())
+    except Exception as exc:
+        return {
+            "exists": True,
+            "path": str(path),
+            "shared_brain_managed": False,
+            "error": str(exc),
+        }
+    mcp_server = (payload.get("mcpServers") or {}).get("nexo", {})
+    metadata = ((payload.get("nexo") or {}).get("claude_desktop") or {})
+    return {
+        "exists": True,
+        "path": str(path),
+        "has_mcp_server": isinstance(mcp_server, dict) and bool(mcp_server.get("command")) and bool(mcp_server.get("args")),
+        "shared_brain_managed": bool(metadata.get("shared_brain_managed")),
+        "shared_brain_mode": str(metadata.get("shared_brain_mode", "") or ""),
+        "managed_runtime_home": str(metadata.get("managed_runtime_home", "") or ""),
+        "managed_runtime_root": str(metadata.get("managed_runtime_root", "") or ""),
+    }
+
+
+def _recent_codex_session_parity_status(*, days: int = 7, max_files: int = 24) -> dict:
+    roots = [
+        Path.home() / ".codex" / "sessions",
+        Path.home() / ".codex" / "archived_sessions",
+    ]
+    cutoff = time.time() - (days * 86400)
+    candidates: list[tuple[float, Path]] = []
+    for root in roots:
+        if not root.exists():
+            continue
+        for path in root.rglob("*.jsonl"):
+            try:
+                mtime = path.stat().st_mtime
+            except OSError:
+                continue
+            if mtime >= cutoff:
+                candidates.append((mtime, path))
+    candidates.sort(key=lambda item: item[0], reverse=True)
+    files = [path for _, path in candidates[:max_files]]
+
+    status = {
+        "files": len(files),
+        "bootstrap_sessions": 0,
+        "startup_sessions": 0,
+        "heartbeat_sessions": 0,
+        "origins": set(),
+        "samples": [],
+    }
+    for path in files:
+        saw_bootstrap = False
+        saw_startup = False
+        saw_heartbeat = False
+        origin = ""
+        try:
+            with path.open() as fh:
+                for raw in fh:
+                    if (
+                        not saw_bootstrap
+                        and (
+                            "NEXO Shared Brain for Codex" in raw
+                            or "<!-- nexo-codex-agents-version:" in raw
+                            or "You are NEXO" in raw
+                        )
+                    ):
+                        saw_bootstrap = True
+                    try:
+                        event = json.loads(raw)
+                    except Exception:
+                        continue
+                    payload = event.get("payload", {})
+                    if event.get("type") == "session_meta" and isinstance(payload, dict):
+                        origin = str(payload.get("originator", "") or payload.get("source", "") or "")
+                    if event.get("type") != "response_item" or not isinstance(payload, dict):
+                        continue
+                    if payload.get("type") != "function_call":
+                        continue
+                    name = str(payload.get("name", "") or "")
+                    if name in {"mcp__nexo__nexo_startup", "nexo_startup"}:
+                        saw_startup = True
+                    elif name in {"mcp__nexo__nexo_heartbeat", "nexo_heartbeat"}:
+                        saw_heartbeat = True
+                    if saw_bootstrap and saw_startup and saw_heartbeat and origin:
+                        break
+        except Exception:
+            continue
+        if origin:
+            status["origins"].add(origin)
+        if saw_bootstrap:
+            status["bootstrap_sessions"] += 1
+        if saw_startup:
+            status["startup_sessions"] += 1
+        if saw_heartbeat:
+            status["heartbeat_sessions"] += 1
+        status["samples"].append(
+            {
+                "file": str(path),
+                "bootstrap": saw_bootstrap,
+                "startup": saw_startup,
+                "heartbeat": saw_heartbeat,
+                "origin": origin,
+            }
+        )
+    status["origins"] = sorted(status["origins"])
+    return status
+
+
+def _client_assumption_regressions() -> list[str]:
+    src_root = NEXO_CODE / "src"
+    if not src_root.is_dir():
+        return []
+    allowed_claude_projects = {
+        (src_root / "scripts" / "deep-sleep" / "collect.py").resolve(),
+    }
+    offenders: list[str] = []
+    for path in src_root.rglob("*.py"):
+        try:
+            text = path.read_text()
+        except Exception:
+            continue
+        resolved = path.resolve()
+        if ".claude/projects" in text and resolved not in allowed_claude_projects:
+            offenders.append(f"{path.relative_to(NEXO_CODE)} hardcodes ~/.claude/projects")
+    collect_path = src_root / "scripts" / "deep-sleep" / "collect.py"
+    try:
+        collect_text = collect_path.read_text()
+    except Exception:
+        collect_text = ""
+    if collect_text and (".claude/projects" in collect_text) and (".codex" not in collect_text or "find_codex_session_files" not in collect_text):
+        offenders.append("deep-sleep/collect.py references Claude transcripts without Codex transcript parity")
+    return offenders
+
+
 def _file_age_seconds(path: Path) -> float | None:
     """Return file age in seconds, or None if not found."""
     try:
@@ -1093,6 +1237,11 @@ def check_client_bootstrap_parity(fix: bool = False) -> DoctorCheck:
                 severity = "warn"
                 evidence.append(f"codex config missing managed bootstrap injection at {codex_config.get('path')}")
                 repair_plan.append("Run `nexo clients sync` or `nexo update` so plain Codex sessions inherit the NEXO bootstrap")
+            elif codex_config.get("exists") and not codex_config.get("has_mcp_server"):
+                status = "degraded"
+                severity = "warn"
+                evidence.append(f"codex config missing managed `mcp_servers.nexo` at {codex_config.get('path')}")
+                repair_plan.append("Re-sync Codex so manual sessions keep the shared brain even if `codex mcp add` state drifts")
             elif codex_config.get("exists"):
                 evidence.append(
                     "codex config bootstrap managed"
@@ -1140,6 +1289,151 @@ def check_client_bootstrap_parity(fix: bool = False) -> DoctorCheck:
     )
 
 
+def check_codex_session_parity() -> DoctorCheck:
+    try:
+        schedule = _load_json(SCHEDULE_FILE) if SCHEDULE_FILE.is_file() else {}
+    except Exception:
+        schedule = {}
+    prefs = normalize_client_preferences(schedule)
+    wants_codex = bool(
+        prefs.get("interactive_clients", {}).get("codex")
+        or prefs.get("default_terminal_client") == "codex"
+        or (prefs.get("automation_enabled", True) and prefs.get("automation_backend") == "codex")
+    )
+    if not wants_codex:
+        return DoctorCheck(
+            id="runtime.codex_sessions",
+            tier="runtime",
+            status="healthy",
+            severity="info",
+            summary="Codex session parity check skipped (Codex not selected)",
+        )
+
+    audit = _recent_codex_session_parity_status()
+    if audit["files"] == 0:
+        return DoctorCheck(
+            id="runtime.codex_sessions",
+            tier="runtime",
+            status="degraded",
+            severity="warn",
+            summary="No recent Codex sessions found to verify startup discipline",
+            repair_plan=[
+                "Start Codex through `nexo chat` at least once so doctor can verify recent NEXO startup behavior",
+            ],
+            escalation_prompt=(
+                "Codex is selected, but there are no recent durable Codex sessions to inspect. "
+                "NEXO cannot prove that manual Codex sessions are entering the shared-brain startup flow."
+            ),
+        )
+
+    evidence = [
+        f"recent codex sessions inspected: {audit['files']}",
+        f"bootstrap markers seen in {audit['bootstrap_sessions']}/{audit['files']}",
+        f"nexo_startup seen in {audit['startup_sessions']}/{audit['files']}",
+        f"nexo_heartbeat seen in {audit['heartbeat_sessions']}/{audit['files']}",
+    ]
+    if audit["origins"]:
+        evidence.append(f"origins: {', '.join(audit['origins'])}")
+
+    status = "healthy"
+    severity = "info"
+    repair_plan: list[str] = []
+    if audit["bootstrap_sessions"] == 0:
+        status = "degraded"
+        severity = "warn"
+        repair_plan.append("Run `nexo update` or `nexo clients sync` so plain Codex sessions inherit the managed bootstrap")
+    if audit["startup_sessions"] == 0:
+        status = "degraded"
+        severity = "warn"
+        repair_plan.append("Use `nexo chat` or keep the global Codex bootstrap intact so sessions actually call `nexo_startup`")
+
+    return DoctorCheck(
+        id="runtime.codex_sessions",
+        tier="runtime",
+        status=status,
+        severity=severity,
+        summary="Recent Codex sessions show NEXO startup discipline" if status == "healthy" else "Recent Codex sessions need stronger NEXO startup discipline",
+        evidence=evidence,
+        repair_plan=repair_plan,
+        escalation_prompt=(
+            "Codex is selected, but recent durable Codex sessions are not consistently showing NEXO bootstrap markers or `nexo_startup`. "
+            "Manual Codex sessions may still be starting too plain."
+        ) if status != "healthy" else "",
+    )
+
+
+def check_claude_desktop_shared_brain() -> DoctorCheck:
+    try:
+        schedule = _load_json(SCHEDULE_FILE) if SCHEDULE_FILE.is_file() else {}
+    except Exception:
+        schedule = {}
+    prefs = normalize_client_preferences(schedule)
+    wants_desktop = bool(prefs.get("interactive_clients", {}).get("claude_desktop"))
+    installed = detect_installed_clients().get("claude_desktop", {}).get("installed", False)
+    status_info = _claude_desktop_shared_brain_status()
+
+    if not wants_desktop and not installed:
+        return DoctorCheck(
+            id="runtime.claude_desktop",
+            tier="runtime",
+            status="healthy",
+            severity="info",
+            summary="Claude Desktop shared-brain check skipped (client not installed)",
+        )
+
+    evidence = [
+        f"config: {status_info.get('path')}",
+        f"shared brain mode: {status_info.get('shared_brain_mode') or 'mcp_only'}",
+    ]
+    if status_info.get("managed_runtime_home"):
+        evidence.append(f"runtime home: {status_info.get('managed_runtime_home')}")
+
+    if status_info.get("error"):
+        return DoctorCheck(
+            id="runtime.claude_desktop",
+            tier="runtime",
+            status="degraded",
+            severity="warn",
+            summary="Claude Desktop config is unreadable",
+            evidence=evidence + [status_info["error"]],
+            repair_plan=["Repair Claude Desktop config JSON and re-run `nexo clients sync`"],
+        )
+
+    if not status_info.get("exists") or not status_info.get("has_mcp_server"):
+        return DoctorCheck(
+            id="runtime.claude_desktop",
+            tier="runtime",
+            status="degraded",
+            severity="warn",
+            summary="Claude Desktop is not pointed at the shared NEXO brain",
+            evidence=evidence,
+            repair_plan=["Run `nexo clients sync` so Claude Desktop shares the same local brain"],
+            escalation_prompt=(
+                "Claude Desktop is installed or enabled, but its MCP config does not show the shared `nexo` runtime."
+            ),
+        )
+
+    if not status_info.get("shared_brain_managed"):
+        return DoctorCheck(
+            id="runtime.claude_desktop",
+            tier="runtime",
+            status="degraded",
+            severity="warn",
+            summary="Claude Desktop shares NEXO, but managed metadata is missing",
+            evidence=evidence,
+            repair_plan=["Re-sync Claude Desktop so doctor can verify the managed shared-brain contract"],
+        )
+
+    return DoctorCheck(
+        id="runtime.claude_desktop",
+        tier="runtime",
+        status="healthy",
+        severity="info",
+        summary="Claude Desktop shared-brain parity OK (MCP-only mode)",
+        evidence=evidence,
+    )
+
+
 def check_transcript_source_parity() -> DoctorCheck:
     """Check whether Deep Sleep can see transcript sources for the selected clients."""
     try:
@@ -1207,6 +1501,34 @@ def check_transcript_source_parity() -> DoctorCheck:
     )
 
 
+def check_client_assumption_regressions() -> DoctorCheck:
+    offenders = _client_assumption_regressions()
+    if not offenders:
+        return DoctorCheck(
+            id="runtime.client_assumptions",
+            tier="runtime",
+            status="healthy",
+            severity="info",
+            summary="No new Claude-only runtime path assumptions detected",
+        )
+    return DoctorCheck(
+        id="runtime.client_assumptions",
+        tier="runtime",
+        status="critical",
+        severity="error",
+        summary=f"Detected {len(offenders)} client-parity regression(s) in runtime source",
+        evidence=offenders[:10],
+        repair_plan=[
+            "Replace Claude-only transcript or hook assumptions with shared client abstractions",
+            "Keep Deep Sleep and startup flows aware of both Claude Code and Codex surfaces",
+        ],
+        escalation_prompt=(
+            "A runtime source file drifted back to a Claude-only assumption. "
+            "Audit the offending file and restore client-agnostic parity before shipping."
+        ),
+    )
+
+
 def run_runtime_checks(fix: bool = False) -> list[DoctorCheck]:
     """Run all runtime-tier checks. Read-only by default."""
     return [
@@ -1216,7 +1538,10 @@ def run_runtime_checks(fix: bool = False) -> list[DoctorCheck]:
         check_cron_freshness(),
         check_client_backend_preferences(),
         check_client_bootstrap_parity(fix=fix),
+        check_codex_session_parity(),
+        check_claude_desktop_shared_brain(),
         check_transcript_source_parity(),
+        check_client_assumption_regressions(),
         check_launchagent_integrity(fix=fix),
         check_personal_script_registry(fix=fix),
         check_skill_health(fix=fix),

package/src/plugins/cognitive_memory.py

@@ -65,6 +65,10 @@ def handle_cognitive_retrieve(
         mode_parts.append(f"spreading={spreading_depth}")
     elif spreading_depth is None:
         mode_parts.append("spreading=AUTO")
+    if results:
+        top_score = float(results[0].get("score", 0.0) or 0.0)
+        confidence = "high" if top_score >= 0.82 else "medium" if top_score >= 0.66 else "low"
+        mode_parts.append(f"top_confidence={confidence}")
     header = f"COGNITIVE RETRIEVE — query: '{query}' | {len(results)} results ({', '.join(mode_parts)})\n\n"
     return header + formatted