The first AI memory system with architectural inhibitory control — the agent reasons about whether to act before acting. Cognitive Cortex, Context Continuity via auto-compaction hooks, Smart Startup, Context Packets, Auto-Prime, 30 Core Rules as DNA, auto-update, auto-diary, and CLAUDE.md version tracker. Battle-tested from 6 months of production use, validated via multi-AI debate.

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

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.

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.

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.

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.

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.

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 path/to/nexo/src/hooks/pre-compact.sh", "timeout": 10}]
    }],
    "PostCompact": [{
      "matcher": "*",
      "hooks": [{"type": "command", "command": "bash path/to/nexo/src/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 147+ MCP tools across 20+ 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 15 autonomous processes in the background, like a biological nervous system. They handle maintenance, health monitoring, and self-improvement without any user interaction:

All 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 (or crontab fallback). 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

Run python3 src/crons/sync.py --dry-run to preview changes without applying.

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. Runs as a LaunchAgent, auto-starts with the system.

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)

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.

Files and areas that cause repeated errors accumulate a risk score (0.0–1.0). The guard system warns on HIGH RISK (>0.5) and CRITICAL RISK (>0.8), lowering thresholds for more paranoid checking. Clean guard checks reduce risk multiplicatively (×0.7). Nightly decay (×0.95) ensures old pain fades.

6 weighted signals: vibe, corrections, brevity, topic, tool errors, git diff. Emergency keywords bypass hysteresis. Severity-weighted decay. Manual override via nexo_adaptive_override.

npx nexo-brain

The installer handles everything:

  How should I call myself? (default: NEXO) > Atlas

  Can I explore your workspace to learn about your projects? (y/n) > y

  Keep Mac awake so my cognitive processes run on schedule? (y/n) > y

  Installing cognitive engine dependencies...
  Setting up NEXO home...
  Scanning workspace...
    - 3 git repositories
    - Node.js project detected
  Configuring MCP server...
  Setting up nervous system...
    15 autonomous processes configured.
    Dashboard configured at localhost:6174.
  Caffeinate enabled.
  Generating operator instructions...

  +----------------------------------------------------------+
  |  Atlas is ready. Type 'atlas' to start.                  |
  +----------------------------------------------------------+

The installer creates a shell alias with your chosen name. Just type it:

atlas

Under the hood, the alias runs:

claude --append-system-prompt "You are NEXO. Run nexo_startup immediately, load context, greet the user." "."

--append-system-prompt adds to the default system prompt without replacing it (preserves CLAUDE.md). The "." triggers the operator to start immediately.

That's it. No need to run claude manually. Your operator will greet you immediately — adapted to the time of day, resuming from where you left off if there's a previous session. No cold starts, no waiting for your input.

• macOS or Linux (Windows via WSL)
• Node.js 18+ (for the installer)
• Claude Opus (latest version) strongly recommended. NEXO Brain provides 147+ MCP tools across 20+ categories. This cognitive load requires a top-tier model with large context window. Smaller models (Haiku, Sonnet) may struggle with tool selection and produce inconsistent results. Opus handles all 147+ tools without hesitation.
• Python 3, Homebrew, and Claude Code are installed automatically if missing.

NEXO Brain separates code (immutable, in the repo or npm package) from data (personal, in NEXO_HOME):

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.

NEXO Brain supports hot-loadable plugins with a dual-directory loader. Base plugins live in src/plugins/ (repo). Personal plugins go in NEXO_HOME/plugins/ and can override base plugins by filename. Drop a .py file in NEXO_HOME/plugins/:

# my_plugin.py
def handle_my_tool(query: str) -> str:
    """My custom tool description."""
    return f"Result for {query}"

TOOLS = [
    (handle_my_tool, "nexo_my_tool", "Short description"),
]

Reload without restarting: nexo_plugin_load("my_plugin.py")

• Everything stays local. All data in ~/.nexo/, never uploaded anywhere.
• No telemetry. No analytics. No phone-home.
• No cloud dependencies. Vector search runs on CPU (fastembed), not an API.
• Auto-update is resilient. NEXO checks for updates on startup. If an update fails, it continues with the current version and notifies you. Local migrations (database schema, configuration) always run. Network updates (git pull) can be disabled by setting auto_update: false in NEXO_HOME/config/schedule.json.
• Secret redaction. API keys and tokens are stripped before they ever reach memory storage.

NEXO Brain isn't just engineering — it's applied cognitive psychology:

NEXO Brain is designed as an MCP server. Claude Code is the primary supported client:

npx nexo-brain

All 147+ tools are available immediately after installation. The installer configures Claude Code's ~/.claude/settings.json automatically.

NEXO Brain also works as a cognitive memory backend for OpenClaw:

Add NEXO Brain to your OpenClaw config at ~/.openclaw/openclaw.json:

{
  "mcp": {
    "servers": {
      "nexo-brain": {
        "command": "python3",
        "args": ["~/.nexo/server.py"],
        "env": {
          "NEXO_HOME": "~/.nexo"
        }
      }
    }
  }
}

Or via CLI:

openclaw mcp set nexo-brain '{"command":"python3","args":["~/.nexo/server.py"],"env":{"NEXO_HOME":"~/.nexo"}}'
openclaw gateway restart

npx clawhub@latest install nexo-brain

npm install @wazionapps/openclaw-memory-nexo-brain

{
  "plugins": {
    "slots": {
      "memory": "memory-nexo-brain"
    }
  }
}

This replaces OpenClaw's default memory system with NEXO Brain's full cognitive architecture.

NEXO Brain works with any application that supports the MCP protocol. Configure it as an MCP server pointing to server.py in the code directory, with NEXO_HOME env var set.

NEXO Brain builds on ideas from several open-source projects. We're grateful for the research and implementations that inspired specific features:

If NEXO Brain is useful to you, consider:

• Star this repo — it helps others discover the project and motivates continued development
• Sponsor on GitHub — support ongoing development directly
• Share your experience — tell others how you're using cognitive memory in your AI workflows
• Contribute — see CONTRIBUTING.md for guidelines. Issues and PRs welcome

• Code/data separation: Code in repo (src/), personal data in NEXO_HOME (default ~/.nexo/). NEXO_HOME env var required.
• Plugin loader dual-directory: Scans src/plugins/ (base) then NEXO_HOME/plugins/ (personal override by filename).
• Auto-update on startup: Non-blocking (5s max), resilient, opt-out via schedule.json. Separate from manual nexo_update tool.
• Auto-diary: 3-layer system — PostToolUse every 10 calls, PreCompact emergency save, heartbeat DIARY_OVERDUE signal.
• CLAUDE.md version tracker: Section markers enable safe core updates without losing user customizations.
• schedule.json: Customizable process schedules with timezone support and auto_update flag.
• 15 autonomous processes: Added auto-close-sessions, synthesis, backup, tcc-approve, prevent-sleep (cross-platform).
• 7 hooks: SessionStart (timestamp + briefing), Stop, PostToolUse (capture + inbox), PreCompact, PostCompact.
• 147+ MCP tools: Added nexo_update tool for manual updates with rollback.
• Lambda fix: Decay values were 24x too aggressive (STM: 7h to 7d, LTM: 2.4d to 60d).
• Guard scoping: Was returning 35+ irrelevant blocking rules; now scoped to area and gated to high/critical.
• 12 rounds of external audit: ~60 findings resolved.

• Full i18n: All UI strings, error messages, DB status values in English. NLP detection patterns retain bilingual keywords (Spanish + English) for multilingual user support.
• Linux support: systemd user timers (preferred) or crontab fallback for all automated cognitive processes.
• Auto-resolve followups: Change log entries automatically cross-reference and complete matching open followups.
• Free-form learning categories: No more hardcoded category validation — use any category name.
• CLAUDE.md template rewrite: 494 to 127 lines, compact procedural format with full heartbeat signal reactions.
• Complete sanitization: All hardcoded paths use NEXO_HOME env var. Zero personal data in the repo.

• Nervous System: 11 autonomous scripts (decay, deep sleep, self-audit, catchup, evolution, followup hygiene, immune, watchdog, github monitor, learning validator)
• Dashboard v2: 6 interactive pages at localhost:6174 (Overview, Graph, Memory, Somatic, Adaptive, Sessions)
• LaunchAgent Templates: macOS automation templates included in the package for scheduling the nervous system
• Hooks: 7 total — SessionStart, Stop, PostToolUse, PreCompact, PostCompact
• Installer: Now configures dashboard LaunchAgent, nervous system scripts, and all templates automatically

• Deep Sleep: Reads full session transcripts (not just diary) — finds uncaptured corrections, protocol violations, missed commitments
• Uses Claude CLI in --bare mode (no hooks, no CLAUDE.md interference)
• Catch-up system re-runs yesterday if the Mac was off

• Architecture: db.py refactored into db/ package (11 modules); cognitive.py into cognitive/ package (6 modules)
• KG Boost: Knowledge Graph connection count influences search result ranking
• HNSW Vector Index: Optional approximate nearest neighbor acceleration (auto-activates above 10,000 memories)
• Claim Graph: Decomposes blob memories into atomic verifiable facts with provenance and contradiction detection
• Inter-terminal Auto-inbox (D+): nexo_startup accepts claude_session_id for automatic inbox delivery between parallel terminals
• Tests: 24 pytest tests across 3 suites (cognitive, knowledge graph, migrations)

• Fix: 3 bugs found by GPT-5.4 (Codex CLI) + Gemini 2.5 (Gemini CLI) reviewing full codebase
• Security: Memory sanitization prevents prompt injection via stored content
• Migration #13: Normalizes legacy status values on upgrade

• Major: All 9 nightly scripts migrated from Python word-overlap to CLI wrapper pattern
• Stop Hook v8: Session-scoped tool counting, buffer fallback removed
• Guard: Behavioral rules section surfaces most-violated rules at session start

• New: Self-improvement cycle — NEXO proposes and applies improvements weekly
• Dual-mode: auto (low-risk) and review (owner approval required)
• Circuit breaker, snapshot/rollback, immutable file protection

• License changed from MIT to AGPL-3.0

• Fix: v1.2.0 deleted the flag on approve, causing infinite block loops if session didn't close immediately
• Fix: Removed TTL on flag — it persists until SessionStart cleans it up next session
• New: Trivial sessions (<5 meaningful tool calls) skip post-mortem entirely and approve immediately
• SessionStart hook now cleans up .postmortem-complete flag on session start

• Fix: Stop hook now uses "decision": "block" instead of "approve" to enforce post-mortem execution
• Previous behavior: hook injected systemMessage but AI had already responded — instructions were never processed
• New behavior: session close is blocked until AI completes self-critique, session diary, buffer entry, and followups
• Flag-based mechanism (.postmortem-complete) allows second close attempt to succeed
• Works for all NEXO users, not just specific setups

• Fix: PostCompact now reads the correct session's checkpoint in multi-terminal setups
• Changelog section added to README

• Context Continuity: PreCompact/PostCompact hooks preserve session state across compaction events
• New session_checkpoints SQLite table + migration #12
• New tools: nexo_checkpoint_save, nexo_checkpoint_read
• Heartbeat automatically maintains checkpoint every interaction
• Core Memory Block re-injected post-compaction with task, files, decisions, reasoning thread
• 115+ total tools at the time, 20 categories

• Cognitive Cortex: architectural inhibitory control (ASK/PROPOSE/ACT modes)
• 30 Core Rules as immutable DNA in SQLite
• Designed via 3-way AI debate (Claude Opus + GPT-5.4 + Gemini 3.1 Pro)
• Artifact Registry for operational facts
• Full benchmark suite (LoCoMo F1: 0.588)

• Smart Startup: pre-loads memories from pending followups + diary
• Context Packet: structured injection for subagents
• Auto-Prime: keyword-triggered area learnings in heartbeat
• Diary Archive: permanent subconscious memory (180d+ auto-archived)

• Atkinson-Shiffrin memory model (STM → LTM promotion)
• Semantic RAG with fastembed (BAAI/bge-base-en-v1.5, 768 dims)
• Trust scoring, sentiment detection, adaptive personality modes
• Ebbinghaus decay, sister detection, quarantine system

AGPL-3.0 -- see LICENSE

Created by Francisco Cerdà Puigserver & NEXO (Claude Opus) · Built by WAzion