nexo-brain 2.6.18 → 2.6.21

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "2.6.18",
+  "version": "2.6.21",
   "description": "Local cognitive runtime for Claude Code \u2014 persistent memory, overnight learning, doctor diagnostics, personal scripts, recovery-aware jobs, startup preflight, and optional dashboard/power helper.",
   "author": {
     "name": "NEXO Brain",

package/README.md

@@ -38,7 +38,7 @@ That means NEXO now manages not only the shared runtime and MCP wiring, but also
 - For Codex specifically, `nexo chat` and Codex headless automation inject the current bootstrap explicitly, so Codex starts as NEXO even when plain global Codex startup is inconsistent about global instructions.
 - Deep Sleep now reads both Claude Code and Codex transcript stores, so overnight analysis still works even when the user spends the day in Codex.
 
-Version `2.6.14` closes those parity gaps in practice, `2.6.15` hardens the installed-runtime migration path so existing users actually receive the managed bootstrap updates cleanly, `2.6.16` pushes the system further in three directions, `2.6.17` finishes the annoying last-mile migration bugs for real existing installs, and `2.6.18` tightens the remaining practical gaps around manual Codex use, Deep Sleep horizon artifacts, and retrieval honesty:
+Version `2.6.14` closes those parity gaps in practice, `2.6.15` hardens the installed-runtime migration path so existing users actually receive the managed bootstrap updates cleanly, `2.6.16` pushes the system further in three directions, `2.6.17` finishes the annoying last-mile migration bugs for real existing installs, `2.6.18` tightens the remaining practical gaps around manual Codex use, Deep Sleep horizon artifacts, and retrieval honesty, `2.6.20` makes the recommended Claude profile explicit across installer, runtime defaults, existing installs, and the update path itself with `Opus 4.6 with 1M context`, and `2.6.21` upgrades Deep Sleep from passive nightly analysis toward concrete engineering action.
 
 - Codex now gets managed global bootstrap/model sync in `~/.codex/config.toml`, so sessions opened outside `nexo chat` are much less likely to start as plain Codex.
 - Codex config now also persists a managed `mcp_servers.nexo` entry, so the shared brain survives even if ad-hoc Codex MCP state drifts.
@@ -47,6 +47,7 @@ Version `2.6.14` closes those parity gaps in practice, `2.6.15` hardens the inst
 - Retrieval explanations now surface confidence and the auto-strategy that fired, while associative expansion trims itself back to `top_k` instead of leaking low-signal neighbors.
 - Deep Sleep now blends recent context with older context over a 60-day horizon, and memory decay now tracks per-memory `stability` and `difficulty` instead of relying only on global decay constants.
 - Deep Sleep now also carries project-priority weighting into its long-horizon context and writes reusable weekly/monthly summary artifacts instead of reasoning only day by day.
+- Deep Sleep now semantically deduplicates followups, consolidates overlapping learnings, flags contradictory learnings for review, and backfills explicit engineering followups when recurring patterns imply a concrete fix.
 - Existing installs that already had NEXO connected to Codex now backfill that client state automatically during update/sync, so the managed Codex bootstrap actually lands without manual cleanup.
 - Bootstrap docs now fall back to the operator name `NEXO` when local metadata is blank, avoiding broken headings in `CLAUDE.md` and `AGENTS.md`.
 
@@ -645,7 +646,7 @@ nexo scripts list  # See your personal scripts
 During install, NEXO now asks which interactive clients you want to connect, which one `nexo chat` should open by default, whether to enable background automation, which backend should run that automation, and which model profile each active terminal/backend should use. Shared brain stays on in every mode.
 
 Recommended defaults:
-- Claude Code: `Opus latest`
+- Claude Code: `Opus 4.6 with 1M context`
 - Codex: `gpt-5.4` with `xhigh` reasoning
 
 Or use the shell alias created during install (e.g. `atlas`), which now runs `nexo chat .` so it opens whichever terminal client you selected as default.
@@ -662,6 +663,9 @@ NEXO is being hardened in public, and the best contributions now are not only co
 
 The project still recommends Claude Code as the primary path, but contributions that improve Codex, client parity, installer clarity, and ecosystem integrations are especially valuable.
 
+Maintainers and contributors touching startup, bootstrap, Deep Sleep, or shared-brain behavior should also use the client parity checklist:
+- [docs/client-parity-checklist.md](docs/client-parity-checklist.md)
+
 ### What Gets Installed
 
 | Component | What | Where |
@@ -723,7 +727,7 @@ The Doctor system reads existing health artifacts (immune, watchdog, self-audit)
 - **macOS or Linux** (Windows via [WSL](https://learn.microsoft.com/en-us/windows/wsl/install))
 - **Node.js 18+** (for the installer)
 - **Claude Code is the primary recommended client.** It remains the most mature NEXO path: native hooks, the most battle-tested automation contract, and the clearest parity with historical production behavior.
-- **Recommended profiles:** Claude Code + `Opus latest`; Codex + `gpt-5.4` with `xhigh` reasoning if you prefer Codex as your terminal or automation backend.
+- **Recommended profiles:** Claude Code + `Opus 4.6 with 1M context`; Codex + `gpt-5.4` with `xhigh` reasoning if you prefer Codex as your terminal or automation backend.
 - Python 3, Homebrew, and the selected required client/backend can be installed automatically when NEXO has a supported installer path for that dependency.
 
 ## Architecture
@@ -830,7 +834,7 @@ NEXO Brain is designed as an MCP server. Claude Code remains the primary recomme
 npx nexo-brain
 ```
 
-All 150+ tools are available immediately after installation. The installer configures Claude Code's `~/.claude/settings.json` automatically. The recommended Claude profile is `Opus latest`.
+All 150+ tools are available immediately after installation. The installer configures Claude Code's `~/.claude/settings.json` automatically. The recommended Claude profile is `Opus 4.6 with 1M context`.
 
 ### Claude Desktop
 
@@ -920,6 +924,7 @@ If NEXO Brain is useful to you, consider:
 - **[Sponsor on GitHub](https://github.com/sponsors/wazionapps)** — support ongoing development directly
 - **Share your experience** — tell others how you're using cognitive memory in your AI workflows
 - **Contribute** — see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Issues and PRs welcome
+- **Client parity / shared-brain maintenance** — see [docs/client-parity-checklist.md](docs/client-parity-checklist.md)
 
 [![Star History Chart](https://api.star-history.com/svg?repos=wazionapps/nexo&type=Date)](https://star-history.com/#wazionapps/nexo&Date)
 

package/bin/nexo-brain.js

@@ -33,6 +33,10 @@ const LAUNCH_AGENTS = path.join(
 );
 const MACOS_FDA_SETTINGS_URL = "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles";
 const PUBLIC_CONTRIBUTION_UPSTREAM = "wazionapps/nexo";
+const DEFAULT_CLAUDE_CODE_MODEL = "claude-opus-4-6[1m]";
+const DEFAULT_CLAUDE_CODE_REASONING_EFFORT = "";
+const DEFAULT_CODEX_MODEL = "gpt-5.4";
+const DEFAULT_CODEX_REASONING_EFFORT = "xhigh";
 
 function isEphemeralInstall(nexoHome) {
   const homeDir = require("os").homedir();
@@ -480,12 +484,12 @@ function getDefaultSchedule(timezone) {
     automation_backend: "claude_code",
     client_runtime_profiles: {
       claude_code: {
-        model: "opus",
-        reasoning_effort: "",
+        model: DEFAULT_CLAUDE_CODE_MODEL,
+        reasoning_effort: DEFAULT_CLAUDE_CODE_REASONING_EFFORT,
       },
       codex: {
-        model: "gpt-5.4",
-        reasoning_effort: "xhigh",
+        model: DEFAULT_CODEX_MODEL,
+        reasoning_effort: DEFAULT_CODEX_REASONING_EFFORT,
       },
     },
     client_install_preferences: {
@@ -656,12 +660,12 @@ async function askChoice(question, options, defaultValue) {
 function defaultClientRuntimeProfiles() {
   return {
     claude_code: {
-      model: "opus",
-      reasoning_effort: "",
+      model: DEFAULT_CLAUDE_CODE_MODEL,
+      reasoning_effort: DEFAULT_CLAUDE_CODE_REASONING_EFFORT,
     },
     codex: {
-      model: "gpt-5.4",
-      reasoning_effort: "xhigh",
+      model: DEFAULT_CODEX_MODEL,
+      reasoning_effort: DEFAULT_CODEX_REASONING_EFFORT,
     },
   };
 }
@@ -690,10 +694,11 @@ function runtimeProfileCatalog(lang, client) {
       customModelQuestionEn: `  Enter the model alias/name for ${runtimeClientLabel(client)} > `,
       customEffortQuestion: `  Escribe el effort para ${runtimeClientLabel(client)} (vacío = default) > `,
       customEffortQuestionEn: `  Enter the effort for ${runtimeClientLabel(client)} (blank = default) > `,
-      modelDefault: "opus",
+      modelDefault: DEFAULT_CLAUDE_CODE_MODEL,
       effortDefault: "",
       modelOptions: [
-        { value: "opus", label: `Opus latest${recommended}` },
+        { value: DEFAULT_CLAUDE_CODE_MODEL, label: `Opus 4.6 with 1M context${recommended}` },
+        { value: "claude-opus-4-6", label: "Opus 4.6" },
         { value: "sonnet", label: "Sonnet latest" },
         { value: "custom", label: lang === "es" ? "Modelo personalizado" : "Custom model" },
       ],
@@ -715,8 +720,8 @@ function runtimeProfileCatalog(lang, client) {
     customModelQuestionEn: `  Enter the model name for ${runtimeClientLabel(client)} > `,
     customEffortQuestion: `  Escribe el reasoning effort para ${runtimeClientLabel(client)} > `,
     customEffortQuestionEn: `  Enter the reasoning effort for ${runtimeClientLabel(client)} > `,
-    modelDefault: "gpt-5.4",
-    effortDefault: "xhigh",
+    modelDefault: DEFAULT_CODEX_MODEL,
+    effortDefault: DEFAULT_CODEX_REASONING_EFFORT,
     modelOptions: [
       { value: "gpt-5.4", label: `GPT-5.4${recommended}` },
       { value: "gpt-5.4-pro", label: "GPT-5.4 Pro" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "2.6.18",
+  "version": "2.6.21",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO Brain — Shared brain for AI agents. Persistent memory, semantic RAG, natural forgetting, metacognitive guard, trust scoring, 150+ MCP tools. Works with Claude Code, Codex, Claude Desktop & any MCP client. 100% local, free.",
   "homepage": "https://nexo-brain.com",

package/src/agent_runner.py

@@ -229,6 +229,9 @@ def _resolve_runtime_model_and_effort(
     if client == CLIENT_CODEX:
         if not requested_model or requested_model.lower() in CLAUDE_LEGACY_MODEL_HINTS:
             requested_model = profile["model"]
+    elif client == CLIENT_CLAUDE_CODE:
+        if not requested_model or requested_model.lower() in CLAUDE_LEGACY_MODEL_HINTS:
+            requested_model = profile["model"]
     elif not requested_model:
         requested_model = profile["model"]
 

package/src/client_preferences.py

@@ -36,18 +36,10 @@ INSTALL_PREFERENCE_KEYS = {
     "skip",
     "manual",
 }
-DEFAULT_CLIENT_RUNTIME_PROFILES = {
-    CLIENT_CLAUDE_CODE: {
-        "model": "opus",
-        "reasoning_effort": "",
-    },
-    CLIENT_CODEX: {
-        "model": "gpt-5.4",
-        "reasoning_effort": "xhigh",
-    },
-}
-
-
+DEFAULT_CLAUDE_CODE_MODEL = "claude-opus-4-6[1m]"
+DEFAULT_CLAUDE_CODE_REASONING_EFFORT = ""
+DEFAULT_CODEX_MODEL = "gpt-5.4"
+DEFAULT_CODEX_REASONING_EFFORT = "xhigh"
 def _user_home() -> Path:
     return Path(os.environ.get("HOME", str(Path.home()))).expanduser()
 
@@ -225,8 +217,14 @@ def normalize_client_install_preferences(value) -> dict[str, str]:
 
 def default_client_runtime_profiles() -> dict[str, dict[str, str]]:
     return {
-        client_key: dict(profile)
-        for client_key, profile in DEFAULT_CLIENT_RUNTIME_PROFILES.items()
+        CLIENT_CLAUDE_CODE: {
+            "model": DEFAULT_CLAUDE_CODE_MODEL,
+            "reasoning_effort": DEFAULT_CLAUDE_CODE_REASONING_EFFORT,
+        },
+        CLIENT_CODEX: {
+            "model": DEFAULT_CODEX_MODEL,
+            "reasoning_effort": DEFAULT_CODEX_REASONING_EFFORT,
+        },
     }
 
 

package/src/client_sync.py

@@ -55,7 +55,7 @@ except Exception:
 
     def resolve_client_runtime_profile(client: str, preferences: dict | None = None) -> dict:
         defaults = {
-            "claude_code": {"model": "opus", "reasoning_effort": ""},
+            "claude_code": {"model": "claude-opus-4-6[1m]", "reasoning_effort": ""},
             "codex": {"model": "gpt-5.4", "reasoning_effort": "xhigh"},
         }
         return dict(defaults.get(client, {}))

package/src/runtime_power.py

@@ -65,6 +65,10 @@ MACOS_FDA_PROBE_PATHS = (
     Path.home() / "Library" / "Safari",
     Path.home() / "Library" / "Application Support" / "AddressBook",
 )
+DEFAULT_CLAUDE_CODE_MODEL = "claude-opus-4-6[1m]"
+DEFAULT_CLAUDE_CODE_REASONING_EFFORT = ""
+DEFAULT_CODEX_MODEL = "gpt-5.4"
+DEFAULT_CODEX_REASONING_EFFORT = "xhigh"
 
 
 def _schedule_defaults() -> dict:
@@ -81,12 +85,12 @@ def _schedule_defaults() -> dict:
         "automation_backend": "claude_code",
         "client_runtime_profiles": {
             "claude_code": {
-                "model": "opus",
-                "reasoning_effort": "",
+                "model": DEFAULT_CLAUDE_CODE_MODEL,
+                "reasoning_effort": DEFAULT_CLAUDE_CODE_REASONING_EFFORT,
             },
             "codex": {
-                "model": "gpt-5.4",
-                "reasoning_effort": "xhigh",
+                "model": DEFAULT_CODEX_MODEL,
+                "reasoning_effort": DEFAULT_CODEX_REASONING_EFFORT,
             },
         },
         "client_install_preferences": {

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

@@ -17,10 +17,12 @@ Environment variables:
 import hashlib
 import json
 import os
+import re
 import sqlite3
 import sys
 from collections import Counter
 from datetime import datetime, timedelta
+from difflib import SequenceMatcher
 from pathlib import Path
 
 NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
@@ -34,6 +36,36 @@ COGNITIVE_DB = NEXO_HOME / "data" / "cognitive.db"
 OPERATIONS_DIR = NEXO_HOME / "operations"
 BACKUP_DIR = DEEP_SLEEP_DIR  # backups stored alongside outputs
 
+STOPWORDS = {
+    "the", "a", "an", "and", "or", "but", "with", "for", "from", "into", "onto",
+    "that", "this", "these", "those", "have", "has", "had", "will", "would",
+    "could", "should", "must", "need", "needs", "your", "their", "there", "here",
+    "about", "before", "after", "during", "through", "without", "within", "while",
+    "que", "con", "para", "por", "los", "las", "una", "uno", "sobre", "desde",
+    "cuando", "como", "pero", "todo", "toda", "cada", "into", "across", "using",
+}
+CONCRETE_ACTION_VERBS = {
+    "add", "implement", "create", "write", "build", "introduce", "enforce",
+    "automate", "validate", "check", "verify", "guard", "fix", "migrate",
+    "review", "reconcile", "pin", "sync", "instrument",
+}
+NEGATION_PATTERNS = (
+    "do not", "don't", "never", "avoid", "skip", "without", "forbid", "forbidden",
+    "disable", "disabled", "remove", "ban", "bypass",
+)
+CONTRADICTION_PAIRS = (
+    ("enable", "disable"),
+    ("use", "avoid"),
+    ("add", "remove"),
+    ("allow", "forbid"),
+    ("always", "never"),
+    ("before", "after"),
+    ("require", "skip"),
+    ("validate", "bypass"),
+    ("include", "exclude"),
+)
+TABLE_COLUMNS_CACHE: dict[tuple[str, str], set[str]] = {}
+
 
 def generate_run_id(target_date: str) -> str:
     """Generate a unique run ID for this execution."""
@@ -75,41 +107,435 @@ def backup_db(db_path: Path, run_id: str) -> Path | None:
         return None
 
 
+def _table_columns(db_path: Path, table: str) -> set[str]:
+    cache_key = (str(db_path), table)
+    if cache_key in TABLE_COLUMNS_CACHE:
+        return TABLE_COLUMNS_CACHE[cache_key]
+    if not db_path.exists():
+        TABLE_COLUMNS_CACHE[cache_key] = set()
+        return set()
+    try:
+        conn = sqlite3.connect(str(db_path))
+        rows = conn.execute(f"PRAGMA table_info({table})").fetchall()
+        conn.close()
+    except Exception:
+        TABLE_COLUMNS_CACHE[cache_key] = set()
+        return set()
+    cols = {str(row[1]) for row in rows}
+    TABLE_COLUMNS_CACHE[cache_key] = cols
+    return cols
+
+
+def _row_dict(row) -> dict:
+    if row is None:
+        return {}
+    if isinstance(row, sqlite3.Row):
+        return dict(row)
+    return dict(zip(row.keys(), row)) if hasattr(row, "keys") else dict(row)
+
+
+def _normalize_text(value: str) -> str:
+    text = str(value or "").lower()
+    text = re.sub(r"https?://\S+", " ", text)
+    text = re.sub(r"[^a-z0-9_/\-\s]+", " ", text)
+    text = re.sub(r"\s+", " ", text)
+    return text.strip()
+
+
+def _tokenize(value: str) -> list[str]:
+    tokens = re.findall(r"[a-z0-9_/-]+", _normalize_text(value))
+    return [token for token in tokens if len(token) > 2 and token not in STOPWORDS]
+
+
+def _text_similarity(left: str, right: str) -> float:
+    normalized_left = _normalize_text(left)
+    normalized_right = _normalize_text(right)
+    if not normalized_left or not normalized_right:
+        return 0.0
+    if normalized_left == normalized_right:
+        return 1.0
+
+    left_tokens = set(_tokenize(normalized_left))
+    right_tokens = set(_tokenize(normalized_right))
+    shared = left_tokens & right_tokens
+    if not shared:
+        return SequenceMatcher(None, normalized_left, normalized_right).ratio()
+
+    seq = SequenceMatcher(None, normalized_left, normalized_right).ratio()
+    jaccard = len(shared) / len(left_tokens | right_tokens) if (left_tokens or right_tokens) else 0.0
+    overlap = len(shared) / min(len(left_tokens), len(right_tokens)) if min(len(left_tokens), len(right_tokens)) else 0.0
+    containment = (
+        1.0
+        if normalized_left in normalized_right or normalized_right in normalized_left
+        else 0.0
+    )
+    return round(max((seq * 0.45) + (jaccard * 0.2) + (overlap * 0.35), overlap, (containment * 0.8) + (seq * 0.2)), 4)
+
+
+def _is_concrete_action(text: str) -> bool:
+    tokens = set(_tokenize(text))
+    return bool(tokens & CONCRETE_ACTION_VERBS)
+
+
+def _prefer_due_date(current_value, new_value) -> str:
+    current = _parse_any_datetime(current_value)
+    new = _parse_any_datetime(new_value)
+    if new and (not current or new <= current):
+        return str(new_value or "")
+    return str(current_value or "")
+
+
+def _append_note(base: str, note: str) -> str:
+    base = str(base or "").strip()
+    note = str(note or "").strip()
+    if not note:
+        return base
+    if not base:
+        return note
+    if note.lower() in base.lower():
+        return base
+    return f"{base}\n\n{note}"
+
+
+def _contains_negation(text: str) -> bool:
+    lowered = _normalize_text(text)
+    return any(token in lowered for token in NEGATION_PATTERNS)
+
+
+def _negated_action_verbs(text: str) -> set[str]:
+    lowered = _normalize_text(text)
+    matches = set()
+    for pattern in (r"(?:never|avoid|skip|disable|remove|forbid|bypass)\s+([a-z0-9_-]+)", r"(?:do not|don't)\s+([a-z0-9_-]+)"):
+        matches.update(re.findall(pattern, lowered))
+    return {match for match in matches if len(match) > 2}
+
+
+def _looks_contradictory(existing_text: str, new_text: str) -> bool:
+    existing_norm = _normalize_text(existing_text)
+    new_norm = _normalize_text(new_text)
+    if not existing_norm or not new_norm:
+        return False
+    existing_tokens = set(_tokenize(existing_norm))
+    new_tokens = set(_tokenize(new_norm))
+    if len(existing_tokens & new_tokens) < 3:
+        return False
+    existing_negated_verbs = _negated_action_verbs(existing_norm)
+    new_negated_verbs = _negated_action_verbs(new_norm)
+    if existing_negated_verbs & new_tokens and not existing_negated_verbs & new_negated_verbs:
+        return True
+    if new_negated_verbs & existing_tokens and not existing_negated_verbs & new_negated_verbs:
+        return True
+    if _contains_negation(existing_norm) != _contains_negation(new_norm):
+        return True
+    for positive, negative in CONTRADICTION_PAIRS:
+        existing_has_pair = positive in existing_norm or negative in existing_norm
+        new_has_pair = positive in new_norm or negative in new_norm
+        if existing_has_pair and new_has_pair:
+            if (positive in existing_norm and negative in new_norm) or (negative in existing_norm and positive in new_norm):
+                return True
+    return False
+
+
+def _fetch_open_followups() -> list[dict]:
+    if not NEXO_DB.exists():
+        return []
+    conn = sqlite3.connect(str(NEXO_DB))
+    conn.row_factory = sqlite3.Row
+    cols = _table_columns(NEXO_DB, "followups")
+    reasoning_sql = ", reasoning" if "reasoning" in cols else ""
+    verification_sql = ", verification" if "verification" in cols else ""
+    try:
+        rows = conn.execute(
+            "SELECT id, description, date, status"
+            f"{verification_sql}{reasoning_sql} "
+            "FROM followups WHERE status NOT LIKE 'COMPLETED%' "
+            "AND status NOT IN ('DELETED','archived','blocked','waiting','CANCELLED')"
+        ).fetchall()
+    finally:
+        conn.close()
+    return [dict(row) for row in rows]
+
+
+def _find_similar_followup(description: str, threshold: float = 0.58) -> dict | None:
+    candidates = []
+    query = str(description or "").strip()
+    if not query:
+        return None
+    query_tokens = set(_tokenize(query))
+    for row in _fetch_open_followups():
+        haystack = " ".join(
+            [
+                str(row.get("description", "") or ""),
+                str(row.get("verification", "") or ""),
+                str(row.get("reasoning", "") or ""),
+            ]
+        )
+        haystack_tokens = set(_tokenize(haystack))
+        if len(query_tokens & haystack_tokens) < 2 and _normalize_text(query) not in _normalize_text(haystack):
+            continue
+        score = _text_similarity(query, haystack)
+        if score >= threshold:
+            candidates.append({**row, "_similarity": score})
+    if not candidates:
+        return None
+    candidates.sort(key=lambda item: item["_similarity"], reverse=True)
+    return candidates[0]
+
+
+def _touch_existing_followup(existing: dict, *, description: str, date: str = "", reasoning_note: str = "") -> dict:
+    cols = _table_columns(NEXO_DB, "followups")
+    if not cols:
+        return {"success": False, "error": "followups table not found"}
+
+    updates: dict[str, object] = {}
+    existing_description = str(existing.get("description", "") or "")
+    if _is_concrete_action(description) and not _is_concrete_action(existing_description):
+        updates["description"] = description
+    preferred_date = _prefer_due_date(existing.get("date", ""), date)
+    if preferred_date and preferred_date != str(existing.get("date", "") or "") and "date" in cols:
+        updates["date"] = preferred_date
+    if "reasoning" in cols and reasoning_note:
+        updates["reasoning"] = _append_note(existing.get("reasoning", ""), reasoning_note)
+    if "updated_at" in cols:
+        updates["updated_at"] = datetime.now().timestamp()
+
+    if updates:
+        conn = sqlite3.connect(str(NEXO_DB))
+        set_clause = ", ".join(f"{column} = ?" for column in updates)
+        params = list(updates.values()) + [existing["id"]]
+        conn.execute(f"UPDATE followups SET {set_clause} WHERE id = ?", params)
+        conn.commit()
+        conn.close()
+
+    return {
+        "success": True,
+        "id": existing["id"],
+        "outcome": "matched_existing_followup",
+        "similarity": existing.get("_similarity", 1.0),
+        "updated_existing": bool(updates),
+    }
+
+
+def _fetch_learning_candidates(category: str = "") -> list[dict]:
+    if not NEXO_DB.exists():
+        return []
+    cols = _table_columns(NEXO_DB, "learnings")
+    if not cols:
+        return []
+    select_fields = ["id", "category", "title", "content", "created_at", "updated_at"]
+    for optional in ("reasoning", "prevention", "applies_to", "status", "review_due_at", "last_reviewed_at", "weight", "priority"):
+        if optional in cols:
+            select_fields.append(optional)
+    query = f"SELECT {', '.join(select_fields)} FROM learnings"
+    params: list[object] = []
+    if category and "category" in cols:
+        query += " WHERE category = ?"
+        params.append(category)
+    query += " ORDER BY COALESCE(updated_at, created_at) DESC LIMIT 240"
+    conn = sqlite3.connect(str(NEXO_DB))
+    conn.row_factory = sqlite3.Row
+    try:
+        rows = conn.execute(query, tuple(params)).fetchall()
+    finally:
+        conn.close()
+    return [dict(row) for row in rows]
+
+
+def _find_learning_match(category: str, title: str, content: str) -> dict | None:
+    candidates = []
+    new_text = " ".join([str(title or ""), str(content or "")]).strip()
+    for row in _fetch_learning_candidates(category):
+        existing_text = " ".join([str(row.get("title", "") or ""), str(row.get("content", "") or "")])
+        similarity = _text_similarity(new_text, existing_text)
+        if similarity < 0.58:
+            continue
+        contradiction = _looks_contradictory(existing_text, new_text)
+        candidates.append({**row, "_similarity": similarity, "_contradiction": contradiction})
+    if not candidates:
+        return None
+    candidates.sort(
+        key=lambda item: (item["_contradiction"], item["_similarity"], item.get("updated_at", 0) or item.get("created_at", 0)),
+        reverse=True,
+    )
+    return candidates[0]
+
+
+def _update_learning_row(learning_id: int, updates: dict[str, object]) -> None:
+    if not updates:
+        return
+    conn = sqlite3.connect(str(NEXO_DB))
+    set_clause = ", ".join(f"{column} = ?" for column in updates)
+    conn.execute(f"UPDATE learnings SET {set_clause} WHERE id = ?", list(updates.values()) + [learning_id])
+    conn.commit()
+    conn.close()
+
+
+def _bump_weight(existing_value, amount: float) -> float:
+    try:
+        base = float(existing_value or 0)
+    except Exception:
+        base = 0.0
+    return round(min(10.0, base + amount), 2)
+
+
+def _flag_learning_contradiction(existing: dict, category: str, title: str, content: str) -> dict:
+    review_description = (
+        f"Reconcile contradictory learning in {category or 'general'}: "
+        f"review existing learning #{existing.get('id')} ('{existing.get('title', '')}') "
+        f"against new Deep Sleep finding '{title}'. Produce one canonical rule, update guardrails, and remove ambiguity."
+    )
+    followup_result = create_followup(
+        description=review_description,
+        date="",
+        reasoning_note=f"Contradiction detected against learning #{existing.get('id')}: {content[:240]}",
+    )
+    return {
+        "success": followup_result.get("success", False),
+        "id": existing.get("id"),
+        "outcome": "contradiction_review",
+        "similarity": existing.get("_similarity", 0.0),
+        "review_followup_id": followup_result.get("id"),
+        "followup_result": followup_result,
+    }
+
+
 def add_learning(category: str, title: str, content: str) -> dict:
     """Add a learning to nexo.db. Returns result dict."""
     if not NEXO_DB.exists():
         return {"success": False, "error": "nexo.db not found"}
     try:
+        existing = _find_learning_match(category, title, content)
+        if existing:
+            similarity = existing.get("_similarity", 0.0)
+            if existing.get("_contradiction"):
+                return _flag_learning_contradiction(existing, category, title, content)
+
+            updates: dict[str, object] = {}
+            columns = _table_columns(NEXO_DB, "learnings")
+            if "updated_at" in columns:
+                updates["updated_at"] = datetime.now().timestamp()
+
+            existing_title = _normalize_text(existing.get("title", ""))
+            existing_content = _normalize_text(existing.get("content", ""))
+            incoming_title = _normalize_text(title)
+            incoming_content = _normalize_text(content)
+
+            if similarity >= 0.95 and (
+                existing_title == incoming_title
+                or existing_content == incoming_content
+                or incoming_content in existing_content
+                or existing_content in incoming_content
+            ):
+                if "weight" in columns:
+                    updates["weight"] = _bump_weight(existing.get("weight"), 0.1)
+                if "last_reviewed_at" in columns:
+                    updates["last_reviewed_at"] = datetime.now().timestamp()
+                if "reasoning" in columns:
+                    updates["reasoning"] = _append_note(
+                        existing.get("reasoning", ""),
+                        f"Reconfirmed by Deep Sleep on {datetime.now().strftime('%Y-%m-%d')}.",
+                    )
+                _update_learning_row(existing["id"], updates)
+                return {
+                    "success": True,
+                    "id": existing["id"],
+                    "outcome": "duplicate_learning",
+                    "similarity": similarity,
+                    "updated_existing": bool(updates),
+                }
+
+            if similarity >= 0.58:
+                if "weight" in columns:
+                    updates["weight"] = _bump_weight(existing.get("weight"), 0.25)
+                if "reasoning" in columns:
+                    updates["reasoning"] = _append_note(
+                        existing.get("reasoning", ""),
+                        f"Deep Sleep reinforcement ({datetime.now().strftime('%Y-%m-%d')}): {title}. {content[:240]}",
+                    )
+                elif "content" in columns and content and content not in str(existing.get("content", "")):
+                    updates["content"] = _append_note(
+                        existing.get("content", ""),
+                        f"Reinforced by Deep Sleep: {content[:240]}",
+                    )
+                _update_learning_row(existing["id"], updates)
+                return {
+                    "success": True,
+                    "id": existing["id"],
+                    "outcome": "reinforced_learning",
+                    "similarity": similarity,
+                    "updated_existing": bool(updates),
+                }
+
         now = datetime.now().timestamp()
+        columns = _table_columns(NEXO_DB, "learnings")
+        payload = {
+            "category": category,
+            "title": title,
+            "content": content,
+            "created_at": now,
+            "updated_at": now,
+        }
+        if "reasoning" in columns:
+            payload["reasoning"] = "Deep Sleep v2 overnight analysis"
+        if "status" in columns:
+            payload["status"] = "active"
+        insert_columns = [column for column in payload if column in columns]
+        values = [payload[column] for column in insert_columns]
+
         conn = sqlite3.connect(str(NEXO_DB))
         cursor = conn.execute(
-            "INSERT INTO learnings (category, title, content, created_at, updated_at, reasoning) VALUES (?, ?, ?, ?, ?, ?)",
-            (category, title, content, now, now, "Deep Sleep v2 overnight analysis")
+            f"INSERT INTO learnings ({', '.join(insert_columns)}) VALUES ({', '.join('?' for _ in insert_columns)})",
+            values,
         )
         learning_id = cursor.lastrowid
         conn.commit()
         conn.close()
-        return {"success": True, "id": learning_id}
+        return {"success": True, "id": learning_id, "outcome": "new_learning"}
     except Exception as e:
         return {"success": False, "error": str(e)}
 
 
-def create_followup(description: str, date: str = "") -> dict:
+def create_followup(description: str, date: str = "", reasoning_note: str = "") -> dict:
     """Create a followup in nexo.db. Returns result dict."""
     if not NEXO_DB.exists():
         return {"success": False, "error": "nexo.db not found"}
     try:
+        matched = _find_similar_followup(description)
+        if matched:
+            return _touch_existing_followup(
+                matched,
+                description=description,
+                date=date,
+                reasoning_note=reasoning_note or "Deep Sleep matched this followup semantically.",
+            )
+
         now = datetime.now().timestamp()
         # Generate a deterministic ID
         fid = "NF-DS-" + hashlib.md5(description.encode()).hexdigest()[:8].upper()
+        columns = _table_columns(NEXO_DB, "followups")
+        payload = {
+            "id": fid,
+            "description": description,
+            "date": date,
+            "status": "PENDING",
+            "created_at": now,
+            "updated_at": now,
+        }
+        if "reasoning" in columns:
+            payload["reasoning"] = reasoning_note or "Deep Sleep v2 overnight analysis"
+        if "verification" in columns:
+            payload["verification"] = ""
+        insert_columns = [column for column in payload if column in columns]
+        values = [payload[column] for column in insert_columns]
+
         conn = sqlite3.connect(str(NEXO_DB))
         conn.execute(
-            "INSERT OR IGNORE INTO followups (id, description, date, status, created_at, updated_at, reasoning) VALUES (?, ?, ?, 'PENDING', ?, ?, ?)",
-            (fid, description, date, now, now, "Deep Sleep v2 overnight analysis")
+            f"INSERT OR IGNORE INTO followups ({', '.join(insert_columns)}) VALUES ({', '.join('?' for _ in insert_columns)})",
+            values,
         )
         conn.commit()
         conn.close()
-        return {"success": True, "id": fid}
+        return {"success": True, "id": fid, "outcome": "new_followup"}
     except Exception as e:
         return {"success": False, "error": str(e)}
 
@@ -964,7 +1390,8 @@ def apply_action(action: dict, run_id: str) -> dict:
     elif action_type == "followup_create":
         result = create_followup(
             description=content.get("description", content.get("title", "")),
-            date=content.get("date", "")
+            date=content.get("date", ""),
+            reasoning_note=content.get("reasoning", content.get("why", "")),
         )
         log_entry["status"] = "applied" if result.get("success") else "error"
         log_entry["details"] = result

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

@@ -30,6 +30,15 @@ Synthesize across all sessions:
 - Cross-domain connections where an older learning or session sample explains a current issue
 - Topics repeatedly mentioned over time but never formalized into a learning or followup
 - Project pressure that is rising because of repeated diary mentions, open followups, or adverse outcomes
+- For medium/high-severity patterns, propose a concrete fix artifact:
+  - script
+  - hook
+  - checklist
+  - validation step
+  - workflow change
+  - guardrail
+
+Do not stop at diagnosis. Turn repeated problems into concrete engineering work.
 
 ### 2. Morning Agenda
 Generate a prioritized agenda for the next morning:
@@ -126,6 +135,14 @@ Merge and deduplicate all findings into a final action list. Each action should
 - `dedupe_key`: deterministic key for idempotency
 - `content`: the actual data to write
 
+When generating `followup_create`, prefer descriptions that start with a concrete verb and include the deliverable:
+- "Add a pre-release validation script ..."
+- "Implement a guard hook that ..."
+- "Create a checklist for ..."
+- "Write a watchdog check that ..."
+
+Avoid vague followups that merely restate the diagnosis.
+
 ## Output Format
 
 Return ONLY valid JSON. No markdown code fences. No explanation text.
@@ -140,6 +157,12 @@ Return ONLY valid JSON. No markdown code fences. No explanation text.
       "pattern": "Description of the pattern",
       "sessions": ["session1.jsonl", "session2.jsonl"],
       "severity": "low|medium|high",
+      "proposed_fix": {
+        "title": "Short concrete fix title",
+        "description": "Concrete engineering change to make",
+        "deliverable": "script|hook|checklist|workflow|guardrail",
+        "confidence": 0.0
+      },
       "evidence": [
         {"type": "transcript", "session_id": "...", "message_index": 42, "quote": "..."}
       ]

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

@@ -14,6 +14,7 @@ import json
 import os
 import subprocess
 import sys
+import hashlib
 from datetime import datetime
 from pathlib import Path
 
@@ -28,6 +29,7 @@ if str(NEXO_CODE) not in sys.path:
 from agent_runner import AutomationBackendUnavailableError, run_automation_prompt
 
 CLAUDE_TIMEOUT = 21600  # 3h safety net (prevents zombie processes)
+ACTION_VERBS = {"add", "implement", "create", "write", "build", "enforce", "automate", "validate", "guard", "fix", "review"}
 
 
 def extract_json_from_response(text: str) -> dict | None:
@@ -86,6 +88,96 @@ def collect_skill_runtime_candidates(target_date: str) -> tuple[Path, dict]:
     return output_file, payload
 
 
+def _normalize_action_text(value: str) -> str:
+    return " ".join(str(value or "").strip().lower().split())
+
+
+def _looks_concrete_action(text: str) -> bool:
+    words = {word.strip(".,:;()[]{}").lower() for word in str(text or "").split()}
+    return bool(words & ACTION_VERBS)
+
+
+def _pattern_followup_from_fix(pattern: dict) -> dict | None:
+    severity = str(pattern.get("severity", "") or "").lower()
+    sessions = pattern.get("sessions", []) or []
+    if severity not in {"medium", "high"} and len(sessions) < 2:
+        return None
+
+    proposed_fix = pattern.get("proposed_fix") or {}
+    pattern_text = str(pattern.get("pattern", "") or "").strip()
+    title = str(proposed_fix.get("title", "") or "").strip()
+    description = str(proposed_fix.get("description", "") or "").strip()
+    deliverable = str(proposed_fix.get("deliverable", "") or proposed_fix.get("artifact", "") or "").strip()
+
+    if title and description:
+        if _looks_concrete_action(description):
+            followup_description = description
+        else:
+            followup_description = f"{title}: {description}"
+    elif description:
+        followup_description = description
+    elif title:
+        followup_description = title
+    elif pattern_text:
+        followup_description = (
+            f"Implement a concrete guardrail for recurring issue: {pattern_text}. "
+            "Deliverable should be a script, hook, checklist, or automated validation that prevents the same failure from repeating."
+        )
+    else:
+        return None
+
+    if deliverable and deliverable.lower() not in followup_description.lower():
+        followup_description = f"{followup_description} Deliverable: {deliverable}."
+    if not _looks_concrete_action(followup_description):
+        followup_description = f"Implement this fix: {followup_description}"
+
+    return {
+        "action_type": "followup_create",
+        "action_class": "auto_apply" if severity == "high" else "draft_for_morning",
+        "confidence": round(max(float(proposed_fix.get("confidence", 0.0) or 0.0), 0.86 if severity == "high" else 0.78), 2),
+        "impact": "high" if severity == "high" else "medium",
+        "reversibility": "reversible",
+        "evidence": pattern.get("evidence", []) or [],
+        "dedupe_key": "engineering-fix:" + hashlib.md5(
+            _normalize_action_text(followup_description).encode("utf-8")
+        ).hexdigest()[:16],
+        "content": {
+            "title": title or f"Engineering fix for: {pattern_text[:90]}",
+            "description": followup_description,
+            "date": "",
+            "reasoning": f"Deep Sleep engineering followup from recurring pattern: {pattern_text}",
+        },
+    }
+
+
+def backfill_engineering_actions(payload: dict) -> dict:
+    if not isinstance(payload, dict):
+        return payload
+    actions = payload.get("actions")
+    if not isinstance(actions, list):
+        actions = []
+        payload["actions"] = actions
+
+    existing_keys = {str(action.get("dedupe_key", "") or "") for action in actions}
+    existing_descriptions = {
+        _normalize_action_text(action.get("content", {}).get("description", ""))
+        for action in actions
+        if isinstance(action, dict)
+    }
+
+    for pattern in payload.get("cross_session_patterns", []) or []:
+        action = _pattern_followup_from_fix(pattern)
+        if not action:
+            continue
+        description = _normalize_action_text(action["content"]["description"])
+        if action["dedupe_key"] in existing_keys or description in existing_descriptions:
+            continue
+        actions.append(action)
+        existing_keys.add(action["dedupe_key"])
+        existing_descriptions.add(description)
+    return payload
+
+
 def main():
     target_date = sys.argv[1] if len(sys.argv) > 1 else datetime.now().strftime("%Y-%m-%d")
 
@@ -177,6 +269,8 @@ def main():
             print(f"[synthesize] Failed to parse JSON. Raw output saved to {debug_file}", file=sys.stderr)
             sys.exit(1)
 
+        parsed = backfill_engineering_actions(parsed)
+
         # Write synthesis output
         output_file = DEEP_SLEEP_DIR / f"{target_date}-synthesis.json"
         with open(output_file, "w") as f:

package/templates/nexo_helper.py

@@ -16,6 +16,36 @@ from pathlib import Path
 
 
 NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+DEFAULT_ALLOWED_TOOLS = "Read,Write,Edit,Glob,Grep,Bash,mcp__nexo__*"
+
+
+def _load_schedule() -> dict:
+    schedule_path = NEXO_HOME / "config" / "schedule.json"
+    if not schedule_path.is_file():
+        return {}
+    try:
+        return json.loads(schedule_path.read_text())
+    except Exception:
+        return {}
+
+
+def _resolve_automation_backend() -> str:
+    data = _load_schedule()
+    return str(data.get("automation_backend", "claude_code") or "claude_code")
+
+
+def _load_bootstrap_prompt() -> str:
+    backend = _resolve_automation_backend()
+    if backend == "codex":
+        path = Path.home() / ".codex" / "AGENTS.md"
+    else:
+        path = Path.home() / ".claude" / "CLAUDE.md"
+    if not path.is_file():
+        return ""
+    try:
+        return path.read_text()
+    except Exception:
+        return ""
 
 
 def run_nexo(args: list[str]) -> str:
@@ -57,6 +87,9 @@ def run_automation_text(
     model: str = "",
     reasoning_effort: str = "",
     cwd: str = "",
+    allowed_tools: str = DEFAULT_ALLOWED_TOOLS,
+    append_system_prompt: str = "",
+    include_bootstrap: bool = True,
 ) -> str:
     """Run the configured NEXO automation backend and return text output.
 
@@ -75,6 +108,17 @@ def run_automation_text(
         cmd.extend(["--reasoning-effort", reasoning_effort])
     if cwd:
         cmd.extend(["--cwd", cwd])
+    merged_system_prompt = []
+    if include_bootstrap:
+        bootstrap = _load_bootstrap_prompt()
+        if bootstrap:
+            merged_system_prompt.append(bootstrap)
+    if append_system_prompt:
+        merged_system_prompt.append(append_system_prompt)
+    if merged_system_prompt:
+        cmd.extend(["--append-system-prompt", "\n\n".join(merged_system_prompt)])
+    if allowed_tools:
+        cmd.extend(["--allowed-tools", allowed_tools])
 
     env = os.environ.copy()
     env.setdefault("NEXO_HOME", str(NEXO_HOME))