Register new session, clean stale ones, return active sessions + alerts.

Call this ONCE at the start of every conversation. Returns the session ID (SID) — store it for use in all other nexo_ tools.

Update session task, check inbox and pending questions. Auto-detects trust events.

Call this at the START of every user interaction (before doing work). Output always begins with a NOW_UTC line (ISO-8601, UTC) — use it as the authoritative wall-clock time for any artifact (emails, diaries, followups) to avoid date/day-of-week drift across long sessions. Args: sid: Your session ID from nexo_startup. task: Brief description of current work (5-10 words). context_hint: Last 2-3 sentences from the user or current topic. Used for sentiment detection, trust auto-scoring, and mid-session RAG. ALWAYS provide this for best results.

Cleanly close a session. Removes it from active sessions immediately.

Call this when ending a conversation to avoid ghost sessions. Args: sid: Session ID to close.

List active sessions. Filter by keyword if provided.

Write a durable continuity snapshot for Desktop/Brain handoff.

Read recent continuity snapshots by conversation_id or session_id.

Build the small continuity bundle Desktop injects after restore or stale resume loss.

Persist a compaction-related continuity event into the canonical snapshot stream.

Return the forensic continuity timeline for a conversation.

Build a context packet for subagent injection. Returns learnings + changes + followups + preferences + cognitive memories for a specific area.

MUST call before delegating ANY task to a subagent. Inject the result into the subagent's prompt.

Capture/update a recent 24h context item and append an event.

Use this for important ongoing threads that should stay mentally fresh across sessions/clients.

Read recent hot context and continuity events from the last N hours.

Build the 24h recent-context bundle that should be reviewed before acting.

Especially useful for emails, orchestrators, and any work where the same topic may reappear hours later.

Resolve a recent hot-context item and append a resolution event.

List hot-context items currently alive in the recent continuity window.

List recent Claude Code / Codex transcripts visible to NEXO.

Search recent transcripts directly when recall/hot-context are not enough.

Read a full transcript fallback by session id, transcript display name, session_uid, or exact path.

Read NEXO's live system catalog built from core tools, plugins, skills, scripts, crons, projects, and artifacts.

Explain a live NEXO tool/capability from the generated system catalog.

Temporarily override a Guardian rule's mode (Plan Consolidado 0.17).

Writes to ~/.nexo/config/guardian-runtime-overrides.json which guardian_config.rule_mode already honours at read time. Useful when a rule is noisy during an incident and needs to drop to shadow for an hour without a server restart.

Pre-load relevant cognitive memories based on pending followups, due reminders, and last session topics.

Call during startup (after nexo_startup) to ensure the session starts with the right context loaded. Returns up to 10 memories matching the current operational state.

Build a portable handoff packet for another client/runtime.

Use this when another client should continue the same work with explicit task/checkpoint/goal/workflow context instead of relying on memory alone.

Export a machine-readable session bundle for cross-client handoff or archival.

Save a session checkpoint for auto-compaction continuity.

Call this BEFORE context compaction to preserve session state. The PostCompact hook reads this checkpoint and re-injects it as a Core Memory Block, so the session continues seamlessly.

Read the latest session checkpoint. Used by PostCompact hook and for manual recovery.

Track files being edited. Detects conflicts with other sessions.

MUST call before editing any shared file. Args: sid: Your session ID. paths: List of absolute file paths to track.

Stop tracking files. If no paths given, releases all.

Show all tracked files across all active sessions with conflict detection.

Send a fire-and-forget message to another session or broadcast.

Ask a question to another session (they see it on next heartbeat).

Answer a pending question from another session.

Check if a question has been answered.

Check reminders and followups.

Generate the NEXO operations center menu with alerts and active sessions.

Shows: date, due alerts, all menu items by category, active sessions. Uses box-drawing characters for formatting.

Create a new reminder for the user.

Read a reminder with its history and usage rules.

IMPORTANT: before update/delete/restore/note, call this tool first and use the returned READ_TOKEN.

Update fields of an existing reminder. Only non-empty fields are changed.

IMPORTANT: call nexo_reminder_get first and pass its READ_TOKEN.

Mark a reminder as completed with today's date.

Append a note to reminder history.

IMPORTANT: call nexo_reminder_get first and pass its READ_TOKEN.

Restore a soft-deleted reminder back to PENDING.

IMPORTANT: call nexo_reminder_get first and pass its READ_TOKEN.

Soft-delete a reminder.

IMPORTANT: call nexo_reminder_get first and pass its READ_TOKEN.

Create a new agent followup (autonomous task).

Read a followup with its history and usage rules.

IMPORTANT: before update/delete/restore/note, call this tool first and use the returned READ_TOKEN.

Update fields of an existing followup. Only non-empty fields are changed.

IMPORTANT: call nexo_followup_get first and pass its READ_TOKEN.

Mark a followup as completed. Appends result to verification field.

Append a note to followup history.

IMPORTANT: call nexo_followup_get first and pass its READ_TOKEN.

Restore a soft-deleted followup back to PENDING.

IMPORTANT: call nexo_followup_get first and pass its READ_TOKEN.

Soft-delete a followup.

IMPORTANT: call nexo_followup_get first and pass its READ_TOKEN.

Add a new learning (resolved error, pattern, gotcha).

Search learnings by keyword. Searches title and content.

Scan recent decisions and surface those that conflict with a learning's prevention rule.

Closes Fase 2 item 3 of NEXO-AUDIT-2026-04-11. Use this when you add a new rule and want to retroactively check whether past decisions still hold. Creates deterministic NF-RETRO-L-D followups so the helper is idempotent across reruns. nexo_learning_add invokes this automatically when the new learning has a prevention field — call this tool manually only when you want to re-scan with a longer window or a different threshold.

List recent hook lifecycle runs and per-hook health summary.

Closes Fase 3 item 7 of NEXO-AUDIT-2026-04-11. Each NEXO hook (session-start, post-compact, pre-compact, inbox-hook, etc.) writes a row to hook_runs when it finishes via scripts/nexo-hook-record.py. This tool reads them back so the agent can answer "is the hook pipeline healthy?" without needing the dashboard or grepping log files.

Update a learning entry. Only non-empty fields are changed.

Delete a learning entry.

List all learnings, grouped by category.

Score learning quality so fragile rules can be strengthened before they mislead guard or retrieval.

Force full rebuild of the FTS5 search index. Use after bulk changes or if search seems stale.

Register a new directory for FTS5 search indexing. Survives restarts.

Remove a directory from FTS5 indexing and clean up its entries.

List all directories being indexed by FTS5 (builtin + dynamic).

Get credential value(s) for a service.

Store a new credential.

Update a credential's value and/or notes.

Delete credential(s). If no key, deletes all for the service.

List credentials (names and notes only, no values).

Record that an operational task was executed.

Show execution history for operational tasks.

Check which operational tasks are overdue based on their frequency.

Compares last execution date vs configured frequency. Returns overdue tasks or 'all tasks up to date'.

Load or reload a plugin. Searches repo plugins/ first, then NEXO_HOME/personal/plugins/.

List all loaded plugins and their tools, showing source (repo/personal).

Unregister a plugin's tools from MCP (does not delete files).

List autonomous drive/curiosity signals.

Drive signals are observations NEXO accumulates during normal work. When tension crosses threshold, NEXO investigates silently.

Reinforce a drive signal with a new observation.

Increases tension and may promote the signal status (latent → rising → ready).

Mark a drive signal as investigated with an outcome.

Call this after NEXO has autonomously investigated a READY signal.

Dismiss a drive signal (archived, not deleted).

Call this when a signal is not worth investigating.

Open an automation_runs row for an interactive Claude/Codex session.

Designed for clients that spawn Claude/Codex directly (notably NEXO Desktop, which runs a TypeScript process that shells out to the CLI without going through run_automation_prompt). Call this BEFORE spawning the child, store the returned session_id, then call nexo_session_log_close when the session ends.

Close an automation_runs row opened by nexo_session_log_create.

Get or compute adaptive personality mode (FLOW/NORMAL/TENSION) from 6 signals

View recent adaptive mode transitions and signal history

Trigger inter-session tension decay (severity-weighted)

Reset adaptive state for new session

Manual override: force FLOW/NORMAL/TENSION or CLEAR to return to auto

View adaptive weights — static vs learned, training stats, shadow mode, drift

Get an agent's full profile

Register a new agent

Update agent fields

List all registered agents

Remove an agent from registry

Register a new artifact (service, dashboard, script, API, etc.) in the Artifact Registry. Call this whenever NEXO creates, deploys, or discovers a runnable/accessible artifact.

Find artifacts using the retrieval ladder: exact alias → port/path → fuzzy token → recent. PRIMARY retrieval tool for when users reference something built/deployed. Handles natural language like 'the backend', 'that script', 'localhost something'.

Update an existing artifact. Only non-empty fields are changed.

Learn a new alias from user language. Call when the user refers to an artifact with an unregistered term (e.g., 'backend' for the NEXO Brain Dashboard).

List all registered artifacts, optionally filtered by kind, state, or recency.

Delete an artifact from the registry.

Create an immediate backup of the NEXO database

List available backups with dates and sizes

Restore database from a backup (DESTRUCTIVE)

List visible official NEXO protocol cards from the authenticated backend. Does not return protocol text.

Fetch one official NEXO protocol card by slug from the authenticated backend, including protocol text.