nexo-brain 3.1.9 → 3.2.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "3.1.9",
+  "version": "3.2.0",
   "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

@@ -21,6 +21,7 @@
 Start here:
 - [5-minute quickstart](docs/quickstart-5-minutes.md)
 - [Workflow quickstart](docs/workflows-quickstart.md)
+- [Recent memory fallbacks + live system catalog](docs/recent-memory-fallbacks-and-system-catalog.md)
 - [Supported client guides](docs/integrations/cursor.md)
 - [Docker setup](docs/docker-setup.md)
 - [Architecture visuals](docs/architecture-visuals.md)
@@ -79,6 +80,13 @@ Versions `3.0.0` and `3.0.1` close the next execution gap:
   - `cost_per_solved_task`
   - SDK/API/quickstart surface
 
+Versions `3.1.7` through `3.2.0` close the recent-memory gap:
+
+- recent operational continuity is now first-class through `hot context` and `recent events`
+- the runtime can build a reusable pre-action bundle instead of reconstructing the last few hours from diaries and durable recall only
+- when even that misses, NEXO now exposes raw transcript fallback tools for Claude Code and Codex session stores
+- NEXO can now inspect itself through a live system catalog derived from canonical sources instead of relying only on stale docs or operator memory
+
 ### Client Capability Matrix
 
 | Capability | Claude Code | Codex | Claude Desktop |
@@ -340,6 +348,15 @@ NEXO Brain provides **150+ MCP tools** across 23 categories. These features impl
 | **Auto-Merge Duplicates** | Batch cosine deduplication during the 03:00 sleep cycle. Respects sibling discrimination — similar memories about different contexts are kept separate. |
 | **Memory Dreaming** | Discovers hidden connections between recent memories during the 03:00 sleep cycle and now feeds a 60-day long-horizon Deep Sleep blend, so older patterns can reappear when they become relevant again. |
 
+### Operational Continuity
+
+| Feature | What It Does |
+|---------|-------------|
+| **Hot Context 24h** | Keeps active topics, blockers, and waiting states fresh across sessions, clients, cron ticks, and channel changes. This is the shared recent-memory substrate for operational continuity. |
+| **Pre-Action Context Bundle** | Loads recent contexts, recent events, related reminders, and related followups before acting, so continuity is explicit instead of prompt-only. |
+| **Transcript Fallback** | When recent-memory capture is thin or missing, NEXO can now search and read recent Claude Code / Codex transcripts directly through MCP instead of pretending the conversation is lost. |
+| **Live System Catalog** | NEXO can now inspect its own current surface — core tools, plugin tools, skills, scripts, crons, projects, and artifacts — through a live catalog derived from canonical sources at read time. |
+
 ### Retrieval
 
 | Feature | What It Does |
@@ -724,10 +741,14 @@ Public entry points for the mental model now stay intentionally small:
 - `nexo_memory_recall`
 - `nexo_consolidate`
 - `nexo_run_workflow`
+- `nexo_pre_action_context`
+- `nexo_transcript_search`
+- `nexo_system_catalog`
 
 If you want the shell or Python wrappers instead of raw MCP tools:
 - [docs/quickstart-5-minutes.md](docs/quickstart-5-minutes.md)
 - [docs/memory-classes.md](docs/memory-classes.md)
+- [docs/recent-memory-fallbacks-and-system-catalog.md](docs/recent-memory-fallbacks-and-system-catalog.md)
 - [docs/sdk-python.md](docs/sdk-python.md)
 - [docs/reference-verticals.md](docs/reference-verticals.md)
 - [compare/README.md](compare/README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "3.1.9",
+  "version": "3.2.0",
   "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/scripts/deep-sleep/collect.py

@@ -19,6 +19,7 @@ import sys
 from collections import Counter
 from datetime import datetime, timedelta
 from pathlib import Path
+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", ""))
@@ -64,196 +65,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 +89,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,8 @@ 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. "
         "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 +391,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.

package/src/system_catalog.py

@@ -0,0 +1,419 @@
+from __future__ import annotations
+"""Live system catalog / ontology derived from canonical NEXO sources."""
+
+import ast
+import importlib.util
+import json
+import os
+import sys
+from pathlib import Path
+
+from db import get_db, list_skills, sync_skill_directories
+from plugin_loader import PERSONAL_PLUGINS_DIR, PLUGINS_DIR, list_plugins
+from script_registry import list_scripts
+
+NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+NEXO_CODE = Path(__file__).resolve().parent
+SERVER_PATH = NEXO_CODE / "server.py"
+MANIFEST_PATHS = [NEXO_CODE / "crons" / "manifest.json", NEXO_HOME / "crons" / "manifest.json"]
+ATLAS_PATH = NEXO_HOME / "brain" / "project-atlas.json"
+
+SECTION_ORDER = (
+    "core_tools",
+    "plugin_tools",
+    "skills",
+    "scripts",
+    "crons",
+    "projects",
+    "artifacts",
+)
+
+
+def _normalize_text(text: str | None) -> str:
+    return str(text or "").strip().lower()
+
+
+def _tokenize(text: str | None) -> set[str]:
+    import re
+    normalized = _normalize_text(text)
+    return {
+        token
+        for token in re.findall(r"[a-z0-9][a-z0-9._:-]{1,}", normalized)
+        if len(token) >= 3
+    }
+
+
+def _score(query_tokens: set[str], haystack: str) -> float:
+    if not query_tokens:
+        return 0.0
+    haystack_tokens = _tokenize(haystack)
+    if not haystack_tokens:
+        return 0.0
+    overlap = query_tokens & haystack_tokens
+    if not overlap:
+        return 0.0
+    return len(overlap) / max(1, min(len(query_tokens), len(haystack_tokens)))
+
+
+def _truncate(text: str | None, limit: int = 180) -> str:
+    clean = str(text or "").strip()
+    if len(clean) <= limit:
+        return clean
+    return clean[: limit - 3] + "..."
+
+
+def _tool_category(name: str) -> str:
+    if name.startswith("nexo_recent_context") or name.startswith("nexo_pre_action_context") or name.startswith("nexo_hot_context"):
+        return "recent_memory"
+    if name.startswith("nexo_transcript"):
+        return "transcripts"
+    if name.startswith("nexo_session") or name.startswith("nexo_checkpoint"):
+        return "sessions"
+    if name.startswith("nexo_followup") or name.startswith("nexo_reminder"):
+        return "reminders"
+    if name.startswith("nexo_skill"):
+        return "skills"
+    if name.startswith("nexo_plugin"):
+        return "plugins"
+    if name.startswith("nexo_goal") or name.startswith("nexo_workflow"):
+        return "workflow"
+    if name.startswith("nexo_learning"):
+        return "learnings"
+    if name.startswith("nexo_guard") or name.startswith("nexo_task") or name.startswith("nexo_cortex"):
+        return "protocol"
+    return "general"
+
+
+def _parse_core_tools() -> list[dict]:
+    if not SERVER_PATH.is_file():
+        return []
+    try:
+        tree = ast.parse(SERVER_PATH.read_text())
+    except Exception:
+        return []
+
+    entries: list[dict] = []
+    for node in tree.body:
+        if not isinstance(node, ast.FunctionDef):
+            continue
+        if not any(
+            isinstance(dec, ast.Attribute) and getattr(dec.value, "id", "") == "mcp" and dec.attr == "tool"
+            for dec in node.decorator_list
+        ):
+            continue
+        doc = ast.get_docstring(node) or ""
+        first_line = doc.strip().splitlines()[0].strip() if doc.strip() else ""
+        entries.append(
+            {
+                "kind": "core_tool",
+                "name": node.name,
+                "description": first_line,
+                "category": _tool_category(node.name),
+                "path": str(SERVER_PATH),
+                "line": int(getattr(node, "lineno", 0) or 0),
+                "source": "core",
+            }
+        )
+    return entries
+
+
+def _plugin_module_tools(filename: str, created_by: str) -> dict[str, str]:
+    module_name = f"plugins.{filename[:-3]}"
+    module = sys.modules.get(module_name)
+    if module is None:
+        plugin_dir = PLUGINS_DIR if created_by == "repo" else PERSONAL_PLUGINS_DIR
+        path = Path(plugin_dir) / filename
+        if not path.is_file():
+            return {}
+        try:
+            spec = importlib.util.spec_from_file_location(module_name, path)
+            if spec is None or spec.loader is None:
+                return {}
+            module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(module)
+        except Exception:
+            return {}
+    tools = getattr(module, "TOOLS", []) or []
+    result: dict[str, str] = {}
+    for item in tools:
+        try:
+            _, name, description = item
+        except Exception:
+            continue
+        result[str(name)] = str(description or "")
+    return result
+
+
+def _plugin_entries() -> list[dict]:
+    rows = list_plugins()
+    entries: list[dict] = []
+    for row in rows:
+        filename = str(row.get("filename") or "")
+        created_by = str(row.get("created_by") or row.get("source") or "repo")
+        descriptions = _plugin_module_tools(filename, created_by)
+        names = str(row.get("tool_names") or "").split(",")
+        for name in [n.strip() for n in names if n.strip()]:
+            entries.append(
+                {
+                    "kind": "plugin_tool",
+                    "name": name,
+                    "description": descriptions.get(name, ""),
+                    "plugin": filename,
+                    "source": created_by,
+                    "category": _tool_category(name),
+                }
+            )
+    return entries
+
+
+def _skill_entries() -> list[dict]:
+    try:
+        sync_skill_directories()
+    except Exception:
+        pass
+    entries: list[dict] = []
+    for row in list_skills():
+        entries.append(
+            {
+                "kind": "skill",
+                "name": row.get("id", ""),
+                "display_name": row.get("name", ""),
+                "description": row.get("description", "") or "",
+                "source": row.get("source_kind", "") or "",
+                "level": row.get("level", "") or "",
+                "mode": row.get("mode", "") or "",
+                "execution_level": row.get("execution_level", "") or "",
+                "trust_score": row.get("trust_score", 0),
+                "tags": row.get("tags", "[]"),
+            }
+        )
+    return entries
+
+
+def _script_entries() -> list[dict]:
+    entries: list[dict] = []
+    for row in list_scripts(include_core=True):
+        entries.append(
+            {
+                "kind": "script",
+                "name": row.get("name", ""),
+                "description": row.get("description", "") or "",
+                "runtime": row.get("runtime", "") or "",
+                "path": row.get("path", "") or "",
+                "source": "core" if row.get("core") else "personal",
+                "classification": row.get("classification", "") or "",
+                "declared_schedule": row.get("declared_schedule", {}) or {},
+            }
+        )
+    return entries
+
+
+def _cron_entries() -> list[dict]:
+    manifest = None
+    for path in MANIFEST_PATHS:
+        if path.is_file():
+            try:
+                manifest = json.loads(path.read_text())
+                break
+            except Exception:
+                continue
+    if not isinstance(manifest, dict):
+        return []
+    entries: list[dict] = []
+    for cron in manifest.get("crons", []) or []:
+        entries.append(
+            {
+                "kind": "cron",
+                "name": cron.get("id", ""),
+                "description": cron.get("description", "") or "",
+                "script": cron.get("script", "") or "",
+                "schedule": cron.get("schedule", {}) or {},
+                "optional": bool(cron.get("optional", False)),
+            }
+        )
+    return entries
+
+
+def _project_entries() -> list[dict]:
+    if not ATLAS_PATH.is_file():
+        return []
+    try:
+        payload = json.loads(ATLAS_PATH.read_text())
+    except Exception:
+        return []
+    entries: list[dict] = []
+    if isinstance(payload, dict):
+        for key, value in payload.items():
+            if str(key).startswith("_"):
+                continue
+            if not isinstance(value, dict):
+                continue
+            entries.append(
+                {
+                    "kind": "project",
+                    "name": key,
+                    "path": value.get("path", "") or "",
+                    "domain": value.get("domain", "") or "",
+                    "aliases": value.get("aliases", []) or [],
+                    "services": value.get("services", {}) or {},
+                    "plugins": value.get("plugins", "") or value.get("plugin_path", "") or "",
+                }
+            )
+    return entries
+
+
+def _artifact_entries() -> list[dict]:
+    conn = get_db()
+    try:
+        rows = conn.execute(
+            "SELECT canonical_name, kind, domain, state, uri, paths, ports, aliases FROM artifact_registry ORDER BY last_touched_at DESC LIMIT 100"
+        ).fetchall()
+    except Exception:
+        return []
+    return [
+        {
+            "kind": "artifact",
+            "name": row["canonical_name"],
+            "artifact_kind": row["kind"],
+            "domain": row["domain"],
+            "state": row["state"],
+            "uri": row["uri"],
+            "paths": row["paths"],
+            "ports": row["ports"],
+            "aliases": row["aliases"],
+        }
+        for row in rows
+    ]
+
+
+def build_system_catalog() -> dict:
+    catalog = {
+        "core_tools": _parse_core_tools(),
+        "plugin_tools": _plugin_entries(),
+        "skills": _skill_entries(),
+        "scripts": _script_entries(),
+        "crons": _cron_entries(),
+        "projects": _project_entries(),
+        "artifacts": _artifact_entries(),
+    }
+    catalog["summary"] = {
+        section: len(catalog.get(section) or [])
+        for section in SECTION_ORDER
+    }
+    return catalog
+
+
+def search_system_catalog(query: str, *, section: str = "", limit: int = 20) -> list[dict]:
+    catalog = build_system_catalog()
+    query_tokens = _tokenize(query)
+    sections = [section] if section in SECTION_ORDER else list(SECTION_ORDER)
+    matches: list[dict] = []
+    for section_name in sections:
+        for entry in catalog.get(section_name) or []:
+            haystack = " ".join(
+                [
+                    section_name,
+                    str(entry.get("name", "") or ""),
+                    str(entry.get("display_name", "") or ""),
+                    str(entry.get("description", "") or ""),
+                    str(entry.get("source", "") or ""),
+                    str(entry.get("category", "") or ""),
+                    str(entry.get("plugin", "") or ""),
+                    str(entry.get("domain", "") or ""),
+                    str(entry.get("path", "") or ""),
+                    json.dumps(entry, ensure_ascii=False),
+                ]
+            )
+            score = _score(query_tokens, haystack) if query_tokens else 0.5
+            if query_tokens and score <= 0:
+                continue
+            row = dict(entry)
+            row["_section"] = section_name
+            row["_score"] = round(score, 4)
+            matches.append(row)
+    matches.sort(key=lambda row: (row["_score"], row.get("name", "")), reverse=True)
+    return matches[: max(1, int(limit or 20))]
+
+
+def explain_tool(name: str) -> dict | None:
+    clean = _normalize_text(name)
+    if not clean:
+        return None
+    exact = search_system_catalog(clean, limit=200)
+    for row in exact:
+        if _normalize_text(row.get("name")) == clean:
+            return row
+    for row in exact:
+        if clean in _normalize_text(row.get("name")):
+            return row
+    return None
+
+
+def format_catalog(catalog: dict, *, section: str = "", query: str = "", limit: int = 20) -> str:
+    summary = catalog.get("summary") or {}
+    if query:
+        matches = search_system_catalog(query, section=section, limit=limit)
+        if not matches:
+            scope = section or "all sections"
+            return f"No system-catalog matches for '{query}' in {scope}."
+        lines = [f"SYSTEM CATALOG SEARCH — '{query}' ({len(matches)} match(es))"]
+        for row in matches:
+            label = row.get("_section", "")
+            title = row.get("display_name") or row.get("name") or "(unnamed)"
+            desc = _truncate(row.get("description") or row.get("path") or row.get("script") or "", 180)
+            suffix = f" — {desc}" if desc else ""
+            lines.append(f"- [{label}] {title}{suffix}")
+        return "\n".join(lines)
+
+    if section in SECTION_ORDER:
+        entries = catalog.get(section) or []
+        if not entries:
+            return f"SYSTEM CATALOG — {section}: empty"
+        lines = [f"SYSTEM CATALOG — {section} ({len(entries)})"]
+        for row in entries[: max(1, int(limit or 20))]:
+            title = row.get("display_name") or row.get("name") or "(unnamed)"
+            desc = _truncate(row.get("description") or row.get("path") or row.get("script") or "", 180)
+            suffix = f" — {desc}" if desc else ""
+            lines.append(f"- {title}{suffix}")
+        return "\n".join(lines)
+
+    lines = ["SYSTEM CATALOG SUMMARY"]
+    for name in SECTION_ORDER:
+        lines.append(f"- {name}: {summary.get(name, 0)}")
+    return "\n".join(lines)
+
+
+def format_tool_explanation(entry: dict | None) -> str:
+    if not entry:
+        return "Tool/capability not found in the live system catalog."
+    lines = [
+        f"CATALOG ENTRY — {entry.get('name') or entry.get('display_name')}",
+        f"Section: {entry.get('_section') or entry.get('kind')}",
+    ]
+    if entry.get("display_name"):
+        lines.append(f"Display name: {entry['display_name']}")
+    if entry.get("description"):
+        lines.append(f"Description: {entry['description']}")
+    if entry.get("category"):
+        lines.append(f"Category: {entry['category']}")
+    if entry.get("source"):
+        lines.append(f"Source: {entry['source']}")
+    if entry.get("plugin"):
+        lines.append(f"Plugin: {entry['plugin']}")
+    if entry.get("path"):
+        lines.append(f"Path: {entry['path']}")
+    if entry.get("line"):
+        lines.append(f"Line: {entry['line']}")
+    if entry.get("script"):
+        lines.append(f"Script: {entry['script']}")
+    if entry.get("runtime"):
+        lines.append(f"Runtime: {entry['runtime']}")
+    if entry.get("level"):
+        lines.append(f"Level: {entry['level']}")
+    if entry.get("mode"):
+        lines.append(f"Mode: {entry['mode']}")
+    if entry.get("execution_level"):
+        lines.append(f"Execution level: {entry['execution_level']}")
+    if entry.get("domain"):
+        lines.append(f"Domain: {entry['domain']}")
+    return "\n".join(lines)

package/src/tools_system_catalog.py

@@ -0,0 +1,19 @@
+"""Public MCP tools for the live NEXO system catalog / ontology."""
+
+from __future__ import annotations
+
+from system_catalog import build_system_catalog, explain_tool, format_catalog, format_tool_explanation
+
+
+def handle_system_catalog(section: str = "", query: str = "", limit: int = 20) -> str:
+    catalog = build_system_catalog()
+    return format_catalog(
+        catalog,
+        section=(section or "").strip(),
+        query=(query or "").strip(),
+        limit=max(1, int(limit or 20)),
+    )
+
+
+def handle_tool_explain(name: str) -> str:
+    return format_tool_explanation(explain_tool(name))

package/src/tools_transcripts.py

@@ -0,0 +1,98 @@
+"""Public MCP tools for transcript fallback access."""
+
+from __future__ import annotations
+
+from transcript_utils import (
+    clamp_transcript_hours,
+    list_recent_transcripts,
+    load_transcript,
+    search_transcripts,
+)
+
+
+def handle_transcript_search(query: str = "", hours: int = 24, client: str = "", limit: int = 10) -> str:
+    """Search recent Claude Code / Codex transcripts as a fallback when memory is insufficient."""
+    window = clamp_transcript_hours(hours)
+    rows = search_transcripts(query or "", hours=window, client=(client or "").strip(), limit=limit)
+    if not rows:
+        scope = f"query='{query}'" if query else "recent transcripts"
+        return f"No transcript matches for {scope} in the last {window}h."
+
+    lines = [f"TRANSCRIPTS ({len(rows)}) — last {window}h"]
+    for item in rows:
+        lines.append(
+            f"- {item.get('session_file')}: [{item.get('client')}] {item.get('display_name')} "
+            f"(modified={item.get('modified')}, messages={item.get('message_count')}, user={item.get('user_message_count')})"
+        )
+        if item.get("cwd"):
+            lines.append(f"  cwd: {item['cwd']}")
+        if item.get("session_uid"):
+            lines.append(f"  session_uid: {item['session_uid']}")
+        for snippet in item.get("matched_messages") or []:
+            lines.append(
+                f"  [{snippet.get('role')}#{snippet.get('index')}] {snippet.get('snippet')}"
+            )
+    return "\n".join(lines)
+
+
+def handle_transcript_recent(hours: int = 24, client: str = "", limit: int = 10) -> str:
+    """List recent transcripts without searching full text."""
+    window = clamp_transcript_hours(hours)
+    rows = list_recent_transcripts(hours=window, client=(client or "").strip(), limit=limit)
+    if not rows:
+        return f"No transcripts found in the last {window}h."
+
+    lines = [f"RECENT TRANSCRIPTS ({len(rows)}) — last {window}h"]
+    for item in rows:
+        lines.append(
+            f"- {item.get('session_file')}: [{item.get('client')}] {item.get('display_name')} "
+            f"(modified={item.get('modified')}, messages={item.get('message_count')}, user={item.get('user_message_count')})"
+        )
+    return "\n".join(lines)
+
+
+def handle_transcript_read(
+    session_ref: str = "",
+    transcript_path: str = "",
+    client: str = "",
+    max_messages: int = 80,
+) -> str:
+    """Read a transcript in fallback mode. Accepts session_file, display name, session_uid or exact path."""
+    transcript = load_transcript(
+        session_ref=(session_ref or "").strip(),
+        transcript_path=(transcript_path or "").strip(),
+        client=(client or "").strip(),
+    )
+    if not transcript:
+        target = session_ref or transcript_path or "(empty ref)"
+        return f"Transcript not found for {target}."
+
+    limit = max(1, min(int(max_messages or 80), 200))
+    messages = transcript.get("messages") or []
+    truncated = len(messages) > limit
+    visible = messages[-limit:] if truncated else messages
+
+    lines = [
+        f"TRANSCRIPT {transcript.get('session_file')}",
+        f"Client: {transcript.get('client')}",
+        f"Display: {transcript.get('display_name')}",
+        f"Path: {transcript.get('session_path')}",
+        f"Modified: {transcript.get('modified')}",
+        f"Messages: {transcript.get('message_count')} (user={transcript.get('user_message_count')}, tools={transcript.get('tool_use_count')})",
+    ]
+    if transcript.get("cwd"):
+        lines.append(f"CWD: {transcript.get('cwd')}")
+    if transcript.get("session_uid"):
+        lines.append(f"Session UID: {transcript.get('session_uid')}")
+    if truncated:
+        lines.append(f"Showing last {limit} messages.")
+
+    for message in visible:
+        role = str(message.get("role") or "?").upper()
+        index = message.get("index", "?")
+        text = str(message.get("text") or "").strip()
+        lines.append("")
+        lines.append(f"[{role} #{index}]")
+        lines.append(text)
+
+    return "\n".join(lines)

package/src/transcript_utils.py

@@ -0,0 +1,412 @@
+from __future__ import annotations
+"""Shared transcript helpers for Deep Sleep and public MCP fallback tools."""
+
+import json
+import os
+import re
+import unicodedata
+from datetime import datetime, timedelta
+from pathlib import Path
+
+MIN_USER_MESSAGES = 3
+DEFAULT_TRANSCRIPT_HOURS = 24
+MAX_TRANSCRIPT_HOURS = 30 * 24
+
+_SENSITIVE_PATTERNS = re.compile(
+    r'(?:'
+    r'sk-ant-[A-Za-z0-9_-]+'
+    r'|shpat_[A-Fa-f0-9]+'
+    r'|shpss_[A-Fa-f0-9]+'
+    r'|sk-[A-Za-z0-9]{20,}'
+    r'|ghp_[A-Za-z0-9]{36,}'
+    r'|gho_[A-Za-z0-9]{36,}'
+    r'|AIza[A-Za-z0-9_-]{35}'
+    r'|ya29\.[A-Za-z0-9_-]+'
+    r'|xox[bpsa]-[A-Za-z0-9-]+'
+    r'|EAAG[A-Za-z0-9]+'
+    r'|[Pp]assword\s*[:=]\s*\S+'
+    r'|[Ss]ecret\s*[:=]\s*\S+'
+    r'|[Tt]oken\s*[:=]\s*\S+'
+    r'|[Aa]pi[_-]?[Kk]ey\s*[:=]\s*\S+'
+    r')'
+)
+
+
+def _redact_sensitive(text: str) -> str:
+    return _SENSITIVE_PATTERNS.sub("[REDACTED]", text)
+
+
+def _normalize_text(text: str | None) -> str:
+    if not text:
+        return ""
+    normalized = unicodedata.normalize("NFKD", str(text))
+    ascii_text = normalized.encode("ascii", "ignore").decode("ascii")
+    return ascii_text.lower()
+
+
+def _tokenize(text: str | None) -> set[str]:
+    normalized = _normalize_text(text)
+    return {
+        token
+        for token in re.findall(r"[a-z0-9][a-z0-9._:-]{1,}", normalized)
+        if len(token) >= 3
+    }
+
+
+def _score_text_match(query_tokens: set[str], haystack: str) -> float:
+    if not query_tokens:
+        return 0.0
+    haystack_tokens = _tokenize(haystack)
+    if not haystack_tokens:
+        return 0.0
+    intersection = query_tokens & haystack_tokens
+    if not intersection:
+        return 0.0
+    smaller = min(len(query_tokens), len(haystack_tokens))
+    return len(intersection) / max(1, smaller)
+
+
+def _truncate(text: str | None, limit: int = 240) -> str:
+    if not text:
+        return ""
+    clean = str(text).strip()
+    return clean if len(clean) <= limit else clean[: limit - 3] + "..."
+
+
+def _session_identifier(client: str, session_file: str) -> str:
+    return f"{client}:{session_file}"
+
+
+def _claude_root() -> Path:
+    return Path.home() / ".claude" / "projects"
+
+
+def _codex_roots() -> list[Path]:
+    return [
+        Path.home() / ".codex" / "sessions",
+        Path.home() / ".codex" / "archived_sessions",
+    ]
+
+
+def clamp_transcript_hours(hours: int | float | str | None) -> int:
+    try:
+        value = int(float(hours or DEFAULT_TRANSCRIPT_HOURS))
+    except Exception:
+        value = DEFAULT_TRANSCRIPT_HOURS
+    return max(1, min(value, MAX_TRANSCRIPT_HOURS))
+
+
+def find_claude_session_files() -> list[Path]:
+    claude_dir = _claude_root()
+    if not claude_dir.exists():
+        return []
+    return sorted(claude_dir.rglob("*.jsonl"))
+
+
+def find_codex_session_files() -> list[Path]:
+    files: list[Path] = []
+    seen: set[str] = set()
+    for root in _codex_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
+
+
+def extract_claude_session(jsonl_path: Path) -> dict | None:
+    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:
+                    payload = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+
+                msg_type = payload.get("type")
+                if msg_type == "user":
+                    content = payload.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": payload.get("uuid", ""),
+                            }
+                        )
+                        user_msg_count += 1
+                elif msg_type in ("message", "assistant"):
+                    msg = payload.get("message", {})
+                    content_blocks = msg.get("content", [])
+                    text_parts = []
+                    for block in content_blocks:
+                        if not isinstance(block, dict):
+                            continue
+                        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),
+                                }
+                            )
+                    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]),
+                            }
+                        )
+    except Exception:
+        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",
+    }
+
+
+def extract_codex_session(jsonl_path: Path) -> dict | None:
+    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:
+                    payload = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+
+                item_type = payload.get("type")
+                data = payload.get("payload", {})
+
+                if item_type == "session_meta" and isinstance(data, dict):
+                    session_meta = data
+                    continue
+
+                if item_type == "event_msg" and isinstance(data, dict) and data.get("type") == "user_message":
+                    content = str(data.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(data, dict):
+                    response_type = data.get("type")
+                    role = data.get("role")
+                    if response_type == "message" and role == "assistant":
+                        text_parts = []
+                        for block in data.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": data.get("name", ""),
+                                "input_keys": [],
+                                "file": _redact_sensitive(str(data.get("arguments", ""))[:100]),
+                            }
+                        )
+    except Exception:
+        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", ""),
+    }
+
+
+def collect_transcripts_since(since_iso: str, until_iso: str = "") -> list[dict]:
+    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 row: row["modified"])
+    return sessions
+
+
+def list_recent_transcripts(hours: int = DEFAULT_TRANSCRIPT_HOURS, client: str = "", limit: int = 10) -> list[dict]:
+    window = clamp_transcript_hours(hours)
+    since = datetime.now() - timedelta(hours=window)
+    sessions = collect_transcripts_since(since.isoformat())
+    filtered = []
+    for item in sessions:
+        if client and item.get("client") != client:
+            continue
+        filtered.append(item)
+    filtered.sort(key=lambda row: row.get("modified", ""), reverse=True)
+    return filtered[: max(1, int(limit or 10))]
+
+
+def search_transcripts(query: str, *, hours: int = DEFAULT_TRANSCRIPT_HOURS, client: str = "", limit: int = 10) -> list[dict]:
+    rows = list_recent_transcripts(hours=hours, client=client, limit=200)
+    query_tokens = _tokenize(query)
+    if not query_tokens:
+        return rows[: max(1, int(limit or 10))]
+
+    matches: list[dict] = []
+    cutoff_seconds = clamp_transcript_hours(hours) * 3600
+    now = datetime.now().timestamp()
+    for item in rows:
+        snippets = []
+        best_score = 0.0
+        for message in item.get("messages") or []:
+            text = str(message.get("text", "") or "")
+            score = _score_text_match(query_tokens, text)
+            if score <= 0:
+                continue
+            best_score = max(best_score, score)
+            snippets.append(
+                {
+                    "role": message.get("role", ""),
+                    "index": message.get("index", 0),
+                    "snippet": _truncate(text, 220),
+                    "score": round(score, 4),
+                }
+            )
+        meta_text = " ".join(
+            [
+                str(item.get("display_name", "") or ""),
+                str(item.get("session_file", "") or ""),
+                str(item.get("source", "") or ""),
+                str(item.get("cwd", "") or ""),
+            ]
+        )
+        meta_score = _score_text_match(query_tokens, meta_text)
+        best_score = max(best_score, meta_score)
+        if best_score <= 0:
+            continue
+        modified = item.get("modified", "")
+        try:
+            modified_ts = datetime.fromisoformat(modified).timestamp()
+        except Exception:
+            modified_ts = now
+        recency = max(0.0, 1.0 - ((now - modified_ts) / max(1, cutoff_seconds)))
+        item["_score"] = round(best_score + recency * 0.35, 4)
+        item["matched_messages"] = sorted(snippets, key=lambda row: row["score"], reverse=True)[:3]
+        matches.append(item)
+
+    matches.sort(key=lambda row: (row.get("_score", 0), row.get("modified", "")), reverse=True)
+    return matches[: max(1, int(limit or 10))]
+
+
+def load_transcript(session_ref: str = "", transcript_path: str = "", client: str = "") -> dict | None:
+    ref = str(session_ref or "").strip()
+    path_ref = str(transcript_path or "").strip()
+
+    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 detected_client, path in transcript_files:
+        if client and detected_client != client:
+            continue
+        if path_ref:
+            try:
+                if Path(path_ref).expanduser().resolve() != path.resolve():
+                    continue
+            except Exception:
+                continue
+        session = extract_codex_session(path) if detected_client == "codex" else extract_claude_session(path)
+        if not session:
+            continue
+        if ref:
+            if ref not in {
+                str(session.get("session_file", "")),
+                str(session.get("display_name", "")),
+                str(session.get("session_uid", "")),
+                str(path),
+            }:
+                continue
+        try:
+            session["modified"] = datetime.fromtimestamp(path.stat().st_mtime).isoformat()
+        except OSError:
+            session["modified"] = ""
+        return session
+    return None