nexo-brain 0.10.0-beta.7 → 1.0.0

package/README.md

@@ -1,12 +1,12 @@
 # NEXO Brain — Your AI Gets a Brain
 
-[![npm v0.10.0-beta.7](https://img.shields.io/npm/v/nexo-brain?label=npm&color=purple)](https://www.npmjs.com/package/nexo-brain)
+[![npm v1.0.0](https://img.shields.io/npm/v/nexo-brain?label=npm&color=purple)](https://www.npmjs.com/package/nexo-brain)
 [![F1 0.588 on LoCoMo](https://img.shields.io/badge/LoCoMo_F1-0.588-brightgreen)](https://github.com/wazionapps/nexo/blob/main/benchmarks/locomo/results/)
 [![+55% vs GPT-4](https://img.shields.io/badge/vs_GPT--4-%2B55%25-blue)](https://github.com/snap-research/locomo/issues/33)
 [![GitHub stars](https://img.shields.io/github/stars/wazionapps/nexo?style=social)](https://github.com/wazionapps/nexo/stargazers)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> **v0.10.0-beta.7** — 30 Core System Rules (versioned, with migration). Battle-tested behavioral rules from 6 months production use, validated via multi-AI debate (Claude + GPT-4o). 6 categories: Integrity, Execution, Memory, Delegation, Communication, Proactivity. 25 BLOCKING + 5 ADVISORY. Plus: Smart Startup, Context Packets, Auto-Prime, and zero-decay pinning.
+> **v1.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).
 
 **NEXO Brain transforms any MCP-compatible AI agent from a stateless assistant into a cognitive partner that remembers, learns, forgets, adapts, and builds a relationship with you over time.**
 
@@ -136,9 +136,36 @@ Like a human brain, NEXO Brain has automated processes that run while you're not
 
 If your Mac was asleep during any scheduled process, NEXO Brain catches up in order when it wakes.
 
+## Cognitive Cortex (v1.0.0)
+
+The Cortex is a middleware cognitive layer that makes the agent **think before acting**. It implements architectural inhibitory control — the agent cannot bypass reasoning.
+
+```
+User message → Fast Path check → Simple chat? → Respond directly
+                                → Action needed? → Cortex activates
+                                                    ↓
+                                              Generate cognitive state
+                                              (goal, plan, unknowns, evidence)
+                                                    ↓
+                                              Middleware validates
+                                              ├─ Unknowns? → ASK mode (tools blocked)
+                                              ├─ No plan? → PROPOSE mode (read-only)
+                                              └─ Plan + evidence → ACT mode (full access)
+```
+
+| Feature | What It Does |
+|---------|-------------|
+| **Inhibitory Control** | Physically restricts tools based on reasoning quality. Unknowns → can only ask. No plan → can only propose. Evidence + verification → can act. |
+| **Event-Driven Activation** | Only activates on tool intent, ambiguity, destructive actions, or retries. Simple chat has zero overhead. |
+| **Trust-Gated Escalation** | Low trust score → requires more evidence before allowing "act" mode. Trust builds through successful execution. |
+| **Core Rules Injection** | Automatically surfaces relevant behavioral rules based on task type. |
+| **Activation Metrics** | Tracks modes, inhibition rates, and task types for continuous improvement. |
+
+The Cortex was designed through a 3-way AI debate (Claude Opus 4.6 + GPT-5.4 + Gemini 3.1 Pro) and validated against 6 months of real production failures.
+
 ## Cognitive Features
 
-NEXO Brain provides 27 cognitive tools on top of the 76 base tools, totaling **111+ MCP tools**. These features implement cognitive science concepts that go beyond basic memory:
+NEXO Brain provides 29 cognitive tools on top of the 76 base tools, totaling **113+ MCP tools**. These features implement cognitive science concepts that go beyond basic memory:
 
 ### Input Pipeline
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "nexo-brain",
-  "version": "0.10.0-beta.7",
+  "version": "1.0.0",
   "mcpName": "io.github.wazionapps/nexo",
-  "description": "NEXO — Cognitive co-operator for Claude Code. Atkinson-Shiffrin memory, semantic RAG, trust scoring, and metacognitive error prevention.",
+  "description": "NEXO \u2014 Cognitive co-operator for Claude Code. Atkinson-Shiffrin memory, semantic RAG, trust scoring, and metacognitive error prevention.",
   "bin": {
     "nexo-brain": "./bin/nexo-brain.js"
   },
@@ -32,4 +32,4 @@
     "templates/",
     "scripts/"
   ]
-}
+}

package/src/db.py

@@ -950,6 +950,59 @@ def _m9_maintenance_schedule(conn):
         )
 
 
+def _m11_core_rules(conn):
+    """Core system rules table — versioned behavioral rules with migration support."""
+    conn.executescript("""
+        CREATE TABLE IF NOT EXISTS core_rules (
+            id TEXT PRIMARY KEY,
+            category TEXT NOT NULL,
+            rule TEXT NOT NULL,
+            why TEXT NOT NULL,
+            importance INTEGER NOT NULL DEFAULT 4,
+            type TEXT NOT NULL DEFAULT 'advisory' CHECK(type IN ('blocking', 'advisory')),
+            added_in TEXT NOT NULL DEFAULT '1.0.0',
+            removed_in TEXT DEFAULT NULL,
+            is_active INTEGER NOT NULL DEFAULT 1,
+            created_at TEXT DEFAULT (datetime('now'))
+        );
+
+        CREATE TABLE IF NOT EXISTS core_rules_version (
+            id INTEGER PRIMARY KEY CHECK(id = 1),
+            version TEXT NOT NULL DEFAULT '0.0.0',
+            updated_at TEXT DEFAULT (datetime('now'))
+        );
+
+        INSERT OR IGNORE INTO core_rules_version (id, version) VALUES (1, '0.0.0');
+    """)
+    # Seed rules from core-rules.json if available
+    _seed_core_rules(conn)
+
+
+def _seed_core_rules(conn):
+    """Load rules from core-rules.json into the database."""
+    import json
+    rules_file = os.path.join(os.path.dirname(os.path.abspath(__file__)), "rules", "core-rules.json")
+    if not os.path.exists(rules_file):
+        return
+
+    with open(rules_file) as f:
+        data = json.load(f)
+
+    version = data["_meta"]["version"]
+
+    for cat_key, cat in data["categories"].items():
+        for rule in cat["rules"]:
+            conn.execute(
+                """INSERT OR REPLACE INTO core_rules (id, category, rule, why, importance, type, added_in)
+                   VALUES (?, ?, ?, ?, ?, ?, ?)""",
+                (rule["id"], cat_key, rule["rule"], rule["why"],
+                 rule["importance"], rule["type"], rule.get("added_in", version))
+            )
+
+    conn.execute("UPDATE core_rules_version SET version = ?, updated_at = datetime('now') WHERE id = 1", (version,))
+    conn.commit()
+
+
 # Migration registry — APPEND ONLY, never reorder or delete
 MIGRATIONS = [
     (1, "learnings_columns", _m1_learnings_columns),
@@ -962,6 +1015,7 @@ MIGRATIONS = [
     (8, "adaptive_log_and_somatic", _m8_adaptive_log_and_somatic),
     (9, "maintenance_schedule", _m9_maintenance_schedule),
     (10, "diary_archive", _m10_diary_archive),
+    (11, "core_rules", _m11_core_rules),
 ]
 
 

package/src/plugins/core_rules.py

@@ -0,0 +1,231 @@
+"""Core Rules plugin — query and manage versioned behavioral rules."""
+
+import json
+import os
+
+
+def _get_db():
+    from db import get_db
+    return get_db()
+
+
+def _seed_if_empty():
+    """Seed rules from JSON if table is empty (first run after migration)."""
+    conn = _get_db()
+    count = conn.execute("SELECT COUNT(*) FROM core_rules WHERE is_active = 1").fetchone()[0]
+    if count > 0:
+        return
+
+    rules_file = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+                              "rules", "core-rules.json")
+    if not os.path.exists(rules_file):
+        return
+
+    with open(rules_file) as f:
+        data = json.load(f)
+
+    version = data["_meta"]["version"]
+    for cat_key, cat in data["categories"].items():
+        for rule in cat["rules"]:
+            conn.execute(
+                """INSERT OR REPLACE INTO core_rules (id, category, rule, why, importance, type, added_in)
+                   VALUES (?, ?, ?, ?, ?, ?, ?)""",
+                (rule["id"], cat_key, rule["rule"], rule["why"],
+                 rule["importance"], rule["type"], rule.get("added_in", version))
+            )
+
+    conn.execute("UPDATE core_rules_version SET version = ?, updated_at = datetime('now') WHERE id = 1", (version,))
+    conn.commit()
+
+
+def handle_rules_check(area: str = "", importance_min: int = 0) -> str:
+    """Get applicable core rules for a given area or action.
+
+    Returns BLOCKING rules that must be followed and ADVISORY rules as guidance.
+    Call this before taking any significant action.
+
+    Args:
+        area: Area of work — 'code', 'delegation', 'communication', 'memory', or empty for all.
+              Maps to categories: code→execution+integrity, delegation→delegation, etc.
+        importance_min: Minimum importance level (1-5, default 0 = all rules)
+    """
+    _seed_if_empty()
+    conn = _get_db()
+
+    area_to_categories = {
+        "code": ("integrity", "execution"),
+        "edit": ("integrity", "execution"),
+        "delegation": ("delegation",),
+        "delegate": ("delegation",),
+        "subagent": ("delegation",),
+        "communication": ("communication",),
+        "respond": ("communication",),
+        "memory": ("memory",),
+        "learn": ("memory",),
+        "proactivity": ("proactivity",),
+        "protect": ("proactivity",),
+    }
+
+    where = "WHERE is_active = 1"
+    params = []
+
+    if area and area.lower() in area_to_categories:
+        cats = area_to_categories[area.lower()]
+        placeholders = ",".join("?" * len(cats))
+        where += f" AND category IN ({placeholders})"
+        params.extend(cats)
+
+    if importance_min > 0:
+        where += " AND importance >= ?"
+        params.append(importance_min)
+
+    rows = conn.execute(
+        f"SELECT id, category, rule, why, importance, type FROM core_rules {where} ORDER BY importance DESC, category, id",
+        params
+    ).fetchall()
+
+    if not rows:
+        return "No rules found for this area."
+
+    # Get version
+    ver = conn.execute("SELECT version FROM core_rules_version WHERE id = 1").fetchone()
+    version = ver[0] if ver else "unknown"
+
+    blocking = [r for r in rows if r["type"] == "blocking"]
+    advisory = [r for r in rows if r["type"] == "advisory"]
+
+    lines = [f"CORE RULES (v{version}) — {len(blocking)} BLOCKING, {len(advisory)} ADVISORY"]
+    if area:
+        lines[0] += f" [area: {area}]"
+    lines.append("")
+
+    if blocking:
+        lines.append("## BLOCKING (must follow)")
+        for r in blocking:
+            lines.append(f"  {r['id']}. {r['rule']}")
+            lines.append(f"     Why: {r['why']}")
+        lines.append("")
+
+    if advisory:
+        lines.append("## ADVISORY (recommended)")
+        for r in advisory:
+            lines.append(f"  {r['id']}. {r['rule']}")
+            lines.append(f"     Why: {r['why']}")
+
+    return "\n".join(lines)
+
+
+def handle_rules_list() -> str:
+    """List all core rules with their status, grouped by category."""
+    _seed_if_empty()
+    conn = _get_db()
+
+    ver = conn.execute("SELECT version FROM core_rules_version WHERE id = 1").fetchone()
+    version = ver[0] if ver else "unknown"
+
+    rows = conn.execute(
+        "SELECT id, category, rule, importance, type, is_active, added_in, removed_in FROM core_rules ORDER BY category, id"
+    ).fetchall()
+
+    lines = [f"CORE RULES v{version} — {len([r for r in rows if r['is_active']])} active, {len([r for r in rows if not r['is_active']])} removed", ""]
+
+    current_cat = None
+    for r in rows:
+        if r["category"] != current_cat:
+            current_cat = r["category"]
+            lines.append(f"### {current_cat.upper()}")
+
+        status = "✓" if r["is_active"] else "✗"
+        tag = "BLOCK" if r["type"] == "blocking" else "ADVSR"
+        lines.append(f"  [{status}] {r['id']} [{tag}] imp={r['importance']} — {r['rule']}")
+        if r["removed_in"]:
+            lines.append(f"       Removed in v{r['removed_in']}")
+
+    return "\n".join(lines)
+
+
+def handle_rules_migrate(dry_run: bool = False) -> str:
+    """Sync core rules from the JSON definition file to the database.
+
+    Adds new rules, marks removed ones as inactive. Safe to run multiple times.
+
+    Args:
+        dry_run: If True, show what would change without applying
+    """
+    conn = _get_db()
+    rules_file = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+                              "rules", "core-rules.json")
+    if not os.path.exists(rules_file):
+        return "ERROR: core-rules.json not found"
+
+    with open(rules_file) as f:
+        data = json.load(f)
+
+    new_version = data["_meta"]["version"]
+    ver = conn.execute("SELECT version FROM core_rules_version WHERE id = 1").fetchone()
+    current_version = ver[0] if ver else "0.0.0"
+
+    # Collect all rule IDs from JSON
+    json_ids = set()
+    json_rules = {}
+    for cat_key, cat in data["categories"].items():
+        for rule in cat["rules"]:
+            json_ids.add(rule["id"])
+            json_rules[rule["id"]] = {**rule, "category": cat_key}
+
+    # Collect active IDs from DB
+    db_ids = set()
+    for r in conn.execute("SELECT id FROM core_rules WHERE is_active = 1").fetchall():
+        db_ids.add(r[0])
+
+    added = json_ids - db_ids
+    removed = db_ids - json_ids
+    unchanged = json_ids & db_ids
+
+    lines = [
+        f"RULES MIGRATION: v{current_version} → v{new_version}",
+        f"  Added: {len(added)} — {', '.join(sorted(added)) if added else 'none'}",
+        f"  Removed: {len(removed)} — {', '.join(sorted(removed)) if removed else 'none'}",
+        f"  Unchanged: {len(unchanged)}",
+    ]
+
+    if dry_run:
+        lines.append("  Mode: DRY RUN (no changes applied)")
+        return "\n".join(lines)
+
+    # Apply additions
+    for rid in added:
+        r = json_rules[rid]
+        conn.execute(
+            """INSERT OR REPLACE INTO core_rules (id, category, rule, why, importance, type, added_in, is_active)
+               VALUES (?, ?, ?, ?, ?, ?, ?, 1)""",
+            (r["id"], r["category"], r["rule"], r["why"], r["importance"], r["type"], r.get("added_in", new_version))
+        )
+
+    # Apply removals (soft delete)
+    for rid in removed:
+        conn.execute(
+            "UPDATE core_rules SET is_active = 0, removed_in = ? WHERE id = ?",
+            (new_version, rid)
+        )
+
+    # Update existing rules (content might have changed)
+    for rid in unchanged:
+        r = json_rules[rid]
+        conn.execute(
+            "UPDATE core_rules SET rule = ?, why = ?, importance = ?, type = ?, category = ? WHERE id = ?",
+            (r["rule"], r["why"], r["importance"], r["type"], r["category"], rid)
+        )
+
+    conn.execute("UPDATE core_rules_version SET version = ?, updated_at = datetime('now') WHERE id = 1", (new_version,))
+    conn.commit()
+
+    lines.append("  Status: APPLIED")
+    return "\n".join(lines)
+
+
+TOOLS = [
+    (handle_rules_check, "nexo_rules_check", "Get applicable core rules for an area before acting. Returns BLOCKING and ADVISORY rules."),
+    (handle_rules_list, "nexo_rules_list", "List all core rules with status, grouped by category."),
+    (handle_rules_migrate, "nexo_rules_migrate", "Sync rules from JSON definition to database. Adds new, soft-deletes removed."),
+]

package/src/plugins/cortex.py

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