nexo-brain 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WAzion Apps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,241 @@
+# 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
+
+| Without NEXO | With NEXO |
+|-------------|-----------|
+| 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 |
+
+## 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:
+
+| Time | Process | Human Analogy |
+|------|---------|---------------|
+| 03:00 | Decay + memory consolidation + merge duplicates | 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 catches up in order when it wakes.
+
+## Quick Start
+
+```bash
+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.                                       ║
+  ║  Open Claude Code and start a conversation.            ║
+  ╚══════════════════════════════════════════════════════════╝
+```
+
+Open Claude Code and start working. Atlas will introduce itself on the first message.
+
+### What Gets Installed
+
+| Component | What | Where |
+|-----------|------|-------|
+| Cognitive engine | Python: fastembed, numpy, vector search | pip packages |
+| MCP server | 50+ tools for memory, 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)
+- Python 3, Homebrew, and Claude Code are installed automatically if missing.
+
+## Architecture
+
+### 50+ MCP Tools
+
+| Category | Tools | Purpose |
+|----------|-------|---------|
+| Cognitive (8) | retrieve, stats, inspect, metrics, dissonance, resolve, sentiment, trust | The brain |
+| Guard (3) | check, stats, log_repetition | Error prevention |
+| Episodic (10) | changes, decisions, session diary, recall | What happened and why |
+| Sessions (3) | startup, heartbeat, status | Session lifecycle |
+| Reminders (4) | create, update, complete, delete | User's tasks |
+| Followups (4) | create, update, complete, delete | System's tasks |
+| Learnings (5) | add, search, update, delete, list | Error patterns |
+| Entities (5) | search, create, update, delete, list | People, services, URLs |
+| Preferences (4) | get, set, list, delete | Observed preferences |
+| Credentials (5) | create, get, update, delete, list | Secure storage |
+| Agents (5) | get, create, update, delete, list | Agent delegation |
+| Backup (3) | now, list, restore | Data safety |
+| Evolution (5) | propose, approve, reject, status, history | Self-improvement |
+
+### Plugin System
+
+NEXO supports hot-loadable plugins. Drop a `.py` file in `~/.nexo/plugins/`:
+
+```python
+# 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:
+
+| Psychological Concept | How NEXO Implements It |
+|----------------------|----------------------|
+| Atkinson-Shiffrin (1968) | Three memory stores: sensory register → STM → LTM |
+| Ebbinghaus Forgetting Curve (1885) | Exponential decay: `strength = strength × e^(-λ × time)` |
+| Rehearsal Effect | Accessing a memory resets its strength to 1.0 |
+| Memory Consolidation | Nightly process promotes frequently-used STM to LTM |
+| Metacognition | Guard system checks past errors before acting |
+| Cognitive Dissonance | 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 |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Issues and PRs welcome.
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+---
+
+Built by [WAzion](https://wazion.com) | Created by Francisco Garcia