nexo-brain 0.5.0 → 0.7.0

package/README.md

@@ -1,8 +1,12 @@
 # NEXO Brain — Your AI Gets a Brain
 
+[![npm v0.6.0](https://img.shields.io/npm/v/nexo-brain?label=npm&color=purple)](https://www.npmjs.com/package/nexo-brain)
+[![F1 0.588 on LoCoMo](https://img.shields.io/badge/LoCoMo_F1-0.588-brightgreen)](https://github.com/wazionapps/nexo/blob/main/benchmarks/locomo/results/)
+[![+55% vs GPT-4](https://img.shields.io/badge/vs_GPT--4-%2B55%25-blue)](https://github.com/snap-research/locomo/issues/33)
 [![GitHub stars](https://img.shields.io/github/stars/wazionapps/nexo?style=social)](https://github.com/wazionapps/nexo/stargazers)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink)](https://github.com/sponsors/wazionapps)
+
+> **v0.6.0** — Now ships with **full orchestration**: 5 automated hooks, mandatory post-mortem with self-critique, pre-compaction context preservation, reflection engine, and auto-migration. Plus: F1 **0.588** on [LoCoMo](https://github.com/snap-research/locomo) (ACL 2024) — outperforms GPT-4 by 55%. Runs on CPU. [Full results](benchmarks/locomo/results/)
 
 **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.**
 
@@ -72,7 +76,7 @@ NEXO Brain uses **Ebbinghaus forgetting curves** — memories naturally fade ove
 
 ### Semantic Search (Finding by Meaning)
 
-NEXO Brain doesn't search by keywords. It searches by **meaning** using vector embeddings (fastembed, 384 dimensions).
+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.
 
@@ -126,9 +130,9 @@ Like a human brain, NEXO Brain has automated processes that run while you're not
 
 If your Mac was asleep during any scheduled process, NEXO Brain catches up in order when it wakes.
 
-## Cognitive Features (v0.3.1)
+## Cognitive Features
 
-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:
+NEXO Brain provides 21 cognitive tools on top of the 76 base tools, totaling **97+ MCP tools**. These features implement cognitive science concepts that go beyond basic memory:
 
 ### Input Pipeline
 
@@ -144,6 +148,9 @@ NEXO Brain v0.3.1 adds 21 cognitive tools on top of the 76 base tools, bringing
 | 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). |
+| **Intelligent Chunking** | Adaptive chunking that respects sentence and paragraph boundaries. Produces semantically coherent chunks instead of arbitrary token splits, reducing retrieval noise. |
+| **Adaptive Decay** | Decay rate adapts per memory based on access patterns: frequently-accessed memories decay slower, rarely-accessed ones fade faster. Prevents permanent clutter while keeping active knowledge sharp. |
+| **Auto-Migration** | Formal schema migration system (schema_migrations table) tracks all database changes. Safe, reversible schema evolution for production systems — upgrades never lose data. |
 | **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." |
 
@@ -152,6 +159,10 @@ NEXO Brain v0.3.1 adds 21 cognitive tools on top of the 76 base tools, bringing
 | 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. |
+| **Hybrid Search (FTS5+BM25+RRF)** | Combines dense vector search with BM25 keyword search via Reciprocal Rank Fusion. Outperforms pure semantic search on precise terminology and code identifiers. |
+| **Cross-Encoder Reranking** | After initial vector retrieval, a cross-encoder model rescores candidates for precision. The top-k results are reordered by true semantic relevance before being returned to the agent. |
+| **Multi-Query Decomposition** | Complex questions are automatically split into sub-queries. Each component is retrieved independently, then fused for a higher-quality answer — improves recall on multi-faceted prompts. |
+| **Temporal Indexing** | Memories are indexed by time in addition to semantics. Time-sensitive queries ("what did we decide last Tuesday?") use temporal proximity scoring alongside semantic similarity. |
 | **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. |
 
@@ -161,6 +172,7 @@ NEXO Brain v0.3.1 adds 21 cognitive tools on top of the 76 base tools, bringing
 |---------|-------------|
 | **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. |
+| **Session Summaries** | Automatic end-of-session summarization that distills key decisions, errors, and follow-ups into a compact diary entry. The next session starts with full context — not a cold slate. |
 
 ## Benchmark: LoCoMo (ACL 2024)
 
@@ -168,21 +180,83 @@ NEXO Brain was evaluated on [LoCoMo](https://github.com/snap-research/locomo) (A
 
 | System | F1 | Adversarial | Hardware |
 |---|---|---|---|
+| **NEXO Brain v0.5.0** | **0.588** | **93.3%** | **CPU only** |
 | GPT-4 (128K full context) | 0.379 | — | GPU cloud |
 | Gemini Pro 1.0 | 0.313 | — | GPU cloud |
-| **NEXO Brain** | **0.297** | **89.2%** | **CPU only** |
 | LLaMA-3 70B | 0.295 | — | A100 GPU |
 | GPT-3.5 + Contriever RAG | 0.283 | — | GPU |
 
+**+55% vs GPT-4. Running entirely on CPU.**
+
 **Key findings:**
-- Matches 70B-parameter models running entirely on CPU with 384-dim embeddings
-- 89.2% adversarial rejection rate — reliably says "I don't know" when information isn't available
-- 25s ingestion for 10 full conversations (no GPU, no batching)
-- 58.9% temporal recall on "when did X happen?" questions
+- 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/`](benchmarks/locomo/results/).
 
+## Full Orchestration System (v0.6.0)
+
+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.
+
+### 5 Automated Hooks
+
+These fire automatically at key moments in every Claude Code session:
+
+| Hook | When | What It Does |
+|------|------|-------------|
+| **SessionStart** | Session opens | Generates a briefing from SQLite: overdue reminders, today's tasks, pending followups, active sessions |
+| **Stop** | Session ends | Mandatory post-mortem: self-critique (5 questions), session buffer entry, followup creation, proactive seeds for next session |
+| **PostToolUse** | After each tool call | Captures meaningful mutations to the Sensory Register |
+| **PreCompact** | Before context compression | Saves checkpoint, reminds operator to write diary — prevents losing the thread |
+| **Caffeinate** | Always (optional) | Keeps Mac awake for nocturnal cognitive processes |
+
+### The Session Lifecycle
+
+```
+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 context if conversation is compressed
+    ↓
+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
+```
+
+### Reflection Engine
+
+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
+
+### Auto-Migration
+
+Existing users upgrading from v0.5.0:
+```bash
+npx nexo-brain  # detects v0.5.0, migrates automatically
+```
+- Updates hooks, core files, plugins, scripts
+- **Never touches your data** (memories, learnings, preferences)
+- Saves updated CLAUDE.md as reference (doesn't overwrite customizations)
+
 ## Quick Start
 
 ### Claude Code (Primary)
@@ -233,10 +307,12 @@ That's it. No need to run `claude` manually. Atlas will greet you immediately
 | 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/ |
+| Hooks (5) | SessionStart briefing, Stop post-mortem, PostToolUse capture, PreCompact checkpoint, Caffeinate | ~/.nexo/hooks/ |
+| Reflection engine | Processes session buffer, extracts patterns, updates user model | ~/.nexo/scripts/ |
+| CLAUDE.md | Complete operator instructions (Codex, hooks, guard, trust, memory) | ~/.claude/CLAUDE.md |
 | 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 |
+| Claude Code config | MCP server + 5 hooks registered | ~/.claude/settings.json |
 
 ### Requirements
 

package/bin/nexo-brain.js

@@ -75,6 +75,120 @@ async function main() {
     process.exit(1);
   }
 
+  // Auto-migration: detect existing installation
+  const versionFile = path.join(NEXO_HOME, "version.json");
+  if (fs.existsSync(versionFile)) {
+    try {
+      const installed = JSON.parse(fs.readFileSync(versionFile, "utf8"));
+      const currentPkg = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8"));
+      const installedVersion = installed.version || "0.0.0";
+      const currentVersion = currentPkg.version;
+
+      if (installedVersion !== currentVersion) {
+        log(`Existing installation detected: v${installedVersion} → v${currentVersion}`);
+        log("Running auto-migration...");
+
+        // Update hooks
+        const hooksSrc = path.join(__dirname, "..", "src", "hooks");
+        const hooksDest = path.join(NEXO_HOME, "hooks");
+        fs.mkdirSync(hooksDest, { recursive: true });
+        ["session-start.sh", "capture-session.sh", "session-stop.sh", "pre-compact.sh", "caffeinate-guard.sh"].forEach((h) => {
+          const src = path.join(hooksSrc, h);
+          const dest = path.join(hooksDest, h);
+          if (fs.existsSync(src)) {
+            fs.copyFileSync(src, dest);
+            fs.chmodSync(dest, "755");
+          }
+        });
+        log("  Hooks updated.");
+
+        // Update core Python files
+        const srcDir = path.join(__dirname, "..", "src");
+        ["server.py", "db.py", "plugin_loader.py", "cognitive.py",
+         "tools_sessions.py", "tools_coordination.py", "tools_reminders.py",
+         "tools_reminders_crud.py", "tools_learnings.py", "tools_credentials.py",
+         "tools_task_history.py", "tools_menu.py"].forEach((f) => {
+          const src = path.join(srcDir, f);
+          if (fs.existsSync(src)) {
+            fs.copyFileSync(src, path.join(NEXO_HOME, f));
+          }
+        });
+        log("  Core files updated.");
+
+        // Update plugins
+        const pluginsSrc = path.join(srcDir, "plugins");
+        const pluginsDest = path.join(NEXO_HOME, "plugins");
+        fs.mkdirSync(pluginsDest, { recursive: true });
+        if (fs.existsSync(pluginsSrc)) {
+          fs.readdirSync(pluginsSrc).filter(f => f.endsWith(".py")).forEach((f) => {
+            fs.copyFileSync(path.join(pluginsSrc, f), path.join(pluginsDest, f));
+          });
+        }
+        log("  Plugins updated.");
+
+        // Update scripts
+        const scriptsSrc = path.join(srcDir, "scripts");
+        const scriptsDest = path.join(NEXO_HOME, "scripts");
+        fs.mkdirSync(scriptsDest, { recursive: true });
+        if (fs.existsSync(scriptsSrc)) {
+          fs.readdirSync(scriptsSrc).filter(f => f.endsWith(".py") || f.endsWith(".sh")).forEach((f) => {
+            fs.copyFileSync(path.join(scriptsSrc, f), path.join(scriptsDest, f));
+          });
+        }
+        log("  Scripts updated.");
+
+        // Add PreCompact hook to settings.json if missing
+        let settings = {};
+        if (fs.existsSync(CLAUDE_SETTINGS)) {
+          try { settings = JSON.parse(fs.readFileSync(CLAUDE_SETTINGS, "utf8")); } catch {}
+        }
+        if (settings.hooks && !settings.hooks.PreCompact) {
+          settings.hooks.PreCompact = [];
+        }
+        if (settings.hooks && settings.hooks.PreCompact) {
+          const hookPath = path.join(hooksDest, "pre-compact.sh");
+          if (!settings.hooks.PreCompact.some((h) => h.command && h.command.includes("pre-compact.sh"))) {
+            settings.hooks.PreCompact.push({
+              type: "command",
+              command: `bash ${hookPath}`,
+            });
+            fs.writeFileSync(CLAUDE_SETTINGS, JSON.stringify(settings, null, 2));
+            log("  PreCompact hook added to Claude Code settings.");
+          }
+        }
+
+        // Update version file
+        fs.writeFileSync(versionFile, JSON.stringify({
+          version: currentVersion,
+          installed_at: installed.installed_at,
+          updated_at: new Date().toISOString(),
+          migrated_from: installedVersion,
+        }, null, 2));
+
+        // Save updated CLAUDE.md template as reference (don't overwrite user's)
+        const templateSrc = path.join(__dirname, "..", "templates", "CLAUDE.md.template");
+        if (fs.existsSync(templateSrc)) {
+          const operatorName = installed.operator_name || "NEXO";
+          let claudeMd = fs.readFileSync(templateSrc, "utf8")
+            .replace(/\{\{NAME\}\}/g, operatorName)
+            .replace(/\{\{NEXO_HOME\}\}/g, NEXO_HOME);
+          fs.writeFileSync(path.join(NEXO_HOME, "CLAUDE.md.updated"), claudeMd);
+          log(`  Updated CLAUDE.md template saved to ~/.nexo/CLAUDE.md.updated`);
+          log(`  Review and merge changes into your ~/.claude/CLAUDE.md if desired.`);
+        }
+
+        console.log("");
+        log(`Migration complete: v${installedVersion} → v${currentVersion}`);
+        log("Your data (memories, learnings, preferences) is untouched.");
+        console.log("");
+        rl.close();
+        return;
+      }
+    } catch (e) {
+      // Version file corrupt — proceed with fresh install
+    }
+  }
+
   // Find or install Homebrew (needed for Python)
   let hasBrew = run("which brew");
   if (!hasBrew) {
@@ -249,6 +363,7 @@ async function main() {
     JSON.stringify({
       version: pkg.version,
       installed_at: new Date().toISOString(),
+      operator_name: operatorName,
       files_updated: 0,
     }, null, 2)
   );
@@ -421,7 +536,7 @@ Operator name: ${operatorName}
   const hooksSrcDir = path.join(__dirname, "..", "src", "hooks");
   const hooksDestDir = path.join(NEXO_HOME, "hooks");
   fs.mkdirSync(hooksDestDir, { recursive: true });
-  ["session-start.sh", "capture-session.sh", "session-stop.sh"].forEach((h) => {
+  ["session-start.sh", "capture-session.sh", "session-stop.sh", "pre-compact.sh"].forEach((h) => {
     const src = path.join(hooksSrcDir, h);
     const dest = path.join(hooksDestDir, h);
     if (fs.existsSync(src)) {
@@ -460,6 +575,16 @@ Operator name: ${operatorName}
     settings.hooks.Stop.push(stopHook);
   }
 
+  // PreCompact hook (saves context before conversation compression)
+  if (!settings.hooks.PreCompact) settings.hooks.PreCompact = [];
+  const preCompactHook = {
+    type: "command",
+    command: `bash ${path.join(hooksDestDir, "pre-compact.sh")}`,
+  };
+  if (!settings.hooks.PreCompact.some((h) => h.command && h.command.includes("pre-compact.sh"))) {
+    settings.hooks.PreCompact.push(preCompactHook);
+  }
+
   const settingsDir = path.dirname(CLAUDE_SETTINGS);
   fs.mkdirSync(settingsDir, { recursive: true });
   fs.writeFileSync(CLAUDE_SETTINGS, JSON.stringify(settings, null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO — Cognitive co-operator for Claude Code. Atkinson-Shiffrin memory, semantic RAG, trust scoring, and metacognitive error prevention.",
   "bin": {