nexo-brain 3.1.8 → 3.2.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "3.1.8",
+  "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.8",
+  "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/auto_update.py

@@ -1186,27 +1186,38 @@ def _source_repo_status(repo_dir: Path) -> dict:
     }
 
 
+def _discover_runtime_root_python_modules(base_dir: Path) -> list[str]:
+    """Return every top-level runtime `.py` module in the source/runtime root."""
+    if not base_dir.is_dir():
+        return []
+    modules: list[str] = []
+    for item in sorted(base_dir.iterdir(), key=lambda path: path.name):
+        if not item.is_file() or item.suffix != ".py":
+            continue
+        if item.name.startswith(".") or item.name == "__init__.py":
+            continue
+        modules.append(item.name)
+    return modules
+
+
+def _runtime_flat_files(base_dir: Path) -> list[str]:
+    ordered: list[str] = []
+    seen: set[str] = set()
+    for name in _discover_runtime_root_python_modules(base_dir) + ["requirements.txt", "package.json", "version.json"]:
+        if name in seen:
+            continue
+        seen.add(name)
+        ordered.append(name)
+    return ordered
+
+
 def _backup_runtime_tree(dest: Path = NEXO_HOME) -> str:
     timestamp = time.strftime("%Y-%m-%d-%H%M%S")
     backup_dir = NEXO_HOME / "backups" / f"runtime-tree-{timestamp}"
     backup_dir.mkdir(parents=True, exist_ok=True)
 
     code_dirs = ["hooks", "plugins", "db", "cognitive", "dashboard", "rules", "crons", "scripts", "doctor", "skills-core"]
-    flat_files = [
-        "server.py", "plugin_loader.py", "knowledge_graph.py", "kg_populate.py",
-        "maintenance.py", "storage_router.py", "claim_graph.py", "hnsw_index.py",
-        "evolution_cycle.py", "migrate_embeddings.py", "auto_close_sessions.py",
-        "client_sync.py",
-        "client_preferences.py", "agent_runner.py", "bootstrap_docs.py",
-        "hook_guardrails.py", "protocol_settings.py", "public_evolution_queue.py",
-        "auto_update.py", "tools_sessions.py", "tools_coordination.py",
-        "tools_hot_context.py",
-        "tools_reminders.py", "tools_reminders_crud.py", "tools_learnings.py",
-        "tools_credentials.py", "tools_task_history.py", "tools_menu.py",
-        "cli.py", "script_registry.py", "skills_runtime.py", "user_context.py",
-        "public_contribution.py",
-        "cron_recovery.py", "runtime_power.py", "requirements.txt", "package.json", "version.json",
-    ]
+    flat_files = _runtime_flat_files(dest)
     for name in code_dirs:
         src = dest / name
         if src.is_dir():
@@ -1244,21 +1255,7 @@ def _copy_runtime_from_source(src_dir: Path, repo_dir: Path, dest: Path = NEXO_H
     import shutil
 
     packages = ["db", "cognitive", "doctor", "dashboard", "rules", "crons", "hooks"]
-    flat_files = [
-        "server.py", "plugin_loader.py", "knowledge_graph.py", "kg_populate.py",
-        "maintenance.py", "storage_router.py", "claim_graph.py", "hnsw_index.py",
-        "evolution_cycle.py", "migrate_embeddings.py", "auto_close_sessions.py",
-        "client_sync.py",
-        "client_preferences.py", "agent_runner.py", "bootstrap_docs.py",
-        "hook_guardrails.py", "protocol_settings.py", "public_evolution_queue.py",
-        "auto_update.py", "tools_sessions.py", "tools_coordination.py",
-        "tools_hot_context.py",
-        "tools_reminders.py", "tools_reminders_crud.py", "tools_learnings.py",
-        "tools_credentials.py", "tools_task_history.py", "tools_menu.py",
-        "cli.py", "script_registry.py", "skills_runtime.py", "user_context.py",
-        "public_contribution.py",
-        "cron_recovery.py", "runtime_power.py", "requirements.txt",
-    ]
+    flat_files = _runtime_flat_files(src_dir)
     copied_packages = 0
     copied_files = 0
 

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.