nexo-brain 2.6.13 → 2.6.14

package/.claude-plugin/plugin.json

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

@@ -6,7 +6,7 @@
 [![GitHub stars](https://img.shields.io/github/stars/wazionapps/nexo?style=social)](https://github.com/wazionapps/nexo/stargazers)
 [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 
-> Local cognitive runtime for Claude Code — persistent memory, overnight learning, runtime CLI, recovery-aware background jobs, startup preflight, and doctor diagnostics. 150+ MCP tools. Benchmarked on LoCoMo (F1 0.588, +55% vs GPT-4). Claude Code plugin packaging included.
+> Local cognitive runtime with a shared brain across Claude Code, Codex, Claude Desktop, and other MCP clients. Persistent memory, selectable terminal and automation backends, overnight learning, self-healing background jobs, startup preflight, and doctor diagnostics. 150+ MCP tools. Benchmarked on LoCoMo (F1 0.588, +55% vs GPT-4).
 
 **NEXO Brain transforms any MCP-compatible AI agent from a stateless assistant into a cognitive partner that remembers, learns, forgets, adapts, and builds a relationship with you over time.**
 
@@ -20,6 +20,26 @@
 
 Every time you close a session, everything is lost. Your agent doesn't remember yesterday's decisions, repeats the same mistakes, and starts from zero. NEXO Brain fixes this with a cognitive architecture modeled after how human memory actually works.
 
+## Shared Brain Across Clients
+
+Shared brain is now the baseline:
+
+- **Claude Code** remains the recommended path because it still has the deepest hook integration and the most battle-tested headless automation surface.
+- **Codex** is supported both as an interactive terminal client and as the background automation backend.
+- **Claude Desktop** can point at the same local brain through MCP.
+
+That means NEXO now manages not only the shared runtime and MCP wiring, but also the startup layer around it:
+
+- `nexo chat` opens the configured client instead of assuming Claude Code forever.
+- Claude Code and Codex both get managed bootstrap files:
+  - `~/.claude/CLAUDE.md`
+  - `~/.codex/AGENTS.md`
+- Those files now use an explicit **`CORE` / `USER`** contract, so NEXO can update product rules in `CORE` while preserving operator-specific instructions in `USER`.
+- 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` is the release that closes those last two parity gaps in practice: startup bootstrap parity and transcript-aware Deep Sleep parity.
+
 ## The Problem
 
 AI coding agents are powerful but amnesic:
@@ -198,7 +218,7 @@ This means long sessions (8+ hours) feel like one continuous conversation instea
 
 ## Cognitive Features
 
-NEXO Brain provides **150+ MCP tools** across 20+ categories. These features implement cognitive science concepts that go beyond basic memory:
+NEXO Brain provides **150+ MCP tools** across 23 categories. These features implement cognitive science concepts that go beyond basic memory:
 
 ### Input Pipeline
 
@@ -586,6 +606,16 @@ Or use the shell alias created during install (e.g. `atlas`), which now runs `ne
 
 Your operator will greet you immediately — adapted to the time of day, resuming from where you left off. No cold starts.
 
+### Contributing
+
+NEXO is being hardened in public, and the best contributions now are not only code changes but also real workflow feedback:
+
+- Open issues when a client flow feels asymmetric across Claude Code, Codex, Claude Desktop, OpenClaw, or other MCP environments.
+- Send PRs for docs, install UX, tests, compatibility checks, and public-facing copy.
+- If you use NEXO in production-like daily work, include exact runtime symptoms and commands in bug reports. This project improves fastest when the operational reality is concrete.
+
+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.
+
 ### What Gets Installed
 
 | Component | What | Where |
@@ -608,7 +638,7 @@ Your operator will greet you immediately — adapted to the time of day, resumin
 | Shared client sync | Same `nexo` MCP entry wired into Claude Code, Claude Desktop, and Codex | User config dirs |
 | Client/backend preferences | Selected interactive clients, default terminal client, automation backend, and model/reasoning profiles per client | `NEXO_HOME/config/schedule.json` |
 | Auto-diary | 3-layer system: PostToolUse every 10 calls, PreCompact emergency, heartbeat DIARY_OVERDUE | Built into hooks |
-| Claude Code config | MCP server + 7 hooks + 15 processes registered | ~/.claude/settings.json |
+| Claude Code config | MCP server + 7 hooks + 15 managed processes registered | ~/.claude/settings.json |
 
 ### Runtime CLI
 
@@ -667,7 +697,7 @@ NEXO Brain separates **code** (immutable, in the repo or npm package) from **dat
 The plugin loader scans `src/plugins/` first (base), then `NEXO_HOME/plugins/` (personal override by filename). This dual-directory approach lets you extend NEXO without forking the repo.
 The client sync layer points Claude Code, Claude Desktop, and Codex at the same runtime and `NEXO_HOME`, so all three clients share one brain instead of drifting into separate local memories.
 
-### 150+ MCP Tools across 21+ Categories
+### 150+ MCP Tools across 23 Categories
 
 | Category | Count | Tools | Purpose |
 |----------|-------|-------|---------|

package/bin/nexo-brain.js

@@ -105,6 +105,7 @@ function getCoreRuntimeFlatFiles() {
     "client_sync.py",
     "client_preferences.py",
     "agent_runner.py",
+    "bootstrap_docs.py",
     "auto_update.py",
     "tools_sessions.py",
     "tools_coordination.py",

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "nexo-brain",
-  "version": "2.6.13",
+  "version": "2.6.14",
   "mcpName": "io.github.wazionapps/nexo",
-  "description": "NEXO — local cognitive runtime for Claude Code. Persistent memory, overnight learning, recovery-aware crons, personal scripts, doctor diagnostics, startup preflight, and optional power helper.",
+  "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",
   "bin": {
     "nexo-brain": "./bin/nexo-brain.js",
     "nexo": "./bin/nexo.js"

package/src/agent_runner.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 """Terminal client launchers and headless automation backend runner."""
 
+import json
 import os
 import shutil
 import subprocess
@@ -75,6 +76,18 @@ def _headless_env(env: dict | None = None) -> dict:
     return merged
 
 
+def _load_client_bootstrap_prompt(client: str) -> str:
+    try:
+        from bootstrap_docs import load_bootstrap_prompt
+    except Exception:
+        return ""
+    return load_bootstrap_prompt(client, nexo_home=NEXO_HOME, user_home=Path.home())
+
+
+def _codex_initial_messages_config(prompt_text: str) -> str:
+    return f'initial_messages=[{{role="system",content={json.dumps(prompt_text, ensure_ascii=False)}}}]'
+
+
 def build_interactive_client_command(
     *,
     target: str | os.PathLike[str],
@@ -107,6 +120,9 @@ def build_interactive_client_command(
                 "Codex launcher not found in PATH. Install `codex` first or reconfigure NEXO."
             )
         cmd = [codex_bin]
+        bootstrap_prompt = _load_client_bootstrap_prompt(CLIENT_CODEX)
+        if bootstrap_prompt:
+            cmd.extend(["-c", _codex_initial_messages_config(bootstrap_prompt)])
         if profile["model"]:
             cmd.extend(["-m", profile["model"]])
         if profile["reasoning_effort"]:
@@ -253,6 +269,9 @@ def run_automation_prompt(
                 "-o",
                 str(output_path),
             ]
+            bootstrap_prompt = _load_client_bootstrap_prompt(CLIENT_CODEX)
+            if bootstrap_prompt:
+                cmd.extend(["-c", _codex_initial_messages_config(bootstrap_prompt)])
             if resolved_model:
                 cmd.extend(["-m", resolved_model])
             if resolved_effort:

package/src/auto_update.py

@@ -735,83 +735,61 @@ def _list_section_ids(text: str) -> list[str]:
 
 
 def _migrate_claude_md() -> str | None:
-    """Compare template version vs installed version. If newer, update core sections in user's CLAUDE.md.
-
-    Returns a status message or None if no migration was needed.
-    """
-    template_version = _read_template_version()
-    if not template_version:
+    """Sync the managed Claude bootstrap into ~/.claude/CLAUDE.md."""
+    try:
+        from bootstrap_docs import sync_client_bootstrap
+    except Exception as exc:
+        _log(f"CLAUDE.md migration import error: {exc}")
         return None
 
-    installed_version = _read_installed_claude_md_version()
-    if installed_version == template_version:
-        return None  # Already up to date
-
-    user_md_path = _find_user_claude_md()
-    if not user_md_path:
-        _log("CLAUDE.md migration: no user CLAUDE.md found, skipping")
+    result = sync_client_bootstrap(
+        "claude_code",
+        nexo_home=NEXO_HOME,
+        operator_name="",
+        user_home=Path.home(),
+    )
+    if not result.get("ok"):
+        _log(f"CLAUDE.md migration failed: {result.get('error', 'unknown error')}")
         return None
+    version = result.get("version", "")
+    if version:
+        _write_installed_claude_md_version(version)
+    action = result.get("action", "updated")
+    if action == "unchanged":
+        return f"CLAUDE.md v{version}: already current"
+    msg = f"CLAUDE.md v{version}: {action}"
+    _log(msg)
+    return msg
 
-    # Read both files
-    user_md = user_md_path.read_text()
-    template_raw = TEMPLATE_FILE.read_text()
-    template_resolved = _resolve_placeholders(template_raw)
-
-    # Get all section IDs from the template
-    section_ids = _list_section_ids(template_resolved)
-    if not section_ids:
-        _log("CLAUDE.md migration: no section markers in template, skipping")
-        _write_installed_claude_md_version(template_version)
-        return None
 
-    updated = user_md
-    sections_replaced = 0
-    sections_added = 0
+def _sync_client_bootstraps(preferences: dict | None = None) -> list[str]:
+    try:
+        from bootstrap_docs import sync_enabled_bootstraps
+    except Exception as exc:
+        _log(f"Client bootstrap sync import error: {exc}")
+        return []
 
-    for sid in section_ids:
-        new_section = _extract_section(template_resolved, sid)
-        if not new_section:
+    results = sync_enabled_bootstraps(
+        nexo_home=NEXO_HOME,
+        operator_name="",
+        user_home=Path.home(),
+        preferences=preferences,
+    )
+    messages: list[str] = []
+    for client_key, item in results.items():
+        if item.get("skipped"):
             continue
-
-        old_section = _extract_section(updated, sid)
-        if old_section:
-            if old_section != new_section:
-                updated = updated.replace(old_section, new_section)
-                sections_replaced += 1
+        if not item.get("ok"):
+            _log(f"{client_key} bootstrap sync failed: {item.get('error', 'unknown error')}")
+            continue
+        action = item.get("action", "updated")
+        version = item.get("version", "")
+        label = "Codex AGENTS.md" if client_key == "codex" else "CLAUDE.md"
+        if action == "unchanged":
+            messages.append(f"{label} v{version}: already current")
         else:
-            # Section doesn't exist in user's file — append before the end
-            # (new sections added by template updates)
-            updated = updated.rstrip() + "\n\n" + new_section + "\n"
-            sections_added += 1
-
-    # Update the version comment if present in user's file
-    updated = re.sub(
-        r"<!-- nexo-claude-md-version: [\d.]+ -->",
-        f"<!-- nexo-claude-md-version: {template_version} -->",
-        updated,
-    )
-    # If no version comment existed, add one at the top
-    if "nexo-claude-md-version:" not in updated:
-        updated = f"<!-- nexo-claude-md-version: {template_version} -->\n" + updated
-
-    if sections_replaced > 0 or sections_added > 0:
-        # Backup before writing
-        backup_path = user_md_path.with_suffix(".md.bak")
-        try:
-            backup_path.write_text(user_md)
-        except Exception:
-            pass  # Non-critical
-
-        user_md_path.write_text(updated)
-
-    _write_installed_claude_md_version(template_version)
-
-    if sections_replaced == 0 and sections_added == 0:
-        return f"CLAUDE.md v{template_version}: already current (version file updated)"
-
-    msg = f"CLAUDE.md migrated to v{template_version}: {sections_replaced} section(s) updated, {sections_added} new section(s) added"
-    _log(msg)
-    return msg
+            messages.append(f"{label} v{version}: {action}")
+    return messages
 
 
 # ── Main entry point ─────────────────────────────────────────────────
@@ -824,7 +802,7 @@ def auto_update_check() -> dict:
     Phase 1 (local, safe, no network):
         - DB schema migrations
         - File-based migrations
-        - CLAUDE.md version migration
+        - managed client bootstrap migration
 
     Phase 2 (network, wrapped in try/except):
         - git fetch/pull (if git repo)
@@ -835,6 +813,7 @@ def auto_update_check() -> dict:
         - git_update: str|None — git update status message
         - npm_notice: str|None — npm upgrade notice for non-git installs
         - claude_md_update: str|None — CLAUDE.md migration status
+        - client_bootstrap_updates: list[str] — Codex/Claude bootstrap sync statuses
         - migrations: list — file-based migration results
         - db_migrations: int — number of DB schema migrations applied
         - skipped_reason: str|None — why the network check was skipped (cooldown, etc.)
@@ -845,6 +824,7 @@ def auto_update_check() -> dict:
         "git_update": None,
         "npm_notice": None,
         "claude_md_update": None,
+        "client_bootstrap_updates": [],
         "migrations": [],
         "db_migrations": 0,
         "skipped_reason": None,
@@ -933,7 +913,7 @@ def auto_update_check() -> dict:
 
     # Backfill runtime CLI modules for existing installs
     try:
-        for fname in ("cli.py", "script_registry.py", "skills_runtime.py", "cron_recovery.py", "client_preferences.py", "agent_runner.py"):
+        for fname in ("cli.py", "script_registry.py", "skills_runtime.py", "cron_recovery.py", "client_preferences.py", "agent_runner.py", "bootstrap_docs.py"):
             src_file = SRC_DIR / fname
             dest_file = NEXO_HOME / fname
             if src_file.is_file() and (not dest_file.exists() or src_file.stat().st_mtime > dest_file.stat().st_mtime):
@@ -1024,11 +1004,13 @@ def auto_update_check() -> dict:
     except Exception as e:
         _log(f"Template backfill error: {e}")
 
-    # CLAUDE.md version migration
+    # Managed client bootstrap migration
     try:
-        result["claude_md_update"] = _migrate_claude_md()
+        bootstrap_messages = _sync_client_bootstraps(schedule_data if "schedule_data" in locals() else None)
+        result["client_bootstrap_updates"] = bootstrap_messages
+        result["claude_md_update"] = next((msg for msg in bootstrap_messages if msg.startswith("CLAUDE.md")), None)
     except Exception as e:
-        _log(f"CLAUDE.md migration error: {e}")
+        _log(f"Client bootstrap migration error: {e}")
 
     # ── Phase 2: Network operations (wrapped, never fatal) ──────────
     # Skip entirely if auto_update is disabled in schedule.json
@@ -1198,7 +1180,7 @@ def _backup_runtime_tree(dest: Path = NEXO_HOME) -> str:
         "maintenance.py", "storage_router.py", "claim_graph.py", "hnsw_index.py",
         "evolution_cycle.py", "migrate_embeddings.py", "auto_close_sessions.py",
         "client_sync.py",
-        "client_preferences.py", "agent_runner.py",
+        "client_preferences.py", "agent_runner.py", "bootstrap_docs.py",
         "auto_update.py", "tools_sessions.py", "tools_coordination.py",
         "tools_reminders.py", "tools_reminders_crud.py", "tools_learnings.py",
         "tools_credentials.py", "tools_task_history.py", "tools_menu.py",
@@ -1248,7 +1230,7 @@ def _copy_runtime_from_source(src_dir: Path, repo_dir: Path, dest: Path = NEXO_H
         "maintenance.py", "storage_router.py", "claim_graph.py", "hnsw_index.py",
         "evolution_cycle.py", "migrate_embeddings.py", "auto_close_sessions.py",
         "client_sync.py",
-        "client_preferences.py", "agent_runner.py",
+        "client_preferences.py", "agent_runner.py", "bootstrap_docs.py",
         "auto_update.py", "tools_sessions.py", "tools_coordination.py",
         "tools_reminders.py", "tools_reminders_crud.py", "tools_learnings.py",
         "tools_credentials.py", "tools_task_history.py", "tools_menu.py",
@@ -1617,6 +1599,7 @@ def startup_preflight(*, entrypoint: str, interactive: bool = False) -> dict:
         "git_update": None,
         "npm_notice": None,
         "claude_md_update": None,
+        "client_bootstrap_updates": [],
         "migrations": [],
         "power_policy": None,
         "power_message": None,
@@ -1651,7 +1634,9 @@ def startup_preflight(*, entrypoint: str, interactive: bool = False) -> dict:
 
             _run_db_migrations()
             result["migrations"] = run_file_migrations()
-            result["claude_md_update"] = _migrate_claude_md()
+            bootstrap_messages = _sync_client_bootstraps()
+            result["client_bootstrap_updates"] = bootstrap_messages
+            result["claude_md_update"] = next((msg for msg in bootstrap_messages if msg.startswith("CLAUDE.md")), None)
             _sync_watchdog_hash_registry()
             _warn_protected_runtime_location()
             _ensure_runtime_cli_wrapper()