nexo-brain 1.5.0 → 1.5.2

package/README.md

@@ -198,7 +198,7 @@ This means long sessions (8+ hours) feel like one continuous conversation instea
 
 ## Cognitive Features
 
-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:
+NEXO Brain provides **100+ MCP tools** implementing cognitive science concepts that go beyond basic memory:
 
 ### Input Pipeline
 
@@ -226,11 +226,13 @@ NEXO Brain provides 29 cognitive tools on top of the 78 base tools, totaling **1
 |---------|-------------|
 | **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. |
+| **KG Boost** | Knowledge Graph connection count influences retrieval ranking. Memories linked to well-connected entities (many edges) receive a logarithmic score bonus, surfacing contextually important facts higher. |
+| **HNSW Vector Index** | Optional approximate nearest neighbor index (hnswlib). Activates automatically when memory count exceeds 10,000. Falls back to exact brute-force below that threshold — no configuration needed. |
 | **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. |
+| **Recall Explanations** | Transparent score breakdown for every retrieval result. Shows exactly why a memory was returned: semantic similarity, recency, access frequency, KG boost, and co-activation bonuses. |
 
 ### Proactive
 
@@ -430,6 +432,17 @@ That's it. No need to run `claude` manually. Your operator will greet you immedi
 
 ## Architecture
 
+### Modular Package Structure (v1.5.0)
+
+The core is organized into two Python packages:
+
+| Package | Modules | Responsibility |
+|---------|---------|----------------|
+| `db/` | 11 modules (`_core`, `_schema`, `_sessions`, `_learnings`, `_episodic`, `_credentials`, `_entities`, `_evolution`, `_fts`, `_reminders`, `_tasks`) | All SQLite persistence: schema migrations, CRUD, FTS indexing |
+| `cognitive/` | 6 modules (`_core`, `_memory`, `_ingest`, `_search`, `_decay`, `_trust`) | Cognitive engine: embeddings, RAG, decay, trust scoring |
+
+The rest of the server (`server.py`, `tools_*.py`, `plugins/`) stays flat for clarity.
+
 ### 100+ MCP Tools across 20 Categories
 
 | Category | Count | Tools | Purpose |
@@ -439,7 +452,7 @@ That's it. No need to run `claude` manually. Your operator will greet you immedi
 | Cognitive Advanced | 8 | hyde_search, spread_activate, explain_recall, dream, prospect, hook_capture, pin, archive | Advanced retrieval, proactive, lifecycle |
 | Guard | 3 | check, stats, log_repetition | Metacognitive error prevention |
 | Episodic | 10 | change_log/search/commit, decision_log/outcome/search, review_queue, diary_write/read, recall | What happened and why |
-| Sessions | 4 | startup, heartbeat, stop, status | Session lifecycle + context shift detection |
+| Sessions | 4 | startup, heartbeat, stop, status | Session lifecycle + context shift detection + inter-terminal auto-inbox |
 | Coordination | 7 | track, untrack, files, send, ask, answer, check_answer | Multi-session file coordination + messaging |
 | Reminders | 5 | list, create, update, complete, delete | User's tasks and deadlines |
 | Followups | 4 | create, update, complete, delete | System's autonomous verification tasks |
@@ -455,6 +468,7 @@ That's it. No need to run `claude` manually. Your operator will greet you immedi
 | 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 |
+| Claim Graph | — | (internal) | Atomic facts with provenance and contradiction detection |
 
 ### Plugin System
 
@@ -591,11 +605,11 @@ NEXO Brain builds on ideas from several open-source projects. We're grateful for
 
 | Project | Inspired Features |
 |---------|------------------|
-| [Vestige](https://github.com/pchaganti/gx-vestige) | HyDE query expansion, spreading activation, prediction error gating, memory dreaming, prospective memory |
-| [ShieldCortex](https://github.com/PShieldCortex/ShieldCortex) | Security pipeline (4-layer memory poisoning defense) |
-| [Bicameral](https://github.com/nicobailey/Bicameral) | Quarantine queue (trust promotion policy for new facts) |
-| [claude-mem](https://github.com/nicobailey/claude-mem) | Hook auto-capture (extracting decisions and facts from conversations) |
-| [ClawMem](https://github.com/nicobailey/ClawMem) | Co-activation reinforcement (memories retrieved together strengthen connections) |
+| Vestige | HyDE query expansion, spreading activation, prediction error gating, memory dreaming, prospective memory |
+| ShieldCortex | Security pipeline (4-layer memory poisoning defense) |
+| Bicameral | Quarantine queue (trust promotion policy for new facts) |
+| claude-mem | Hook auto-capture (extracting decisions and facts from conversations) |
+| ClawMem | Co-activation reinforcement (memories retrieved together strengthen connections) |
 
 ## Support the Project
 
@@ -610,6 +624,15 @@ If NEXO Brain is useful to you, consider:
 
 ## Changelog
 
+### v1.5.0 — Modular Core + Knowledge Graph Search (2026-03-29)
+- **Architecture**: `db.py` refactored into `db/` package (11 modules: core, schema, sessions, learnings, episodic, credentials, entities, evolution, fts, reminders, tasks)
+- **Architecture**: `cognitive.py` refactored into `cognitive/` package (6 modules: core, memory, ingest, search, decay, trust)
+- **KG Boost**: Knowledge Graph connection count now influences search result ranking — well-connected entities surface higher in retrieval
+- **HNSW Vector Index**: Optional approximate nearest neighbor acceleration (activates automatically above 10,000 memories, falls back to brute-force otherwise)
+- **Claim Graph**: Decomposes blob memories into atomic verifiable facts with provenance, confidence scores, and contradiction detection
+- **Inter-terminal Auto-inbox (D+)**: `nexo_startup` now accepts `claude_session_id` (Claude Code session UUID) — enables automatic inbox delivery between parallel terminals via PostToolUse hook + migration v13
+- **Tests**: 24 pytest tests across 3 suites (cognitive, knowledge graph, migrations)
+
 ### v1.4.1 — Multi-AI Code Review (2026-03-29)
 - **Fix**: 3 bugs found by GPT-5.4 (Codex CLI) + Gemini 2.5 (Gemini CLI) reviewing full codebase
   - `session_diaries` → `session_diary` table name (smart startup silently failed)

package/package.json

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

package/src/scripts/deep-sleep/analyze_session.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""
+Deep Sleep — Step 2: Analyze transcripts with Claude CLI (bare mode).
+Sends each session to Claude opus for analysis, then consolidates findings.
+"""
+import json
+import os
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+PROMPT_FILE = Path(__file__).parent / "prompt.md"
+DEEP_SLEEP_DIR = Path.home() / "claude" / "operations" / "deep-sleep"
+MAX_TRANSCRIPT_CHARS = 150_000
+
+
+def build_transcript_text(session: dict) -> str:
+    """Build a readable transcript from a session."""
+    lines = [
+        f"## Session: {session['session_file']}",
+        f"Modified: {session['modified']}",
+        f"Messages: {session['message_count']}, Tool uses: {session['tool_use_count']}",
+        "",
+        "### Conversation"
+    ]
+    for msg in session["messages"]:
+        role = "USER" if msg["role"] == "user" else "NEXO"
+        lines.append(f"\n**{role}:**")
+        lines.append(msg["text"])
+
+    if session["tool_uses"]:
+        lines.append("\n### Tool Usage Log")
+        for tu in session["tool_uses"]:
+            file_info = f" [{tu['file'][:80]}]" if tu.get("file") else ""
+            lines.append(f"- {tu['tool']}{file_info}")
+
+    return "\n".join(lines)
+
+
+def find_api_key() -> str | None:
+    """Find Anthropic API key from common locations."""
+    # Environment variable
+    key = os.environ.get("ANTHROPIC_API_KEY", "")
+    if key:
+        return key
+
+    # Common file locations
+    for path in [
+        Path.home() / ".claude" / "anthropic-api-key.txt",
+        Path.home() / ".anthropic" / "api_key",
+        Path.home() / ".config" / "anthropic" / "api_key",
+    ]:
+        if path.exists():
+            return path.read_text().strip()
+
+    return None
+
+
+def analyze_with_claude(transcript: str, prompt: str) -> dict | None:
+    """Send transcript to Claude CLI for analysis."""
+    full_prompt = (
+        f"{prompt}\n\n---\n\n# TODAY'S TRANSCRIPT\n\n{transcript}\n\n---\n\n"
+        "Analyze this transcript and return the JSON output as specified. "
+        "Return ONLY the JSON, no markdown code fences."
+    )
+
+    api_key = find_api_key()
+    env = os.environ.copy()
+    if api_key:
+        env["ANTHROPIC_API_KEY"] = api_key
+
+    try:
+        result = subprocess.run(
+            ["claude", "-p", full_prompt, "--model", "opus", "--output-format", "text", "--bare"],
+            capture_output=True, text=True, timeout=300, env=env
+        )
+
+        if result.returncode != 0:
+            print(f"Claude CLI error: {result.stderr[:500]}", file=sys.stderr)
+            return None
+
+        response_text = result.stdout.strip()
+
+        # Strip markdown code fences if present
+        if response_text.startswith("```"):
+            lines = response_text.split("\n")
+            response_text = "\n".join(lines[1:-1] if lines[-1].strip() == "```" else lines[1:])
+            response_text = response_text.strip()
+
+        # Find JSON object in response
+        json_start = response_text.find("{")
+        json_end = response_text.rfind("}") + 1
+        if json_start >= 0 and json_end > json_start:
+            response_text = response_text[json_start:json_end]
+
+        return json.loads(response_text)
+
+    except subprocess.TimeoutExpired:
+        print("Claude CLI timeout (300s)", file=sys.stderr)
+        return None
+    except json.JSONDecodeError as e:
+        print(f"Failed to parse Claude response: {e}", file=sys.stderr)
+        return None
+    except FileNotFoundError:
+        print("Claude CLI not found. Install: npm install -g @anthropic-ai/claude-code", file=sys.stderr)
+        return None
+
+
+def consolidate_findings(results: list[dict]) -> dict:
+    """Merge findings from multiple sessions into one report."""
+    consolidated = {
+        "uncaptured_corrections": [],
+        "uncaptured_ideas": [],
+        "missed_commitments": [],
+        "protocol_compliance": {
+            "guard_check": {"required": 0, "executed": 0},
+            "heartbeat_quality": {"total": 0, "with_good_context": 0},
+            "trust_adjustments": {"corrections_detected": 0, "adjusted": 0},
+            "learning_capture": {"errors_resolved": 0, "captured": 0},
+            "change_log": {"production_edits": 0, "logged": 0},
+            "feedback_capture": {"corrections": 0, "captured": 0},
+        },
+        "protocol_violations": [],
+        "quality_issues": [],
+        "auto_reinforcements": [],
+    }
+
+    for r in results:
+        if not r:
+            continue
+        for key in ["uncaptured_corrections", "uncaptured_ideas", "missed_commitments",
+                     "protocol_violations", "quality_issues", "auto_reinforcements"]:
+            consolidated[key].extend(r.get(key, []))
+
+        pc = r.get("protocol_compliance", {})
+        for key in consolidated["protocol_compliance"]:
+            if key in pc and isinstance(pc[key], dict):
+                for subkey in consolidated["protocol_compliance"][key]:
+                    consolidated["protocol_compliance"][key][subkey] += pc[key].get(subkey, 0)
+
+    # Calculate rates
+    for key, vals in consolidated["protocol_compliance"].items():
+        keys = list(vals.keys())
+        if len(keys) == 2:
+            denominator = vals[keys[0]]
+            numerator = vals[keys[1]]
+            vals["rate"] = round(numerator / denominator, 2) if denominator > 0 else 1.0
+
+    rates = [v.get("rate", 1.0) for v in consolidated["protocol_compliance"].values()]
+    consolidated["protocol_compliance"]["overall_compliance"] = round(sum(rates) / len(rates), 2) if rates else 1.0
+    consolidated["auto_reinforcements"] = list(set(consolidated["auto_reinforcements"]))
+
+    return consolidated
+
+
+def main():
+    date = sys.argv[1] if len(sys.argv) > 1 else datetime.now().strftime("%Y-%m-%d")
+
+    transcripts_file = DEEP_SLEEP_DIR / f"{date}-transcripts.json"
+    if not transcripts_file.exists():
+        print(f"No transcripts found for {date}. Run collect_transcripts.py first.")
+        sys.exit(1)
+
+    with open(transcripts_file) as f:
+        data = json.load(f)
+
+    sessions = data["sessions"]
+    print(f"Analyzing {len(sessions)} sessions from {date}...")
+
+    prompt = PROMPT_FILE.read_text()
+
+    results = []
+    for i, session in enumerate(sessions):
+        transcript = build_transcript_text(session)
+
+        if len(transcript) < 500:
+            print(f"  Session {i+1}/{len(sessions)}: skipped (too short)")
+            continue
+
+        if len(transcript) > MAX_TRANSCRIPT_CHARS:
+            transcript = transcript[:MAX_TRANSCRIPT_CHARS] + "\n\n[TRUNCATED]"
+
+        print(f"  Session {i+1}/{len(sessions)}: {session['session_file'][:12]}... ({len(transcript)} chars)")
+        result = analyze_with_claude(transcript, prompt)
+        if result:
+            results.append(result)
+            print(f"    → {len(result.get('uncaptured_corrections', []))} corrections, "
+                  f"{len(result.get('protocol_violations', []))} violations")
+        else:
+            print(f"    → Analysis failed")
+
+    consolidated = consolidate_findings(results)
+    consolidated["date"] = date
+    consolidated["sessions_analyzed"] = len(results)
+
+    n_corrections = len(consolidated["uncaptured_corrections"])
+    n_violations = len(consolidated["protocol_violations"])
+    compliance = consolidated["protocol_compliance"]["overall_compliance"]
+    consolidated["summary"] = (
+        f"Analyzed {len(results)} sessions. "
+        f"Found {n_corrections} uncaptured corrections, {n_violations} protocol violations. "
+        f"Overall compliance: {compliance:.0%}."
+    )
+
+    output_file = DEEP_SLEEP_DIR / f"{date}-analysis.json"
+    with open(output_file, "w") as f:
+        json.dump(consolidated, f, indent=2, ensure_ascii=False)
+
+    print(f"\nResults: {output_file}")
+    print(consolidated["summary"])
+
+
+if __name__ == "__main__":
+    main()

package/src/scripts/deep-sleep/apply_findings.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""
+Deep Sleep — Step 3: Apply findings.
+Takes the analysis output and writes feedback memories + trust adjustments.
+"""
+import json
+import sqlite3
+import sys
+from datetime import datetime
+from pathlib import Path
+
+DEEP_SLEEP_DIR = Path.home() / "claude" / "operations" / "deep-sleep"
+NEXO_DB = Path.home() / "claude" / "nexo-mcp" / "nexo.db"
+
+
+def find_memory_dir() -> Path:
+    """Find the Claude Code auto-memory directory."""
+    claude_dir = Path.home() / ".claude" / "projects"
+    for d in claude_dir.iterdir():
+        if d.is_dir():
+            mem_dir = d / "memory"
+            if mem_dir.exists():
+                return mem_dir
+    # Fallback: create under first project dir
+    for d in claude_dir.iterdir():
+        if d.is_dir():
+            mem_dir = d / "memory"
+            mem_dir.mkdir(exist_ok=True)
+            return mem_dir
+    return claude_dir / "memory"
+
+
+def write_feedback_memory(memory_dir: Path, filename: str, name: str, description: str, content: str):
+    """Write a feedback memory file."""
+    filepath = memory_dir / filename
+    feedback = f"""---
+name: {name}
+description: {description}
+type: feedback
+---
+
+{content}
+"""
+    filepath.write_text(feedback)
+
+
+def update_memory_index(memory_dir: Path, new_entries: list[dict]):
+    """Append new entries to MEMORY.md index."""
+    index_file = memory_dir / "MEMORY.md"
+    if not index_file.exists() or not new_entries:
+        return
+
+    current = index_file.read_text()
+    lines_to_add = []
+    for entry in new_entries:
+        line = f"- **{entry['title']}:** `{entry['filename']}` --- {entry['summary']}"
+        if line not in current:
+            lines_to_add.append(line)
+
+    if lines_to_add:
+        current += "\n" + "\n".join(lines_to_add) + "\n"
+        index_file.write_text(current)
+
+
+def adjust_trust(points: int, context: str):
+    """Record trust adjustment in cognitive.db if available."""
+    cog_db = Path.home() / "claude" / "nexo-mcp" / "cognitive.db"
+    if not cog_db.exists():
+        return
+    try:
+        conn = sqlite3.connect(str(cog_db))
+        conn.execute(
+            "INSERT INTO trust_events (event, context, points, created_at) VALUES (?, ?, ?, ?)",
+            ("deep_sleep_violations", context, points, datetime.now().isoformat())
+        )
+        conn.commit()
+        conn.close()
+    except Exception:
+        pass
+
+
+def add_learning(category: str, title: str, content: str) -> bool:
+    """Add a learning to nexo.db using real schema."""
+    if not NEXO_DB.exists():
+        return False
+    try:
+        now = datetime.now().timestamp()
+        conn = sqlite3.connect(str(NEXO_DB))
+        conn.execute(
+            "INSERT INTO learnings (category, title, content, created_at, updated_at, reasoning) VALUES (?, ?, ?, ?, ?, ?)",
+            (category, title, content, now, now, "Deep Sleep overnight analysis")
+        )
+        conn.commit()
+        conn.close()
+        return True
+    except Exception as e:
+        print(f"  Error adding learning: {e}", file=sys.stderr)
+        return False
+
+
+def add_followup(followup_id: str, description: str, date: str = None) -> bool:
+    """Add a followup to nexo.db using real schema."""
+    if not NEXO_DB.exists():
+        return False
+    try:
+        now = datetime.now().timestamp()
+        conn = sqlite3.connect(str(NEXO_DB))
+        conn.execute(
+            "INSERT OR IGNORE INTO followups (id, description, date, status, created_at, updated_at, reasoning) VALUES (?, ?, ?, 'PENDIENTE', ?, ?, ?)",
+            (followup_id, description, date or "", now, now, "Deep Sleep overnight analysis")
+        )
+        conn.commit()
+        conn.close()
+        return True
+    except Exception as e:
+        print(f"  Error adding followup: {e}", file=sys.stderr)
+        return False
+
+
+def apply(analysis: dict):
+    """Apply all findings from deep sleep analysis."""
+    memory_dir = find_memory_dir()
+    actions_taken = []
+    memory_entries = []
+    date = analysis["date"]
+
+    print(f"\nApplying findings for {date}...")
+
+    # 1. Uncaptured corrections → learnings + feedback memories
+    for i, correction in enumerate(analysis.get("uncaptured_corrections", [])):
+        severity = correction.get("severity", "medium")
+        category = correction.get("category", "process")
+        content = correction.get("what_nexo_should_have_saved", "")
+        quote = correction.get("quote", "")
+
+        # All corrections → learnings
+        learning_title = f"[Deep Sleep] {content[:80]}"
+        learning_content = f"User said: \"{quote}\"\nContext: {correction.get('context', '')}\nRepeated: {correction.get('times_repeated', 1)} times"
+        if add_learning(category, learning_title, learning_content):
+            actions_taken.append(f"learning_add: {learning_title[:50]}")
+
+        # High/critical → also feedback memories
+        if severity in ("high", "critical"):
+            safe_name = category.replace(" ", "_").lower()
+            filename = f"ds_{date}_{safe_name}_{i}.md"
+            write_feedback_memory(
+                memory_dir, filename,
+                name=content[:60],
+                description=f"Deep sleep detected uncaptured correction ({severity})",
+                content=f"{content}\n\n**Why:** User said: \"{quote}\"\nContext: {correction.get('context', '')}\n\n**How to apply:** {content}"
+            )
+            memory_entries.append({
+                "title": content[:40],
+                "filename": filename,
+                "summary": f"Deep sleep {date}, severity {severity}"
+            })
+            actions_taken.append(f"feedback_write: {filename}")
+
+    # 2. Missed commitments → followups
+    for i, commitment in enumerate(analysis.get("missed_commitments", [])):
+        fid = f"NF-DS-{date}-{i}"
+        desc = f"[Deep Sleep] {commitment.get('commitment', '')[:100]}"
+        if add_followup(fid, desc, commitment.get("due_date")):
+            actions_taken.append(f"followup: {desc[:50]}")
+
+    # 3. Trust adjustments for critical violations
+    critical_violations = [v for v in analysis.get("protocol_violations", []) if v.get("severity") == "critical"]
+    if critical_violations:
+        points = -3 * len(critical_violations)
+        adjust_trust(points, f"{len(critical_violations)} critical violations on {date}")
+        actions_taken.append(f"trust: {points} points ({len(critical_violations)} critical violations)")
+
+    # 3. Update MEMORY.md index
+    update_memory_index(memory_dir, memory_entries)
+    if memory_entries:
+        actions_taken.append(f"memory_index: {len(memory_entries)} entries added")
+
+    # 4. Save applied actions log
+    applied_log = {
+        "date": date,
+        "applied_at": datetime.now().isoformat(),
+        "actions_taken": actions_taken,
+        "corrections_processed": len(analysis.get("uncaptured_corrections", [])),
+        "compliance": analysis.get("protocol_compliance", {}).get("overall_compliance", 0)
+    }
+
+    applied_file = DEEP_SLEEP_DIR / f"{date}-applied.json"
+    with open(applied_file, "w") as f:
+        json.dump(applied_log, f, indent=2, ensure_ascii=False)
+
+    print(f"Applied {len(actions_taken)} actions:")
+    for a in actions_taken:
+        print(f"  ✓ {a}")
+
+    return applied_log
+
+
+def main():
+    date = sys.argv[1] if len(sys.argv) > 1 else datetime.now().strftime("%Y-%m-%d")
+
+    analysis_file = DEEP_SLEEP_DIR / f"{date}-analysis.json"
+    if not analysis_file.exists():
+        print(f"No analysis found for {date}. Run analyze_session.py first.")
+        sys.exit(1)
+
+    with open(analysis_file) as f:
+        analysis = json.load(f)
+
+    result = apply(analysis)
+
+    compliance = analysis.get("protocol_compliance", {}).get("overall_compliance", 0)
+    print(f"\nDeep Sleep {date} — {result['corrections_processed']} corrections, "
+          f"{compliance:.0%} compliance, {len(result['actions_taken'])} actions applied")
+
+
+if __name__ == "__main__":
+    main()

package/src/scripts/deep-sleep/collect_transcripts.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""
+Deep Sleep — Step 1: Collect today's session transcripts.
+Reads Claude Code .jsonl files, extracts clean conversation text + tool usage.
+"""
+import json
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+
+MIN_USER_MESSAGES = 3  # Skip trivial sessions
+
+
+def find_sessions_dir() -> Path:
+    """Find the Claude Code sessions directory dynamically."""
+    claude_dir = Path.home() / ".claude" / "projects"
+    if not claude_dir.exists():
+        return claude_dir
+
+    # Find the project directory (usually named after the home path)
+    for d in claude_dir.iterdir():
+        if d.is_dir() and list(d.glob("*.jsonl")):
+            return d
+
+    # Fallback: look for any .jsonl in the projects dir tree
+    for jsonl in claude_dir.rglob("*.jsonl"):
+        return jsonl.parent
+
+    return claude_dir
+
+
+def extract_session(jsonl_path: str) -> dict | None:
+    """Extract clean transcript from a session JSONL file."""
+    messages = []
+    tool_uses = []
+    user_msg_count = 0
+
+    try:
+        with open(jsonl_path, "r") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    d = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+
+                msg_type = d.get("type")
+
+                # User messages
+                if msg_type == "user":
+                    content = d.get("message", {}).get("content", "")
+                    if isinstance(content, str) and content.strip():
+                        if content.startswith("<system-reminder>"):
+                            continue
+                        messages.append({
+                            "role": "user",
+                            "text": content[:5000],
+                            "uuid": d.get("uuid", "")
+                        })
+                        user_msg_count += 1
+
+                # Assistant messages
+                elif msg_type in ("message", "assistant"):
+                    msg = d.get("message", {})
+                    content_blocks = msg.get("content", [])
+                    text_parts = []
+                    for block in content_blocks:
+                        if isinstance(block, dict):
+                            if block.get("type") == "text":
+                                text_parts.append(block.get("text", ""))
+                            elif block.get("type") == "tool_use":
+                                tool_uses.append({
+                                    "tool": block.get("name", ""),
+                                    "input_keys": list(block.get("input", {}).keys()) if isinstance(block.get("input"), dict) else [],
+                                    "file": block.get("input", {}).get("file_path", "") or block.get("input", {}).get("command", "")[:100] if isinstance(block.get("input"), dict) else ""
+                                })
+                    if text_parts:
+                        combined = "\n".join(text_parts)[:5000]
+                        messages.append({
+                            "role": "assistant",
+                            "text": combined
+                        })
+
+    except Exception as e:
+        print(f"Error reading {jsonl_path}: {e}", file=sys.stderr)
+        return None
+
+    if user_msg_count < MIN_USER_MESSAGES:
+        return None
+
+    return {
+        "session_file": os.path.basename(jsonl_path),
+        "message_count": len(messages),
+        "user_message_count": user_msg_count,
+        "tool_use_count": len(tool_uses),
+        "messages": messages,
+        "tool_uses": tool_uses
+    }
+
+
+def collect_date(target_date: str, sessions_dir: Path) -> list[dict]:
+    """Collect all sessions modified on a given date."""
+    sessions = []
+    for f in sessions_dir.glob("*.jsonl"):
+        mtime = datetime.fromtimestamp(f.stat().st_mtime)
+        if mtime.strftime("%Y-%m-%d") == target_date:
+            session = extract_session(str(f))
+            if session:
+                session["modified"] = mtime.isoformat()
+                sessions.append(session)
+    sessions.sort(key=lambda s: s["modified"])
+    return sessions
+
+
+def main():
+    date_arg = sys.argv[1] if len(sys.argv) > 1 else datetime.now().strftime("%Y-%m-%d")
+    sessions_dir = find_sessions_dir()
+
+    sessions = collect_date(date_arg, sessions_dir)
+
+    output = {
+        "date": date_arg,
+        "sessions_found": len(sessions),
+        "total_messages": sum(s["message_count"] for s in sessions),
+        "total_tool_uses": sum(s["tool_use_count"] for s in sessions),
+        "sessions": sessions
+    }
+
+    output_dir = Path.home() / "claude" / "operations" / "deep-sleep"
+    output_dir.mkdir(parents=True, exist_ok=True)
+    output_file = output_dir / f"{output['date']}-transcripts.json"
+    with open(output_file, "w") as f:
+        json.dump(output, f, indent=2, ensure_ascii=False)
+
+    print(f"Collected {len(sessions)} sessions, {output['total_messages']} messages, {output['total_tool_uses']} tool uses")
+    print(f"Output: {output_file}")
+
+
+if __name__ == "__main__":
+    main()

package/src/scripts/deep-sleep/prompt.md

@@ -0,0 +1,109 @@
+# Deep Sleep Analyst — Session Transcript Analysis
+
+You are NEXO's overnight analyst. You read the COMPLETE transcripts of today's sessions between Francisco and NEXO, and you find what NEXO missed.
+
+## Your job
+
+NEXO captures feedback, learnings, and corrections during sessions — but it misses things. Your job is to find the gaps by reading what ACTUALLY happened (the transcript), not what NEXO thinks happened (the diary).
+
+## What you analyze
+
+### 1. Uncaptured corrections
+Francisco corrected NEXO but NEXO didn't save a learning or feedback memory.
+Signals: "no", "mal", "eso no es", "por dios", "no ves que", "pero que coño", frustration tone, repeating the same instruction 2+ times, Francisco having to explain something twice.
+
+### 2. Repeated patterns
+The same correction appears multiple times in the day. This is a SYSTEMIC failure — it needs a strong learning with high severity.
+
+### 3. Uncaptured ideas
+Francisco mentioned an idea, plan, or intention that nobody formalized. Signals: "podríamos", "habría que", "molaría", "quiero", "necesito".
+
+### 4. Missed commitments
+Francisco said "lo miro mañana", "esta semana", "cuando pueda" — was a followup created? If not, flag it.
+
+### 5. Protocol compliance (from tool_uses)
+Check if NEXO followed its own protocols:
+- `nexo_guard_check` before Edit/Write on production files?
+- `nexo_heartbeat` called with meaningful context_hint?
+- `nexo_cognitive_trust` called after corrections?
+- `nexo_learning_add` called after resolving errors?
+- `nexo_followup_complete` called when Francisco said "ya está"/"hecho"?
+- `nexo_change_log` called after production code changes?
+- Feedback memory saved after corrections?
+
+### 6. Quality assessment
+- Did NEXO declare "perfecto"/"completado" and Francisco had to correct after?
+- Was NEXO too verbose when Francisco wanted action?
+- Did NEXO delegate to subagents when it should have done the work directly?
+
+## Output format
+
+Return ONLY valid JSON:
+
+```json
+{
+  "date": "YYYY-MM-DD",
+  "sessions_analyzed": 5,
+  "uncaptured_corrections": [
+    {
+      "quote": "Francisco's exact words (max 100 chars)",
+      "context": "What they were working on",
+      "what_nexo_should_have_saved": "The learning/feedback content",
+      "action": "learning_add|feedback_write|preference_set",
+      "category": "ui|code|process|communication",
+      "severity": "low|medium|high|critical",
+      "times_repeated": 1
+    }
+  ],
+  "uncaptured_ideas": [
+    {
+      "quote": "Francisco's words",
+      "idea": "What the idea is",
+      "action": "reminder_create|followup_create",
+      "suggested_date": "YYYY-MM-DD or null"
+    }
+  ],
+  "missed_commitments": [
+    {
+      "quote": "Francisco's words",
+      "commitment": "What was promised",
+      "action": "followup_create",
+      "due_date": "YYYY-MM-DD"
+    }
+  ],
+  "protocol_compliance": {
+    "guard_check": {"required": 0, "executed": 0, "rate": 1.0},
+    "heartbeat_quality": {"total": 0, "with_good_context": 0, "rate": 1.0},
+    "trust_adjustments": {"corrections_detected": 0, "adjusted": 0, "rate": 1.0},
+    "learning_capture": {"errors_resolved": 0, "captured": 0, "rate": 1.0},
+    "change_log": {"production_edits": 0, "logged": 0, "rate": 1.0},
+    "feedback_capture": {"corrections": 0, "captured": 0, "rate": 1.0},
+    "overall_compliance": 1.0
+  },
+  "protocol_violations": [
+    {
+      "protocol": "guard_check|trust_adjustment|feedback_capture|...",
+      "context": "What happened",
+      "severity": "low|medium|high|critical"
+    }
+  ],
+  "quality_issues": [
+    {
+      "issue": "Description of quality problem",
+      "example": "Specific instance",
+      "severity": "low|medium|high"
+    }
+  ],
+  "auto_reinforcements": [
+    "Specific rule to add or reinforce in CLAUDE.md or guard"
+  ],
+  "summary": "2-3 sentence overall assessment of the day"
+}
+```
+
+## Rules
+- Be SPECIFIC. Quote Francisco's exact words.
+- Only flag REAL issues. If NEXO did capture something correctly, don't flag it.
+- severity=critical means Francisco repeated the same correction 3+ times or expressed strong frustration
+- For protocol compliance, count ACTUAL tool_use entries in the transcript
+- If no issues found in a category, return empty array — don't invent problems

package/src/scripts/nexo-deep-sleep.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+# NEXO Deep Sleep — Complete overnight session transcript analysis
+# Reads ALL Claude Code session transcripts from the day, analyzes with
+# Claude CLI (bare mode), and applies findings as feedback memories.
+#
+# Features:
+# - Catch-up: if yesterday was missed (Mac off/asleep), runs it first
+# - Uses --bare mode to avoid loading NEXO hooks during analysis
+# - Requires ANTHROPIC_API_KEY env var or ~/.claude/anthropic-api-key.txt
+#
+# Install: Add as LaunchAgent for daily execution (recommended: 4:30 AM)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+LOG_DIR="$HOME/claude/logs"
+DEEP_SLEEP_DIR="$HOME/claude/operations/deep-sleep"
+LAST_RUN_FILE="$DEEP_SLEEP_DIR/.last-run"
+TODAY=$(date +%Y-%m-%d)
+
+mkdir -p "$LOG_DIR" "$DEEP_SLEEP_DIR"
+
+log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" | tee -a "$LOG_DIR/deep-sleep.log"; }
+
+run_analysis() {
+    local DATE="$1"
+    log "=== Deep Sleep starting for $DATE ==="
+
+    log "Step 1: Collecting transcripts for $DATE..."
+    python3 "$SCRIPT_DIR/deep-sleep/collect_transcripts.py" "$DATE" 2>&1 | tee -a "$LOG_DIR/deep-sleep.log"
+
+    if [ ! -f "$DEEP_SLEEP_DIR/$DATE-transcripts.json" ]; then
+        log "No transcripts file generated for $DATE. Skipping."
+        return 0
+    fi
+
+    SESSIONS=$(python3 -c "import json; print(json.load(open('$DEEP_SLEEP_DIR/$DATE-transcripts.json'))['sessions_found'])")
+    if [ "$SESSIONS" -eq 0 ]; then
+        log "No sessions found for $DATE. Skipping."
+        return 0
+    fi
+
+    log "Step 2: Analyzing $SESSIONS sessions with Claude CLI..."
+    python3 "$SCRIPT_DIR/deep-sleep/analyze_session.py" "$DATE" 2>&1 | tee -a "$LOG_DIR/deep-sleep.log"
+
+    if [ ! -f "$DEEP_SLEEP_DIR/$DATE-analysis.json" ]; then
+        log "Analysis failed for $DATE. No output generated."
+        return 1
+    fi
+
+    log "Step 3: Applying findings for $DATE..."
+    python3 "$SCRIPT_DIR/deep-sleep/apply_findings.py" "$DATE" 2>&1 | tee -a "$LOG_DIR/deep-sleep.log"
+
+    log "=== Deep Sleep complete for $DATE ==="
+    return 0
+}
+
+# --- Catch-up: check if yesterday was missed ---
+YESTERDAY=$(date -v-1d +%Y-%m-%d 2>/dev/null || date -d "yesterday" +%Y-%m-%d 2>/dev/null)
+LAST_RUN=""
+if [ -f "$LAST_RUN_FILE" ]; then
+    LAST_RUN=$(cat "$LAST_RUN_FILE")
+fi
+
+if [ -n "$YESTERDAY" ] && [ "$LAST_RUN" != "$YESTERDAY" ] && [ "$LAST_RUN" != "$TODAY" ]; then
+    if [ ! -f "$DEEP_SLEEP_DIR/$YESTERDAY-analysis.json" ]; then
+        log "*** CATCH-UP: $YESTERDAY was missed. Running now. ***"
+        run_analysis "$YESTERDAY" || log "Catch-up for $YESTERDAY failed."
+    fi
+fi
+
+# --- Run today's analysis ---
+run_analysis "$TODAY"
+
+# Mark completion
+echo "$TODAY" > "$LAST_RUN_FILE"

package/src/scripts/nexo-watchdog.sh

@@ -139,6 +139,80 @@ try_repair_cron() {
   return 1
 }
 
+try_reexecute_missed_cron() {
+  # Re-execute a cron that missed its scheduled run
+  local plist_id="$1"
+  local plist_file="$HOME_DIR/Library/LaunchAgents/${plist_id}.plist"
+
+  if [ ! -f "$plist_file" ]; then
+    return 1
+  fi
+
+  local cmd
+  cmd=$(python3 -c "
+import plistlib, sys
+try:
+    with open('$plist_file', 'rb') as f:
+        d = plistlib.load(f)
+    if d.get('KeepAlive'):
+        sys.exit(1)
+    if not d.get('StartCalendarInterval') and not d.get('StartInterval'):
+        sys.exit(1)
+    print(' '.join(d.get('ProgramArguments', [])))
+except:
+    sys.exit(1)
+" 2>/dev/null)
+
+  if [ -z "$cmd" ] || [ $? -ne 0 ]; then
+    return 1
+  fi
+
+  log "Re-executing missed cron: $plist_id"
+  timeout 300 bash -c "$cmd" >> "$LOG_DIR/watchdog-reexec.log" 2>&1 &
+  local pid=$!
+  sleep 2
+  if kill -0 "$pid" 2>/dev/null || wait "$pid" 2>/dev/null; then
+    log_repair "$plist_id: re-executed missed cron (PID $pid)"
+    return 0
+  fi
+  return 1
+}
+
+try_verify_repair() {
+  # After Level 2 repair, verify the service is healthy
+  local plist_id="$1"
+  local log_stdout="$2"
+  local proc_grep="$3"
+  local max_wait=30
+
+  if ! is_loaded "$plist_id"; then
+    return 1
+  fi
+
+  if [ -n "$proc_grep" ]; then
+    local waited=0
+    while [ $waited -lt $max_wait ]; do
+      if process_running "$proc_grep"; then
+        log "Verify OK: $plist_id process running after ${waited}s"
+        return 0
+      fi
+      sleep 5
+      waited=$((waited + 5))
+    done
+    return 1
+  fi
+
+  if [ -n "$log_stdout" ] && [ -f "$log_stdout" ]; then
+    local age
+    age=$(file_age "$log_stdout")
+    if [ "$age" -lt 300 ]; then
+      return 0
+    fi
+  fi
+
+  return 0
+}
+
 try_repair_backup() {
   local backup_script="$NEXO_DIR/backup_cron.sh"
   if [ -x "$backup_script" ]; then
@@ -263,13 +337,19 @@ for monitor in "${MONITORS[@]}"; do
     fi
   fi
 
-  # Check 3: Log staleness
+  # Check 3: Log staleness + AUTO RE-EXECUTE missed crons
   if [ -n "$log_stdout" ] && [ "$max_stale" -gt 0 ]; then
     age=$(file_age "$log_stdout")
     stale_age=$(format_age "$age")
     if [ "$age" -gt $(( max_stale * 3 )) ]; then
-      status="FAIL"
-      details="${details}Log stale: $stale_age (limit: $(format_age "$max_stale")). "
+      if try_reexecute_missed_cron "$plist_id"; then
+        status="HEALED"
+        details="${details}Self-healed: re-executed missed cron (was stale: $stale_age). "
+        TOTAL_HEALED=$((TOTAL_HEALED + 1))
+      else
+        status="FAIL"
+        details="${details}Log stale: $stale_age (limit: $(format_age "$max_stale")). Re-execute failed. "
+      fi
     elif [ "$age" -gt "$max_stale" ]; then
       [ "$status" = "PASS" ] && status="WARN"
       details="${details}Log slightly stale: $stale_age. "