NEXO Brain — Your AI Gets a Brain

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

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.

The Problem

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

The Solution: A Cognitive Architecture

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.

What Makes NEXO Brain Different

Without NEXO Brain	With NEXO Brain
Memory gone after each session	Persistent across sessions with natural decay and reinforcement
Repeats the same mistakes	Checks "have I made this mistake before?" before every action
Keyword search only	Finds memories by meaning, not just words
Starts cold every time	Resumes from the mental state of the last session
Same behavior regardless of context	Adapts tone and approach based on your mood
No relationship	Trust score that evolves — makes fewer redundant checks as alignment grows
Stores everything blindly	Prediction error gating rejects redundant information at write time
Vulnerable to memory poisoning	4-layer security pipeline scans every memory before storage
No proactive behavior	Context-triggered reminders fire when topics match, not just by date

How the Brain Works

Memory That Forgets (And That's a Feature)

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.

Semantic Search (Finding by Meaning)

NEXO Brain doesn't search by keywords. It searches by meaning using vector embeddings (fastembed, 384 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.

Metacognition (Thinking About Thinking)

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.

Cognitive Dissonance

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

Sibling Memories

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

Trust Score (0-100)

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.

Sentiment Detection

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.

Sleep Cycle

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

Time	Process	Human Analogy
03:00	Decay + memory consolidation + merge duplicates + dreaming	Deep sleep consolidation
04:00	Clean expired data, prune redundant memories	Synaptic pruning
07:00	Self-audit, health checks, metrics	Waking up + orientation
23:30	Process day's events, extract patterns	Pre-sleep reflection
Boot	Catch-up: run anything missed while computer was off	--

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

Cognitive Features (v0.3.1)

NEXO Brain v0.3.1 adds 21 cognitive tools on top of the 76 base tools, bringing the total to 97+ MCP tools. These features implement cognitive science concepts that go beyond basic memory:

Input Pipeline

Feature	What It Does
Prediction Error Gating	Only novel information is stored. Redundant content that matches existing memories is rejected at write time, keeping your memory clean without manual curation.
Security Pipeline	4-layer defense against memory poisoning: injection detection, encoding analysis, behavioral anomaly scoring, and credential scanning. Every memory passes through all four layers before storage.
Quarantine Queue	New facts enter quarantine status and must pass a promotion policy before becoming trusted knowledge. Prevents unverified information from influencing decisions.
Secret Redaction	Auto-detects and redacts API keys, tokens, passwords, and other sensitive data before storage. Secrets never reach the vector database.

Memory Management

Feature	What It Does
Pin / Snooze / Archive	Granular lifecycle states for memories. Pin = never decays (critical knowledge). Snooze = temporarily hidden (revisit later). Archive = cold storage (searchable but inactive).
Auto-Merge Duplicates	Batch cosine deduplication during the 03:00 sleep cycle. Respects sibling discrimination — similar memories about different contexts are kept separate.
Memory Dreaming	Discovers hidden connections between recent memories during the 03:00 sleep cycle. Surfaces non-obvious patterns like "these three bugs all relate to the same root cause."

Retrieval

Feature	What It Does
HyDE Query Expansion	Generates hypothetical answer embeddings for richer semantic search. Instead of searching for "deploy error", it imagines what a helpful memory about deploy errors would look like, then searches for that.
Spreading Activation	Graph-based co-activation network. Memories retrieved together reinforce each other's connections, building an associative web that improves over time.
Recall Explanations	Transparent score breakdown for every retrieval result. Shows exactly why a memory was returned: semantic similarity, recency, access frequency, and co-activation bonuses.

Proactive

Feature	What It Does
Prospective Memory	Context-triggered reminders that fire when conversation topics match, not just by date. "Remind me about X when we discuss Y" works naturally.
Hook Auto-capture	Extracts decisions, corrections, and factual statements from conversations automatically. You don't need to explicitly say "remember this" — the system detects what's worth storing.

Quick Start

Claude Code (Primary)

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

Component	What	Where
Cognitive engine	Python: fastembed, numpy, vector search	pip packages
MCP server	97+ tools for memory, cognition, learning, guard	~/.nexo/
Plugins	Guard, episodic memory, cognitive memory, entities, preferences	~/.nexo/plugins/
Hooks	Session capture, briefing, stop detection	~/.nexo/hooks/
LaunchAgents	Decay, sleep, audit, postmortem, catch-up	~/Library/LaunchAgents/
Auto-update	Checks for new versions at boot	Built into catch-up
Claude Code config	MCP server + hooks registered	~/.claude/settings.json

Requirements

• macOS (Linux support planned)
• Node.js 18+ (for the installer)
• Claude Opus (latest version) strongly recommended. NEXO Brain provides 97+ MCP tools across 17 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 97+ tools without hesitation.
• Python 3, Homebrew, and Claude Code are installed automatically if missing.

Architecture

97+ MCP Tools across 17 Categories

Category	Count	Tools	Purpose
Cognitive	8	retrieve, stats, inspect, metrics, dissonance, resolve, sentiment, trust	The brain — memory, RAG, trust, mood
Cognitive Input	5	prediction_gate, security_scan, quarantine, promote, redact	Input pipeline — gating, security, quarantine
Cognitive Advanced	8	hyde_search, spread_activate, explain_recall, dream, prospect, hook_capture, pin, archive	Advanced retrieval, proactive, lifecycle
Guard	3	check, stats, log_repetition	Metacognitive error prevention
Episodic	10	change_log/search/commit, decision_log/outcome/search, review_queue, diary_write/read, recall	What happened and why
Sessions	4	startup, heartbeat, stop, status	Session lifecycle + context shift detection
Coordination	7	track, untrack, files, send, ask, answer, check_answer	Multi-session file coordination + messaging
Reminders	5	list, create, update, complete, delete	User's tasks and deadlines
Followups	4	create, update, complete, delete	System's autonomous verification tasks
Learnings	5	add, search, update, delete, list	Error patterns and prevention rules
Credentials	5	create, get, update, delete, list	Secure local credential storage
Task History	3	log, list, frequency	Execution tracking and overdue alerts
Menu	1	menu	Operations center with box-drawing UI
Entities	5	search, create, update, delete, list	People, services, URLs
Preferences	4	get, set, list, delete	Observed user preferences
Agents	5	get, create, update, delete, list	Agent delegation registry
Backup	3	now, list, restore	SQLite data safety
Evolution	5	propose, approve, reject, status, history	Self-improvement proposals

Plugin System

NEXO Brain 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.
• Secret redaction. API keys and tokens are stripped before they ever reach memory storage.

The Psychology Behind NEXO Brain

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

Psychological Concept	How NEXO Brain Implements It
Atkinson-Shiffrin (1968)	Three memory stores: sensory register --> STM --> LTM
Ebbinghaus Forgetting Curve (1885)	Exponential decay: strength = strength * e^(-lambda * time)
Rehearsal Effect	Accessing a memory resets its strength to 1.0
Memory Consolidation	Nightly process promotes frequently-used STM to LTM
Prediction Error	Only surprising (novel) information gets stored — redundant input is gated
Spreading Activation (Collins & Loftus, 1975)	Retrieving a memory co-activates related memories through an associative graph
HyDE (Gao et al., 2022)	Hypothetical document embeddings improve semantic recall
Prospective Memory (Einstein & McDaniel, 1990)	Context-triggered intentions fire when cue conditions match
Metacognition	Guard system checks past errors before acting
Cognitive Dissonance (Festinger, 1957)	Detects and verbalizes conflicts between old and new knowledge
Theory of Mind	Models user behavior, preferences, and mood
Synaptic Pruning	Automated cleanup of weak, unused memories
Associative Memory	Semantic search finds related concepts, not just matching words
Memory Reconsolidation	Dreaming process discovers hidden connections during sleep

Integrations

Claude Code (Primary)

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

npx nexo-brain

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

OpenClaw

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

MCP Bridge (Zero Code)

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

ClawHub Skill

npx clawhub@latest install nexo-brain

Native Memory Plugin

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.

Any MCP Client

NEXO Brain works with any application that supports the MCP protocol. Configure it as an MCP server pointing to ~/.nexo/src/server.py.

Listed On

Directory	Type	Link
npm	Package	nexo-brain
Glama	MCP Directory	glama.ai
mcp.so	MCP Directory	mcp.so
mcpservers.org	MCP Directory	mcpservers.org
OpenClaw	Native Plugin	openclaw.com
dev.to	Technical Article	How I Applied Cognitive Psychology to AI Agents
nexo-brain.com	Official Website	nexo-brain.com

Inspired By

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

Project	Inspired Features
Vestige	HyDE query expansion, spreading activation, prediction error gating, memory dreaming, prospective memory
ShieldCortex	Security pipeline (4-layer memory poisoning defense)
Bicameral	Quarantine queue (trust promotion policy for new facts)
claude-mem	Hook auto-capture (extracting decisions and facts from conversations)
ClawMem	Co-activation reinforcement (memories retrieved together strengthen connections)

Contributing

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

License

MIT -- see LICENSE

---

Built by WAzion