nexo-brain 3.1.9 → 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

@@ -20,8 +20,14 @@ 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"
@@ -64,196 +70,22 @@ def _session_identifier(client: str, session_file: str) -> str:
 
 def find_claude_session_files() -> list[Path]:
     """Find Claude Code session JSONL files under ~/.claude/projects."""
-    claude_dir = Path.home() / ".claude" / "projects"
-    if not claude_dir.exists():
-        return []
-    return sorted(claude_dir.rglob("*.jsonl"))
+    return _transcripts.find_claude_session_files()
 
 
 def find_codex_session_files() -> list[Path]:
     """Find Codex session JSONL files under ~/.codex/sessions and archived_sessions."""
-    roots = [
-        Path.home() / ".codex" / "sessions",
-        Path.home() / ".codex" / "archived_sessions",
-    ]
-    files: list[Path] = []
-    seen: set[str] = set()
-    for root in roots:
-        if not root.exists():
-            continue
-        for jsonl in sorted(root.rglob("*.jsonl")):
-            key = jsonl.name
-            if key in seen:
-                continue
-            seen.add(key)
-            files.append(jsonl)
-    return files
+    return _transcripts.find_codex_session_files()
 
 
 def extract_claude_session(jsonl_path: Path) -> dict | None:
     """Extract clean transcript from a Claude Code JSONL session."""
-    messages = []
-    tool_uses = []
-    user_msg_count = 0
-
-    try:
-        with open(jsonl_path, "r") as f:
-            for line_no, line in enumerate(f, 1):
-                line = line.strip()
-                if not line:
-                    continue
-                try:
-                    d = json.loads(line)
-                except json.JSONDecodeError:
-                    continue
-
-                msg_type = d.get("type")
-
-                # User messages
-                if msg_type == "user":
-                    content = d.get("message", {}).get("content", "")
-                    if isinstance(content, str) and content.strip():
-                        if content.startswith("<system-reminder>"):
-                            continue
-                        messages.append({
-                            "role": "user",
-                            "index": line_no,
-                            "text": _redact_sensitive(content[:5000]),
-                            "uuid": d.get("uuid", "")
-                        })
-                        user_msg_count += 1
-
-                # Assistant messages
-                elif msg_type in ("message", "assistant"):
-                    msg = d.get("message", {})
-                    content_blocks = msg.get("content", [])
-                    text_parts = []
-                    for block in content_blocks:
-                        if isinstance(block, dict):
-                            if block.get("type") == "text":
-                                text_parts.append(block.get("text", ""))
-                            elif block.get("type") == "tool_use":
-                                tool_input = block.get("input", {})
-                                raw_file = (
-                                    tool_input.get("file_path", "")
-                                    or str(tool_input.get("command", ""))[:100]
-                                ) if isinstance(tool_input, dict) else ""
-                                tool_uses.append({
-                                    "tool": block.get("name", ""),
-                                    "input_keys": list(tool_input.keys()) if isinstance(tool_input, dict) else [],
-                                    "file": _redact_sensitive(raw_file)
-                                })
-                    if text_parts:
-                        combined = "\n".join(text_parts)[:5000]
-                        combined = _redact_sensitive(combined)
-                        messages.append({
-                            "role": "assistant",
-                            "index": line_no,
-                            "text": combined
-                        })
-
-    except Exception as e:
-        print(f"  [collect] Error reading {jsonl_path}: {e}", file=sys.stderr)
-        return None
-
-    if user_msg_count < MIN_USER_MESSAGES:
-        return None
-
-    return {
-        "client": "claude_code",
-        "session_file": _session_identifier("claude_code", jsonl_path.name),
-        "display_name": jsonl_path.name,
-        "session_path": str(jsonl_path),
-        "message_count": len(messages),
-        "user_message_count": user_msg_count,
-        "tool_use_count": len(tool_uses),
-        "messages": messages,
-        "tool_uses": tool_uses,
-        "source": "claude_projects",
-    }
+    return _transcripts.extract_claude_session(jsonl_path)
 
 
 def extract_codex_session(jsonl_path: Path) -> dict | None:
     """Extract clean transcript from a Codex JSONL session."""
-    messages = []
-    tool_uses = []
-    user_msg_count = 0
-    session_meta: dict = {}
-
-    try:
-        with open(jsonl_path, "r") as f:
-            for line_no, line in enumerate(f, 1):
-                line = line.strip()
-                if not line:
-                    continue
-                try:
-                    d = json.loads(line)
-                except json.JSONDecodeError:
-                    continue
-
-                item_type = d.get("type")
-                payload = d.get("payload", {})
-
-                if item_type == "session_meta" and isinstance(payload, dict):
-                    session_meta = payload
-                    continue
-
-                if item_type == "event_msg" and isinstance(payload, dict) and payload.get("type") == "user_message":
-                    content = str(payload.get("message", "") or "").strip()
-                    if not content or content.startswith("<environment_context>"):
-                        continue
-                    messages.append({
-                        "role": "user",
-                        "index": line_no,
-                        "text": _redact_sensitive(content[:5000]),
-                    })
-                    user_msg_count += 1
-                    continue
-
-                if item_type == "response_item" and isinstance(payload, dict):
-                    response_type = payload.get("type")
-                    role = payload.get("role")
-                    if response_type == "message" and role == "assistant":
-                        text_parts = []
-                        for block in payload.get("content", []) or []:
-                            if isinstance(block, dict) and block.get("type") == "output_text":
-                                text_parts.append(str(block.get("text", "")))
-                        combined = "\n".join(part for part in text_parts if part).strip()
-                        if combined:
-                            messages.append({
-                                "role": "assistant",
-                                "index": line_no,
-                                "text": _redact_sensitive(combined[:5000]),
-                            })
-                    elif response_type == "function_call":
-                        tool_uses.append({
-                            "tool": payload.get("name", ""),
-                            "input_keys": [],
-                            "file": _redact_sensitive(str(payload.get("arguments", ""))[:100]),
-                        })
-
-    except Exception as e:
-        print(f"  [collect] Error reading {jsonl_path}: {e}", file=sys.stderr)
-        return None
-
-    if user_msg_count < MIN_USER_MESSAGES:
-        return None
-
-    return {
-        "client": "codex",
-        "session_file": _session_identifier("codex", jsonl_path.name),
-        "display_name": jsonl_path.name,
-        "session_path": str(jsonl_path),
-        "message_count": len(messages),
-        "user_message_count": user_msg_count,
-        "tool_use_count": len(tool_uses),
-        "messages": messages,
-        "tool_uses": tool_uses,
-        "source": session_meta.get("source", "codex"),
-        "cwd": session_meta.get("cwd", ""),
-        "originator": session_meta.get("originator", ""),
-        "session_uid": session_meta.get("id", ""),
-    }
+    return _transcripts.extract_codex_session(jsonl_path)
 
 
 def collect_transcripts_since(since_iso: str, until_iso: str = "") -> list[dict]:
@@ -262,28 +94,7 @@ def collect_transcripts_since(since_iso: str, until_iso: str = "") -> list[dict]
     Uses a watermark approach: deep sleep tracks the last processed timestamp
     so nothing is missed regardless of when sessions happen (day, night, etc.).
     """
-    since_dt = datetime.fromisoformat(since_iso)
-    until_dt = datetime.fromisoformat(until_iso) if until_iso else datetime.now()
-
-    sessions = []
-    transcript_files: list[tuple[str, Path]] = [
-        ("claude_code", path) for path in find_claude_session_files()
-    ] + [
-        ("codex", path) for path in find_codex_session_files()
-    ]
-    for client, session_file in transcript_files:
-        try:
-            mtime = datetime.fromtimestamp(session_file.stat().st_mtime)
-        except OSError:
-            continue
-        if not (since_dt < mtime <= until_dt):
-            continue
-        session = extract_codex_session(session_file) if client == "codex" else extract_claude_session(session_file)
-        if session:
-            session["modified"] = mtime.isoformat()
-            sessions.append(session)
-    sessions.sort(key=lambda s: s["modified"])
-    return sessions
+    return _transcripts.collect_transcripts_since(since_iso, until_iso)
 
 
 # ── Database queries ──────────────────────────────────────────────────────

package/src/server.py

@@ -23,6 +23,15 @@ from tools_hot_context import (
     handle_recent_context_resolve,
     handle_hot_context_list,
 )
+from tools_transcripts import (
+    handle_transcript_recent,
+    handle_transcript_search,
+    handle_transcript_read,
+)
+from tools_system_catalog import (
+    handle_system_catalog,
+    handle_tool_explain,
+)
 from user_context import get_context as _get_ctx
 from tools_coordination import (
     handle_track, handle_untrack, handle_files,
@@ -209,6 +218,9 @@ mcp = FastMCP(
         "- **Delegate:** prefer direct. If needed: `nexo_context_packet(area)` + guard + 'if unsure STOP'\n"
         "- **Memory:** `nexo_recall` searches all. For fresh 24h continuity use `nexo_pre_action_context(query='...')` before acting and "
         "`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.), "
@@ -380,6 +392,36 @@ def nexo_hot_context_list(hours: int = 24, limit: int = 10, state: str = "") ->
     return handle_hot_context_list(hours, limit, state)
 
 
+@mcp.tool
+def nexo_transcript_recent(hours: int = 24, client: str = "", limit: int = 10) -> str:
+    """List recent Claude Code / Codex transcripts visible to NEXO."""
+    return handle_transcript_recent(hours, client, limit)
+
+
+@mcp.tool
+def nexo_transcript_search(query: str = "", hours: int = 24, client: str = "", limit: int = 10) -> str:
+    """Search recent transcripts directly when recall/hot-context are not enough."""
+    return handle_transcript_search(query, hours, client, limit)
+
+
+@mcp.tool
+def nexo_transcript_read(session_ref: str = "", transcript_path: str = "", client: str = "", max_messages: int = 80) -> str:
+    """Read a full transcript fallback by session id, transcript display name, session_uid, or exact path."""
+    return handle_transcript_read(session_ref, transcript_path, client, max_messages)
+
+
+@mcp.tool
+def nexo_system_catalog(section: str = "", query: str = "", limit: int = 20) -> str:
+    """Read NEXO's live system catalog built from core tools, plugins, skills, scripts, crons, projects, and artifacts."""
+    return handle_system_catalog(section, query, limit)
+
+
+@mcp.tool
+def nexo_tool_explain(name: str) -> str:
+    """Explain a live NEXO tool/capability from the generated system catalog."""
+    return handle_tool_explain(name)
+
+
 @mcp.tool
 def nexo_smart_startup() -> str:
     """Pre-load relevant cognitive memories based on pending followups, due reminders, and last session topics.