NEXO Brain — Your AI Gets a Brain

Local cognitive runtime with a shared brain across Claude Code, Codex, Claude Desktop, and other MCP clients. Persistent memory, durable workflow runs, 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.

Watch the overview video · Watch on YouTube · Open the infographic

Version 7.23.1 is the current packaged-runtime line. Express patch over v7.23.0 - headless automations no longer hang on silent Claude children, synthetic followup prompts no longer trigger session-end loops, and runtime backups self-prune under a hard cap before creating new large artifacts.

Previously in 7.23.0: minor release over v7.22.0 - pre-answer routing now consults continuity evidence before visible replies, Memory Observations queue processing converges through a bounded processor, and audits expose saved-but-not-used stores, automation drift, MCP live/catalog gaps, artifact location and transcript coverage.

Previously in 7.22.0: minor release over v7.21.0 - heartbeat stays fast in Desktop-managed sessions, MCP writes can be accepted through a durable file-backed queue before SQLite commit, Brain exposes compliance state for Desktop gates, and Local Context adds Entity Dossier for open-domain local evidence aggregation.

Previously in 7.21.0: minor release over v7.20.25 - MCP now starts through a thin compatibility adapter backed by one resident local Runtime Service, reducing duplicate Brain processes and SQLite contention across Claude Code, Codex, Claude Desktop, and NEXO Desktop.

Previously in 7.20.25: patch release over v7.20.24 — Local Context now uses the pinned local BGE embedding model when available, automatically refreshes old hash embeddings, prioritizes known documents before lower-value files, and treats the Desktop-owned Qwen local-presence model as optional in standalone Brain installs.

Previously in 7.20.24: patch release over v7.20.23 — Local Memory performance profile writes now tolerate active indexing, retry transient SQLite busy states, and shorten indexer write locks between processed files.

Previously in 7.20.23: patch release over v7.20.22 — Local Memory status reads the real split sidecar database read-only, reports retryable keyed failures without false zeroes, and keeps Desktop Spanish/English copy localized.

Previously in 7.20.22: patch release over v7.20.19 — Local Memory moved out of the main Brain database, MCP readiness verifies required tools, and split-aware Desktop backups validate the main DB and Local Memory sidecar separately.

Previously in 7.20.18: patch release over v7.20.17 — Desktop-managed setup now preserves a completed onboarding flag when Brain is later invoked with the non-interactive --skip bootstrap path.

Previously in 7.20.17: patch release over v7.20.16 — validated DB backups now tolerate tiny live-write growth from the Local Memory indexer while still rejecting real protected-table loss.

Previously in 7.20.16: patch release over v7.20.15 — packaged updates keep the local_context runtime shim importable and rollback code-tree snapshots safely when compatibility directories are symlinks.

Previously in 7.20.15: patch release over v7.20.14 — Brain update/recovery paths now fail closed when the DB guard is missing or stale, and backup validation rejects any replacement that loses Local Memory tables.

Previously in 7.20.14: patch release over v7.20.13 — Brain protects Local Memory during update/recovery paths, rotates runtime backup families to the latest 5 entries, keeps first-indexing status stable, and exposes bounded indexing speed profiles for Desktop.

Previously in 7.20.13: patch release over v7.20.12 — Brain recovery now pauses all known DB writers before restoring nexo.db, and Doctor can repair the zero-byte/locked database state that made Desktop Local Memory show zero files.

Previously in 7.20.12: patch release over v7.20.11 — Local Context now keeps the first index pass separate from live change tracking, persists the current indexing start time, caps compact context payloads for agents, and installs the Windows host scheduler needed to keep WSL indexing alive after reboots.

Previously in 7.20.11: patch release over v7.20.10 — Local Context now starts from real system volume roots plus mounted/removable/network volumes, filters system/cache/app/product artifacts, and injects relevant local evidence automatically into heartbeat, task-open and pre-action context.

Previously in 7.20.10: patch release over v7.20.9 — Local Context manual refreshes now reconcile automatic roots every time, so newly mounted disks and upgraded default roots are picked up immediately from Desktop's "comprobar cambios" path.

Previously in 7.20.9: patch release over v7.20.8 — Local Context scans automatic roots at full operational depth, falls back to crontab when Linux/WSL systemd user timers fail, passes Windows AppData email roots into WSL, and blocks Google API keys before HTML cleaning.

Previously in 7.20.8: patch release over v7.20.7 — Local Context recognises Windows Mail package roots and Outlook Mac profile roots as bounded local-email sources instead of rejecting them as generic AppData / Group Containers.

Previously in 7.20.7: patch release over v7.20.6 — Local Context email-root bootstrap is deterministic across CI, WSL and migrated profiles while preserving macOS Mail.app, Windows Outlook, Thunderbird and NEXO email coverage.

Previously in 7.20.6: patch release over v7.20.5 — Local Context ranks entity matches at chunk level, keeps old entity-matched assets eligible, adds safe local email roots for macOS/Windows/Linux, extracts .eml, .emlx, .msg and NEXO email DB continuity, and exposes local graph relations in pre-action context.

Previously in 7.20.5: patch release over v7.20.4 — Local Context status reports elapsed indexing time and a defensive ETA while background jobs remain pending.

Previously in 7.20.4: patch release over v7.20.3 — Local Context now blocks private dotfiles, hidden project folders and secret-bearing content before chunks, embeddings, graph relations or agent context are created.

Previously in 7.20.3: patch release over v7.20.2 — installer DMG volumes are no longer added as local-memory roots, removed roots purge stale payloads, and doctor can repair removed-root residue.

Previously in 7.20.2: patch release over v7.20.1 — Local Context now requeues stalled work, reports real macOS/Windows background-service health, records scan errors and preserves Windows drive roots.

Previously in 7.20.1: patch release over v7.20.0 — the Local Context service now recovers from orphaned locks and mixed-version cycle failures instead of leaving the background index stuck.

Previously in 7.20.0: minor release over v7.19.0 — the Local Context index now reconciles known files and folders on every service cycle, so created, modified, deleted and newly excluded local files are reflected automatically between full scans.

Previously in 7.19.0: minor release over v7.18.1 - bundle-managed installations (NEXO Desktop brain-bundle/) can now pin Brain to the host application release cycle via NEXO_BRAIN_AUTO_UPDATE=false, and the server auto-exits with code 75 on fingerprint mismatch so MCP clients respawn the server with the new code instead of leaving stale server.py processes alive.

Previously in 7.18.1: patch release over v7.18.0 - packaged Brain runtimes now include the local_context package, so Desktop Local Memory and nexo local-context do not get stuck behind ModuleNotFoundError or zero-file status; the local-index service also keeps detecting newly mounted volumes automatically.

Previously in 7.18.0: minor release over v7.17.8 - Brain adds the Local Context Layer: a local-only background memory index with checkpoints, extraction, graph links, embeddings, MCP/CLI controls, and pre-action evidence for NEXO agents.

Previously in 7.17.8: patch release over v7.17.7 - standalone nexo chat now surfaces macOS Full Disk Access guidance, and Brain clears stale permission state after a live access probe succeeds.

Previously in 7.17.7: patch release over v7.17.6 - macOS TCC privacy denials now become a guided Full Disk Access permission state instead of an unexplained cron failure, with Desktop-ready status written for user action.

Previously in 7.17.6: patch release over v7.17.5 - cron health diagnostics are clearer for macOS TCC approval, and catch-up fallback executions now stay visible in cron_runs even on legacy or partially migrated runtimes.

Previously in 7.17.5: patch release over v7.17.4 - nexo --version --json now returns machine-readable update status so NEXO Desktop can populate the Updates panel without scraping slower human output.

Previously in 7.17.4: corrective patch over v7.17.3 - automation runners now keep full NEXO discipline for real background agents while strict JSON children stay clean, and runtime doctor/metrics expose caller coverage and Guardian injection telemetry instead of hiding blind spots.

Previously in 7.17.3: corrective patch over v7.17.2 - standalone Brain install/update no longer aborts when the Desktop-only qwen3-0.6b-q4-local-presence model is not bundled or already cached locally. Required Brain warmups stay strict; only the optional local-presence GGUF now degrades cleanly.

Previously in 7.17.2: patch release over v7.17.1 - email-monitor now guards its /tmp/nexo-* draft buffers before writing, morning-agent closes interrupted/stale briefing claims deterministically, and Codex managed config migrates from the legacy codex_hooks flag to [features].hooks.

Previously in 7.17.1: patch release over v7.17.0 - the headless Claude CLI 2.1+ direct-JSON response shape is now handled: when the wrapper {"result": ...} is absent and the agent's answer is returned directly, _extract_claude_telemetry surfaces the full payload to the caller instead of an empty string. Fixes the daily morning-agent failure with "Morning agent returned invalid JSON output".

Previously in 7.17.0: minor release over v7.16.3 - the headless runner pre-emptive guard becomes advisory: it surfaces learnings/schemas to the agent and logs to guard_checks, but never returns blocked=True. The PreToolUse hook is the authoritative gate at write time.

Previously in 7.16.3: patch release over v7.16.2 - the headless runner guard opts out of the runtime-core blocking rule because actual writes on those paths are already blocked at the PreToolUse layer.

Previously in 7.16.0: minor release over v7.15.2 - Brain adds Memory Observations v2: evidence-backed event capture, derived observations, update-safe backfill, MCP retrieval, dashboard visibility, and safer refusal when memory lacks evidence.

Previously in 7.15.2: patch release over v7.15.1 - Brain treats normal Codex startup context reads of calibration and project atlas files as healthy bootstrap activity instead of conditioned-file drift.

Previously in 7.15.1: patch release over v7.15.0 - Brain drains larger self-audit clusters, bounds hook history with update-time cleanup, filters normal Codex bootstrap reads, routes email-monitor effort by message complexity, and locks morning briefings by local date and recipient.

Previously in 7.15.0: minor release — Brain unifies sent-email continuity across send paths, moves cognitive recall to multilingual embeddings, forces tagged learnings into context, hardens email loop guards and headless runners, exposes learning creation dates, and adds AUTO-N burst postmortems.

Previously in 7.14.0: minor release — Brain closes the install/reliability loop with update-path venv recovery, platform-gated wheels, WSL Desktop-managed flag preservation, startup memory authority warnings, legacy MEMORY write blocking, post-action real-world verification, and stale followup triage.

Previously in 7.13.9: patch release — Brain moves aside an existing managed .venv when it was created with unsupported Python <3.10, then recreates it with the supported interpreter prepared by Desktop.

Previously in 7.13.8: patch release — Brain rejects Python <3.10 during Desktop-managed fresh installs, honors the Python interpreter prepared by Desktop, and fails clearly before dependency resolution if an unsupported Apple Python 3.9 reaches the installer.

Previously in 7.13.7: patch release — Brain adds an authenticated official protocol-card client (nexo_card_catalog, nexo_card_get, nexo_card_match) so agents can ask the NEXO Desktop backend for the right task protocol at runtime. The protocol corpus stays private on the server; this open-source package ships only the client, tool map, and agent guidance.

Previously in 7.13.6: patch release — Codex hook sync now renders the managed PreToolUse shell/exec_command guard with native Windows cmd.exe syntax while preserving the existing POSIX command on macOS/Linux. Result: coordinated Desktop bundles can ship the fixed Brain without changing the Mac/Windows installation contract.

Previously in 7.13.3: unified release — doctor now repairs orphan personal script metadata and ignores historical versions/** snapshots, nexo update prunes runtime snapshots older than two back, protocol compliance self-heals missing task-open/change-log/stale-session gaps, headless automation uses bounded timeouts, Guardian false positives are tightened, and Codex CLI config/default checks are release-gated. Result: coordinated Desktop bundles can ship the new Brain without changing the Mac/Windows installation contract.

Previously in 7.12.15: patch release — same-version packaged updates now still run the safe maintenance path, Deep Sleep clears process locks on shutdown, sent replies are recorded in durable continuity, and personal script schedule-marker drift is surfaced during reconcile. Result: coordinated Desktop bundles can refresh Brain safely without breaking install/update parity on macOS, Windows via WSL, or Linux.

Previously in 7.12.0: minor release — adds nexo support-snapshot for generic local runtime diagnostics and completes the silent-reminder hardening on the live Protocol Enforcer path. The support collector emits one JSON bundle with version/platform metadata, runtime path presence, health-check output, and recent event/operation tails, while map-driven reminders (nexo_startup, nexo_smart_startup, nexo_heartbeat, nexo_reminders, nexo_session_diary_*, nexo_stop, nexo_task_close, compaction checkpoint prompts) now say explicitly that silence owns the entire reminder turn.

Previously in 7.11.5: patch release — Desktop-managed installs now block the standalone dashboard at the same product-mode layer as evolution, so installation_live, cron sync, and watchdog no longer disagree about whether com.nexo.dashboard should exist. Validation: 125 targeted tests across product-mode, cron sync, and doctor, plus a full pre-release wrapper (2321 passed, 2 skipped, 1 xfailed, 4 xpassed).

Previously in 7.11.4: patch release — packaged runtimes now receive root JSON contracts such as local_model_manifest.json, install/update paths sync core crons from src/crons/manifest.json instead of depending on a stale JS list, runner-health-check is wired into cron/doctor/dashboard instead of writing an unread file, and the watchdog retries failed crons immediately while treating run_once_on_wake as catchup-style recovery. Validation: 117 targeted tests across packaged update, cron sync/recovery, dashboard, local models, and runtime update contracts.

Previously in 7.11.3: patch release — root-cause fix for the mcp_restart_required lockup that v7.11.2 only masked at the enforcer layer. _FINGERPRINT_EXCLUDE_DIRS in src/runtime_versioning.py was missing "versions", so compute_mcp_runtime_fingerprint() walked into core/versions/<old>/**.py whenever it was called against the live runtime root. installed_runtime_fingerprint() (which resolves through active_runtime_root() → core/versions/<active>/) returned a clean per-snapshot hash, while prime_process_fingerprint() (which starts from Path(__file__).resolve().parent → live core/) accumulated every retained snapshot. The two never matched after the second-ever nexo update on a host. Every update wrote mcp-restart-required.json and the marker could never be cleared by _ack_current_client_if_restarted() because the installed_fp != process_fp test always returned True. Every non-allowlisted MCP tool (nexo_reminders, nexo_smart_startup, nexo_guard_check, nexo_task_open, …) returned {"error": "mcp_restart_required", "reason": "fingerprint_mismatch"} indefinitely, even after the operator restarted the client. Adding "versions" to _FINGERPRINT_EXCLUDE_DIRS restores parity; 21 runtime-fingerprint tests stayed green.

Previously in 7.11.2: patch release — two reliability fixes in the same family ("components ignoring signals they should respect"): (1) STUCK CRON REAPER added to nexo-watchdog.sh and (2) the Guardian/Enforcer now honors the mcp-restart-required marker. The watchdog reaper closes the v5.8.1 in-flight gap: truly hung wrappers (e.g. headless claude --bare blocked on an MCP that flagged mcp_restart_required) used to hold their slot for days. The reaper sweeps cron_runs rows with ended_at IS NULL past stuck_after_seconds (per-cron from manifest.json, fallback 12h global), SIGTERMs the wrapper (trap closes row at exit 143), grace 10s, SIGKILL on survivors. Generous defaults (deep-sleep 8h, sleep/evolution 4h) prevent any v5.8.1 regression. The enforcer gate skips nexo_*-mentioning reminders when the marker file is present (cached per-instance, 30s TTL); reminders that don't reference nexo_* still fire. 12 new tests; 3 existing watchdog tests + 52 existing enforcer tests stay green.

Previously in 7.11.1: patch release — caches the runtime fingerprint by (file_count, size_total, max_mtime) signature so MCP startup and the per-tool-call resolve_restart_required skip the 263-file rehash when nothing on disk changed. ~11× speedup warm path (~40ms → ~3.7ms locally), ~10-20s/day saved across Claude Code / Codex / headless / deep-sleep / cron startups. Cache miss is always safe (falls through to full hash and self-repairs). Default use_cache=False keeps plugins/update.py on the ground-truth path around git pull / npm update. Builds on the v7.11.0 runtime fingerprint that gates mcp-restart-required.json. Full write-up in docs/runtime-fingerprint.md.

Previously in 7.10.0: minor release — removes the LLM proxy override path that 7.9.28 → 7.9.34 introduced. Background: 7.9.28 added two opt-in files at ~/.nexo/config/llm_endpoint.json and ~/.nexo/config/auth_provider.json that let a third-party orchestrator (NEXO Desktop) redirect every Anthropic SDK call from Brain to a custom proxy and resolve the bearer via a local helper, with concrete model names translated to wire aliases (nexo-max, nexo-high, nexo-medium, nexo-low, nexo-mini) and an Idempotency-Key per request. NEXO Desktop's commercial model has changed: Desktop is now a wrapper over the user's own Claude Code subscription (Max / Pro), with a separate Desktop licence. Brain calls go directly to api.anthropic.com using the user's existing OAuth (the one stored under ~/.claude/ and consumed by Claude Code spawns) or a plain ANTHROPIC_API_KEY. There is no NEXO bearer, no NEXO proxy, no NEXO credit accounting in this codebase. Every proxy symbol is gone from call_model_raw.py and agent_runner.py; the proxy-specific tests and docs/api/override-files.md are removed; any pre-existing override files on disk are simply ignored from this release forward.

Previously in 7.9.34: two fixes — the email monitor's header parser was dropping any email whose RFC822 headers came back as email.header.Header instances (Q-encoded utf-8 / quoted-printable). Every msg.get(...) now goes through _decode_header, and the failure log is lifted from DEBUG to WARNING. The PreToolUse Guardian gate hardens hard blocks with stderr + exit 2 enforcement so terminal Claude cannot ignore the deny channel mid-tool-loop.

Previously in 7.9.33: adds usedforsecurity=False to the SHA-1 call that derives a filesystem-safe checkpoint filename from the email's Message-ID, so Bandit's B324 audit no longer fails the publish workflow on a non-security usage. The v7.9.32 git tag is preserved for traceability but no npm release ever shipped for it; [email protected] is the first release that carries the 7.9.32 email-recovery checkpoints.

Previously in 7.9.32: hardens the email monitor's recovery so emails that fall between Brain releases never end up in a permanent limbo. The periodic _recover_unreplied_processed sweep now looks back 7 days (was 24h), and every failed worker run persists a per-email checkpoint at ~/.nexo/nexo-email/checkpoints/ capturing files touched, last assistant narration, and error. Retry attempts inject that context into the next prompt so a long task (drafting a presentation, multi-step analysis) continues from where the previous attempt died instead of restarting from scratch. Stale checkpoints are pruned automatically after 7 days. 15 new unit tests cover the helpers.

Previously in 7.9.31: fixes a wire-level bug where call_model_raw was sending stop_sequences=["\n", ".", " "] by default, which the current Anthropic Messages API rejects with HTTP 400 each stop sequence must contain non-whitespace. The default is now None (no stop_sequences field sent) since max_tokens=3 already caps the yes/no classifier output. A local guard rejects whitespace-only caller values up front so the error shows where the caller is, not as a remote 400. Also removes an internal design document that did not belong in the open-source distribution.

Previously in 7.9.30: hotfix for a missing import sys in src/agent_runner.py that ruff F821 caught in CI and blocked the 7.9.29 publish workflow before any npm artifact shipped. [email protected] is the first npm release that carries the 7.9.29 override-path hardening.

Previously in 7.9.29: hardening pass on the optional LLM endpoint and auth provider override path. The bearer is now passed to the Anthropic SDK via auth_token so it lands in the standard Authorization: Bearer header (7.9.28 sent it as X-Api-Key and any compatible proxy rejected every request with 401). The Brain config directory is resolved on each call instead of cached at import, so LaunchAgent crons that export NEXO_HOME via a wrapper now reach the right ~/.nexo/config/. The Idempotency-Key header accepts a caller-provided value so application-level retries reuse the same dedup key. Override mode is strict about its bearer source: if auth_provider.json is missing or the helper fails, the call raises ClassifierUnavailableError instead of falling back to the operator's real ANTHROPIC_API_KEY, which would otherwise leak to the custom proxy as a second header. A new end-to-end test suite drives the real SDK against a local http.server and asserts on captured wire headers and body, complementing the SDK-mock unit tests.

Previously in 7.9.28: optional override files at ~/.nexo/config/llm_endpoint.json and ~/.nexo/config/auth_provider.json let third-party orchestrators redirect Brain's Anthropic SDK calls and delegate bearer token resolution to a local command (analogous to git's credential.helper). The same redirection is propagated to every CLI child Brain spawns (deep-sleep, evolution, followup-runner, morning-agent, email-monitor, nexo chat) by injecting ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY into the spawned environment, so headless crons reach the proxy too. An Idempotency-Key (UUID4 hex) is attached per request for proxy-side dedup of transparent retries within 24h. Brain libre standalone (no override files) hits api.anthropic.com directly with ANTHROPIC_API_KEY exactly as before.

Previously in 7.9.27: server startup no longer hangs the MCP initialize handshake when legacy followups/reminders still need owner backfill — the synchronous startup migration now runs --rules-only and skips the multi-minute LocalZeroShotClassifier load, keeping handshake under a few seconds.

Previously in 7.9.26: headless automation prompts now receive the operator-language contract centrally, so reports, diaries, syntheses, followups, escalations, and Deep Sleep-generated memory text follow calibration even when the underlying template is English.

Previously in 7.9.23: Desktop lifecycle fallback diaries now enrich sparse lifecycle events from continuity snapshots, so app-exit fallback evidence preserves recent turn context even when the live agent does not answer the injected diary prompt before shutdown.

Previously in 7.9.22: Desktop lifecycle shutdowns gained an emergency Brain-side fallback diary path, so close/archive/app-exit can preserve title, goal, session ids, and transcript tail even when the live agent does not answer the injected diary prompt before shutdown.

Previously in 7.9.21: LaunchAgent reload/repair now handles macOS already-loaded races by booting out jobs with modern launchctl forms, falling back to legacy load, and treating an already-loaded job as healthy only when it points at the expected plist.

Previously in 7.9.20: packaged update/doctor repair now finds runtime/crons/sync.py, LaunchAgent PATH includes the managed Claude runtime installed under ~/.nexo/runtime/bootstrap/npm-global/bin, root runtime backfill includes claude_cli.py, and Immune no longer treats the legacy optional ~/.claude-mem/claude-mem.db as a required database.

Previously in 7.9.19: runtime doctor now distinguishes real install breakage from tracked in-progress work, interactive Desktop sessions no longer poison automation telemetry scoring, stale filesystem skill rows are pruned during sync, stale protocol debt draining marks rows resolved, and watchdog treats LaunchAgent SIGTERM reloads as supervisor interruptions instead of failures.

Previously in 7.9.18: packaged client-sync imports now work when NEXO_HOME is unset, so nexo clients sync, nexo update, and runtime doctor bootstrap checks no longer hit the _user_home import-order crash.

Previously in 7.9.17: continuity snapshot idempotency marks its SHA-1 digest as non-security usage, keeping the high-severity Bandit gate green while preserving stable idempotency keys.

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.

Previously in 7.9.4: patch release that blocks the Brain 7.9.3 + Desktop 0.28.2 diary regression: canonical lifecycle plans now require real session_diary evidence (wait_for_diary_write) before stop_session, and canonical completion is rejected/retryable without that diary row. It also fixes npm CLI onboarding so nexo-brain --version and subcommands never launch the wizard when legacy/v2 calibration is already valid, commits setup calibration atomically only after the wizard completes, and adds nexo-brain warmup-models so install/update paths predownload the local mDeBERTa/BGE/reranker models. Verification: full Brain pytest (2189 passed, 3 skipped, 1 xfailed, 5 xpassed), release-readiness, npm pack dry-run, and coordinated Desktop v0.28.3 checks.

Previously in 7.9.3: patch release that hardens Brain's canonical lifecycle plan for Desktop close/archive/delete/app-exit diary guarantees: canonical_actions now publish the v2 canonical shape (type plus payload.prompt) while keeping one-release compatibility mirrors (kind plus top-level prompt) for older Desktop clients. This lets Desktop execute resume → diary prompt → stop with one exact owner per lifecycle event and preserve Brain-side dedupe by event id. Targeted verification: pytest tests/test_lifecycle_events.py (25 passing) plus release-readiness after artifact sync.

Previously in 7.9.2: patch release that completes the Brain semantic-router site migration: the remaining decision callers now route through semantic_router.route(...) with named decision_kind policies (r20_constant_change, r34_identity_coherence, t4_r15, t4_r23e, t4_r23f, t4_r23h, followup_operator_attention, drive_signal_type, drive_area, reply_event_type, query_intent, and sentiment_intent). Brain now owns model choice, thresholds, and fallback behaviour centrally instead of each caller carrying its own classifier policy. The patch also fixes packaged headless Guardian map loading: enforcement_engine and agent_runner now check the installed core directory (~/.nexo/core/tool-enforcement-map.json) so followup-runner, morning-agent, digest, and email-monitor load the map instead of falling back to unguarded subprocess execution. Targeted verification: 100 semantic/router/enforcer tests, 125 Drive/cognitive/productization tests, and release-readiness passing.

Previously in 7.9.0: minor release that ships the foundation of the semantic stack (router + reasoner + CLI) under the ONEPASS LLM Coverage plan, plus two product-bug fixes observed in the wild on 2026-04-23. New src/semantic_router.py exposes 18 named decision_kinds (13 textual + 5 code-aware) with a per-kind policy table and the layer chain fast_local → semantic_reasoner → remote_fallback. New src/semantic_reasoner.py adds Mode A (multipass_local: reuses the mDeBERTa pin with three prompt-perturbed passes + majority vote + 0.75 floor) and Mode B (cached_llm: wrapper over call_model_raw with a pid+uuid atomic-write 24h-TTL disk cache at ~/.nexo/runtime/operations/semantic-reasoner-cache.json, SHA-256 keyed by decision_kind + normalized input, LRU-bounded at 2000 entries, corrupt entries dropped on read). New scripts/semantic-classify.py JSON-in JSON-out CLI lets external MCP clients (including the closed-source NEXO Desktop companion) query Brain as the single semantic authority. New NEXO_SEMANTIC_REASONER kill switch (0/off/false/no/disable/disabled) honours the plan mandate for a runtime opt-out separate from NEXO_LOCAL_CLASSIFIER. Bug fixes: bin/nexo-brain.js upgrade flow now copies templates/ root the same way fresh install and same-version refresh already did (Maria iMac 7.1.10→7.8.1 upgrade had lost 27 core-prompts templates and broken post-update import verification); and tool-enforcement-map.json nexo_startup.enforcement.inject_prompt now instructs the model to preload the 13 mcp__nexo__* protocol tools via ToolSearch before calling nexo_startup when the host MCP client defers tool schemas (Claude Code with many MCPs installed). Audit-driven hardening: router/reasoner defensively use getattr over the call_model_raw module and add a trailing except Exception so provider errors degrade with remote_error instead of propagating; cache writes use pid+uuid tmp + fsync + os.replace to survive concurrent writers; NEXO_SEMANTIC_REASONER_TTL parse tolerates malformed values. Tests: +50 (22 router, 20 reasoner, 8 CLI). Per-site migration of existing callers (session_end_intent, r14, r16, r17, r20, r34, T4 gates, tools_drive, nexo-followup-runner) is explicitly deferred to follow-up patch releases and tracked as NF-SEMANTIC-ROUTER-SITE-MIGRATION; nothing in this release changes the behaviour of the existing callers. Companion coordinated release: NEXO Desktop v0.28.0.

Previously in 7.8.2: patch release that fixes the compact-hook observability gap Francisco flagged after v7.8.1: hook_runs.session_id was empty for 7 out of 8 recent compaction rows (and when populated it stored the raw Claude Code token instead of the NEXO sid), so per-session queries over hook_runs for compact events could not be joined back to the NEXO session that actually compacted. v7.8.2 adds src/hooks/compact_session_resolver.py with resolve_nexo_sid(claude_session_id), which walks the same rails the shell already uses: sessions.claude_session_id match, then session_claude_aliases.claude_session_id (most recent last_seen wins), then the per-conversation sidecar under runtime/data/compacting/<safe-claude-id>.txt, then the legacy global sidecar for single-conversation setups. src/hooks/pre_compact.py and src/hooks/post_compact.py now call the resolver and store the real NEXO sid in hook_runs.session_id; both wrappers also stash {claude_session_id, sid_source} in hook_runs.metadata so "why is this row still empty?" has a one-query answer. Nine new tests in tests/test_hook_runs_compact_sid_resolution.py pin the five resolver rails (sessions / alias / sidecar / legacy / none), malformed-sidecar rejection, the pre- and post-compact wrapper end-to-end paths, and the empty-state wrapper rail so a clean audit trail is written even when nothing resolves. No Desktop bump.

Previously in 7.8.1: patch release that closed the last compaction-continuity gap Francisco flagged after v7.8.0: pre-compact.sh Layer 2 emergency auto-diary and Layer 3 compaction_memory.record_auto_flush now use the exact TARGET_SID resolved from CLAUDE_SESSION_ID instead of falling back to ORDER BY last_update_epoch DESC LIMIT 1 ("latest active session"). In multi-conversation Desktop that fallback routinely wrote the emergency diary against the wrong conversation even though the main restore path was already exact-SID in v7.8.0. last_diary_ts is also scoped by session_id now. Fail-closed when no CLAUDE_SESSION_ID resolves. New behavioural tests drive the real shell script with two sessions in the DB to pin the invariant. Fixed a latent bash-escape bug in pre-compact.sh where a double-quoted string inside a Python comment silently closed the python3 -c "..." argument early — caught by adding the behavioural tests. Pytest 2092 passing (+2 new behavioural). No Desktop bump.

Previously in 7.8.0: minor release that closed the PostCompact continuity work Francisco requested after v7.7: src/hooks/post_compact.py is a real registered hook (part of the canonical 9-hook set, was 8), pre-compact.sh resolves the exact NEXO SID from CLAUDE_SESSION_ID instead of falling back to "latest active session" (that was actively wrong in multi-conversation Desktop), the sidecar moves from /tmp to $NEXO_HOME/runtime/data/compacting-sid.txt so two concurrent compactions on two conversations cannot race on /tmp, post-compact.sh removes its "latest checkpoint" fallback (fail-closed to a diagnostic systemMessage instead of restoring the wrong conversation), and the hook cross-checks the sidecar SID against the env-resolved one so a "SID mismatch" is logged as such. Pre- and post-compact now emit NDJSON events the engine drains on every periodic tick via _consume_pending_hook_events(); the queue file is truncated after read so an event never fires twice. A new contract test (tests/test_v78_compaction_continuity.py) pins 11 invariants across ten rails including the hook registration, the exact-SID resolution path, fail-closed behaviour, and that compaction_count only increments on real restore. Pytest 2086 passing (+16 vs v7.7). No Desktop bump — v0.27.0 continues to ship.

Previously in 7.7.0: minor release that closed the six gaps left partial after v7.6.0's constructor-guardian-90 pass 1 (autonomous detector for multi_step_task_detected, R16 vocabulary expansion, R_CATALOG extended to plain Edit/Write, new R_PRIMITIVE_CHOICE rule, R11_plugin_load_pre_inventory hardened, 12 new contract tests). Post-review hotfix on the same release wired task_open rearm properly (discarded from tools_called + per-instance pin cleared on task_close), added live on_event triggers in R14 and R16, and called on_tool_call_before before on_tool_call in run_with_enforcement so before_tool rules fire in Brain the same way Desktop fires onBeforeToolCall.

Previously in 7.6.0: minor release that closed the drift between tool-enforcement-map.json v2.2 and the two enforcement engines (Brain Python + Desktop JS), added per-instance after_tool satisfaction, tightened learning_add grace to 0 and task_open threshold to 4/must, hardened R15/R17/R22/R_CATALOG from soft to hard, and raised R34 from shadow to soft.

Previously in 7.5.0: minor release that promoted nexo_lifecycle_event from ledger + reconciliation authority to canonical authority of session-end. Brain now owns the prompt, the sequence, and the timing of diary+stop; Desktop v0.25.0 (closed-source companion) is the conduit that executes Brain's plan against the live Claude process. The new 2-call contract — nexo_lifecycle_event returns a versioned canonical_plan (resume_session → inject_prompt → stop_session, with stable ids and per-action timeouts) and nexo_lifecycle_complete_canonical confirms execution with a per-action results array — replaces polling with explicit acknowledgement. canonical_plan_id is deterministic: sha256(event_id + "|v" + plan_version)[:24], so retries reuse the same id. Migration m52 extends lifecycle_events with six canonical_* columns plus an index; pre-v7.5 rows simply carry NULL. session_diary is the dedupe key on re-delivery: if Desktop crashes between executing the inject and sending the complete call, the next nexo_lifecycle_event for the same event_id checks for a diary written after canonical_dispatched_at; if one exists, Brain short-circuits to already_processed and refuses to re-dispatch. The seven explicit delivery_status values (accepted, processed, canonical_pending, canonical_done, already_processed, retryable_error, rejected) give the pipeline a diffable state machine. switch and window-close stay observational (no plan ever issued, even with a live session_id). nexo lifecycle record now returns exit code 0 for canonical_pending; older wrappers that treated it as an error are incompatible with v7.5. MCP tool count: 262 → 263.

Previously in 7.4.1: patch release correcting the over-promise in v7.4.0's release notes and locking in the exact role of nexo_lifecycle_event as a ledger + reconciliation authority — NOT the canonical executor of diary+stop, which lived in Desktop. That responsibility moved to Brain in v7.5.

Previously in 7.2.0: minor release consolidating three parallel workstreams into a single Guardian-active-by-default train. Block K roadmap closure (G1 enforcer active, G3 SSH remote-write detector, src/guardian_runtime_config.py resolver, _persist_guardian_hard_defaults during nexo update). F0.6 hardening wave (nexo rollback f06 CLI, src/scripts/prune_runtime_backups.py promoted to core, docs/f06-layout-contract.md, three new doctor boot-tier checks, scripts/nexo-migrate-nora.sh + scripts/f0-safe-apply-remote.sh idempotent migration). Adaptive weights flipped from "14-day calendar wait" to "14 days OR (≥200 samples AND ≥2 days)" with auto-promotion during nexo update. Small-fixes batch: R34 bool("unknown")==True fix, classify_scripts_dir dedup, B10 module-level path constants lazy-evaluated, schedule override audit log, scripts/pre-release-verify.sh + docs/release-discipline.md, pre-commit hook that blocks commits when tool-enforcement-map.json drifts from src/plugins/.

Previously in 7.1.10: follow-up over v7.1.8 that shipped two rescue batches of WIP stashed aside during the v7.1.8 release window. First rescue: src/autonomy_mandate.py expanded the mandate-detection vocabulary (hazlo todo / no pares / estás al mando / te dejo al mando / sigue sin parar / haz el plan completo), added three honest flags on MandateState (execute_until_blocker, suppress_mid_task_menus, revalidate_after_compaction) with session filtering, wired post/pre-compact hooks that read those flags, surfaced them through protocol/workflow handlers and session payload, and introduced the new src/checkpoint_policy.py module with tests. Second rescue: scripts/verify_release_readiness.py gained a smoke-artifact contract pass that validates release-contracts/smoke/v<version>.json before any tag push, the release-final audit skill references the new contract, src/hook_guardrails.py + src/hooks/post_tool_use.py refine the post-tool protocol reminder path with a new contract test, and a couple of core prompts (task-close evidence, r14 correction learning) got wording polish.

Previously in 7.1.8: batch release over v7.1.7 consolidating the Block K Guardian/Enforcer roadmap (auto-drain of stale protocol_debt rows, destructive-command pre-tool gate, guard_check-required gate, inline guard ack on nexo_task_open, Guardian Health in the morning briefing) with Block D hardcode cleanup (classifier-backed backfill_task_owner, migration v50 supersedes the duplicate NEXO-product learning pair, new semantic-hardcodes audit) and Block E product guards (LaunchAgent plist protection, agent-name fallbacks no longer leak the product identity, francisco_emails removed from the email-config dict export, runner-health-check.py + nexo_personal_automation.py promoted from personal to core).

Previously in 7.0.1: hotfix over v7.0.0 (db._core.DB_PATH was only caller still hardcoded to legacy ~/.nexo/data/nexo.db; every shared-DB command silently returned empty results post-migration). Previously in 7.0.0: BREAKING — Plan Consolidado fase F0.6: physical separation of the runtime tree into ~/.nexo/{core,personal,runtime}/. The flat layout (~/.nexo/scripts/, brain/, data/, operations/, ...) is gone. Operators on v6.x are auto-migrated on first nexo update; fresh installs land directly in the new tree. New paths.py helpers are transition-aware.

Previously in 6.5.0: Plan Consolidado fase F0.2: operators can now nexo scripts enable|disable|status <name> any personal automation. The cron wrapper honours the flag at every tick (exit 0 with summary='[disabled]' while the LaunchAgent stays loaded). The companion NEXO Desktop client (a closed-source product, distributed separately) wires the same toggle into its Automatizaciones panel. See CHANGELOG for the full diff.

About NEXO Desktop. NEXO Desktop is a separate closed-source companion app distributed at nexo-desktop.com — its source does not live in this repo. When release notes mention Desktop they describe a coordinated client release that consumes the Brain's CLI / MCP contract; the Brain itself is fully usable on its own (terminal, Codex, Claude Code, or any MCP client). If you want the product edition rather than the open-source Brain alone, contact [email protected] and ask about NEXO Desktop.

Previously in 6.4.0: Plan Consolidado fase F1 — multi-tenant email accounts (email_accounts table, nexo email setup interactive wizard, nexo email add --password-stdin --json for machine consumers, idempotent migrator from legacy ~/.nexo/nexo-email/config.json). On post-F0.6 installs that legacy-looking path is only a compatibility alias/shim into ~/.nexo/runtime/nexo-email/config.json; it should never be treated as a second source of truth.

Previously in 6.3.1: privacy hotfix over v6.3.0. The nightly auditor caught that src/presets/entities_universal.json in v6.3.0 shipped operator-specific vhost_mapping entries (private IPs, hostnames, tenant names). v6.3.1 pulls those out into src/presets/entities_local.sample.json (template) + .gitignore'd ~/.nexo/brain/presets/entities_local.json (operator copy), and the installer drops the sample at nexo init. No behaviour change on the Guardian side.

Previously in 6.3.0 — Plan Consolidado wave 2, coordinated with NEXO Desktop v0.18.0. Closes the remaining Guardian roadmap items that do not require an invasive structure migration: extended cognitive_sentiment shape (is_correction/valence/intent), extended entities schema, 21 labelled rule fixtures with R13 spike gates, Fase F telemetry loops + Deep Sleep phase, pinned local zero-shot classifier skeleton (mDeBERTa), hook respects NEXO_MIGRATING=1, origin column on personal_scripts, and the T4 LLM gate wrapping R15/R23e/R23f/R23h (byte-parity Py ↔ JS). Two pre-release auditors flagged a CRITICAL in the first JS wire (method-name + async mismatch) and a HIGH (classifier bool conflated "no" with "unparseable"); both corrected with regression tests before merge.

Previously in 6.1.1: small fix to nexo --help so the Latest: vX line reliably appears when NEXO Desktop invokes the CLI via subprocess — unblocks the Desktop Brain auto-update banner that previously couldn't parse the version delta. No behaviour change for interactive terminal users; the 6-hour registry cache still rate-limits network calls. Bundles all v6.1.0 Protocol Enforcer Fase 2 + multi-claude-sid hotfix content.

Previously in 6.0.2: adds the reserved caller prefix personal/* so scripts living in ~/.nexo/scripts/ can invoke the automation backend with their own caller id without editing src/resonance_map.py. New kwarg tier ("maximo" / "alto" / "medio" / "bajo") on run_automation_prompt, run_automation_interactive, nexo_helper.run_automation_text, nexo_helper.run_automation_json, and nexo-agent-run.py --tier. Precedence for personal/* callers: explicit tier= → explicit reasoning_effort= → calibration.preferences.default_resonance → DEFAULT_RESONANCE (alto). Registered callers keep their behaviour unchanged. New guide: docs/personal-scripts-guide.md.

Previously in 6.0.1: hotfix on top of the 6.0.0 release. protocol_settings.py now treats the process as interactive when either stdin+stdout are TTYs or NEXO_INTERACTIVE=1 is exported — closes the gap where NEXO Desktop 0.12.0 spawned claude through pipes and Brain fell back to lenient even with a human in the loop. The PostToolUse hook also gains an inbox autodetect stage: when the session has unread nexo_send messages and has gone 60s+ without a heartbeat, it emits a systemMessage asking the agent to run nexo_heartbeat and consume them. Rate-limited to one reminder per minute per SID (new hook_inbox_reminders table, migration m42). Added sessions.last_heartbeat_ts, stamped by every successful heartbeat. NEXO_INTERACTIVE is an internal Brain↔Electron contract — not user-facing, not a resurrection of the removed NEXO_PROTOCOL_STRICTNESS.

Previously in 6.0.0: BREAKING tier-only setup. Onboarding asks for one resonance tier (maximo/alto/medio/bajo) and that choice drives every backend via src/resonance_tiers.json; the per-backend model/effort prompts are gone and the legacy client_runtime_profiles.{claude_code,codex}.{model,reasoning_effort} are silently purged from schedule.json on upgrade. Protocol strictness is no longer configurable — interactive TTY sessions run strict, non-TTY (crons, pipes, tests) run lenient; NEXO_PROTOCOL_STRICTNESS env, preferences.protocol_strictness, and the default/normal/off/warn/soft aliases are all removed. preferences.show_pending_at_start moves to NEXO Desktop's electron-store. The seven core hooks are now unified behind src/hooks/manifest.json (plugin and npm modes read the same file), two new hooks ship (Notification for live-session activity and SubagentStop for auto-closing stale protocol_tasks), and auto_capture.py is wired to both UserPromptSubmit and PostToolUse with a persistent 1h dedup table plus an automatic nexo_learning_add on correction matches. ~/.nexo/hooks_status.json is published after every registerAllCoreHooks() so NEXO Desktop ≥0.12.0 can render Hooks activos X/Y. New nexo-brain --skip flag aliases --yes/--defaults. Full suite 1057 passed, 1 skipped.

Previously in 5.10.2: auto-bootstraps brain/profile.json from brain/calibration.json on nexo update when the profile file is missing, empty, or corrupt AND calibration carries at least one of meta.role, meta.technical_level, name, language. NEXO Desktop's Preferencias → Avanzado tab used to render an empty {} for that block when the onboarding flow had been interrupted; now it either shows the seeded profile or a friendly explanation of what each file is for, paired with Desktop v0.11.2 which adds header descriptions to both JSON blocks. Never overwrites a populated profile, never raises, idempotent. Also fixes a latent host-filesystem leak in test_user_facing_caller_with_no_user_default_uses_alto exposed by the v5.10.1 migration.

Previously in 5.10.1: silent, one-shot migration that recovers legacy reasoning_effort="max" (written by nexo preferences --reasoning-effort max before v5.9.0) into the new preferences.default_resonance map — any user who had configured max before v5.9.0 and never touched the new selector was silently falling back to DEFAULT_RESONANCE="alto" on interactive calls since the v5.10.0 update. _run_runtime_post_sync() runs _migrate_effort_to_resonance() exactly once: max→maximo, xhigh→alto, high→medio, medium→bajo. No-op when calibration or schedule already declares an explicit default_resonance; idempotent; conservative; never raises.

Previously in 5.10.0: fixes the deep-sleep extract bloat that made Session 1 take ~57 minutes on some installs (new bare_mode on run_automation_prompt wires claude --bare for JSON-only extractor callers — ~4.3× faster per child, sourced from ANTHROPIC_API_KEY env or ~/.claude/anthropic-api-key.txt). caller= is now mandatory on run_automation_prompt — no silent fallback; every automation subprocess traces back to a registered caller with a deliberate tier. Five personal scripts (personal/email-monitor, personal/github-monitor, personal/post-x, personal/followup-runner, personal/orchestrator-v2) joined the resonance map with tiers picked per caller based on what each one does. gbp/* marketing posts bumped from medio to alto (public-facing copy, quality first over speed). 65 legacy protocol debts bulk-resolved as part of the audit — the patterns that generated them are structurally closed by mandatory caller= + unified session log + bare_mode.

Previously in 5.9.1: adds default_resonance to brain/calibration.json via the Desktop-facing schema (nexo schema --json), so NEXO Desktop's Preferences dialog renders a select with Máximo / Alto (recomendado) / Medio / Bajo automatically — no Desktop release needed. resolve_tier_for_caller reads calibration first and falls back to the legacy schedule.json location. nexo preferences --resonance writes both. The UI control only affects interactive sessions (nexo chat, Desktop new conversation, interactive nexo update); crons and background processes stay pinned per caller in resonance_map.py.

Previously in 5.9.0: every Claude/Codex invocation now flows through a central resonance map and a unified session log. Four tiers (MAXIMO / ALTO / MEDIO / BAJO) each resolve to a concrete (model, reasoning_effort) pair per backend. User-facing callers (nexo chat, Desktop new conversation, interactive nexo update) honour the user's default_resonance preference; system-owned callers (deep-sleep, evolution, catchup, GBP posts, …) run at a fixed tier chosen per caller in src/resonance_map.py — the user's preference never downgrades a cron we decided needs MAXIMO. Unknown callers raise UnregisteredCallerError. Migration #41 adds caller, session_type, started_at, ended_at, pid, resonance_tier to automation_runs; interactive sessions record a row at spawn (with ended_at=NULL) and update it on close, so the Brain now has a single source of truth for every Claude/Codex call regardless of origin. New nexo preferences --resonance CLI. New MCP tools nexo_session_log_create / nexo_session_log_close let NEXO Desktop (which spawns claude directly from its TypeScript process) feed the same log.

Previously in 5.8.2: the Brain core no longer auto-classifies followups and reminders on behalf of agents. v5.8.0's classify_task() heuristic (NEXO-specific ID prefixes NF-PROTOCOL-* / NF-DS-* / NF-AUDIT-*, Spanish user-verbs debes / revisar / firmar, agent keywords monitor / auditoría diaria / checkpoint) was fine for NEXO's own DB but bled convention into every third-party agent plugged into the shared Brain. The core now persists internal=0 and owner=NULL when the caller omits them, and clients that want automatic classification (NEXO Desktop does, via its _legacyClassifyOwner helpers) compute it themselves and pass the result. Migration #40 keeps the columns + indexes; rows already backfilled by v5.8.0 keep their values. normalise_owner still explicitly rejects the string "nexo" so legacy hardcoding cannot sneak back in.

Previously in 5.8.1: closes a self-reinforcing launchctl kickstart -k loop in the watchdog that wedged deep-sleep Phase 2 between 2026-04-14 and 2026-04-17. The cron wrapper now INSERTs an in-flight row (ended_at=NULL) at start and traps SIGTERM/INT/HUP to close it with exit_code=143 instead of vanishing from cron_runs. The watchdog interprets in-flight rows as "currently running" and only re-executes after verifying the worker process is dead. extract.py classifies CLI failures into transient (overloaded_error, rate-limit, timeout, signal — retried next run) and deterministic (skipped after MAX_POISON_ATTEMPTS), and passes a slim shared-context (200 head lines + metadata) instead of the full 400+ KB dump. A new auto_update._heal_deep_sleep_runtime() repairs existing installs silently on the next nexo update: poisoned checkpoints, stale locks, dangling cron_runs rows, and bloated .watchdog-fails counters.

Previously in 5.8.0: first-class internal and owner columns on followups and reminders. Migration #40 adds both fields with an idempotent one-shot backfill, so the "who does this task belong to?" classification moves from client-side regex (Desktop) to persistent storage every MCP client shares. Taxonomy is intentionally generic — owner in {user, waiting, agent, shared} — so third-party agents plugging into the shared Brain can render whatever assistant label they carry without inheriting NEXO branding. nexo_reminder_create, nexo_reminder_update, nexo_followup_create, and nexo_followup_update gain optional internal and owner parameters that win over the default heuristic.

Previously in 5.7.0: nexo update now keeps Claude Code and Codex CLIs in lockstep with NEXO Brain itself. When the global @anthropic-ai/claude-code or @openai/codex packages are installed, the updater checks the npm registry and runs npm install -g <pkg>@latest in-line — so the terminal boot model stays aligned with the settings NEXO already wrote to ~/.claude/settings.json. Packages the operator never installed are skipped silently. Pass nexo update --no-clis to keep the terminal CLIs pinned.

Previously in 5.6.1: update-path hardening — 0-byte .db orphans from interrupted installs are now purged from ~/.nexo/ and ~/.nexo/data/ before the pre-update backup, and sync_claude_code_model() propagates the NEXO-recommended model into ~/.claude/settings.json whenever heal_runtime_profiles() migrates the claude_code default.

Previously in 5.5.5: data-loss guardrails + automatic self-heal. The updater now refuses to capture an already-wiped nexo.db into a pre-update-* snapshot (validated sqlite3.backup + pre-flight wipe guard + post-migration row-count gate), and an auto-heal restores data/nexo.db from the newest hourly backup on the next server boot when a wipe is detected. New nexo recover CLI + nexo_recover MCP tool.

Previously in 5.5.4: Deep Sleep no longer blocks on unparseable sessions — reduced retries, added a JSON escape hatch, and unified the automation subprocess timeout to 3h across all scripts via a single shared constant.

Previously in 5.5.3: CLAUDE.md CORE teaches the model to trust the Protocol Enforcer, so aligned backends stop rejecting heartbeat, diary, and checkpoint injections as suspected prompt injection.

Start here:

• 5-minute quickstart
• Workflow quickstart
• Runtime templates
• Recent memory fallbacks + live system catalog
• Supported client guides
• Docker setup
• Architecture visuals
• Memory classes
• Session portability
• Python SDK
• Reference verticals
• Measured compare scorecard
• Memory benchmark harness
• Public contribution guide

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.

Versions 2.6.14 through 2.7.0 established the practical shared-brain baseline: managed Claude/Codex bootstrap, Codex config sync, transcript-aware Deep Sleep, 60-day long-horizon analysis, weekly/monthly summary artifacts, retrieval auto-mode, and the first measured engineering loop.

Versions 3.0.0 and 3.0.1 close the next execution gap:

• protocol discipline is now a runtime contract, not just instructions:
  • nexo_task_open
  • nexo_task_close
  • persistent protocol_debt
  • enforceable Cortex gates
• durable execution is now first-class:
  • resumable workflow runs
  • checkpoints
  • replay
  • retries
  • durable goals
• conditioned learnings on critical files are now real guardrails across Claude hooks, Codex transcript audits, and headless automation prompts
• repair/correction work now routes through canonical learning capture instead of depending on the model to remember to document after the fact
• runtime truth is stricter:
  • no more healthy-looking warning storms
  • no more silent Deep Sleep schema drift
  • keep-alive jobs report alive/degraded/duplicated honestly
• public proof is stronger:
  • measured compare scorecard
  • external and internal ablations
  • cost_per_solved_task
  • SDK/API/quickstart surface

Versions 3.1.7 through 3.2.0 close the recent-memory gap:

• recent operational continuity is now first-class through hot context and recent events
• the runtime can build a reusable pre-action bundle instead of reconstructing the last few hours from diaries and durable recall only
• when even that misses, NEXO now exposes raw transcript fallback tools for Claude Code and Codex session stores
• NEXO can now inspect itself through a live system catalog derived from canonical sources instead of relying only on stale docs or operator memory

Version 5.3.11 hardens protocol and Cortex contracts: malformed outcome, task_type, and impact_level values now fail explicitly instead of being coerced into other valid states, so persisted task history, debt, hot context, and decision telemetry stay faithful to what the caller actually asked for. Version 5.3.10 tightened the packaged-runtime truth layer again: installs and updates now keep ~/.nexo/package.json aligned with the published npm package so runtime metadata and doctor evidence no longer drift to an old version, nexo doctor --tier deep treats a missing self-audit-summary.json as a pending bootstrap artifact when the runtime was just installed or updated instead of reporting a false degradation, weekly Evolution now asks for explicit dimension_scores / score_evidence so telemetry can persist instead of staying blank, and daily synthesis only ingests update-last-summary.json when it carries actionable runtime signals. Version 5.3.9 is the packaged core-artifact manifest heal for 5.3.8: packaged updates now rebuild runtime-core-artifacts.json from the canonical npm package src/ tree instead of scanning the live ~/.nexo/scripts directory, script classification prefers that canonical packaged source when available, and runtime doctor syncs personal scripts before LaunchAgent inventory so personal automations recover cleanly instead of being mistaken for unknown core drift. Version 5.3.8 was the immediate packaged-migration hotfix for 5.3.7: the installer/runtime migrator now discovers all top-level runtime Python modules from src/ dynamically instead of relying on a manual allowlist, so new product surfaces like nexo export / nexo import actually arrive in ~/.nexo after update instead of being present only in the published npm tarball. Version 5.3.7 closed the remaining packaged-runtime happy-path gap and finally exposed portable user-data migration commands: packaged nexo update now self-heals cron definitions and LaunchAgents after a successful npm bump, new nexo export / nexo import commands move operator data as a safe bundle instead of leaving that flow implicit, and runtime doctor now distinguishes tracked historical Codex drift from an actually broken runtime so cleaned installs stop staying red for stale transcript debt alone. Version 5.3.6 hardened the Claude Code bootstrap path and related runtime hygiene: managed client sync now writes the NEXO MCP server where current Claude Code actually reads it (~/.claude.json), script classification is stricter about core-vs-personal runtime artifacts, schedule status distinguishes genuinely running jobs from broken ones, and retroactive learnings stop opening keyword-only false positives outside their declared applies_to scope. Version 5.3.5 already keeps CLI version visibility honest right after nexo update: if the cached npm version lags behind the runtime you just installed, nexo / nexo chat now clamp Latest to the installed version and refresh the cache instead of showing a stale older release. Version 5.3.4 already cleaned up legacy core alias leakage and added the version-status banner. Version 5.3.3 closed the remaining packaged-runtime doctor mismatch: the built-in hourly backup helper is now inventoried as a core LaunchAgent, so clean installs no longer get a false unknown-LaunchAgent warning. Version 5.3.2 already h