nexo-brain 1.2.3 → 1.4.0

package/README.md

@@ -1,12 +1,12 @@
 # NEXO Brain — Your AI Gets a Brain
 
-[![npm v1.2.1](https://img.shields.io/npm/v/nexo-brain?label=npm&color=purple)](https://www.npmjs.com/package/nexo-brain)
+[![npm](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: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 
-> **v1.1.1** — 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).
+> The first AI memory system with architectural inhibitory control — the agent reasons about whether to act before acting. Cognitive Cortex, Context Continuity via auto-compaction hooks, Smart Startup, Context Packets, Auto-Prime, and 30 Core Rules as DNA. Battle-tested from 6 months of production use, validated via multi-AI debate.
 
 **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,7 +136,7 @@ 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)
+## Cognitive Cortex
 
 The Cortex is a middleware cognitive layer that makes the agent **think before acting**. It implements architectural inhibitory control — the agent cannot bypass reasoning.
 
@@ -163,7 +163,7 @@ 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.1)
+## Context Continuity (Auto-Compaction)
 
 NEXO Brain automatically preserves session context when Claude Code compacts conversations. Using PreCompact and PostCompact hooks:
 
@@ -399,7 +399,12 @@ The installer creates a shell alias with your chosen name. Just type it:
 atlas
 ```
 
-That's it. No need to run `claude` manually. Atlas will greet you immediately — adapted to the time of day, resuming from where you left off if there's a previous session. No cold starts, no waiting for your input.
+Under the hood, the alias runs:
+```bash
+claude --system-prompt "Start NEXO session. Run nexo_startup, load context, greet the user."
+```
+
+That's it. No need to run `claude` manually. Your operator will greet you immediately — adapted to the time of day, resuming from where you left off if there's a previous session. No cold starts, no waiting for your input.
 
 ### What Gets Installed
 

package/package.json

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

package/src/cognitive.py

@@ -1857,6 +1857,51 @@ def gc_stm():
     return (cur1.rowcount or 0) + (cur2.rowcount or 0)
 
 
+def gc_test_memories() -> int:
+    """Purge STM memories from test/dev sessions that pollute strength metrics.
+    Removes memories with test domains or known test content patterns.
+    Returns count of deleted memories.
+    """
+    db = _get_db()
+    test_domains = ("test", "test_session")
+    deleted = 0
+
+    # 1. Delete by test domain
+    for domain in test_domains:
+        cur = db.execute(
+            "DELETE FROM stm_memories WHERE domain = ? "
+            "AND (lifecycle_state IS NULL OR lifecycle_state != 'pinned')",
+            (domain,)
+        )
+        deleted += cur.rowcount or 0
+
+    # 2. Delete known test content patterns (empty domain, test-like content)
+    test_patterns = [
+        "%Secret redact test%",
+        "%quarantine test fact%",
+        "%Pin test memory%",
+        "%API rate limit%AM10%",
+        "%xyzzy server%",
+        "%Quantum entanglement enables FTL%",
+        "%Install Docker%AM10%",
+        "%normal safe content about coding%",
+        "%test diary%",
+        "%test critique%",
+        "%integration test diary%",
+    ]
+    for pattern in test_patterns:
+        cur = db.execute(
+            "DELETE FROM stm_memories WHERE content LIKE ? "
+            "AND (lifecycle_state IS NULL OR lifecycle_state != 'pinned')",
+            (pattern,)
+        )
+        deleted += cur.rowcount or 0
+
+    if deleted > 0:
+        db.commit()
+    return deleted
+
+
 def ingest_sensory(
     content: str,
     source_id: str = "",

package/src/evolution_cycle.py

@@ -0,0 +1,266 @@
+"""NEXO Evolution Cycle — Self-improvement via Opus API.
+
+Runs weekly after DMN. Analyzes patterns, proposes improvements.
+v1: observe-only (all proposals logged as 'proposed' for the owner to review).
+v1.1 (future): sandbox execution of auto-approved changes.
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import sqlite3
+import time
+from datetime import datetime, date, timedelta
+from pathlib import Path
+
+NEXO_DB = Path.home() / "claude" / "nexo-mcp" / "nexo.db"
+CORTEX_DIR = Path(__file__).parent
+CLAUDE_DIR = Path.home() / "claude"
+SANDBOX_DIR = CLAUDE_DIR / "sandbox" / "workspace"
+SNAPSHOTS_DIR = CLAUDE_DIR / "snapshots"
+OBJECTIVE_FILE = CORTEX_DIR / "evolution-objective.json"
+PROMPT_FILE = CORTEX_DIR / "evolution-prompt.md"
+RESTORE_LOG = CLAUDE_DIR / "logs" / "snapshot-restores.log"
+
+MAX_SNAPSHOTS = 8
+
+
+def load_objective() -> dict:
+    if OBJECTIVE_FILE.exists():
+        return json.loads(OBJECTIVE_FILE.read_text())
+    return {}
+
+
+def save_objective(obj: dict):
+    OBJECTIVE_FILE.write_text(json.dumps(obj, indent=2, ensure_ascii=False))
+
+
+def get_week_data(db_path: str) -> dict:
+    """Gather last 7 days of learnings, decisions, changes, diaries."""
+    conn = sqlite3.connect(db_path, timeout=10)
+    conn.row_factory = sqlite3.Row
+    cutoff_epoch = time.time() - 7 * 86400
+    cutoff_date = (date.today() - timedelta(days=7)).isoformat()
+
+    data = {}
+
+    rows = conn.execute(
+        "SELECT category, title, content FROM learnings WHERE created_at > ? ORDER BY created_at DESC LIMIT 50",
+        (cutoff_epoch,)
+    ).fetchall()
+    data["learnings"] = [dict(r) for r in rows]
+
+    rows = conn.execute(
+        "SELECT domain, decision, alternatives, based_on, confidence, outcome FROM decisions "
+        "WHERE created_at > ? ORDER BY created_at DESC LIMIT 20",
+        (cutoff_date,)
+    ).fetchall()
+    data["decisions"] = [dict(r) for r in rows]
+
+    rows = conn.execute(
+        "SELECT files, what_changed, why, affects, risks FROM change_log "
+        "WHERE created_at > ? ORDER BY created_at DESC LIMIT 30",
+        (cutoff_date,)
+    ).fetchall()
+    data["changes"] = [dict(r) for r in rows]
+
+    rows = conn.execute(
+        "SELECT summary, decisions as diary_decisions, pending, mental_state, domain, user_signals "
+        "FROM session_diary WHERE created_at > ? ORDER BY created_at DESC LIMIT 20",
+        (cutoff_date,)
+    ).fetchall()
+    data["diaries"] = [dict(r) for r in rows]
+
+    rows = conn.execute(
+        "SELECT * FROM evolution_log ORDER BY id DESC LIMIT 20"
+    ).fetchall()
+    data["evolution_history"] = [dict(r) for r in rows]
+
+    rows = conn.execute(
+        "SELECT dimension, score, delta, measured_at FROM evolution_metrics "
+        "WHERE id IN (SELECT MAX(id) FROM evolution_metrics GROUP BY dimension)"
+    ).fetchall()
+    data["current_metrics"] = {r["dimension"]: dict(r) for r in rows}
+
+    conn.close()
+    return data
+
+
+def create_snapshot(files_to_backup: list) -> str:
+    """Create a snapshot of specific files before modification."""
+    ts = datetime.now().strftime("%Y-%m-%dT%H:%M")
+    snap_dir = SNAPSHOTS_DIR / ts
+    files_dir = snap_dir / "files"
+
+    manifest = {
+        "created_at": datetime.now().isoformat(),
+        "files": [],
+        "reason": "evolution_cycle"
+    }
+
+    for filepath in files_to_backup:
+        fp = Path(filepath).expanduser()
+        if fp.exists():
+            rel = str(fp).replace(str(Path.home()) + "/", "")
+            dest = files_dir / rel
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(fp, dest)
+            manifest["files"].append(rel)
+
+    snap_dir.mkdir(parents=True, exist_ok=True)
+    (snap_dir / "manifest.json").write_text(json.dumps(manifest, indent=2))
+
+    latest = SNAPSHOTS_DIR / "latest"
+    if latest.is_symlink():
+        latest.unlink()
+    latest.symlink_to(snap_dir)
+
+    _cleanup_snapshots()
+    return str(snap_dir)
+
+
+def _cleanup_snapshots():
+    """Remove old snapshots, keeping MAX_SNAPSHOTS most recent + golden."""
+    if not SNAPSHOTS_DIR.exists():
+        return
+    snaps = sorted(
+        [d for d in SNAPSHOTS_DIR.iterdir()
+         if d.is_dir() and d.name not in ("latest", "golden")],
+        key=lambda d: d.stat().st_mtime,
+        reverse=True
+    )
+    for old in snaps[MAX_SNAPSHOTS:]:
+        shutil.rmtree(old)
+
+
+def dry_run_restore_test() -> bool:
+    """Test that snapshot+restore works before making real changes."""
+    test_file = SANDBOX_DIR / "restore-test.txt"
+    test_file.parent.mkdir(parents=True, exist_ok=True)
+    test_file.write_text("original_content")
+
+    snap_dir = create_snapshot([str(test_file)])
+
+    test_file.write_text("modified_content")
+
+    try:
+        subprocess.run(
+            [str(CLAUDE_DIR / "scripts" / "nexo-snapshot-restore.sh"), snap_dir],
+            capture_output=True, timeout=10, check=True
+        )
+        content = test_file.read_text()
+        test_file.unlink(missing_ok=True)
+        # Clean up test snapshot
+        snap_path = Path(snap_dir)
+        if snap_path.exists():
+            shutil.rmtree(snap_path)
+        return content == "original_content"
+    except Exception:
+        test_file.unlink(missing_ok=True)
+        return False
+
+
+def build_evolution_prompt(week_data: dict, objective: dict) -> str:
+    """Build the prompt for the Opus Evolution cycle."""
+    if PROMPT_FILE.exists():
+        template = PROMPT_FILE.read_text()
+    else:
+        template = "You are NEXO Evolution. Analyze the data and propose improvements."
+
+    prompt = template + "\n\n## WEEKLY DATA\n\n"
+    prompt += f"### Learnings ({len(week_data.get('learnings', []))} this week)\n"
+    for l in week_data.get("learnings", [])[:30]:
+        prompt += f"- [{l['category']}] {l['title']}: {str(l['content'])[:150]}\n"
+
+    prompt += f"\n### Decisions ({len(week_data.get('decisions', []))} this week)\n"
+    for d in week_data.get("decisions", [])[:15]:
+        outcome = f" → {str(d['outcome'])[:80]}" if d.get("outcome") else " → no outcome yet"
+        prompt += f"- [{d['domain']}] {str(d['decision'])[:150]}{outcome}\n"
+
+    prompt += f"\n### Changes ({len(week_data.get('changes', []))} this week)\n"
+    for c in week_data.get("changes", [])[:20]:
+        prompt += f"- {str(c['files'])[:60]}: {str(c['what_changed'])[:100]}\n"
+
+    prompt += f"\n### Session Diaries ({len(week_data.get('diaries', []))} this week)\n"
+    for s in week_data.get("diaries", [])[:10]:
+        prompt += f"- [{s.get('domain','')}] {str(s['summary'])[:150]}\n"
+        if s.get("user_signals"):
+            prompt += f"  the owner: {str(s['user_signals'])[:100]}\n"
+
+    prompt += "\n### Current Dimension Scores\n"
+    for dim, m in week_data.get("current_metrics", {}).items():
+        prompt += f"- {dim}: {m['score']}% (delta: {m.get('delta', 0)})\n"
+
+    prompt += f"\n### Evolution History ({len(week_data.get('evolution_history', []))} entries)\n"
+    for h in week_data.get("evolution_history", [])[:10]:
+        prompt += f"- #{h['id']} [{h['status']}] {str(h['proposal'])[:100]}\n"
+
+    prompt += f"\n### Objective\n{json.dumps(objective, indent=2)}\n"
+
+    # Guard stats — error prevention effectiveness
+    try:
+        guard_conn = sqlite3.connect(str(NEXO_DB), timeout=10)
+        cutoff_7d = (date.today() - timedelta(days=7)).isoformat()
+        cutoff_epoch_7d = time.time() - 7 * 86400
+
+        total_reps = guard_conn.execute(
+            "SELECT COUNT(*) FROM error_repetitions WHERE created_at > ?", (cutoff_7d,)
+        ).fetchone()[0]
+        new_learnings_7d = guard_conn.execute(
+            "SELECT COUNT(*) FROM learnings WHERE created_at > ?", (cutoff_epoch_7d,)
+        ).fetchone()[0]
+        rep_rate = round(total_reps / new_learnings_7d, 2) if new_learnings_7d > 0 else 0.0
+        guard_checks = guard_conn.execute(
+            "SELECT COUNT(*) FROM guard_checks WHERE created_at > ?", (cutoff_7d,)
+        ).fetchone()[0]
+
+        top_areas = guard_conn.execute(
+            "SELECT area, COUNT(*) as cnt FROM error_repetitions WHERE created_at > ? GROUP BY area ORDER BY cnt DESC LIMIT 5",
+            (cutoff_7d,)
+        ).fetchall()
+
+        most_ignored = guard_conn.execute(
+            "SELECT original_learning_id, COUNT(*) as cnt FROM error_repetitions "
+            "GROUP BY original_learning_id HAVING cnt >= 3 ORDER BY cnt DESC LIMIT 5"
+        ).fetchall()
+
+        guard_conn.close()
+
+        prompt += "\n### Guard Stats (Error Prevention)\n"
+        prompt += f"- Repetition rate: {rep_rate:.0%} (target: <15%)\n"
+        prompt += f"- Guard checks this week: {guard_checks} (target: >5/session)\n"
+        prompt += f"- New learnings: {new_learnings_7d}, Repetitions: {total_reps}\n"
+        if top_areas:
+            prompt += "- Top problem areas: " + ", ".join(f"{r[0]}({r[1]})" for r in top_areas) + "\n"
+        if most_ignored:
+            prompt += "- Most ignored learnings (3+ repeats): " + ", ".join(f"#{r[0]}({r[1]}x)" for r in most_ignored) + "\n"
+        prompt += "- Propose more aggressive rules for areas with high repetition rate.\n"
+    except Exception:
+        pass
+
+    # Infrastructure inventory — so Opus knows what exists before proposing changes
+    inventory_script = Path.home() / "claude" / "scripts" / "nexo-infra-inventory.sh"
+    if inventory_script.exists():
+        try:
+            result = subprocess.run(
+                ["bash", str(inventory_script)],
+                capture_output=True, text=True, timeout=10
+            )
+            if result.stdout.strip():
+                prompt += f"\n### Infrastructure Inventory (hooks, scripts, memory, crons)\n"
+                prompt += "Before proposing any change, check this inventory to avoid duplicating existing infrastructure.\n"
+                prompt += f"```json\n{result.stdout.strip()}\n```\n"
+        except Exception:
+            pass
+
+    return prompt
+
+
+def max_auto_changes(total_evolutions: int) -> int:
+    """Progressive trust: 1 for first 4 cycles, 2 for next 4, then 3."""
+    if total_evolutions < 4:
+        return 1
+    elif total_evolutions < 8:
+        return 2
+    return 3

package/src/plugins/guard.py

@@ -6,7 +6,7 @@ and provides stats on error prevention effectiveness.
 import json
 import os
 from datetime import datetime, timedelta
-from db import get_db, find_similar_learnings, extract_keywords
+from db import get_db, find_similar_learnings, extract_keywords, search_learnings, search_changes
 
 
 
@@ -451,10 +451,244 @@ def handle_somatic_stats() -> str:
         return "Error: {}".format(e)
 
 
+def handle_guard_cross_check(findings: list, area: str = "") -> str:
+    """Cross-check audit findings against known learnings to filter false positives.
+
+    Args:
+        findings: List of audit finding strings to cross-check
+        area: System area to narrow the learning search (wazion, shopify, etc.)
+    """
+    # Common English/Spanish stopwords to skip during keyword extraction
+    STOPWORDS = {
+        "the", "a", "an", "is", "in", "on", "at", "to", "of", "and", "or", "but",
+        "for", "with", "that", "this", "it", "as", "are", "was", "be", "by", "not",
+        "has", "have", "from", "which", "when", "if", "then", "do", "does", "can",
+        "el", "la", "los", "las", "un", "una", "en", "de", "del", "al", "y", "o",
+        "que", "se", "no", "es", "por", "con", "su", "pero", "como", "para",
+        "este", "esta", "esto", "son", "hay", "más", "ya",
+    }
+
+    new_issues = []
+    known_issues = []
+
+    for finding in findings:
+        if not finding or not finding.strip():
+            continue
+
+        # Extract significant keywords from the finding text
+        words = finding.lower().split()
+        keywords = [
+            w.strip(".,;:!?\"'()[]{}") for w in words
+            if len(w) >= 4 and w.lower() not in STOPWORDS
+        ]
+        # Use up to 5 most distinctive keywords to build the search query
+        query_keywords = keywords[:5]
+
+        matched_learnings = []
+        if query_keywords:
+            query = " ".join(query_keywords)
+            try:
+                results = search_learnings(query, category=area if area else None)
+                if not results and area:
+                    # Retry without category filter if area-filtered search returns nothing
+                    results = search_learnings(query)
+                matched_learnings = results[:3]  # Top 3 matches per finding
+            except Exception:
+                pass
+
+        if matched_learnings:
+            refs = [
+                {"id": r["id"], "title": r["title"], "category": r.get("category", "")}
+                for r in matched_learnings
+            ]
+            known_issues.append({
+                "finding": finding,
+                "status": "known",
+                "learning_refs": refs,
+            })
+        else:
+            new_issues.append({
+                "finding": finding,
+                "status": "new",
+            })
+
+    # Build output
+    lines = [
+        f"CROSS-CHECK RESULTS: {len(findings)} findings — "
+        f"{len(new_issues)} new, {len(known_issues)} already documented",
+        "",
+    ]
+
+    if new_issues:
+        lines.append(f"NEW ISSUES ({len(new_issues)}) — not in learnings, investigate:")
+        for i, item in enumerate(new_issues, 1):
+            lines.append(f"  {i}. {item['finding']}")
+        lines.append("")
+
+    if known_issues:
+        lines.append(f"KNOWN ISSUES ({len(known_issues)}) — covered by existing learnings:")
+        for i, item in enumerate(known_issues, 1):
+            refs_str = ", ".join(
+                f"#{r['id']} [{r['category']}] {r['title'][:60]}"
+                for r in item["learning_refs"]
+            )
+            lines.append(f"  {i}. {item['finding']}")
+            lines.append(f"     -> {refs_str}")
+        lines.append("")
+
+    summary = {
+        "total": len(findings),
+        "new_count": len(new_issues),
+        "known_count": len(known_issues),
+        "new_issues": [i["finding"] for i in new_issues],
+        "known_issues": [
+            {"finding": i["finding"], "refs": i["learning_refs"]}
+            for i in known_issues
+        ],
+    }
+    lines.append(f"SUMMARY JSON: {json.dumps(summary)}")
+
+    return "\n".join(lines)
+
+
+def handle_guard_file_check(files: list) -> str:
+    """Pre-edit check: surfaces learnings and recent changes for files about to be modified.
+
+    Args:
+        files: List of file paths about to be edited
+    """
+    from pathlib import Path
+    import re
+
+    BLOCKING_KEYWORDS = re.compile(
+        r'\bNUNCA\b|\bNEVER\b|\bPROHIBIDO\b|\bFORBIDDEN\b|\bBLOCKING\b',
+        re.IGNORECASE
+    )
+
+    if not files:
+        return "ERROR: No files provided."
+
+    file_learnings: dict = {}
+    recent_changes: dict = {}
+    warnings: list = []
+    seen_learning_ids: set = set()
+
+    for filepath in files:
+        p = Path(filepath)
+        filename = p.name
+        parent_dir = p.parent.name
+        stem = p.stem  # filename without extension
+
+        # Build search keywords: filename, stem, parent directory (deduplicated)
+        keywords = [kw for kw in [filename, stem, parent_dir] if kw and kw not in (".", "")]
+        seen_kw: set = set()
+        unique_keywords = []
+        for kw in keywords:
+            if kw not in seen_kw:
+                seen_kw.add(kw)
+                unique_keywords.append(kw)
+
+        file_results = []
+        file_seen_ids: set = set()
+
+        for keyword in unique_keywords:
+            try:
+                rows = search_learnings(keyword)
+                for r in rows:
+                    lid = r.get("id")
+                    if lid and lid not in seen_learning_ids and lid not in file_seen_ids:
+                        file_seen_ids.add(lid)
+                        seen_learning_ids.add(lid)
+                        entry = {
+                            "id": lid,
+                            "category": r.get("category", ""),
+                            "title": r.get("title", ""),
+                            "content": (r.get("content") or "")[:300],
+                        }
+                        file_results.append(entry)
+                        # Flag blocking learnings
+                        if BLOCKING_KEYWORDS.search(r.get("title", "")) or \
+                                BLOCKING_KEYWORDS.search(r.get("content") or ""):
+                            warnings.append(
+                                f"[BLOCKING] #{lid} ({filepath}): {r.get('title', '')}"
+                            )
+            except Exception:
+                pass
+
+        file_learnings[filepath] = file_results
+
+        # Search recent changes (last 7 days) for this file by filename/stem
+        file_changes = []
+        for keyword in unique_keywords[:2]:  # filename + stem are most specific
+            try:
+                changes = search_changes(files=keyword, days=7)
+                for c in changes:
+                    cid = c.get("id")
+                    if cid and not any(fc.get("id") == cid for fc in file_changes):
+                        file_changes.append({
+                            "id": cid,
+                            "files": c.get("files", ""),
+                            "what_changed": (c.get("what_changed") or "")[:200],
+                            "why": (c.get("why") or "")[:150],
+                            "created_at": (c.get("created_at") or "")[:16],
+                        })
+            except Exception:
+                pass
+
+        recent_changes[filepath] = file_changes
+
+    # Build summary line
+    total_learnings = sum(len(v) for v in file_learnings.values())
+    total_changes = sum(len(v) for v in recent_changes.values())
+    summary_parts = []
+    if total_learnings:
+        summary_parts.append(f"{total_learnings} learning(s) found")
+    if total_changes:
+        summary_parts.append(f"{total_changes} recent change(s) in last 7 days")
+    if warnings:
+        summary_parts.append(f"{len(warnings)} BLOCKING warning(s)")
+    summary = ", ".join(summary_parts) if summary_parts else "No relevant learnings or recent changes found."
+
+    # Format output
+    lines = []
+
+    if warnings:
+        lines.append("WARNINGS — resolve before editing:")
+        for w in warnings:
+            lines.append(f"  {w}")
+        lines.append("")
+
+    for filepath in files:
+        learnings = file_learnings.get(filepath, [])
+        changes = recent_changes.get(filepath, [])
+        if not learnings and not changes:
+            continue
+        lines.append(f"FILE: {filepath}")
+        if learnings:
+            lines.append(f"  Learnings ({len(learnings)}):")
+            for entry in learnings[:10]:
+                lines.append(f"    #{entry['id']} [{entry['category']}] {entry['title']}")
+                if entry["content"]:
+                    lines.append(f"      {entry['content'][:120]}")
+        if changes:
+            lines.append(f"  Recent changes ({len(changes)}, last 7d):")
+            for c in changes[:5]:
+                lines.append(f"    [{c['created_at']}] {c['what_changed'][:100]}")
+                if c["why"]:
+                    lines.append(f"      Why: {c['why'][:80]}")
+        lines.append("")
+
+    lines.append(f"SUMMARY: {summary}")
+
+    return "\n".join(lines) if lines else summary
+
+
 TOOLS = [
     (handle_guard_check, "nexo_guard_check", "Check learnings relevant to files/area BEFORE editing code. Call this before any code change."),
     (handle_guard_stats, "nexo_guard_stats", "Get guard system statistics: repetition rate, trends, top problem areas"),
     (handle_guard_log_repetition, "nexo_guard_log_repetition", "Log a learning repetition (new learning matches existing one)"),
     (handle_somatic_check, "nexo_somatic_check", "View somatic risk scores for files/areas — pain memory"),
     (handle_somatic_stats, "nexo_somatic_stats", "Top 10 riskiest targets + risk distribution"),
+    (handle_guard_cross_check, "nexo_guard_cross_check", "Cross-check audit findings against known learnings to filter false positives"),
+    (handle_guard_file_check, "nexo_guard_file_check", "Pre-edit check: surfaces learnings and recent changes for files about to be modified"),
 ]