NEXO — Your Claude Code Gets a Brain

NEXO transforms Claude Code from a stateless assistant into a cognitive partner that remembers, learns, forgets, adapts, and builds a relationship with you over time.

Every time you close a Claude Code session, everything is lost. Your assistant doesn't remember yesterday's decisions, repeats the same mistakes, and starts from zero. NEXO fixes this by giving Claude Code a brain — modeled after how human memory actually works.

The Problem

Claude Code is 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

The Solution: A Cognitive Architecture

NEXO 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?"
    │               │
    │               ↓
    ├─→ 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 literally implements Ebbinghaus forgetting curves, rehearsal-based reinforcement, and memory consolidation during automated "sleep" processes.

What Makes NEXO Different

How the Brain Works

Memory That Forgets (And That's a Feature)

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

Semantic Search (Finding by Meaning)

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

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

Metacognition (Thinking About Thinking)

Before every code change, NEXO 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.

Cognitive Dissonance

When you give an instruction that contradicts NEXO's established knowledge, it 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).

Sibling Memories

Some memories look identical but apply to different contexts. "How to deploy" for Project A is different from Project B. NEXO 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."

Trust Score (0-100)

NEXO tracks alignment with you through a trust score:

• You say thanks → score goes up → NEXO reduces redundant verification checks

• NEXO makes a mistake you already taught it → score drops → NEXO becomes more careful, checks more thoroughly

• The score doesn't control permissions — you're always in control. It's a mirror that helps NEXO calibrate its own rigor.

Sentiment Detection

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

Sleep Cycle

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

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

Quick Start

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 Claude Code MCP server...
  Setting up automated processes...
    5 automated processes configured.
  Caffeinate enabled.
  Generating operator instructions...

  ╔══════════════════════════════════════════════════════════╗
  ║  Atlas is ready. Type 'atlas' to start.                ║
  ╚══════════════════════════════════════════════════════════╝

Starting a Session

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

atlas

That's it. No need to run claude manually. Atlas 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.

What Gets Installed

Requirements

• macOS (Linux support planned)

• Node.js 18+ (for the installer)

• Claude Opus (latest version) strongly recommended. NEXO provides 76 MCP tools across 16 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 76 tools without hesitation.

• Python 3, Homebrew, and Claude Code are installed automatically if missing.

Architecture

76 MCP Tools across 16 Categories

Plugin System

NEXO supports hot-loadable plugins. Drop a .py file in ~/.nexo/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")

Data Privacy

• 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 opt-in. Checks GitHub releases, never sends data.

The Psychology Behind NEXO

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

OpenClaw Integration

NEXO Brain works as a cognitive memory backend for OpenClaw. Three integration paths, from instant to deep:

Path 1: MCP Bridge (Zero Code — Works Now)

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

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

Or via CLI:

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

All 76 NEXO tools become available to your OpenClaw agent immediately.

First time? Run npx nexo-brain first to install the cognitive engine and dependencies.

Path 2: ClawHub Skill (Install in Seconds)

npx clawhub@latest install nexo-brain

Path 3: Native Memory Plugin (Replaces Default Memory)

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

Configure in ~/.openclaw/openclaw.json:

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

This replaces OpenClaw's default memory system with NEXO's full cognitive architecture — Atkinson-Shiffrin memory, semantic RAG, trust scoring, guard system, and all 76 tools.

Contributing

See CONTRIBUTING.md for guidelines. Issues and PRs welcome.

License

MIT — see LICENSE

Built by WAzion | Created by Francisco Garcia