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 on YouTube · Watch the full deep-dive

Start here:

• 5-minute quickstart
• Workflow quickstart
• 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 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

AI coding agents are powerful but amnesic:

• No memory — closes a session, forgets everything
• Repeats mistakes — makes the same error you corrected yesterday
• No context — can't connect today's work with last week's decisions
• Reactive — waits for instructions instead of anticipating needs
• No learning — doesn't improve from experience
• No safety — stores anything it's told, including poisoned or redundant data

NEXO Brain implements the Atkinson-Shiffrin memory model from cognitive psychology (1968) — the same model that explains how human memory works:

What you say and do
    |
    +---> Sensory Register (raw capture, 48h)
    |       |
    |       +---> Attention filter: "Is this worth remembering?"
    |               |
    |               v
    +---> Short-Term Memory (7-day half-life)
    |       |
    |       +---> Used often? --> Consolidate to Long-Term Memory
    |       +---> Not accessed? --> Gradually forgotten
    |
    +---> Long-Term Memory (60-day half-life)
            |
            +---> Active: instantly searchable by meaning
            +---> Dormant: faded but recoverable ("oh right, I remember now!")
            +---> Near-duplicates auto-merged to prevent clutter

This isn't a metaphor. NEXO Brain literally implements Ebbinghaus forgetting curves, rehearsal-based reinforcement, and memory consolidation during automated "sleep" processes.

NEXO Brain uses Ebbinghaus forgetting curves — memories naturally fade over time unless reinforced by use. This isn't a bug, it's how useful memory works:

• A lesson learned yesterday is strong. If you never encounter it again, it fades — because it probably wasn't important.
• A lesson accessed 5 times in 2 weeks gets promoted to long-term memory — because repeated use proves it matters.
• A dormant memory can be reactivated if something similar comes up — the "oh wait, I remember this" moment.

On top of that baseline, NEXO now keeps a lightweight per-memory profile:

• stability slows decay for memories that keep surviving retrieval and reinforcement
• difficulty speeds decay slightly for memories that tend to be weak, noisy, or harder to reuse correctly

That keeps the core Ebbinghaus model, but makes decay more individual and less purely global.

NEXO Brain doesn't search by keywords. It searches by meaning using vector embeddings (fastembed, 768 dimensions).

Example: If you search for "deploy problems", NEXO Brain will find a memory about "SSH connection timeout on production server" — even though they share zero words. This is how human associative memory works.

Retrieval is now also smarter by default:

• HyDE auto mode expands conceptual or ambiguous queries when that improves recall
• Spreading activation auto mode adds a shallow associative boost for concept-heavy searches
• Exact lookup heuristics keep both off for literal file paths, IDs, stack traces, and other precision-sensitive queries

Before every code change, NEXO Brain asks itself: "Have I made a mistake like this before?"

It searches its memory for related errors, warnings, and lessons learned. If it finds something relevant, it surfaces the warning BEFORE acting — not after you've already broken production.

When you give an instruction that contradicts established knowledge, NEXO Brain doesn't silently obey or silently resist. It verbalizes the conflict:

"My memory says you prefer Tailwind over plain CSS, but you're asking me to write inline styles. Is this a permanent change or a one-time exception?"

You decide: paradigm shift (permanent change), exception (one-time), or override (old memory was wrong).

Some memories look identical but apply to different contexts. "How to deploy" for Project A is different from Project B. NEXO Brain detects discriminating entities (different OS, platform, language) and links them as siblings instead of merging them:

"Applying the Linux deploy procedure. Note: there's a sibling for macOS that uses a different port."

NEXO Brain tracks alignment with you through a trust score:

• You say thanks --> score goes up --> reduces redundant verification checks
• Makes a mistake you already taught it --> score drops --> becomes more careful, checks more thoroughly
• The score doesn't control permissions — you're always in control. It's a mirror that helps calibrate rigor.

NEXO Brain reads your tone (keywords, message length, urgency signals) and adapts:

• Frustrated? --> Ultra-concise mode. Zero explanations. Just solve the problem.
• In flow? --> Good moment to suggest that backlog item from last Tuesday.
• Urgent? --> Immediate action, no preamble.

Like a human brain, NEXO Brain has automated processes that run while you're not using it:

If your Mac was asleep during any scheduled process, NEXO Brain catches up in order when it wakes.

Deep Sleep now also mixes recent context with older context across a 60-day horizon. Instead of only looking at the immediate past, it can surface:

• 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.

The Cortex is a middleware cognitive layer that makes the agent think before acting. It implements architectural inhibitory control — the agent cannot bypass reasoning.

User message → Fast Path check → Simple chat? → Respond directly
                                → Action needed? → Cortex activates
                                                    ↓
                                              Generate cognitive state
                                              (goal, plan, unknowns, evidence)
                                                    ↓
                                              Middleware validates
                                              ├─ Unknowns? → ASK mode (tools blocked)
                                              ├─ No plan? → PROPOSE mode (read-only)
                                              └─ Plan + evidence → ACT mode (full access)

The Cortex was designed through a 3-way AI debate (Claude Opus 4.6 + GPT-5.4 + Gemini 3.1 Pro) and validated against 6 months of real production failures.

Memory and guardrails are not enough if long work still restarts from zero.

NEXO now ships a durable workflow runtime for multi-step and cross-session execution:

• nexo_workflow_open creates a persistent run with step metadata, idempotency key, priority, and shared state
• nexo_workflow_update records replayable checkpoints, retry metadata, approval gates, and the current actionable state
• nexo_workflow_resume tells the agent what to do next without guessing
• nexo_workflow_replay reconstructs the recent execution history honestly instead of pretending the run is still in memory
• nexo_workflow_list keeps active and blocked work visible so it does not disappear into reminders or prose notes

This is the bridge between "good memory" and "reliable execution": tasks can now preserve state, retries, approval gates, and next action across interruptions.

NEXO Brain automatically preserves session context when Claude Code compacts conversations. Using PreCompact and PostCompact hooks:

• PreCompact: Saves a complete session checkpoint to SQLite (task, files, decisions, errors, reasoning thread, next step)
• PostCompact: Re-injects a structured Core Memory Block into the conversation, so the session continues seamlessly

This means long sessions (8+ hours) feel like one continuous conversation instead of restarting after each compaction.

How it works:

1. Configure the hooks in your Claude Code settings.json
2. NEXO Brain's heartbeat automatically maintains the checkpoint
3. When compaction happens, the PreCompact hook reads the checkpoint and injects a recovery block
4. The session continues from exactly where it left off

Setup:

{
  "hooks": {
    "PreCompact": [{
      "matcher": "*",
      "hooks": [{"type": "command", "command": "bash $NEXO_HOME/hooks/pre-compact.sh", "timeout": 10}]
    }],
    "PostCompact": [{
      "matcher": "*",
      "hooks": [{"type": "command", "command": "bash $NEXO_HOME/hooks/post-compact.sh", "timeout": 10}]
    }]
  }
}

2 new MCP tools: nexo_checkpoint_save (manual or hook-triggered checkpoint), nexo_checkpoint_read (retrieves the latest checkpoint for context injection).

NEXO Brain provides 150+ MCP tools across 23 categories. These features implement cognitive science concepts that go beyond basic memory:

NEXO Brain was evaluated on LoCoMo (ACL 2024), a long-term conversation memory benchmark with 1,986 questions across 10 multi-session conversations.

+55% vs GPT-4. Running entirely on CPU.

Key findings:

• Outperforms GPT-4 (128K full context) by 55% on F1 score
• 93.3% adversarial rejection rate — reliably says "I don't know" when information isn't available
• 74.9% recall across 1,986 questions
• Open-domain F1: 0.637 | Multi-hop F1: 0.333 | Temporal F1: 0.326
• Runs on CPU with 768-dim embeddings (BAAI/bge-base-en-v1.5) — no GPU required
• First MCP memory server benchmarked on a peer-reviewed dataset

Full results in benchmarks/locomo/results/.

NEXO Brain doesn't just respond — it runs 13 core recovery-aware background jobs plus optional helpers, like a biological nervous system. They handle maintenance, health monitoring, and self-improvement without any user interaction:

Core processes are defined in src/crons/manifest.json and auto-synced to your system by nexo_update. On macOS they run via LaunchAgents; on Linux via systemd user timers. tcc-approve, prevent-sleep, and backup are platform/personal helpers — not in the manifest but listed above for completeness. Personal crons (your own scripts) are never touched by the sync. If your Mac was asleep during a scheduled process, the catch-up script re-runs everything in order when it wakes.

Deep Sleep is a 4-phase pipeline that runs at 4:30 AM and makes NEXO smarter while you sleep:

Phase 1: COLLECT (Python)
├── Reads all session transcripts from the day
├── Splits each session into individual .txt files
└── Gathers DB state (followups, learnings, trust)

Phase 2: EXTRACT (Opus, one call per session)
├── 8 types of findings per session:
│   ├── Uncaptured corrections (user corrected agent, no learning saved)
│   ├── Self-corrected errors (knowledge gaps to fix)
│   ├── Unformalised ideas (mentioned but never tracked)
│   ├── Missed commitments (promised but no followup)
│   ├── Protocol violations (guard_check, heartbeat, change_log)
│   ├── Emotional signals (frustration, flow, satisfaction)
│   ├── Abandoned projects (started but not finished)
│   └── Productivity patterns (corrections, proactivity, tool efficiency)
└── Outputs per-session JSON with findings + emotional timeline

Phase 3: SYNTHESIZE (Opus, one call)
├── Cross-session patterns (same error in 5 sessions = systemic)
├── Daily mood arc with score (0.0 = terrible day, 1.0 = great day)
├── Recurring triggers (what causes frustration vs flow)
├── Productivity analysis (corrections, tool efficiency)
├── Abandoned project detection
├── Morning agenda (prioritized)
└── Calibration recommendations

Phase 4: APPLY (Python)
├── Auto-creates learnings from high-confidence findings
├── Creates followups for unfinished work
├── Updates mood_history in calibration.json (30-day rolling)
├── Generates session-tone.json (emotional guidance for next session)
└── Writes morning-briefing.md

Deep Sleep generates a session-tone.json that tells NEXO how to behave next morning:

• Agent made many mistakes yesterday → Acknowledge them, show what was learned, demonstrate improvement
• User had a bad day (mood < 40%) → Supportive approach, lighter start, avoid known frustration triggers
• User had a great day (mood > 70%) → Reinforce momentum, reference wins, push ambitious goals
• Agent was too reactive → Be proactive today, don't wait for instructions

This is read by nexo_smart_startup and injected into every session's context. NEXO adapts its personality based on real behavioral data, not just configuration.

All core crons are defined in src/crons/manifest.json. When you run nexo_update, the sync script:

• Installs new crons from the manifest
• Updates changed schedules/intervals
• Removes crons no longer in the manifest (only core ones)
• Never touches personal crons you created yourself

Every cron execution is tracked in the cron_runs table via a universal wrapper. Use nexo_schedule_status to see what ran overnight:

✅ deep-sleep: 1/1 OK, 4523s avg — 37 sessions, 259 findings
✅ immune: 48/48 OK, 2s avg
❌ evolution: 0/1 OK — CLI timeout

Add personal crons from conversation with nexo_schedule_add — generates LaunchAgent (macOS) or systemd timer (Linux) automatically.

Deep Sleep automatically extracts reusable procedures from successful multi-step tasks and stores them as skills with full procedural content (steps, gotchas, markdown).

Pipeline: trace → draft → published → archived. Trust rises with successful use, decays without it. No human approval gates.

7 MCP tools: nexo_skill_create, nexo_skill_match, nexo_skill_get, nexo_skill_result, nexo_skill_list, nexo_skill_merge, nexo_skill_stats.

A web interface at localhost:6174 with 6 interactive pages for visual insight into your brain's state:

Built with FastAPI backend and D3.js frontend. Dashboard files are installed to NEXO_HOME/dashboard/ but must be started manually:

python3 ~/.nexo/dashboard/app.py

This opens localhost:6174 in your browser. Add --port 8080 to change the port or --no-browser to skip auto-opening.

Memory alone doesn't make a co-operator. What makes the difference is the behavioral loop — the automated discipline that ensures every session starts informed, runs with guardrails, and ends with self-reflection.

7 hooks fire automatically at key moments in every Claude Code session:

Session starts
    ↓
SessionStart hook generates briefing
    ↓
Operator reads diary, reminders, followups
    ↓
Heartbeat on every interaction (sentiment, context shifts)
    ↓
Guard check before every code edit
    ↓
PreCompact hook saves full checkpoint if conversation is compressed
    ↓
PostCompact hook re-injects Core Memory Block → session continues seamlessly
    ↓
Stop hook triggers mandatory post-mortem:
  - Self-critique: 5 questions about what could be better
  - Session buffer: structured entry for the reflection engine
  - Followups: anything promised gets scheduled
  - Proactive seeds: what can the next session do without being asked?
    ↓
Reflection engine processes buffer (after 3+ sessions)
    ↓
Nocturnal processes: decay, consolidation, self-audit, dreaming

After 3+ sessions accumulate, the stop hook triggers nexo-reflection.py:

• Extracts recurring tasks, error patterns, mood trends
• Updates user_model.json with observed behavior
• No LLM required — runs as pure Python

Existing users upgrading from any previous version:

npx nexo-brain  # detects current version, migrates automatically

• Updates hooks, core files, plugins, scripts, and LaunchAgent templates
• Runs database schema migrations automatically
• Never touches your data (memories, learnings, preferences)
• Saves updated CLAUDE.md as reference (doesn't overwrite customizations)

NEXO Brain includes a local CLI that runs independently of any single terminal client:

• nexo chat — launch a NEXO terminal client; if both Claude Code and Codex are available, it asks every time which one to open and puts the last-used client first
• nexo update — sync runtime from source, run migrations, reconcile schedules
• nexo doctor --tier runtime — boot/runtime/deep diagnostics with --fix mode
• nexo scripts list — list all personal scripts and their status
• nexo scripts reconcile — align declared schedules with actual LaunchAgents/systemd
• nexo -v — show installed runtime version

The CLI lives at NEXO_HOME/bin/nexo and is added to your PATH during install.

Scripts in NEXO_HOME/scripts/ are first-class managed entities:

• Tracked in SQLite with metadata, categories, and schedule associations
• Inline metadata in scripts declares name, runtime, schedule, and recovery policy
• nexo scripts create NAME scaffolds a new script with the correct template
• nexo scripts reconcile creates/repairs LaunchAgents from declared metadata
• nexo scripts sync discovers filesystem state and updates the registry
• nexo doctor --tier runtime detects orphaned schedules, missing plists, and drift

Personal scripts are completely separate from core NEXO processes. The crons/manifest.json defines core; everything in NEXO_HOME/scripts/ is personal.

Core and personal jobs now declare explicit recovery contracts in crons/manifest.json:

If the Mac was asleep during a scheduled window, catchup detects the gap from cron_runs (not a state file) and re-executes eligible jobs once. Interval-based personal scripts get a single recovery run, not repeated ticks.

For personal daemon-style helpers, recovery_policy=restart_daemon plus schedule_required=true declares an official KeepAlive schedule. NEXO can now reconcile and repair those daemons instead of treating them as unmanaged legacy LaunchAgents.

Before nexo chat or MCP server start, NEXO runs a preflight check:

1. Apply power policy (caffeinate on macOS, systemd-inhibit on Linux)
2. Run safe local migrations and backfills
3. Sync personal scripts registry
4. For dev-linked runtimes: check if source repo is behind, pull if safe, sync to runtime

This replaces the old "blind startup" where NEXO entered without verifying runtime health.

A bi-temporal entity-relationship graph with 988 nodes and 896 edges. Entities and relationships carry both valid-time (when the fact was true) and system-time (when it was recorded), enabling temporal queries like "what did we know about X last Tuesday?". BFS traversal discovers multi-hop connections between concepts. Event-sourced edges with smart dedup (ADD/UPDATE/NOOP) prevent redundant writes while preserving full history.

4 MCP tools: nexo_kg_query (SPARQL-like queries), nexo_kg_path (shortest path between entities), nexo_kg_neighbors (direct connections), nexo_kg_stats (graph metrics).

Full Linux support and Windows via WSL. The installer detects the platform and configures the appropriate process manager (LaunchAgents on macOS, catch-up on startup for Linux). PEP 668 compliance (venv on Ubuntu 24.04+). Session keepalive prevents phantom sessions during long tasks. Opportunistic maintenance runs cognitive processes when resources are available.

Windows users: NEXO Brain requires WSL (Windows Subsystem for Linux). Install WSL first, then run npx nexo-brain inside the Ubuntu/WSL terminal.

A new abstraction layer routes storage operations through a unified interface, making the system multi-tenant ready. Each operator's data is isolated while sharing the same cognitive engine.

Signal weights learn from real user feedback via Ridge regression. A 2-week shadow mode observes before activating. Weight momentum (85/15 blend) prevents personality whiplash. Automatic rollback if correction rate doubles.