nexo-brain 2.6.17 → 2.6.20

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "2.6.17",
+  "version": "2.6.20",
   "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, `2.6.18` tightens the remaining practical gaps around manual Codex use, Deep Sleep horizon artifacts, and retrieval honesty, and `2.6.20` makes the recommended Claude profile explicit across installer, runtime defaults, existing installs, and the update path itself: `Opus 4.6 with 1M context`.
 
 - 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
 
@@ -637,7 +645,7 @@ nexo scripts list  # See your personal scripts
 During install, NEXO now asks which interactive clients you want to connect, which one `nexo chat` should open by default, whether to enable background automation, which backend should run that automation, and which model profile each active terminal/backend should use. Shared brain stays on in every mode.
 
 Recommended defaults:
-- Claude Code: `Opus latest`
+- Claude Code: `Opus 4.6 with 1M context`
 - Codex: `gpt-5.4` with `xhigh` reasoning
 
 Or use the shell alias created during install (e.g. `atlas`), which now runs `nexo chat .` so it opens whichever terminal client you selected as default.
@@ -654,6 +662,9 @@ NEXO is being hardened in public, and the best contributions now are not only co
 
 The project still recommends Claude Code as the primary path, but contributions that improve Codex, client parity, installer clarity, and ecosystem integrations are especially valuable.
 
+Maintainers and contributors touching startup, bootstrap, Deep Sleep, or shared-brain behavior should also use the client parity checklist:
+- [docs/client-parity-checklist.md](docs/client-parity-checklist.md)
+
 ### What Gets Installed
 
 | Component | What | Where |
@@ -715,7 +726,7 @@ The Doctor system reads existing health artifacts (immune, watchdog, self-audit)
 - **macOS or Linux** (Windows via [WSL](https://learn.microsoft.com/en-us/windows/wsl/install))
 - **Node.js 18+** (for the installer)
 - **Claude Code is the primary recommended client.** It remains the most mature NEXO path: native hooks, the most battle-tested automation contract, and the clearest parity with historical production behavior.
-- **Recommended profiles:** Claude Code + `Opus latest`; Codex + `gpt-5.4` with `xhigh` reasoning if you prefer Codex as your terminal or automation backend.
+- **Recommended profiles:** Claude Code + `Opus 4.6 with 1M context`; Codex + `gpt-5.4` with `xhigh` reasoning if you prefer Codex as your terminal or automation backend.
 - Python 3, Homebrew, and the selected required client/backend can be installed automatically when NEXO has a supported installer path for that dependency.
 
 ## Architecture
@@ -822,7 +833,7 @@ NEXO Brain is designed as an MCP server. Claude Code remains the primary recomme
 npx nexo-brain
 ```
 
-All 150+ tools are available immediately after installation. The installer configures Claude Code's `~/.claude/settings.json` automatically. The recommended Claude profile is `Opus latest`.
+All 150+ tools are available immediately after installation. The installer configures Claude Code's `~/.claude/settings.json` automatically. The recommended Claude profile is `Opus 4.6 with 1M context`.
 
 ### Claude Desktop
 
@@ -912,6 +923,7 @@ If NEXO Brain is useful to you, consider:
 - **[Sponsor on GitHub](https://github.com/sponsors/wazionapps)** — support ongoing development directly
 - **Share your experience** — tell others how you're using cognitive memory in your AI workflows
 - **Contribute** — see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Issues and PRs welcome
+- **Client parity / shared-brain maintenance** — see [docs/client-parity-checklist.md](docs/client-parity-checklist.md)
 
 [![Star History Chart](https://api.star-history.com/svg?repos=wazionapps/nexo&type=Date)](https://star-history.com/#wazionapps/nexo&Date)
 

package/bin/nexo-brain.js

@@ -33,6 +33,10 @@ const LAUNCH_AGENTS = path.join(
 );
 const MACOS_FDA_SETTINGS_URL = "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles";
 const PUBLIC_CONTRIBUTION_UPSTREAM = "wazionapps/nexo";
+const DEFAULT_CLAUDE_CODE_MODEL = "claude-opus-4-6[1m]";
+const DEFAULT_CLAUDE_CODE_REASONING_EFFORT = "";
+const DEFAULT_CODEX_MODEL = "gpt-5.4";
+const DEFAULT_CODEX_REASONING_EFFORT = "xhigh";
 
 function isEphemeralInstall(nexoHome) {
   const homeDir = require("os").homedir();
@@ -480,12 +484,12 @@ function getDefaultSchedule(timezone) {
     automation_backend: "claude_code",
     client_runtime_profiles: {
       claude_code: {
-        model: "opus",
-        reasoning_effort: "",
+        model: DEFAULT_CLAUDE_CODE_MODEL,
+        reasoning_effort: DEFAULT_CLAUDE_CODE_REASONING_EFFORT,
       },
       codex: {
-        model: "gpt-5.4",
-        reasoning_effort: "xhigh",
+        model: DEFAULT_CODEX_MODEL,
+        reasoning_effort: DEFAULT_CODEX_REASONING_EFFORT,
       },
     },
     client_install_preferences: {
@@ -656,12 +660,12 @@ async function askChoice(question, options, defaultValue) {
 function defaultClientRuntimeProfiles() {
   return {
     claude_code: {
-      model: "opus",
-      reasoning_effort: "",
+      model: DEFAULT_CLAUDE_CODE_MODEL,
+      reasoning_effort: DEFAULT_CLAUDE_CODE_REASONING_EFFORT,
     },
     codex: {
-      model: "gpt-5.4",
-      reasoning_effort: "xhigh",
+      model: DEFAULT_CODEX_MODEL,
+      reasoning_effort: DEFAULT_CODEX_REASONING_EFFORT,
     },
   };
 }
@@ -690,10 +694,11 @@ function runtimeProfileCatalog(lang, client) {
       customModelQuestionEn: `  Enter the model alias/name for ${runtimeClientLabel(client)} > `,
       customEffortQuestion: `  Escribe el effort para ${runtimeClientLabel(client)} (vacío = default) > `,
       customEffortQuestionEn: `  Enter the effort for ${runtimeClientLabel(client)} (blank = default) > `,
-      modelDefault: "opus",
+      modelDefault: DEFAULT_CLAUDE_CODE_MODEL,
       effortDefault: "",
       modelOptions: [
-        { value: "opus", label: `Opus latest${recommended}` },
+        { value: DEFAULT_CLAUDE_CODE_MODEL, label: `Opus 4.6 with 1M context${recommended}` },
+        { value: "claude-opus-4-6", label: "Opus 4.6" },
         { value: "sonnet", label: "Sonnet latest" },
         { value: "custom", label: lang === "es" ? "Modelo personalizado" : "Custom model" },
       ],
@@ -715,8 +720,8 @@ function runtimeProfileCatalog(lang, client) {
     customModelQuestionEn: `  Enter the model name for ${runtimeClientLabel(client)} > `,
     customEffortQuestion: `  Escribe el reasoning effort para ${runtimeClientLabel(client)} > `,
     customEffortQuestionEn: `  Enter the reasoning effort for ${runtimeClientLabel(client)} > `,
-    modelDefault: "gpt-5.4",
-    effortDefault: "xhigh",
+    modelDefault: DEFAULT_CODEX_MODEL,
+    effortDefault: DEFAULT_CODEX_REASONING_EFFORT,
     modelOptions: [
       { value: "gpt-5.4", label: `GPT-5.4${recommended}` },
       { value: "gpt-5.4-pro", label: "GPT-5.4 Pro" },

package/package.json

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

@@ -229,6 +229,9 @@ def _resolve_runtime_model_and_effort(
     if client == CLIENT_CODEX:
         if not requested_model or requested_model.lower() in CLAUDE_LEGACY_MODEL_HINTS:
             requested_model = profile["model"]
+    elif client == CLIENT_CLAUDE_CODE:
+        if not requested_model or requested_model.lower() in CLAUDE_LEGACY_MODEL_HINTS:
+            requested_model = profile["model"]
     elif not requested_model:
         requested_model = profile["model"]
 

package/src/client_preferences.py

@@ -36,18 +36,10 @@ INSTALL_PREFERENCE_KEYS = {
     "skip",
     "manual",
 }
-DEFAULT_CLIENT_RUNTIME_PROFILES = {
-    CLIENT_CLAUDE_CODE: {
-        "model": "opus",
-        "reasoning_effort": "",
-    },
-    CLIENT_CODEX: {
-        "model": "gpt-5.4",
-        "reasoning_effort": "xhigh",
-    },
-}
-
-
+DEFAULT_CLAUDE_CODE_MODEL = "claude-opus-4-6[1m]"
+DEFAULT_CLAUDE_CODE_REASONING_EFFORT = ""
+DEFAULT_CODEX_MODEL = "gpt-5.4"
+DEFAULT_CODEX_REASONING_EFFORT = "xhigh"
 def _user_home() -> Path:
     return Path(os.environ.get("HOME", str(Path.home()))).expanduser()
 
@@ -225,8 +217,14 @@ def normalize_client_install_preferences(value) -> dict[str, str]:
 
 def default_client_runtime_profiles() -> dict[str, dict[str, str]]:
     return {
-        client_key: dict(profile)
-        for client_key, profile in DEFAULT_CLIENT_RUNTIME_PROFILES.items()
+        CLIENT_CLAUDE_CODE: {
+            "model": DEFAULT_CLAUDE_CODE_MODEL,
+            "reasoning_effort": DEFAULT_CLAUDE_CODE_REASONING_EFFORT,
+        },
+        CLIENT_CODEX: {
+            "model": DEFAULT_CODEX_MODEL,
+            "reasoning_effort": DEFAULT_CODEX_REASONING_EFFORT,
+        },
     }
 
 

package/src/client_sync.py

@@ -55,7 +55,7 @@ except Exception:
 
     def resolve_client_runtime_profile(client: str, preferences: dict | None = None) -> dict:
         defaults = {
-            "claude_code": {"model": "opus", "reasoning_effort": ""},
+            "claude_code": {"model": "claude-opus-4-6[1m]", "reasoning_effort": ""},
             "codex": {"model": "gpt-5.4", "reasoning_effort": "xhigh"},
         }
         return dict(defaults.get(client, {}))
@@ -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: