nexo-brain 0.10.0-beta.8 → 1.0.0

package/README.md

@@ -1,12 +1,12 @@
 # NEXO Brain — Your AI Gets a Brain
 
-[![npm v0.10.0-beta.8](https://img.shields.io/npm/v/nexo-brain?label=npm&color=purple)](https://www.npmjs.com/package/nexo-brain)
+[![npm v1.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.8** — 30 Core System Rules (versioned, with migration). Battle-tested behavioral rules from 6 months production use, validated via multi-AI debate (Claude + GPT-4o). 6 categories: Integrity, Execution, Memory, Delegation, Communication, Proactivity. 25 BLOCKING + 5 ADVISORY. Plus: Smart Startup, Context Packets, Auto-Prime, and zero-decay pinning.
+> **v1.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.8",
+  "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/plugins/cortex.py

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

package/src/rules/core-rules.json

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

package/templates/CLAUDE.md.template

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