nexo-brain 0.1.1 → 0.2.0

package/README.md

@@ -143,19 +143,26 @@ The installer handles everything:
   Generating operator instructions...
 
   ╔══════════════════════════════════════════════════════════╗
-  ║  Atlas is ready.                                       ║
-  ║  Open Claude Code and start a conversation.            ║
+  ║  Atlas is ready. Type 'atlas' to start.                ║
   ╚══════════════════════════════════════════════════════════╝
 ```
 
-Open Claude Code and start working. Atlas will introduce itself on the first message.
+### Starting a Session
+
+The installer creates a shell alias with your chosen name. Just type it:
+
+```bash
+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 | 50+ tools for memory, learning, guard | ~/.nexo/ |
+| MCP server | 76 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/ |
@@ -166,27 +173,31 @@ Open Claude Code and start working. Atlas will introduce itself on the first mes
 
 - **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
 
-### 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 |
+### 76 MCP Tools across 16 Categories
+
+| Category | Count | Tools | Purpose |
+|----------|-------|-------|---------|
+| Cognitive | 8 | retrieve, stats, inspect, metrics, dissonance, resolve, sentiment, trust | The brain — memory, RAG, trust, mood |
+| 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 | 3 | startup, heartbeat, 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
 
@@ -228,6 +239,67 @@ NEXO isn't just engineering — it's applied cognitive psychology:
 | Synaptic Pruning | Automated cleanup of weak, unused memories |
 | Associative Memory | Semantic search finds related concepts, not just matching words |
 
+## OpenClaw Integration
+
+NEXO Brain works as a cognitive memory backend for [OpenClaw](https://github.com/openclaw/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`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "nexo-brain": {
+        "command": "python3",
+        "args": ["~/.nexo/src/server.py"],
+        "env": {
+          "NEXO_HOME": "~/.nexo"
+        }
+      }
+    }
+  }
+}
+```
+
+Or via CLI:
+
+```bash
+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)
+
+```bash
+npx clawhub@latest install nexo-brain
+```
+
+### Path 3: Native Memory Plugin (Replaces Default Memory)
+
+```bash
+npm install @wazionapps/openclaw-memory-nexo-brain
+```
+
+Configure in `~/.openclaw/openclaw.json`:
+
+```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](CONTRIBUTING.md) for guidelines. Issues and PRs welcome.