nexo-brain 1.0.0 → 1.1.0

package/README.md

@@ -1,12 +1,12 @@
 # NEXO Brain — Your AI Gets a Brain
 
-[![npm v1.0.0](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)
 
-> **v1.0.0** — 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).
+> **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.**
 
@@ -163,9 +163,42 @@ User message → Fast Path check → Simple chat? → Respond directly
 
 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 29 cognitive tools on top of the 76 base tools, totaling **113+ 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
 
@@ -238,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:
 
@@ -247,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
@@ -263,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
@@ -346,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...
 
@@ -370,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 |
 |----------|-------|-------|---------|
@@ -412,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
 
@@ -469,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,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO \u2014 Cognitive co-operator for Claude Code. Atkinson-Shiffrin memory, semantic RAG, trust scoring, and metacognitive error prevention.",
   "bin": {

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/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()