nexo-brain 0.10.0-beta.8 → 1.1.0

package/README.md

@@ -1,12 +1,12 @@
 # NEXO Brain — Your AI Gets a Brain
 
-[![npm v0.10.0-beta.8](https://img.shields.io/npm/v/nexo-brain?label=npm&color=purple)](https://www.npmjs.com/package/nexo-brain)
+[![npm v1.1.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.10.0-beta.8** — 30 Core System Rules (versioned, with migration). Battle-tested behavioral rules from 6 months production use, validated via multi-AI debate (Claude + GPT-4o). 6 categories: Integrity, Execution, Memory, Delegation, Communication, Proactivity. 25 BLOCKING + 5 ADVISORY. Plus: Smart Startup, Context Packets, Auto-Prime, and zero-decay pinning.
+> **v1.1.0** — Context Continuity via auto-compaction hooks. PreCompact saves a full session checkpoint; PostCompact re-injects it so long sessions (8+ hours) feel like one continuous conversation. Plus: Cognitive Cortex, 30 Core Rules as DNA, Smart Startup, Context Packets, Auto-Prime. The first AI memory system with architectural inhibitory control — the agent reasons about whether to act before acting. Battle-tested from 6 months of production use, validated via multi-AI debate (Claude Opus + GPT-5.4 + Gemini 3.1 Pro).
 
 **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.**
 
@@ -136,9 +136,69 @@ 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 Cortex (v1.0.0)
+
+The Cortex is a middleware cognitive layer that makes the agent **think before acting**. It implements architectural inhibitory control — the agent cannot bypass reasoning.
+
+```
+User message → Fast Path check → Simple chat? → Respond directly
+                                → Action needed? → Cortex activates
+                                                    ↓
+                                              Generate cognitive state
+                                              (goal, plan, unknowns, evidence)
+                                                    ↓
+                                              Middleware validates
+                                              ├─ Unknowns? → ASK mode (tools blocked)
+                                              ├─ No plan? → PROPOSE mode (read-only)
+                                              └─ Plan + evidence → ACT mode (full access)
+```
+
+| Feature | What It Does |
+|---------|-------------|
+| **Inhibitory Control** | Physically restricts tools based on reasoning quality. Unknowns → can only ask. No plan → can only propose. Evidence + verification → can act. |
+| **Event-Driven Activation** | Only activates on tool intent, ambiguity, destructive actions, or retries. Simple chat has zero overhead. |
+| **Trust-Gated Escalation** | Low trust score → requires more evidence before allowing "act" mode. Trust builds through successful execution. |
+| **Core Rules Injection** | Automatically surfaces relevant behavioral rules based on task type. |
+| **Activation Metrics** | Tracks modes, inhibition rates, and task types for continuous improvement. |
+
+The Cortex was designed through a 3-way AI debate (Claude Opus 4.6 + GPT-5.4 + Gemini 3.1 Pro) and validated against 6 months of real production failures.
+
+## Context Continuity (Auto-Compaction) (v1.1.0)
+
+NEXO Brain automatically preserves session context when Claude Code compacts conversations. Using PreCompact and PostCompact hooks:
+
+- **PreCompact**: Saves a complete session checkpoint to SQLite (task, files, decisions, errors, reasoning thread, next step)
+- **PostCompact**: Re-injects a structured Core Memory Block into the conversation, so the session continues seamlessly
+
+This means long sessions (8+ hours) feel like one continuous conversation instead of restarting after each compaction.
+
+**How it works:**
+1. Configure the hooks in your Claude Code `settings.json`
+2. NEXO Brain's heartbeat automatically maintains the checkpoint
+3. When compaction happens, the PreCompact hook reads the checkpoint and injects a recovery block
+4. The session continues from exactly where it left off
+
+**Setup:**
+```json
+{
+  "hooks": {
+    "PreCompact": [{
+      "matcher": "*",
+      "hooks": [{"type": "command", "command": "bash path/to/nexo/src/hooks/pre-compact.sh", "timeout": 10}]
+    }],
+    "PostCompact": [{
+      "matcher": "*",
+      "hooks": [{"type": "command", "command": "bash path/to/nexo/src/hooks/post-compact.sh", "timeout": 10}]
+    }]
+  }
+}
+```
+
+2 new MCP tools: `nexo_checkpoint_save` (manual or hook-triggered checkpoint), `nexo_checkpoint_read` (retrieves the latest checkpoint for context injection).
+
 ## Cognitive Features
 
-NEXO Brain provides 27 cognitive tools on top of the 76 base tools, totaling **111+ MCP tools**. These features implement cognitive science concepts that go beyond basic memory:
+NEXO Brain provides 29 cognitive tools on top of the 78 base tools, totaling **115+ MCP tools**. These features implement cognitive science concepts that go beyond basic memory:
 
 ### Input Pipeline
 
@@ -211,7 +271,7 @@ Full results in [`benchmarks/locomo/results/`](benchmarks/locomo/results/).
 
 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
+### 6 Automated Hooks
 
 These fire automatically at key moments in every Claude Code session:
 
@@ -220,7 +280,8 @@ These fire automatically at key moments in every Claude Code session:
 | **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 |
+| **PreCompact** | Before context compression | Saves full session checkpoint to SQLite — task, files, decisions, errors, reasoning thread |
+| **PostCompact** | After context compression | Re-injects Core Memory Block so the session continues seamlessly from where it left off |
 | **Caffeinate** | Always (optional) | Keeps Mac awake for nocturnal cognitive processes |
 
 ### The Session Lifecycle
@@ -236,7 +297,9 @@ Heartbeat on every interaction (sentiment, context shifts)
     ↓
 Guard check before every code edit
     ↓
-PreCompact hook saves context if conversation is compressed
+PreCompact hook saves full checkpoint if conversation is compressed
+    ↓
+PostCompact hook re-injects Core Memory Block → session continues seamlessly
     ↓
 Stop hook triggers mandatory post-mortem:
   - Self-critique: 5 questions about what could be better
@@ -319,7 +382,7 @@ The installer handles everything:
     - Node.js project detected
   Configuring MCP server...
   Setting up automated processes...
-    5 automated processes configured.
+    6 automated processes configured.
   Caffeinate enabled.
   Generating operator instructions...
 
@@ -343,25 +406,25 @@ That's it. No need to run `claude` manually. Atlas will greet you immediately
 | Component | What | Where |
 |-----------|------|-------|
 | Cognitive engine | Python: fastembed, numpy, vector search | pip packages |
-| MCP server | 109+ tools for memory, cognition, learning, guard | ~/.nexo/ |
+| MCP server | 111+ tools for memory, cognition, learning, guard | ~/.nexo/ |
 | Plugins | Guard, episodic memory, cognitive memory, entities, preferences | ~/.nexo/plugins/ |
-| Hooks (5) | SessionStart briefing, Stop post-mortem, PostToolUse capture, PreCompact checkpoint, Caffeinate | ~/.nexo/hooks/ |
+| Hooks (6) | SessionStart briefing, Stop post-mortem, PostToolUse capture, PreCompact checkpoint, PostCompact recovery, 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 + 5 hooks registered | ~/.claude/settings.json |
+| Claude Code config | MCP server + 6 hooks registered | ~/.claude/settings.json |
 
 ### Requirements
 
 - **macOS or Linux** (Windows via [WSL](https://learn.microsoft.com/en-us/windows/wsl/install))
 - **Node.js 18+** (for the installer)
-- **Claude Opus (latest version) strongly recommended.** NEXO Brain provides 109+ MCP tools across 19 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 109+ tools without hesitation.
+- **Claude Opus (latest version) strongly recommended.** NEXO Brain provides 111+ MCP tools across 20 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 111+ tools without hesitation.
 - Python 3, Homebrew, and Claude Code are installed automatically if missing.
 
 ## Architecture
 
-### 109+ MCP Tools across 19 Categories
+### 111+ MCP Tools across 20 Categories
 
 | Category | Count | Tools | Purpose |
 |----------|-------|-------|---------|
@@ -385,6 +448,7 @@ That's it. No need to run `claude` manually. Atlas will greet you immediately
 | Evolution | 5 | propose, approve, reject, status, history | Self-improvement proposals |
 | Adaptive & Somatic | 4 | adaptive_weights, adaptive_override, somatic_check, somatic_stats | Learned signal weights + pain memory per file |
 | Knowledge Graph | 4 | kg_query, kg_path, kg_neighbors, kg_stats | Bi-temporal entity-relationship graph |
+| Context Continuity | 2 | checkpoint_save, checkpoint_read | Auto-compaction session preservation |
 
 ### Plugin System
 
@@ -442,7 +506,7 @@ NEXO Brain is designed as an MCP server. Claude Code is the primary supported cl
 npx nexo-brain
 ```
 
-All 109+ tools are available immediately after installation. The installer configures Claude Code's `~/.claude/settings.json` automatically.
+All 111+ tools are available immediately after installation. The installer configures Claude Code's `~/.claude/settings.json` automatically.
 
 ### OpenClaw
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "nexo-brain",
-  "version": "0.10.0-beta.8",
+  "version": "1.1.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.",
+  "description": "NEXO \u2014 Cognitive co-operator for Claude Code. Atkinson-Shiffrin memory, semantic RAG, trust scoring, and metacognitive error prevention.",
   "bin": {
     "nexo-brain": "./bin/nexo-brain.js"
   },
@@ -32,4 +32,4 @@
     "templates/",
     "scripts/"
   ]
-}
+}

package/src/db.py

@@ -1003,6 +1003,30 @@ def _seed_core_rules(conn):
     conn.commit()
 
 
+def _m12_session_checkpoints(conn):
+    """Session checkpoints for intelligent auto-compaction.
+
+    PreCompact saves a checkpoint; PostCompact reads it to re-inject a
+    Core Memory Block that preserves continuity after context compression.
+    """
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS session_checkpoints (
+            sid TEXT PRIMARY KEY,
+            task TEXT DEFAULT '',
+            task_status TEXT DEFAULT 'active',
+            active_files TEXT DEFAULT '[]',
+            current_goal TEXT DEFAULT '',
+            decisions_summary TEXT DEFAULT '',
+            errors_found TEXT DEFAULT '',
+            reasoning_thread TEXT DEFAULT '',
+            next_step TEXT DEFAULT '',
+            compaction_count INTEGER DEFAULT 0,
+            created_at TEXT DEFAULT (datetime('now')),
+            updated_at TEXT DEFAULT (datetime('now'))
+        )
+    """)
+
+
 # Migration registry — APPEND ONLY, never reorder or delete
 MIGRATIONS = [
     (1, "learnings_columns", _m1_learnings_columns),
@@ -1016,6 +1040,7 @@ MIGRATIONS = [
     (9, "maintenance_schedule", _m9_maintenance_schedule),
     (10, "diary_archive", _m10_diary_archive),
     (11, "core_rules", _m11_core_rules),
+    (12, "session_checkpoints", _m12_session_checkpoints),
 ]
 
 
@@ -2814,3 +2839,71 @@ def update_evolution_log_status(log_id: int, status: str, **kwargs):
             vals.append(kwargs[k])
     vals.append(log_id)
     conn.execute(f"UPDATE evolution_log SET {', '.join(sets)} WHERE id = ?", vals)
+
+
+# ── Session Checkpoint operations ──────────────────────────────────
+
+def save_checkpoint(sid: str, task: str = '', task_status: str = 'active',
+                    active_files: str = '[]', current_goal: str = '',
+                    decisions_summary: str = '', errors_found: str = '',
+                    reasoning_thread: str = '', next_step: str = '') -> dict:
+    """Save or update a session checkpoint. Called by PreCompact hook."""
+    conn = get_db()
+    # Get current compaction count
+    existing = conn.execute(
+        "SELECT compaction_count FROM session_checkpoints WHERE sid = ?", (sid,)
+    ).fetchone()
+    count = (existing["compaction_count"] + 1) if existing else 0
+
+    conn.execute(
+        """INSERT INTO session_checkpoints
+           (sid, task, task_status, active_files, current_goal,
+            decisions_summary, errors_found, reasoning_thread, next_step,
+            compaction_count, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
+           ON CONFLICT(sid) DO UPDATE SET
+             task = excluded.task,
+             task_status = excluded.task_status,
+             active_files = excluded.active_files,
+             current_goal = excluded.current_goal,
+             decisions_summary = excluded.decisions_summary,
+             errors_found = excluded.errors_found,
+             reasoning_thread = excluded.reasoning_thread,
+             next_step = excluded.next_step,
+             compaction_count = excluded.compaction_count,
+             updated_at = datetime('now')""",
+        (sid, task, task_status, active_files, current_goal,
+         decisions_summary, errors_found, reasoning_thread, next_step, count)
+    )
+    conn.commit()
+    return {"sid": sid, "compaction_count": count}
+
+
+def read_checkpoint(sid: str = '') -> dict | None:
+    """Read the most recent session checkpoint. If no sid, returns the latest."""
+    conn = get_db()
+    if sid:
+        row = conn.execute(
+            "SELECT * FROM session_checkpoints WHERE sid = ?", (sid,)
+        ).fetchone()
+    else:
+        row = conn.execute(
+            "SELECT * FROM session_checkpoints ORDER BY updated_at DESC LIMIT 1"
+        ).fetchone()
+    return dict(row) if row else None
+
+
+def increment_compaction_count(sid: str) -> int:
+    """Increment and return the compaction count for a session."""
+    conn = get_db()
+    conn.execute(
+        """UPDATE session_checkpoints
+           SET compaction_count = compaction_count + 1, updated_at = datetime('now')
+           WHERE sid = ?""",
+        (sid,)
+    )
+    conn.commit()
+    row = conn.execute(
+        "SELECT compaction_count FROM session_checkpoints WHERE sid = ?", (sid,)
+    ).fetchone()
+    return row["compaction_count"] if row else 0

package/src/hooks/post-compact.sh

@@ -0,0 +1,126 @@
+#!/bin/bash
+# NEXO PostCompact Hook — Re-inject Core Memory Block after compaction
+# Reads the latest session checkpoint from SQLite and generates a structured
+# context block that preserves session continuity.
+set -euo pipefail
+
+NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
+NEXO_DB="$NEXO_HOME/nexo.db"
+TODAY=$(date +%Y-%m-%d)
+LOG_FILE="$NEXO_HOME/operations/tool-logs/${TODAY}.jsonl"
+LOG_LINES=0
+if [ -f "$LOG_FILE" ]; then
+    LOG_LINES=$(wc -l < "$LOG_FILE" | tr -d ' ')
+fi
+
+# Read latest checkpoint from SQLite
+if [ -f "$NEXO_DB" ]; then
+    CHECKPOINT=$(sqlite3 "$NEXO_DB" "
+        SELECT sid, task, task_status, active_files, current_goal,
+               decisions_summary, errors_found, reasoning_thread,
+               next_step, compaction_count
+        FROM session_checkpoints
+        ORDER BY updated_at DESC LIMIT 1
+    " 2>/dev/null || echo "")
+
+    if [ -n "$CHECKPOINT" ]; then
+        # Parse pipe-separated fields
+        SID=$(echo "$CHECKPOINT" | cut -d'|' -f1)
+        TASK=$(echo "$CHECKPOINT" | cut -d'|' -f2)
+        TASK_STATUS=$(echo "$CHECKPOINT" | cut -d'|' -f3)
+        ACTIVE_FILES=$(echo "$CHECKPOINT" | cut -d'|' -f4)
+        CURRENT_GOAL=$(echo "$CHECKPOINT" | cut -d'|' -f5)
+        DECISIONS=$(echo "$CHECKPOINT" | cut -d'|' -f6)
+        ERRORS=$(echo "$CHECKPOINT" | cut -d'|' -f7)
+        REASONING=$(echo "$CHECKPOINT" | cut -d'|' -f8)
+        NEXT_STEP=$(echo "$CHECKPOINT" | cut -d'|' -f9)
+        COMPACT_COUNT=$(echo "$CHECKPOINT" | cut -d'|' -f10)
+
+        # Increment compaction count
+        sqlite3 "$NEXO_DB" "
+            UPDATE session_checkpoints
+            SET compaction_count = compaction_count + 1, updated_at = datetime('now')
+            WHERE sid = '$SID'
+        " 2>/dev/null || true
+
+        # Read diary draft for extra context
+        DRAFT=$(sqlite3 "$NEXO_DB" "
+            SELECT tasks_seen, last_context_hint
+            FROM session_diary_draft
+            WHERE sid = '$SID'
+        " 2>/dev/null || echo "")
+
+        TASKS_SEEN=""
+        LAST_HINT=""
+        if [ -n "$DRAFT" ]; then
+            TASKS_SEEN=$(echo "$DRAFT" | cut -d'|' -f1)
+            LAST_HINT=$(echo "$DRAFT" | cut -d'|' -f2)
+        fi
+
+        # Build Core Memory Block
+        BLOCK="## SESSION CONTINUITY [auto-injected post-compaction #$((COMPACT_COUNT + 1))]"
+        BLOCK="$BLOCK\n**Session:** $SID"
+        BLOCK="$BLOCK\n**Task:** $TASK (status: $TASK_STATUS)"
+
+        if [ -n "$CURRENT_GOAL" ] && [ "$CURRENT_GOAL" != "$TASK" ]; then
+            BLOCK="$BLOCK\n**Goal:** $CURRENT_GOAL"
+        fi
+
+        if [ -n "$ACTIVE_FILES" ] && [ "$ACTIVE_FILES" != "[]" ]; then
+            BLOCK="$BLOCK\n**Files:** $ACTIVE_FILES"
+        fi
+
+        if [ -n "$DECISIONS" ]; then
+            BLOCK="$BLOCK\n**Decisions:** $DECISIONS"
+        fi
+
+        if [ -n "$ERRORS" ]; then
+            BLOCK="$BLOCK\n**Errors:** $ERRORS"
+        fi
+
+        if [ -n "$NEXT_STEP" ]; then
+            BLOCK="$BLOCK\n**Next:** $NEXT_STEP"
+        fi
+
+        if [ -n "$REASONING" ]; then
+            BLOCK="$BLOCK\n**Context:** $REASONING"
+        fi
+
+        if [ -n "$LAST_HINT" ]; then
+            BLOCK="$BLOCK\n**Last context:** $LAST_HINT"
+        fi
+
+        if [ -n "$TASKS_SEEN" ] && [ "$TASKS_SEEN" != "[]" ]; then
+            BLOCK="$BLOCK\n**Session tasks so far:** $TASKS_SEEN"
+        fi
+
+        BLOCK="$BLOCK\n**Tool logs:** ${NEXO_HOME}/operations/tool-logs/${TODAY}.jsonl ($LOG_LINES entries)"
+        BLOCK="$BLOCK\n\n**POST-COMPACTION INSTRUCTIONS:**"
+        BLOCK="$BLOCK\n1. Call nexo_heartbeat with the SID above to reconnect with the session"
+        BLOCK="$BLOCK\n2. If you need specific lost data, query tool logs with jq"
+        BLOCK="$BLOCK\n3. Continue the task from where it left off — do NOT start from zero"
+        BLOCK="$BLOCK\n4. MCP tools (nexo_*) have all persistent state"
+
+        # Escape for JSON
+        BLOCK_ESCAPED=$(echo -e "$BLOCK" | python3 -c "import sys,json; print(json.dumps(sys.stdin.read()))")
+
+        cat << HOOKEOF
+{
+  "systemMessage": $BLOCK_ESCAPED
+}
+HOOKEOF
+    else
+        # No checkpoint — fallback to basic message
+        cat << 'HOOKEOF'
+{
+  "systemMessage": "Post-compaction: no prior checkpoint found. Call nexo_heartbeat to reconnect session state."
+}
+HOOKEOF
+    fi
+else
+    cat << 'HOOKEOF'
+{
+  "systemMessage": "Post-compaction: nexo.db not found. Reconnect via nexo_startup."
+}
+HOOKEOF
+fi

package/src/hooks/pre-compact.sh

@@ -1,65 +1,47 @@
 #!/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.
+# NEXO PreCompact Hook — Save checkpoint + inject preservation instructions
+# This runs BEFORE Claude Code compacts. It:
+# 1. Enriches the session checkpoint in SQLite with latest diary draft data
+# 2. Injects a systemMessage telling the operator to save any WIP via MCP tools
 set -euo pipefail
 
 NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
-NEXO_NAME="${NEXO_NAME:-NEXO}"
-CHECKPOINT_FILE="$NEXO_HOME/coordination/pre-compact-checkpoint.json"
+NEXO_DB="$NEXO_HOME/nexo.db"
+TODAY=$(date +%Y-%m-%d)
+LOG_FILE="$NEXO_HOME/operations/tool-logs/${TODAY}.jsonl"
+LOG_LINES=0
+if [ -f "$LOG_FILE" ]; then
+    LOG_LINES=$(wc -l < "$LOG_FILE" | tr -d ' ')
+fi
+
+# Enrich checkpoint: copy diary draft context into checkpoint if exists
+if [ -f "$NEXO_DB" ]; then
+    # Get latest active session's diary draft
+    LATEST_SID=$(sqlite3 "$NEXO_DB" "
+        SELECT sid FROM sessions ORDER BY last_update_epoch DESC LIMIT 1
+    " 2>/dev/null || echo "")
+
+    if [ -n "$LATEST_SID" ]; then
+        # Pull diary draft data into checkpoint
+        sqlite3 "$NEXO_DB" "
+            INSERT INTO session_checkpoints (sid, task, current_goal, updated_at)
+            SELECT s.sid, s.task, COALESCE(d.last_context_hint, s.task), datetime('now')
+            FROM sessions s
+            LEFT JOIN session_diary_draft d ON d.sid = s.sid
+            WHERE s.sid = '$LATEST_SID'
+            ON CONFLICT(sid) DO UPDATE SET
+                task = excluded.task,
+                current_goal = CASE
+                    WHEN excluded.current_goal != '' THEN excluded.current_goal
+                    ELSE session_checkpoints.current_goal
+                END,
+                updated_at = datetime('now')
+        " 2>/dev/null || true
+    fi
+fi
 
-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."
+  "systemMessage": "CONTEXT IS ABOUT TO BE COMPRESSED.\n\nOBLIGATORY ACTIONS BEFORE COMPACTION:\n1. Save critical state via MCP: nexo_checkpoint_save with current task, active files, decisions, errors, next step, and reasoning thread.\n2. If there is work in progress without a commit, save data via nexo_entity_create, nexo_preference_set, nexo_learning_add, nexo_followup_create.\n3. PERSISTENT TOOL LOGS: ${NEXO_HOME}/operations/tool-logs/${TODAY}.jsonl has ${LOG_LINES} entries.\n4. After compaction, the PostCompact hook will re-inject a Core Memory Block with the checkpoint.\n5. MCP tools (nexo_*) preserve all state — use them to recover context."
 }
 HOOKEOF

package/src/plugins/cortex.py

@@ -0,0 +1,299 @@
+"""Cognitive Cortex plugin — middleware cognitive layer for NEXO Brain.
+
+Provides structured pre-action reasoning with architectural inhibitory control.
+The Cortex does NOT generate answers — it gates, plans, and validates actions.
+
+Activation: event-driven, not on every turn. Only on:
+- Tool intent (edit, execute, delegate)
+- Ambiguity in user request
+- Destructive actions
+- Multi-step tasks
+- Retry after failure
+- Contradictions with known facts
+
+v0.1: Single MCP tool + middleware validation.
+"""
+
+import json
+import time
+
+
+def _get_db():
+    from db import get_db
+    return get_db()
+
+
+def _get_core_rules_for_task(task_type: str) -> list[str]:
+    """Get relevant Core Rules for the given task type."""
+    conn = _get_db()
+    try:
+        # Map task type to rule categories
+        category_map = {
+            "edit": ["integrity", "execution"],
+            "execute": ["integrity", "execution", "delegation"],
+            "delegate": ["delegation"],
+            "analyze": ["execution", "memory"],
+            "answer": ["communication"],
+        }
+        categories = category_map.get(task_type, ["integrity", "execution"])
+        placeholders = ",".join("?" * len(categories))
+
+        rows = conn.execute(
+            f"SELECT id, rule FROM core_rules WHERE category IN ({placeholders}) AND is_active = 1 AND type = 'blocking' ORDER BY importance DESC LIMIT 5",
+            categories
+        ).fetchall()
+        return [f"{r['id']}: {r['rule']}" for r in rows]
+    except Exception:
+        return []
+
+
+def _get_trust_score() -> float:
+    """Get current trust score from cognitive.db."""
+    try:
+        import cognitive
+        return cognitive.get_trust_score()
+    except Exception:
+        return 50.0
+
+
+def _validate_state(state: dict) -> dict:
+    """Validate cognitive state and determine action mode.
+
+    Returns dict with: mode, warnings, injected_rules, blocked_reason
+    """
+    warnings = []
+    mode = "act"  # default: allow action
+    blocked_reason = None
+
+    task_type = state.get("task_type", "answer")
+    plan = state.get("plan", [])
+    unknowns = state.get("unknowns", [])
+    evidence = state.get("evidence_refs", [])
+    verification = state.get("verification_step", "")
+    constraints = state.get("constraints", [])
+    goal = state.get("goal", "")
+
+    # === INHIBITION RULES (architectural, not advisory) ===
+
+    # Rule 1: unknowns exist → force ASK mode
+    if unknowns:
+        mode = "ask"
+        blocked_reason = f"Cannot act with {len(unknowns)} unknown(s). Resolve first."
+        warnings.append(f"UNKNOWNS: {', '.join(unknowns[:3])}")
+
+    # Rule 2: edit/execute without plan → force PROPOSE
+    if task_type in ("edit", "execute", "delegate") and not plan and mode == "act":
+        mode = "propose"
+        blocked_reason = "No plan defined for action task. Propose plan first."
+        warnings.append("MISSING PLAN: define steps before executing")
+
+    # Rule 3: edit/execute without verification → force PROPOSE
+    if task_type in ("edit", "execute") and not verification and mode == "act":
+        mode = "propose"
+        blocked_reason = "No verification step. How will you confirm it worked?"
+        warnings.append("MISSING VERIFICATION: define how to verify")
+
+    # Rule 4: execute without evidence → force PROPOSE
+    if task_type == "execute" and not evidence and mode == "act":
+        mode = "propose"
+        blocked_reason = "No evidence supporting this action."
+        warnings.append("MISSING EVIDENCE: what supports this action?")
+
+    # Rule 5: no goal → force ASK
+    if not goal:
+        mode = "ask"
+        blocked_reason = "No goal defined."
+        warnings.append("NO GOAL: what are you trying to achieve?")
+
+    # === TRUST-BASED ADJUSTMENTS ===
+    trust = _get_trust_score()
+    if trust < 30 and mode == "act" and task_type in ("edit", "execute"):
+        mode = "propose"
+        blocked_reason = f"Trust score {trust:.0f}/100 — propose before acting."
+        warnings.append(f"LOW TRUST ({trust:.0f}): extra verification required")
+
+    # === INJECT RELEVANT RULES ===
+    rules = _get_core_rules_for_task(task_type)
+
+    return {
+        "mode": mode,
+        "tools_available": _tools_for_mode(mode),
+        "warnings": warnings,
+        "blocked_reason": blocked_reason,
+        "injected_rules": rules,
+        "trust_score": round(trust),
+    }
+
+
+def _tools_for_mode(mode: str) -> list[str]:
+    """Define which tool categories are available per mode."""
+    if mode == "ask":
+        return ["read", "search", "ask_user"]
+    elif mode == "propose":
+        return ["read", "search", "analyze", "propose_plan"]
+    else:  # act
+        return ["all"]
+
+
+def handle_cortex_check(
+    goal: str,
+    task_type: str = "answer",
+    plan: str = "[]",
+    known_facts: str = "[]",
+    unknowns: str = "[]",
+    constraints: str = "[]",
+    evidence_refs: str = "[]",
+    verification_step: str = "",
+) -> str:
+    """Cognitive Cortex pre-action check. Call BEFORE significant actions.
+
+    Validates your reasoning state and determines if you can act, should propose,
+    or need to ask for clarification first. Implements architectural inhibitory control.
+
+    WHEN TO CALL:
+    - Before editing files or running commands
+    - Before delegating to subagents
+    - When the task has multiple possible approaches
+    - After a failed attempt (before retrying)
+    - When user instruction seems to conflict with known facts
+
+    DO NOT CALL for simple chat responses, greetings, or explanations.
+
+    Args:
+        goal: What you are trying to achieve (required)
+        task_type: One of: answer, analyze, edit, execute, delegate
+        plan: JSON array of planned steps (e.g. '["read file", "edit function", "test"]')
+        known_facts: JSON array of facts you have (from user, memory, files)
+        unknowns: JSON array of things you don't know yet but need
+        constraints: JSON array of rules or limitations that apply
+        evidence_refs: JSON array of evidence supporting your plan (learnings, user statements, file contents)
+        verification_step: How you will verify the action worked
+
+    Returns:
+        Mode (ask/propose/act), available tools, warnings, and relevant Core Rules
+    """
+    # Parse JSON arrays safely
+    def _parse(s):
+        try:
+            v = json.loads(s) if isinstance(s, str) else s
+            return v if isinstance(v, list) else []
+        except (json.JSONDecodeError, TypeError):
+            return []
+
+    state = {
+        "goal": goal.strip() if goal else "",
+        "task_type": task_type if task_type in ("answer", "analyze", "edit", "execute", "delegate") else "answer",
+        "plan": _parse(plan),
+        "known_facts": _parse(known_facts),
+        "unknowns": _parse(unknowns),
+        "constraints": _parse(constraints),
+        "evidence_refs": _parse(evidence_refs),
+        "verification_step": verification_step.strip() if verification_step else "",
+    }
+
+    result = _validate_state(state)
+
+    # Format response
+    lines = [
+        f"CORTEX CHECK — mode: {result['mode'].upper()}",
+        f"Trust: {result['trust_score']}/100",
+    ]
+
+    if result["mode"] == "act":
+        lines.append("CLEARED: You may proceed with the action.")
+    elif result["mode"] == "propose":
+        lines.append(f"PROPOSE ONLY: {result['blocked_reason']}")
+        lines.append("Show the user your plan and get approval before executing.")
+    elif result["mode"] == "ask":
+        lines.append(f"ASK FIRST: {result['blocked_reason']}")
+        lines.append("Gather the missing information before proceeding.")
+
+    if result["warnings"]:
+        lines.append("")
+        lines.append("Warnings:")
+        for w in result["warnings"]:
+            lines.append(f"  - {w}")
+
+    if result["injected_rules"]:
+        lines.append("")
+        lines.append("Applicable Core Rules:")
+        for r in result["injected_rules"]:
+            lines.append(f"  - {r}")
+
+    lines.append("")
+    lines.append(f"Tools available: {', '.join(result['tools_available'])}")
+
+    # Log cortex activation for metrics
+    try:
+        conn = _get_db()
+        conn.execute(
+            """CREATE TABLE IF NOT EXISTS cortex_log (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                goal TEXT,
+                task_type TEXT,
+                mode TEXT,
+                warnings TEXT,
+                trust_score INTEGER,
+                created_at TEXT DEFAULT (datetime('now'))
+            )"""
+        )
+        conn.execute(
+            "INSERT INTO cortex_log (goal, task_type, mode, warnings, trust_score) VALUES (?, ?, ?, ?, ?)",
+            (goal[:200], task_type, result["mode"], json.dumps(result["warnings"]), result["trust_score"])
+        )
+        conn.commit()
+    except Exception:
+        pass
+
+    return "\n".join(lines)
+
+
+def handle_cortex_stats(days: int = 7) -> str:
+    """View Cortex activation statistics — how often it activates, modes, warnings.
+
+    Args:
+        days: Period to analyze (default 7)
+    """
+    conn = _get_db()
+    try:
+        conn.execute("SELECT 1 FROM cortex_log LIMIT 1")
+    except Exception:
+        return "No Cortex data yet. The Cortex activates on significant actions."
+
+    cutoff = f"datetime('now', '-{days} days')"
+
+    total = conn.execute(f"SELECT COUNT(*) FROM cortex_log WHERE created_at >= {cutoff}").fetchone()[0]
+    by_mode = conn.execute(
+        f"SELECT mode, COUNT(*) as c FROM cortex_log WHERE created_at >= {cutoff} GROUP BY mode ORDER BY c DESC"
+    ).fetchall()
+    by_type = conn.execute(
+        f"SELECT task_type, COUNT(*) as c FROM cortex_log WHERE created_at >= {cutoff} GROUP BY task_type ORDER BY c DESC"
+    ).fetchall()
+
+    lines = [
+        f"CORTEX STATS — last {days} days",
+        f"Total activations: {total}",
+        "",
+        "By mode:",
+    ]
+    for r in by_mode:
+        pct = (r["c"] / total * 100) if total > 0 else 0
+        lines.append(f"  {r['mode']}: {r['c']} ({pct:.0f}%)")
+
+    lines.append("")
+    lines.append("By task type:")
+    for r in by_type:
+        lines.append(f"  {r['task_type']}: {r['c']}")
+
+    # Inhibition rate = % of activations that resulted in ask or propose (not act)
+    inhibited = sum(r["c"] for r in by_mode if r["mode"] != "act")
+    inhibition_rate = (inhibited / total * 100) if total > 0 else 0
+    lines.append(f"\nInhibition rate: {inhibition_rate:.0f}% (target: 30-60%)")
+
+    return "\n".join(lines)
+
+
+TOOLS = [
+    (handle_cortex_check, "nexo_cortex_check", "Cognitive pre-action check. Validates reasoning and determines if you can act, should propose, or need to ask first. Call before significant actions."),
+    (handle_cortex_stats, "nexo_cortex_stats", "View Cortex activation statistics — modes, task types, inhibition rate."),
+]

package/src/rules/core-rules.json

@@ -6,7 +6,9 @@
     "source": "Consolidated from 6 months production use + multi-AI debate (Claude Opus + GPT-4o)",
     "total_rules": 30,
     "blocking": 25,
-    "advisory": 5
+    "advisory": 5,
+    "immutable": true,
+    "immutable_note": "Core rules are the DNA of NEXO Brain. They CANNOT be deleted or modified by the user. Only the migration system (version updates from the creators) can add, modify, or remove rules. Users can configure behavioral intensity (autonomy, communication, proactivity) but not the rules themselves."
   },
   "categories": {
     "integrity": {

package/src/server.py

@@ -126,6 +126,77 @@ def nexo_smart_startup() -> str:
     return handle_smart_startup_query()
 
 
+# ── Session Checkpoints (auto-compaction continuity) ──────────────
+
+@mcp.tool
+def nexo_checkpoint_save(
+    sid: str,
+    task: str = '',
+    task_status: str = 'active',
+    active_files: str = '[]',
+    current_goal: str = '',
+    decisions_summary: str = '',
+    errors_found: str = '',
+    reasoning_thread: str = '',
+    next_step: str = ''
+) -> str:
+    """Save a session checkpoint for auto-compaction continuity.
+
+    Call this BEFORE context compaction to preserve session state.
+    The PostCompact hook reads this checkpoint and re-injects it as a
+    Core Memory Block, so the session continues seamlessly.
+
+    Args:
+        sid: Session ID.
+        task: Current task description.
+        task_status: One of 'active', 'investigating', 'fixing', 'deploying', 'blocked'.
+        active_files: JSON array of file paths currently being worked on.
+        current_goal: What you're trying to achieve right now (1-2 sentences).
+        decisions_summary: Recent decisions with brief reasoning (2-3 lines).
+        errors_found: Errors encountered and their status (resolved/open).
+        reasoning_thread: Your current chain of thought (1-2 sentences).
+        next_step: The concrete next action to take.
+    """
+    from db import save_checkpoint
+    result = save_checkpoint(
+        sid=sid, task=task, task_status=task_status,
+        active_files=active_files, current_goal=current_goal,
+        decisions_summary=decisions_summary, errors_found=errors_found,
+        reasoning_thread=reasoning_thread, next_step=next_step,
+    )
+    return f"Checkpoint saved for {sid}. Compaction #{result['compaction_count']}. PostCompact will re-inject this as Core Memory Block."
+
+
+@mcp.tool
+def nexo_checkpoint_read(sid: str = '') -> str:
+    """Read the latest session checkpoint. Used by PostCompact hook and for manual recovery.
+
+    Args:
+        sid: Session ID. If empty, returns the most recent checkpoint from any session.
+    """
+    from db import read_checkpoint
+    cp = read_checkpoint(sid)
+    if not cp:
+        return "No checkpoint found."
+
+    lines = [f"CHECKPOINT for {cp['sid']} (compaction #{cp['compaction_count']})"]
+    lines.append(f"Task: {cp['task']} ({cp['task_status']})")
+    if cp.get('current_goal'):
+        lines.append(f"Goal: {cp['current_goal']}")
+    if cp.get('active_files') and cp['active_files'] != '[]':
+        lines.append(f"Files: {cp['active_files']}")
+    if cp.get('decisions_summary'):
+        lines.append(f"Decisions: {cp['decisions_summary']}")
+    if cp.get('errors_found'):
+        lines.append(f"Errors: {cp['errors_found']}")
+    if cp.get('reasoning_thread'):
+        lines.append(f"Context: {cp['reasoning_thread']}")
+    if cp.get('next_step'):
+        lines.append(f"Next: {cp['next_step']}")
+    lines.append(f"Updated: {cp['updated_at']}")
+    return "\n".join(lines)
+
+
 # ── File coordination (3 tools) ───────────────────────────────────
 
 @mcp.tool

package/src/tools_sessions.py

@@ -8,6 +8,7 @@ from db import (
     get_active_sessions, clean_stale_sessions, search_sessions,
     get_inbox, get_pending_questions, now_epoch,
     SESSION_STALE_SECONDS, check_session_has_diary,
+    save_checkpoint, read_checkpoint, increment_compaction_count,
 )
 
 # ── Session Keepalive ────────────────────────────────────────────────
@@ -317,6 +318,16 @@ def handle_heartbeat(sid: str, task: str, context_hint: str = '') -> str:
     except Exception:
         pass  # Draft accumulation is best-effort, never block heartbeat
 
+    # Update session checkpoint with current goal (lightweight, every heartbeat)
+    try:
+        save_checkpoint(
+            sid=sid,
+            task=task,
+            current_goal=context_hint[:300] if context_hint else task,
+        )
+    except Exception:
+        pass  # Checkpoint update is best-effort
+
     # Diary reminder: after 30 min active with no diary entry
     conn = get_db()
     row = conn.execute("SELECT started_epoch FROM sessions WHERE sid = ?", (sid,)).fetchone()

package/templates/CLAUDE.md.template

@@ -58,6 +58,28 @@ _Subagents inherit zero session memory. Without context = guaranteed errors._
 
 For the full 30 rules across 6 categories (Integrity, Execution, Memory, Delegation, Communication, Proactivity), call `nexo_rules_check`.
 
+## Cognitive Cortex (Pre-Action Reasoning)
+
+Before significant actions, call `nexo_cortex_check` to validate your reasoning. The Cortex determines if you can **act**, should **propose**, or need to **ask** first.
+
+**WHEN to call `nexo_cortex_check`:**
+- Before editing files or running commands
+- Before delegating to subagents
+- When the task has multiple possible approaches
+- After a failed attempt (before retrying differently)
+- When user instruction conflicts with known facts
+
+**DO NOT call** for simple chat, greetings, explanations, or read-only queries.
+
+**How it works:** You provide your goal, plan, knowns, unknowns, and evidence. The Cortex validates and returns:
+- **ACT** — proceed with execution (all tools available)
+- **PROPOSE** — show plan to user first (no write/execute tools)
+- **ASK** — gather missing information first (read/search only)
+
+The Cortex enforces inhibitory control architecturally — it physically restricts available tools based on your reasoning quality. This prevents premature action, hallucinated certainty, and unverified execution.
+
+`nexo_cortex_stats` shows activation metrics and inhibition rates.
+
 ## Personality Calibration
 
 Read `{{NEXO_HOME}}/brain/calibration.json` at startup to load user preferences. These override defaults: