nexo-brain 0.3.6 → 0.6.0

package/README.md

@@ -1,5 +1,13 @@
 # NEXO Brain — Your AI Gets a Brain
 
+[![npm v0.5.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)
+
+> **v0.5.0** — Highest published score on [LoCoMo benchmark](https://github.com/snap-research/locomo) (ACL 2024). F1 **0.588** — outperforms GPT-4 (0.379) by 55%. Runs on CPU. No GPU required. [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.**
 
 [Watch the overview on YouTube](https://www.youtube.com/watch?v=-uvhicUhGTY)
@@ -68,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.
 
@@ -140,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." |
 
@@ -148,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. |
 
@@ -157,6 +172,31 @@ 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)
+
+NEXO Brain was evaluated on [LoCoMo](https://github.com/snap-research/locomo) (ACL 2024), a long-term conversation memory benchmark with 1,986 questions across 10 multi-session conversations.
+
+| 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 |
+| 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:**
+- 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/).
 
 ## Quick Start
 
@@ -386,9 +426,16 @@ NEXO Brain builds on ideas from several open-source projects. We're grateful for
 | [claude-mem](https://github.com/nicobailey/claude-mem) | Hook auto-capture (extracting decisions and facts from conversations) |
 | [ClawMem](https://github.com/nicobailey/ClawMem) | Co-activation reinforcement (memories retrieved together strengthen connections) |
 
-## Contributing
+## Support the Project
+
+If NEXO Brain is useful to you, consider:
+
+- **Star this repo** — it helps others discover the project and motivates continued development
+- **[Sponsor on GitHub](https://github.com/sponsors/wazionapps)** — support ongoing development directly
+- **Share your experience** — tell others how you're using cognitive memory in your AI workflows
+- **Contribute** — see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Issues and PRs welcome
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Issues and PRs welcome.
+[![Star History Chart](https://api.star-history.com/svg?repos=wazionapps/nexo&type=Date)](https://star-history.com/#wazionapps/nexo&Date)
 
 ## License
 
@@ -396,4 +443,4 @@ MIT -- see [LICENSE](LICENSE)
 
 ---
 
-Built by [WAzion](https://www.wazion.com)
+Created by **Francisco Cerdà Puigserver** & **NEXO** (Claude Opus) · Built by [WAzion](https://www.wazion.com)

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.3.6",
+  "version": "0.6.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": {
@@ -17,7 +17,7 @@
     "openclaw",
     "openclaw-plugin"
   ],
-  "author": "WAzion Apps <hello@wazion.com>",
+  "author": "NEXO Brain <info@nexo-brain.com>",
   "license": "MIT",
   "repository": {
     "type": "git",