nexo-brain 3.2.0 → 4.0.0

package/src/plugins/memory_export.py

@@ -0,0 +1,196 @@
+"""Readable export and auto-flush inspection tools."""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+
+import cognitive
+import claim_graph
+import compaction_memory
+import media_memory
+import user_state_model
+from db import get_db
+from memory_backends import get_backend, list_backends
+
+
+def _nexo_home() -> Path:
+    return Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo"))).expanduser()
+
+
+def _write(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+
+
+def handle_auto_flush_recent(limit: int = 20, session_id: str = "") -> str:
+    rows = compaction_memory.list_auto_flushes(session_id=session_id, limit=limit)
+    if not rows:
+        return "No auto-flush records."
+    lines = [f"AUTO-FLUSH — {len(rows)} record(s):", ""]
+    for row in rows:
+        lines.append(f"  #{row['id']} {row['created_at']} [{row.get('session_id','unknown')}]")
+        lines.append(f"    {row.get('summary','')[:220]}")
+        if row.get("next_step"):
+            lines.append(f"    next: {row['next_step'][:160]}")
+    return "\n".join(lines)
+
+
+def handle_auto_flush_stats(days: int = 7) -> str:
+    stats = compaction_memory.auto_flush_stats(days=days)
+    return (
+        f"AUTO-FLUSH STATS — {stats['window_days']}d\n"
+        f"  total: {stats['total']}\n"
+        f"  backend: {stats['backend']}\n"
+        f"  by_source: {stats['by_source']}"
+    )
+
+
+def handle_memory_backend_status() -> str:
+    active = get_backend()
+    backends = list_backends()
+    lines = [
+        f"MEMORY BACKEND: {active.key} — {active.label}",
+        f"Description: {active.description}",
+        f"Supports: {', '.join(active.supports)}",
+        "",
+        "Registered backends:",
+    ]
+    for item in backends:
+        marker = "*" if item["active"] else "-"
+        lines.append(f"  {marker} {item['key']} [{item['maturity']}] {item['label']}")
+    return "\n".join(lines)
+
+
+def handle_memory_export(format: str = "markdown", output_dir: str = "") -> str:
+    if format.strip().lower() != "markdown":
+        return "ERROR: only markdown export is supported for now."
+
+    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    root = Path(output_dir).expanduser() if output_dir.strip() else (_nexo_home() / "exports" / "memory" / stamp)
+    root.mkdir(parents=True, exist_ok=True)
+
+    conn = get_db()
+    learnings = [dict(r) for r in conn.execute("SELECT id, category, title, status, prevention, updated_at FROM learnings ORDER BY updated_at DESC LIMIT 50").fetchall()]
+    decisions = [dict(r) for r in conn.execute("SELECT id, domain, decision, confidence, status, created_at FROM decisions ORDER BY created_at DESC LIMIT 50").fetchall()]
+    claims = claim_graph.search_claims(limit=100)
+    claim_lint = claim_graph.lint_claims(limit=50)
+    media = media_memory.list_media_memories(limit=100)
+    flushes = compaction_memory.list_auto_flushes(limit=100)
+    user_state = user_state_model.build_user_state(days=7, persist=False)
+    user_history = user_state_model.list_user_state_snapshots(limit=30)
+    cognitive_stats = cognitive.get_stats()
+
+    _write(
+        root / "README.md",
+        "\n".join(
+            [
+                "# NEXO Memory Export",
+                "",
+                f"- Generated: {datetime.now().isoformat(timespec='seconds')}",
+                f"- Backend: {get_backend().key}",
+                f"- Learnings: {len(learnings)}",
+                f"- Decisions: {len(decisions)}",
+                f"- Claims: {len(claims)}",
+                f"- Media memories: {len(media)}",
+                f"- Auto-flush records: {len(flushes)}",
+                "",
+                "Files:",
+                "- `learnings.md`",
+                "- `decisions.md`",
+                "- `claims.md`",
+                "- `media.md`",
+                "- `auto-flush.md`",
+                "- `user-state.md`",
+                "- `cognitive.json`",
+            ]
+        ),
+    )
+    _write(
+        root / "learnings.md",
+        "\n".join(
+            ["# Learnings", ""]
+            + [
+                f"- #{item['id']} [{item.get('category','general')}] {item['title']} "
+                f"({item.get('status','active')}, updated {item.get('updated_at','')})"
+                for item in learnings
+            ]
+        ),
+    )
+    _write(
+        root / "decisions.md",
+        "\n".join(
+            ["# Decisions", ""]
+            + [
+                f"- #{item['id']} [{item.get('domain','other')}] {item['decision']} "
+                f"({item.get('confidence','medium')}, {item.get('status','pending_review')})"
+                for item in decisions
+            ]
+        ),
+    )
+    _write(
+        root / "claims.md",
+        "\n".join(
+            ["# Claims", ""]
+            + [
+                f"- #{item['id']} [{item.get('verification_status','unverified')}] "
+                f"{item.get('freshness_state','?')}({item.get('freshness_score',0)}): {item['text']}"
+                for item in claims
+            ]
+            + ["", "## Attention", ""]
+            + [
+                f"- #{item['id']} [{', '.join(item.get('lint_reasons', []))}] {item['text']}"
+                for item in claim_lint
+            ]
+        ),
+    )
+    _write(
+        root / "media.md",
+        "\n".join(
+            ["# Media Memory", ""]
+            + [
+                f"- #{item['id']} [{item['media_type']}] {item['title']} :: {item.get('file_path') or item.get('url') or 'n/a'}"
+                for item in media
+            ]
+        ),
+    )
+    _write(
+        root / "auto-flush.md",
+        "\n".join(
+            ["# Auto Flush", ""]
+            + [
+                f"- #{item['id']} [{item.get('session_id','unknown')}] {item.get('created_at','')}: "
+                f"{item.get('summary','')}"
+                for item in flushes
+            ]
+        ),
+    )
+    _write(
+        root / "user-state.md",
+        "\n".join(
+            [
+                "# User State",
+                "",
+                f"- Current: {user_state['state_label']} ({user_state['confidence']})",
+                f"- Trust: {user_state['trust_score']}",
+                f"- Guidance: {user_state['guidance']}",
+                "",
+                "## Signals",
+            ]
+            + [f"- {key}: {value}" for key, value in user_state["signals"].items()]
+            + ["", "## History", ""]
+            + [f"- {item['created_at']} :: {item['state_label']} ({item['confidence']})" for item in user_history]
+        ),
+    )
+    _write(root / "cognitive.json", json.dumps(cognitive_stats, indent=2, sort_keys=True))
+    return f"Memory export written to {root}"
+
+
+TOOLS = [
+    (handle_auto_flush_recent, "nexo_auto_flush_recent", "Show recent structured auto-flush records written before compaction."),
+    (handle_auto_flush_stats, "nexo_auto_flush_stats", "Stats for pre-compaction auto-flush activity."),
+    (handle_memory_backend_status, "nexo_memory_backend_status", "Show the active memory backend contract and registered backend list."),
+    (handle_memory_export, "nexo_memory_export", "Export a readable markdown snapshot of key NEXO memory layers."),
+]

package/src/plugins/user_state_tools.py

@@ -0,0 +1,43 @@
+"""User-state modeling tools."""
+
+import user_state_model
+
+
+def handle_user_state(days: int = 7, persist: bool = True) -> str:
+    snapshot = user_state_model.build_user_state(days=days, persist=persist)
+    lines = [
+        f"USER STATE: {snapshot['state_label'].upper()} (confidence={snapshot['confidence']})",
+        f"Trust: {snapshot['trust_score']}/100",
+        f"Guidance: {snapshot['guidance']}",
+        "Signals:",
+    ]
+    for key, value in snapshot["signals"].items():
+        lines.append(f"  {key}: {value}")
+    return "\n".join(lines)
+
+
+def handle_user_state_history(limit: int = 20) -> str:
+    items = user_state_model.list_user_state_snapshots(limit=limit)
+    if not items:
+        return "No user-state snapshots yet."
+    lines = [f"USER STATE HISTORY — {len(items)} snapshot(s):", ""]
+    for item in items:
+        lines.append(f"  {item['created_at']} — {item['state_label']} ({item['confidence']})")
+    return "\n".join(lines)
+
+
+def handle_user_state_stats(days: int = 30) -> str:
+    stats = user_state_model.user_state_stats(days=days)
+    return (
+        f"USER STATE STATS — {days}d\n"
+        f"  snapshots: {stats['snapshots']}\n"
+        f"  backend: {stats['backend']}\n"
+        f"  by_state: {stats['by_state']}"
+    )
+
+
+TOOLS = [
+    (handle_user_state, "nexo_user_state", "Compute a richer, inspectable user-state snapshot from trust, corrections, sentiment, and hot context."),
+    (handle_user_state_history, "nexo_user_state_history", "List recent user-state snapshots."),
+    (handle_user_state_stats, "nexo_user_state_stats", "Aggregate user-state snapshots by label."),
+]

package/src/script_registry.py

@@ -77,6 +77,7 @@ METADATA_KEYS = {
 SUPPORTED_RUNTIMES = {"python", "shell", "node", "php", "unknown"}
 PERSONAL_SCHEDULE_MANAGED_ENV = "NEXO_MANAGED_PERSONAL_CRON"
 SUPPORTED_RECOVERY_POLICIES = {"none", "run_once_on_wake", "catchup", "restart", "restart_daemon"}
+PERSONAL_SCRIPT_FILENAME_PREFIX = "ps-"
 
 
 def get_nexo_home() -> Path:
@@ -248,6 +249,17 @@ def _safe_slug(value: str) -> str:
     return slug or "script"
 
 
+def has_personal_script_filename_prefix(value: str) -> bool:
+    return _safe_slug(value).startswith(PERSONAL_SCRIPT_FILENAME_PREFIX)
+
+
+def _logical_personal_script_name(name: str) -> str:
+    slug = _safe_slug(name)
+    if slug.startswith(PERSONAL_SCRIPT_FILENAME_PREFIX):
+        slug = slug[len(PERSONAL_SCRIPT_FILENAME_PREFIX):]
+    return slug or "personal-script"
+
+
 def get_declared_schedule(metadata: dict, default_name: str = "") -> dict:
     """Parse desired schedule metadata from inline script metadata."""
     explicit_name = metadata.get("name", "").strip()
@@ -460,7 +472,7 @@ def get_declared_schedule(metadata: dict, default_name: str = "") -> dict:
 def _script_entry(path: Path, meta: dict, *, is_core: bool, classification: str, reason: str = "") -> dict:
     runtime = classify_runtime(path, meta)
     name = meta.get("name", path.stem)
-    return {
+    entry = {
         "name": name,
         "runtime": runtime,
         "description": meta.get("description", ""),
@@ -470,7 +482,11 @@ def _script_entry(path: Path, meta: dict, *, is_core: bool, classification: str,
         "classification": classification,
         "reason": reason,
         "declared_schedule": get_declared_schedule(meta, name),
+        "filename_prefixed": has_personal_script_filename_prefix(path.stem),
     }
+    if classification == "personal":
+        entry["naming_policy"] = "preferred" if entry["filename_prefixed"] else "legacy-nonprefixed"
+    return entry
 
 
 def classify_scripts_dir() -> dict:
@@ -1173,13 +1189,7 @@ def _template_path(filename: str) -> Path | None:
 
 
 def _script_filename_from_name(name: str, runtime: str) -> str:
-    slug = []
-    for ch in name.strip().lower():
-        if ch.isalnum():
-            slug.append(ch)
-        elif ch in {" ", "-", "_"}:
-            slug.append("-")
-    stem = "".join(slug).strip("-") or "personal-script"
+    stem = _safe_slug(name) or "personal-script"
     ext = {
         "python": ".py",
         "shell": ".sh",
@@ -1189,6 +1199,11 @@ def _script_filename_from_name(name: str, runtime: str) -> str:
     return stem + ext
 
 
+def _personal_script_filename_from_name(name: str, runtime: str) -> str:
+    logical_name = _logical_personal_script_name(name)
+    return _script_filename_from_name(f"{PERSONAL_SCRIPT_FILENAME_PREFIX}{logical_name}", runtime)
+
+
 def create_script(name: str, *, description: str = "", runtime: str = "python", force: bool = False) -> dict:
     runtime = runtime if runtime in SUPPORTED_RUNTIMES else "python"
     if runtime == "unknown":
@@ -1196,7 +1211,8 @@ def create_script(name: str, *, description: str = "", runtime: str = "python",
 
     scripts_dir = get_scripts_dir()
     scripts_dir.mkdir(parents=True, exist_ok=True)
-    filename = _script_filename_from_name(name, runtime)
+    logical_name = _logical_personal_script_name(name)
+    filename = _personal_script_filename_from_name(name, runtime)
     path = scripts_dir / filename
     if path.exists() and not force:
         raise FileExistsError(f"Script already exists: {path}")
@@ -1226,10 +1242,9 @@ def create_script(name: str, *, description: str = "", runtime: str = "python",
             "print('hello')\n"
         )
 
-    script_name = Path(filename).stem
-    content = content.replace("example-script", script_name)
-    content = content.replace("Example personal script using the stable NEXO CLI", description or f"Personal script: {script_name}")
-    content = content.replace("Example shell script using NEXO", description or f"Personal script: {script_name}")
+    content = content.replace("example-script", logical_name)
+    content = content.replace("Example personal script using the stable NEXO CLI", description or f"Personal script: {logical_name}")
+    content = content.replace("Example shell script using NEXO", description or f"Personal script: {logical_name}")
 
     path.write_text(content)
     if runtime in {"shell", "python"}:
@@ -1237,8 +1252,10 @@ def create_script(name: str, *, description: str = "", runtime: str = "python",
     sync_result = sync_personal_scripts()
     return {
         "ok": True,
-        "name": script_name,
+        "name": logical_name,
+        "requested_name": name,
         "path": str(path),
+        "filename": filename,
         "runtime": runtime,
         "description": description,
         "sync": sync_result,

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

@@ -19,10 +19,15 @@ import sys
 from collections import Counter
 from datetime import datetime, timedelta
 from pathlib import Path
+
+_DEFAULT_RUNTIME_ROOT = Path(__file__).resolve().parents[2]
+NEXO_CODE = Path(os.environ.get("NEXO_CODE", str(_DEFAULT_RUNTIME_ROOT)))
+if str(NEXO_CODE) not in sys.path:
+    sys.path.insert(0, str(NEXO_CODE))
+
 import transcript_utils as _transcripts
 
 NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
-NEXO_CODE = Path(os.environ.get("NEXO_CODE", ""))
 DEEP_SLEEP_DIR = NEXO_HOME / "operations" / "deep-sleep"
 NEXO_DB = NEXO_HOME / "data" / "nexo.db"
 COGNITIVE_DB = NEXO_HOME / "data" / "cognitive.db"

package/src/server.py

@@ -220,6 +220,7 @@ mcp = FastMCP(
         "`nexo_recent_context_capture(...)` / `nexo_recent_context_resolve(...)` for important ongoing threads. "
         "If that is not enough, use `nexo_transcript_search(...)` / `nexo_transcript_read(...)` as the raw fallback to full conversations. "
         "Use `nexo_system_catalog(...)` / `nexo_tool_explain(...)` when you need the live map of NEXO itself. "
+        "Before the first use of an unfamiliar NEXO tool, call `nexo_tool_explain(name)` to see its signature, examples, workflow notes, and common errors. "
         "Capture: errors→`nexo_learning_add`, prefs, entities, decisions\n"
         "- **Change log:** `nexo_task_close` should be the default closure path. If you bypass it, call `nexo_change_log(...)` after production edits. NOT for config dir\n"
         "- **Diary:** When user signals end of session (any language, any style — 'bye', 'done', 'cierro', etc.), "