nexo-brain 0.5.0 → 0.6.0

package/README.md

@@ -1,8 +1,12 @@
 # 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)
-[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink)](https://github.com/sponsors/wazionapps)
+
+> **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.**
 
@@ -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.
 
@@ -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,17 +180,20 @@ 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/).

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

package/src/hooks/pre-compact.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# NEXO PreCompact hook — saves context before Claude Code compacts the conversation.
+# Compaction loses context silently. This hook ensures the operator writes a checkpoint
+# before that happens, and saves the last known state to a recovery file.
+set -euo pipefail
+
+NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
+NEXO_NAME="${NEXO_NAME:-NEXO}"
+CHECKPOINT_FILE="$NEXO_HOME/coordination/pre-compact-checkpoint.json"
+
+mkdir -p "$NEXO_HOME/coordination"
+
+# Save current state to checkpoint file
+python3 -c "
+import json, os, sys
+from datetime import datetime
+
+nexo_home = os.environ.get('NEXO_HOME', os.path.expanduser('~/.nexo'))
+db_path = os.path.join(nexo_home, 'nexo.db')
+
+checkpoint = {
+    'timestamp': datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%S'),
+    'active_sessions': [],
+    'last_context_hints': [],
+}
+
+try:
+    import sqlite3
+    if os.path.exists(db_path):
+        db = sqlite3.connect(db_path, timeout=5)
+        db.row_factory = sqlite3.Row
+        sessions = db.execute(
+            'SELECT sid, task, started FROM sessions WHERE completed=0'
+        ).fetchall()
+        checkpoint['active_sessions'] = [
+            {'sid': s['sid'], 'task': s['task'], 'started': s['started']}
+            for s in sessions
+        ]
+        # Get last diary drafts for context
+        try:
+            drafts = db.execute(
+                'SELECT sid, last_context_hint, tasks_seen FROM session_diary_draft '
+                'ORDER BY updated_at DESC LIMIT 3'
+            ).fetchall()
+            checkpoint['last_context_hints'] = [
+                {'sid': d['sid'], 'hint': d['last_context_hint'], 'tasks': d['tasks_seen']}
+                for d in drafts
+            ]
+        except Exception:
+            pass
+        db.close()
+except Exception:
+    pass
+
+with open('$CHECKPOINT_FILE', 'w') as f:
+    json.dump(checkpoint, f, indent=2)
+" 2>/dev/null || true
+
+# Emit hook response with systemMessage
+cat << HOOKEOF
+{
+  "decision": "approve",
+  "systemMessage": "PRE-COMPACT HOOK — Context is about to be compressed. BEFORE continuing:\n\n1. **Write a diary draft NOW** — call nexo_session_diary_write with what you've done so far, decisions made, and current mental state. This is your lifeline after compaction.\n2. **Note your current task** — after compaction you may lose the thread. Write it down in the diary.\n3. **Check pending followups** — if you promised to do something, make sure it's recorded before context is lost.\n4. **Read the checkpoint** after compaction: ${NEXO_HOME}/coordination/pre-compact-checkpoint.json\n\nDo NOT skip this. Compaction without a diary = starting from zero."
+}
+HOOKEOF

package/src/hooks/session-start.sh

@@ -1,27 +1,163 @@
 #!/bin/bash
-# NEXO SessionStart hook — runs when a new Claude Code session begins.
-# Generates a session briefing from the last self-audit and cognitive stats.
+# NEXO SessionStart hook — generates a comprehensive briefing.
+# Reads SQLite directly for reminders, followups, active sessions.
+# Caches output for 1 hour to avoid regenerating on rapid successive sessions.
+set -euo pipefail
 
 NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
 BRIEFING_FILE="$NEXO_HOME/coordination/session-briefing.txt"
+MAX_AGE_SECONDS=3600  # 1 hour cache
 
 mkdir -p "$NEXO_HOME/coordination"
 
-# Read last self-audit summary if available
-AUDIT_SUMMARY=""
-if [ -f "$NEXO_HOME/logs/self-audit-summary.json" ]; then
-    AUDIT_SUMMARY=$(cat "$NEXO_HOME/logs/self-audit-summary.json" 2>/dev/null)
+# If briefing exists and is less than 1 hour old, skip regeneration
+if [ -f "$BRIEFING_FILE" ]; then
+    if [ "$(uname)" = "Darwin" ]; then
+        file_age=$(( $(date +%s) - $(stat -f %m "$BRIEFING_FILE") ))
+    else
+        file_age=$(( $(date +%s) - $(stat -c %Y "$BRIEFING_FILE") ))
+    fi
+    if [ "$file_age" -lt "$MAX_AGE_SECONDS" ]; then
+        exit 0
+    fi
 fi
 
-# Read GitHub status if available
-GITHUB_STATUS=""
-if [ -f "$NEXO_HOME/github-status.json" ]; then
-    GITHUB_STATUS=$(cat "$NEXO_HOME/github-status.json" 2>/dev/null)
-fi
+TODAY=$(date +%Y-%m-%d)
+WEEKDAY=$(date +%A)
+
+# Generate briefing from SQLite
+python3 -c "
+import json, os, sys
+from datetime import date
+
+today_str = '$TODAY'
+weekday = '$WEEKDAY'
+nexo_home = os.environ.get('NEXO_HOME', os.path.expanduser('~/.nexo'))
+db_path = os.path.join(nexo_home, 'nexo.db')
+
+lines = []
+lines.append(f'## Date: {today_str} ({weekday})')
+lines.append('')
+
+# Read from SQLite
+reminders_rows = []
+followups_rows = []
+sessions = []
+sqlite_ok = True
+
+try:
+    import sqlite3
+    if not os.path.exists(db_path):
+        sqlite_ok = False
+    else:
+        db = sqlite3.connect(db_path, timeout=10)
+        db.execute('PRAGMA journal_mode=WAL')
+        db.execute('PRAGMA busy_timeout=10000')
+        db.row_factory = sqlite3.Row
+
+        try:
+            reminders_rows = [dict(r) for r in db.execute(
+                'SELECT id, date, description, status, category FROM reminders '
+                'WHERE status NOT LIKE \"%COMPLETADO%\" AND status NOT LIKE \"%ELIMINADO%\" '
+                'AND status NOT LIKE \"%COMPLETED%\" AND status NOT LIKE \"%DELETED%\"'
+            ).fetchall()]
+        except Exception:
+            pass
+
+        try:
+            followups_rows = [dict(r) for r in db.execute(
+                'SELECT id, date, description, status FROM followups '
+                'WHERE status NOT LIKE \"%COMPLETADO%\" AND status NOT LIKE \"%COMPLETED%\"'
+            ).fetchall()]
+        except Exception:
+            pass
+
+        try:
+            rows = db.execute(
+                'SELECT sid, task, started FROM sessions '
+                'WHERE completed=0 AND (strftime(\"%s\",\"now\") - last_update) < 900'
+            ).fetchall()
+            sessions = [{'sid': r['sid'], 'task': r['task'], 'started': r['started'][:16]} for r in rows]
+        except Exception:
+            pass
 
-# Write briefing
-cat > "$BRIEFING_FILE" << EOF
-Session started: $(date '+%Y-%m-%d %H:%M:%S')
-Self-audit: ${AUDIT_SUMMARY:-"no recent audit"}
-GitHub: ${GITHUB_STATUS:-"no status available"}
-EOF
+        db.close()
+except Exception:
+    sqlite_ok = False
+
+if not sqlite_ok:
+    lines.append('Database not initialized yet. Run nexo_startup to begin.')
+    lines.append('')
+    print('\n'.join(lines))
+    sys.exit(0)
+
+# Overdue reminders
+lines.append('## Overdue Reminders')
+found = False
+for r in reminders_rows:
+    rdate = r.get('date', '')
+    if rdate and rdate[:10] < today_str:
+        try:
+            delta = (date.fromisoformat(today_str) - date.fromisoformat(rdate[:10])).days
+        except:
+            delta = '?'
+        desc = (r.get('description', '') or '')[:120]
+        lines.append(f'- [{r[\"id\"]}] {rdate} {desc} — {delta} day(s) overdue')
+        found = True
+if not found:
+    lines.append('NONE')
+lines.append('')
+
+# Today's reminders
+lines.append('## Reminders Due Today')
+found = False
+for r in reminders_rows:
+    rdate = r.get('date', '')
+    if rdate and rdate[:10] == today_str:
+        desc = (r.get('description', '') or '')[:120]
+        lines.append(f'- [{r[\"id\"]}] {desc}')
+        found = True
+if not found:
+    lines.append('NONE')
+lines.append('')
+
+# Pending followups (due today or overdue)
+lines.append('## Followups Due Today or Overdue')
+found = False
+for r in followups_rows:
+    fdate = r.get('date', '')
+    if fdate and fdate[:10] <= today_str:
+        desc = (r.get('description', '') or '')[:100]
+        lines.append(f'- [{r[\"id\"]}] {fdate} {desc}')
+        found = True
+if not found:
+    lines.append('NONE')
+lines.append('')
+
+# Active sessions
+lines.append('## Active Sessions')
+if sessions:
+    for s in sessions:
+        lines.append(f'- [{s[\"sid\"]}] {s[\"task\"]} (since {s[\"started\"]})')
+else:
+    lines.append('NONE')
+lines.append('')
+
+# Last self-audit
+audit_file = os.path.join(nexo_home, 'logs', 'self-audit-summary.json')
+if os.path.exists(audit_file):
+    try:
+        audit = json.load(open(audit_file))
+        lines.append('## Last Self-Audit')
+        lines.append(json.dumps(audit, indent=2)[:500])
+        lines.append('')
+    except Exception:
+        pass
+
+print('\n'.join(lines))
+" > "$BRIEFING_FILE" 2>/dev/null
+
+# If generation failed, write minimal briefing
+if [ ! -s "$BRIEFING_FILE" ]; then
+    echo "## Briefing unavailable — generation error. Use nexo_reminders MCP for fresh data." > "$BRIEFING_FILE"
+fi

package/src/hooks/session-stop.sh

@@ -1,11 +1,127 @@
 #!/bin/bash
-# NEXO Stop hook — runs when Claude Code session ends.
-# Captures a summary event to session_buffer for the Sensory Register.
+# NEXO Stop hook — Full post-mortem and session closure.
+# Injects a systemMessage with mandatory self-critique instructions.
+# After emitting the hook response, writes a fallback buffer entry
+# and triggers intra-day reflection if enough sessions have accumulated.
+set -euo pipefail
 
 NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
+NEXO_NAME="${NEXO_NAME:-NEXO}"
+
+# 0. Refresh diary draft with latest changes/decisions (best-effort)
+python3 -c "
+import sys, json, os
+sys.path.insert(0, os.environ.get('NEXO_HOME', os.path.expanduser('~/.nexo')))
+os.environ['NEXO_SKIP_FS_INDEX'] = '1'
+try:
+    from db import init_db, get_db, get_active_sessions, upsert_diary_draft, get_diary_draft
+    init_db()
+    conn = get_db()
+    sessions = get_active_sessions()
+    for s in sessions:
+        sid = s['sid']
+        draft = get_diary_draft(sid)
+        if not draft:
+            continue
+        change_ids = [r[0] for r in conn.execute('SELECT id FROM change_log WHERE session_id = ?', (sid,)).fetchall()]
+        decision_ids = [r[0] for r in conn.execute('SELECT id FROM decisions WHERE session_id = ?', (sid,)).fetchall()]
+        upsert_diary_draft(
+            sid=sid,
+            tasks_seen=draft['tasks_seen'],
+            change_ids=json.dumps(change_ids),
+            decision_ids=json.dumps(decision_ids),
+            last_context_hint=draft['last_context_hint'],
+            heartbeat_count=draft['heartbeat_count'],
+            summary_draft=draft['summary_draft'],
+        )
+except Exception:
+    pass
+" 2>/dev/null || true
+
+# 1. Emit hook response (must be first output — Claude Code reads this)
+cat << HOOKEOF
+{
+  "decision": "approve",
+  "systemMessage": "STOP HOOK — MANDATORY POST-MORTEM before ending (do NOT ask permission, do NOT skip):\n\n## 1. SELF-CRITIQUE (MANDATORY — write to session diary)\nAnswer these questions in the self_critique field of nexo_session_diary_write:\n- Did the user have to ask me for something I should have detected or done on my own?\n- Did I wait for the user to tell me something I could have verified proactively?\n- Are there systems/states I can check next session without being asked?\n- Did I repeat an error that already had a registered learning?\n- What would I do differently if I repeated this session?\nIf any answer is YES — write the specific rule that would prevent repetition.\nIf the session was flawless, write 'No self-critique — clean session.'\n\n## 2. SESSION BUFFER\nIf the session was NOT trivial, append ONE JSON line to ${NEXO_HOME}/brain/session_buffer.jsonl:\n{\"ts\":\"YYYY-MM-DDTHH:MM:SS\",\"tasks\":[...],\"decisions\":[...],\"user_patterns\":[...],\"files_modified\":[...],\"errors_resolved\":[...],\"self_critique\":\"short summary of what I should have done better\",\"mood\":\"focused|impatient|exploratory|frustrated|satisfied|neutral\",\"source\":\"claude\"}\n\n## 3. FOLLOWUPS\nIf there were deploys/cron changes/fixes — nexo_followup_create with verification date.\n\n## 4. PROACTIVE SEEDS\nBefore closing, think: what can I leave prepared so the next session starts doing useful work without the user asking? Create followups with date=tomorrow for proactive verifications.\n\nEntities, preferences, learnings — only if they appeared during the session."
+}
+HOOKEOF
+
+# 2. Direct session buffer fallback (Claude's MCP write is better but not guaranteed)
 BUFFER="$NEXO_HOME/brain/session_buffer.jsonl"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%S")
+
+# Check if Claude already wrote to the buffer in the last 60 seconds
+SKIP_FALLBACK=false
+if [ -f "$BUFFER" ]; then
+    LAST_SOURCE=$(python3 -c "
+import json, sys
+from datetime import datetime, timedelta
+try:
+    lines = open('$BUFFER').readlines()
+    if lines:
+        d = json.loads(lines[-1])
+        ts = d.get('ts','')
+        src = d.get('source','')
+        entry_dt = datetime.strptime(ts, '%Y-%m-%dT%H:%M:%S')
+        if datetime.utcnow() - entry_dt < timedelta(seconds=60) and src == 'claude':
+            print('skip')
+        else:
+            print('write')
+    else:
+        print('write')
+except:
+    print('write')
+" 2>/dev/null || echo "write")
+    if [ "$LAST_SOURCE" = "skip" ]; then
+        SKIP_FALLBACK=true
+    fi
+fi
+
+if [ "$SKIP_FALLBACK" = false ]; then
+    mkdir -p "$(dirname "$BUFFER")"
+    echo "{\"ts\":\"$TIMESTAMP\",\"tasks\":[\"session ended\"],\"decisions\":[],\"user_patterns\":[],\"files_modified\":[],\"errors_resolved\":[],\"self_critique\":\"hook-fallback, no self-critique captured\",\"mood\":\"unknown\",\"source\":\"hook-fallback\"}" >> "$BUFFER" 2>/dev/null
+fi
+
+# 3. Intra-day reflection trigger
+# Check if buffer has >=3 sessions AND last reflection was >4h ago
+REFLECTION_SCRIPT="$NEXO_HOME/scripts/nexo-reflection.py"
+REFLECTION_STATE="$NEXO_HOME/coordination/reflection-log.json"
+TRIGGER_THRESHOLD=3
+
+if [ -f "$BUFFER" ] && [ -f "$REFLECTION_SCRIPT" ]; then
+    LINE_COUNT=$(wc -l < "$BUFFER" | tr -d ' ')
 
-mkdir -p "$NEXO_HOME/brain"
+    if [ "$LINE_COUNT" -ge "$TRIGGER_THRESHOLD" ]; then
+        SHOULD_REFLECT=true
+        if [ -f "$REFLECTION_STATE" ]; then
+            LAST_TS=$(python3 -c "
+import json
+from datetime import datetime, timedelta
+try:
+    log = json.load(open('$REFLECTION_STATE'))
+    if log:
+        last = log[-1]['timestamp']
+        last_dt = datetime.strptime(last, '%Y-%m-%d %H:%M')
+        if datetime.now() - last_dt < timedelta(hours=4):
+            print('too_recent')
+        else:
+            print('ok')
+    else:
+        print('ok')
+except:
+    print('ok')
+" 2>/dev/null)
+            if [ "$LAST_TS" = "too_recent" ]; then
+                SHOULD_REFLECT=false
+            fi
+        fi
 
-TS=$(date -u +"%Y-%m-%dT%H:%M:%S")
-echo "{\"ts\":\"$TS\",\"tasks\":[\"session ended\"],\"source\":\"hook-stop\"}" >> "$BUFFER"
+        if [ "$SHOULD_REFLECT" = true ]; then
+            # Find Python — prefer the one used by NEXO
+            PYTHON=$(which python3 2>/dev/null || echo "/usr/bin/python3")
+            nohup "$PYTHON" "$REFLECTION_SCRIPT" \
+                >> "$NEXO_HOME/logs/reflection-stdout.log" \
+                2>> "$NEXO_HOME/logs/reflection-stderr.log" &
+        fi
+    fi
+fi