MCP tool reference — gateway

Auto-generated from TOOL_DEFINITIONS in runtime/src/mcp/tools.ts — do not edit by hand.

The ai-framework gateway exposes 114 MCP tools at http://localhost:3100/mcp. Any MCP-capable agent (Claude Code, Cursor, Windsurf, Codex CLI — see myai connect-agent) can call them. Required parameters are marked bold.

• MEMORY / RAG — memory_search, recall_session, memory_store, memory_context, memory_stats, memory_reindex
• STATE — state_read, state_update
• TASKS — tasks_list, tasks_create, tasks_update, tasks_next, tasks_claim, tasks_fail
• TASK ARTIFACTS (per-task reviewable output) — artifacts_register, artifacts_list
• RUNNER LEASES (ADR-011 slice 3 — fleet-wide concurrency) — runner_lease_acquire, runner_lease_heartbeat, runner_lease_release, runner_lease_list
• REPOS — repos_list, repos_status, repos_priority, repos_scan, repos_upsert, get_pr_impact, triage_prs, get_neighbors, shortest_path, plan_list, plan_set
• HANDOFF (betaC — first-class handoff store) — handoff_write, handoff_read
• SESSION export / import + cross-session recall (betaC context-SHARING) — session_export, session_import, session_recall, context_boot, continuity_stats, user_savings, activation_funnel, perf_stats, slo_status, repos_card_list, repos_card_upsert, new_app
• CONNECTORS (bundled MCP connector set + per-tenant manager) — connectors_list, connectors_seed_defaults, connectors_set, connectors_toggle, connectors_remove, connectors_mcp_config
• FLEET RUN (morning "agent mode -resume all" console) — fleet_run_start, fleet_run_repo_update, fleet_run_finish, fleet_run_latest, fleet_run_list
• AGENTS / SKILLS — agents_list, skills_list, agents_invoke, skills_invoke
• SCHEDULES — schedules_list, schedules_create, schedules_update, schedules_run_now, schedules_delete, schedules_seed
• BUDGETS (read-only) — budgets_status, budgets_breakdown
• USAGE METER (product events, read-only — ADR-014 S2) — usage_summary
• SWEEPS / REPORTS — morning_sweep, evening_sweep
• HEALTH / MONITORING — health_status, provider_health, provider_reset, provider_maintenance_enter, provider_maintenance_exit
• ROUTING / DISPATCH — routing_info, routing_config, dispatch_cycle, inline_execute
• FLEET / PATTERNS / STANDING AGENTS — fleet_overview, pattern_analyze, standing_agents_status
• NOTIFICATIONS — notifications_send, notifications_history, notifications_test
• HEALTH ALERTS — health_alerts_status, health_alerts_run
• BRAIN (git-versioned agent memory — BRAIN B2) — brain_status, brain_manifest, brain_explore, brain_commit, brain_stash, brain_pop, brain_branch, brain_checkout, brain_merge, brain_log, brain_diff, brain_delta, brain_blame, brain_entity, brain_timeline, brain_communities, brain_revert, brain_search, brain_namespace_share, brain_namespace_unshare, brain_namespace_grants, brain_namespace_read, brain_namespace_write, brain_host_provision, brain_host_status, brain_host_rotate

MEMORY / RAG

memory_search

Search the RAG memory for relevant context. Returns semantically similar chunks from state files, handoff notes, commit messages, PR descriptions, and SONA patterns across all managed repos.

recall_session

Recall past work sessions by semantic similarity. Searches the session corpus (STATE.md session blocks, handoff notes, and archived sessions) and returns the most relevant blocks ranked by similarity. Use to answer "what did we do for PR #99?", "when did we ship Phase 5b?", or "what was the fix for the update_all.sh bug?" without grepping the archive. Filter by repo or restrict to recent work with since.

memory_store

Store a new text chunk in the RAG memory with automatic embedding. Deduplicates by content hash.

memory_context

Assemble a pre-built context block for a repo: top recent state chunks + handoff + related patterns. Returns a ready-to-inject markdown block.

memory_stats

Get vector count statistics by repo and source type.

memory_reindex

Re-embed and upsert vectors for STATE.md, AI_AGENT_HANDOFF.md, and state/archive/*.md. Call after wrap-up to keep the RAG corpus current. Idempotent via content-hash dedup. Master repo only by default; pass scope=all to also index every managed repo.

STATE

state_read

Read STATE.md or AI_AGENT_HANDOFF.md for a repo. Returns raw file content.

state_update

Replace or append a section in STATE.md or AI_AGENT_HANDOFF.md. Section is identified by a markdown heading (e.g. "## 3. Blockers"). If the heading does not exist, content is appended to the file.

TASKS

tasks_list

List tasks in the queue. Filter by repo, status, priority, or assigned agent. Sorted by priority then creation time.

tasks_create

Create a new task in the queue. Returns the created task with assigned ID.

tasks_update

Update a task by ID: re-point repo, change status, priority, assigned agent, PR URL, notes, telegram message ID. Automatically sets startedAt when moving to working, completedAt when moving to done/blocked.

tasks_next

Get the highest-priority pending task (P0 first, then oldest). Optionally filter by repo.

tasks_claim

Atomically claim the highest-priority pending task (P0 first, then oldest), flipping it pending→working in a single findOneAndUpdate. Cross-machine safe: when two runners fire concurrently against the same queue, exactly one wins each task — no double-pick. Sets claimedBy/claimedAt/leaseUntil for stale-runner reclaim. Returns the claimed task, or {claimed:false} when nothing is claimable. Use this from the runner instead of tasks_list + tasks_update.

tasks_fail

Record a genuine runner failure (dead-letter queue + bounded retry-with-backoff). Bumps the task's retry ledger: while under maxRetries (default 3) releases it back to pending with an exponential-backoff nextRetryAt (5m, 10m, 20m, … capped at 6h) so claimTask/tasks_claim won't re-pick it before then. Once retries are exhausted, sets status to dead_letter instead of looping or vanishing — surfaced on the dashboard for operator triage. Use this from the runner's genuine-failure branch INSTEAD OF tasks_update {status:"blocked"}.

TASK ARTIFACTS (per-task reviewable output)

artifacts_register

Attach a downloadable artifact (git diff, build/test console output, generated report) to a completed task. Content is capped and compressed server-side. Returns the stored artifact metadata.

artifacts_list

List artifacts captured for a task (metadata only — no content), newest last.

RUNNER LEASES (ADR-011 slice 3 — fleet-wide concurrency)

runner_lease_acquire

Acquire one of the N fleet-wide runner-lease slots (N = active Claude accounts, default 2) before starting an autonomous session. Cross-machine safe: slots live in the shared runner_leases collection, so at most N sessions run fleet-wide no matter how many Macs fire. Atomically reclaims a stale slot (crashed runner past leaseUntil) and is idempotent for the same holder. Returns {acquired:true, lease} or {acquired:false} when all slots are validly held — back off, do not start a session.

runner_lease_heartbeat

Extend a held runner-lease slot (resets leaseUntil to now + leaseSeconds). Only succeeds while the slot still belongs to this holder; {ok:false} means the lease was reclaimed after going stale — the runner must stop claiming new work. Optionally stamps the taskId being worked.

runner_lease_release

Release a held runner-lease slot when the session ends, freeing it for the next fire. Holder-scoped (cannot free a slot another runner reclaimed) and idempotent: releasing an already-released slot returns {released:false}, not an error.

runner_lease_list

List runner-lease slots for this tenant: holder, machine, account, taskId, heartbeat, leaseUntil and a stale flag per slot, plus active/max counts. Read-only fleet visibility (dashboard, debugging "why is the runner backing off").

REPOS

repos_list

List all managed repos from managed_repos.txt with health indicators (exists, is git repo, has AI/, has state + handoff).

No parameters.

repos_status

Detailed status for a repo: current branch, uncommitted file count, ahead/behind counts, last handoff/state modification time.

repos_priority

Rank managed repos by attention needed: open task count, stale handoff, missing AI framework. Highest score first.

No parameters.

repos_scan

Scan a directory to discover git repositories and their tech stacks. Returns discovered repos with name, path, stack detection (Next.js, Express, Docker, MongoDB, TypeScript, Python), and whether the AI framework is already installed. Use to discover repos before registering them.

repos_upsert

ADR-021 Phase 2 — self-register (or refresh) one repo in the caller's tenant repos DB roster. Used by myai init (source: myai-init) and myai scan --register (source: scan) so a repo's fleet-tracking entry lives under the owning tenant instead of the shared managed_repos.txt.

get_pr_impact

Blast radius for a change: given a set of changed files (or a base...head git diff), returns every in-repo file transitively affected via the deterministic typed code-edge graph (git-tracked TS/JS/Python, regex-resolved import/calls/tests_of edges — same class of heuristic as scripts/scan_repo_index.py + scripts/code_graph.py, not a real compiler). affectedFiles is the import-based blast radius; callers surfaces files that call into a changed file even without importing it; affectedTests lists tests covering the impacted footprint. Use before re-reading files to reason about a PR/diff's reach: unaffected files can be skipped. Aliased/bare-package imports and uncommon call patterns are not resolved, so this is a lower bound on impact.

triage_prs

Rank a set of open PRs by risk/impact using get_pr_impact's blast radius plus heuristics (infra/config/schema files touched, source changes with no accompanying test file, no known test coverage anywhere in the impacted footprint per the tests_of edge, blast radius exceeding the depth cap). Highest risk first. Feed the PR-review swarm and the runner's pre-claim preflight this instead of re-reading every changed file per PR.

get_neighbors

Typed neighbors of one node in the deterministic code-edge graph (B-1.5) — a scoped subgraph, not raw files. node is a repo-relative file path OR a declared symbol (function/class/const) name, resolved to its declaring file(s). Returns each neighbor's edge type (import/calls/tests_of), direction, and file — never file contents. Same-process TS counterpart to scripts/code_graph.py get_neighbors(); use to answer "what does X import/call" or "what calls/imports/tests X" without re-reading files.

shortest_path

Shortest typed-edge path between two nodes in the deterministic code-edge graph (B-1.5) — returns the file path chain, not file contents. src/dst are repo-relative file paths OR declared symbol names (resolved to declaring file(s); ambiguous symbols try every candidate file pair and keep the shortest). BFS over import/calls/tests_of edges, same heuristic class as scripts/code_graph.py shortest_path(). Null path means unreachable within the selected edge types.

plan_list

List the 10-day improvement plan (day-by-day focus schedule) for a repo (or all repos). Each day has a fire time (UTC, ≈9am Sydney), a one-line focus, and a status. Rendered as a table on the dashboard /plan page.

plan_set

Set/replace a repo's multi-day improvement plan. Pass an array of {day, focus, status?} and a startDate; fire times auto-compute (day 1 = startDate at the off-hours default 10:00 UTC ≈ 8pm Sydney, then +1 day each). OFF-HOURS POLICY: any fire time landing in the user's weekday interactive window (9am–6pm Sydney) is auto-clamped into the 6pm–9am off-hours band. Use after producing the mythos improvement plan, alongside scheduling the actual tasks via schedule_task.sh.

HANDOFF (betaC — first-class handoff store)

handoff_write

Write a session handoff for a repo to the gateway (betaC first-class handoff store). Append-only — each call adds a new entry, building an auditable handoff trail across sessions and machines. Replaces git-syncing AI_AGENT_HANDOFF.md: the next agent reads the latest handoff from the gateway instead of pulling main. Pass the full handoff body in content and a one-line "what's next" in summary.

handoff_read

Read the latest session handoff for a repo from the gateway (betaC first-class handoff store). Returns the most recent entry (the "what's next" the next agent needs) plus the total entry count. Pass history > 0 to also get that many recent entries (newest first). Omit repo to list the latest handoff for every repo the tenant has.

SESSION export / import + cross-session recall (betaC context-SHARING)

session_export

Export a live or persisted session as a portable bundle so its context can follow the user to another device (betaC context-sharing). Returns a versioned, tenant-owned snapshot (agent, status, full message history, workspace, metadata) — prefers the durable DB copy, falls back to the in-memory cache. Pass the bundle to session_import on the other device.

session_import

Import a session bundle produced by session_export so context follows the user across devices (betaC context-sharing). The session is stamped with the importing tenant (a bundle can never smuggle a foreign tenant), loaded into the live cache and persisted. By default a fresh session id is minted so cross-device imports never collide; set preserveId to keep the original id (idempotent same-device re-import).

session_recall

Recall the tenant's recent sessions into a single ready-to-inject context block so a fresh session — typically on another device — resumes with continuity (betaC context-sharing). Returns the recent sessions (agent, status, recent messages) plus a markdown digest. Filter to one agent with agentName.

context_boot

Fetch the betaC boot bundle ON DEMAND — the tight, token-budgeted OPERATOR BRIEF a blank agent needs to greet the operator and continue the work. Returns bundle (rendered markdown) plus brief structured as who / state / handoff / next: WHO you are working with, the STATE (active project), the last HANDOFF summary, and what comes NEXT from the active plan. This is the callable form of the auto-boot the gateway injects on MCP initialize: use it from the wrap-it tier (a blank ChatGPT/Ollama via a thin shim that cannot read InitializeResult.instructions) or to RE-fetch a fresh bundle mid-session. CHEAP BY DESIGN: with no query it returns only the tight brief and runs NO search. Pass a query to LAZILY pull deeper context — one capped semantic search whose short snippet pointers are returned under deeper — so depth is opt-in and auto-boot fixes token-burn instead of recreating it. For full depth, follow the returned lazyRecall tools (handoff_read / recall_session / memory_search).

continuity_stats

The cold-start tokens-saved meter. Every context_boot bundle, brain_delta catch-up, and memory_context block the gateway serves is metered (estimated tokens = the re-teaching cost the operator avoided); this tool returns the tenant-scoped rollup: month-to-date and all-time boots + tokens saved, split by serving tool, plus coldStart — the today-vs-brain comparison (avg tokens per session start on the brain path vs the measured legacy file-read baseline). Surfaced on the dashboard /analytics page and in myai status — the headline continuity number ("myAI saved N tokens this month").

user_savings

Per-user cumulative cold-start savings + the shareable "myAI saved me N tokens / $X this month" figure. Returns month-to-date and all-time tokens saved with their USD value (cold-start tokens priced at the input-token tier the model would otherwise re-ingest). Pass userId to scope to one tenant member (the share-card number); omit it for the whole-tenant total plus a month-to-date per-member breakdown (byUser, highest first). Powers the dashboard /savings view and the /savings/card share image.

activation_funnel

The activation funnel — privacy-respecting product analytics with NO third-party tracker. Returns the tenant's own onboarding journey (steps signup → init → first_brain_boot → first_brain_delta → wrapup_merge, which are reached, when, and activation %). Pass fleet:true for the operator/product rollup instead: distinct tenants at each step, per-step conversion, and the headline activationRate (activated ÷ signed-up). Milestones are stamped first-touch from existing gateway chokepoints (ADR-014 usage-metering write path) and surfaced on the dashboard /analytics Activation tab.

perf_stats

Gateway hot-path performance meter. Every MCP tool call is timed at the single executeTool chokepoint; this returns the live in-process rollup: per-tool count / avg / p50 / p95 / p99 / max latency (ms), the aggregate p95, a slow-query log of the most recent calls over the slow threshold (default 500ms, MYAI_SLOW_QUERY_MS), and hotPaths (the tools accumulating the most slow hits). Surfaced on the dashboard /analytics "Gateway performance" card. In-process + bounded — no DB write on the hot path, so it never adds latency; state resets on gateway restart (this is a live operational meter, not a historical store).

No parameters.

slo_status

Per-route SLO alerting status. Returns the active SLO configuration (default p95-latency + error-rate thresholds, per-route overrides, min-sample floor, cooldown), and — evaluating the live perf meter right now — the routes currently breaching their SLO. The gateway fires cooldown-guarded Telegram alerts on breach (via the notification engine); this tool is the read-only view of that alerter. Disable alerting with SLO_ALERTS_DISABLED=1; tune with MYAI_SLO_P95_MS / MYAI_SLO_ERROR_RATE_PCT / MYAI_SLO_ROUTES (JSON per-route overrides) / MYAI_SLO_MIN_SAMPLES / MYAI_SLO_COOLDOWN_MIN.

No parameters.

repos_card_list

List the app-directory cards for every tracked repo — the one-point pointer showing each app's localhost address, app/api URLs, MongoDB (non-secret label), Vercel/DNS URLs, short description, and rolling last-update status. Populated by each repo on wrap up.

No parameters.

repos_card_upsert

Create or update THIS repo's app-directory card. Only provided fields are written (partial update), so a wrap-up can refresh just the status without clobbering the URLs. Store NON-SECRET values only for mongo (e.g. host + db name, never a connection string with credentials).

new_app

Spin up a brand-new app from a plain-English idea: drives agentFlow's idea→app pipeline (project create + auto-run codegen→runner bridge) and registers the generated repo in the gateway app-directory so it shows on the dashboard. Backs the myai new-app "<idea>" CLI command. Requires AGENTFLOW_URL + AGENTFLOW_TOKEN env for the trigger; the card is registered regardless so the app is always tracked.

CONNECTORS (bundled MCP connector set + per-tenant manager)

connectors_list

List this tenant's MCP connectors — the curated bundled set (betaC gateway, Context7, shadcn/ui, Playwright, GitHub, Vercel, Dropbox) plus any custom connectors. Auto-seeds the bundle on first read so a fresh install is never empty. Each entry shows transport (http/stdio), enabled state, source (bundled/custom), and any env vars (e.g. a GitHub PAT) the operator still needs to supply.

No parameters.

connectors_seed_defaults

Seed (or refresh) the curated default MCP connector bundle for this tenant so a fresh betaC install has working connectors day one. Idempotent — bundled catalog fields are refreshed but an existing connector's enabled toggle is preserved. Returns counts of newly seeded vs already present.

No parameters.

connectors_set

Create or update a connector. For a CUSTOM connector supply transport + url (http) or command/args (stdio). For a BUNDLED connector you can pass just {key, enabled} to toggle it without resupplying catalog fields.

connectors_toggle

Enable or disable a connector by key. Convenience over connectors_set for the dashboard toggle.

connectors_remove

Remove a connector. Custom connectors are deleted; bundled connectors are disabled instead (a re-seed would otherwise bring them back). Returns whether it was removed vs disabled.

connectors_mcp_config

Build an .mcp.json-shaped object from this tenant's ENABLED connectors — the artifact a scaffolded project or CLI session consumes to get working connectors day one.

No parameters.

FLEET RUN (morning "agent mode -resume all" console)

fleet_run_start

Open a fleet morning-sweep run. The master repo aggregates each managed repo's overnight state (commits / open PRs / runner activity / queued review+blocked tasks) into repos[] with a per-repo recommendation. Renders live on the dashboard /fleet page. Keyed by runId (re-running the same runId replaces it).

fleet_run_repo_update

Update ONE repo's live progress within a fleet run as the operator approves and the agent executes an action (merge/fix/test/ship/wrap-up). Flips actionStatus and appends a detail line so the dashboard /fleet page reflects work in realtime.

fleet_run_finish

Close a fleet run (status completed or aborted) and stamp the final summary.

fleet_run_latest

Get the most recent fleet run (what the dashboard /fleet page shows). Returns null if no run yet.

No parameters.

fleet_run_list

List recent fleet runs (history of morning sweeps), most recent first.

AGENTS / SKILLS

agents_list

List all loaded specialist agents with name, category, description, and tool count.

skills_list

List all loaded skills with name, description, and trigger keywords.

agents_invoke

Invoke a specialist agent with a task message. Loads the agent's instructions as the system prompt, calls the configured LLM provider, and returns the response. Optionally injects memory_context for the target repo to ground the answer in current state.

skills_invoke

Invoke a skill with a task message. Loads the skill's playbook as the system prompt, calls the configured LLM provider, and returns the response.

SCHEDULES

schedules_list

List schedules sorted by nextRun. Filter by enabled, kind (agent|skill|tool), or last run status.

schedules_create

Create a new scheduled dispatch. kind=agent invokes a specialist via agents_invoke; kind=skill invokes a skill via skills_invoke; kind=tool dispatches an MCP tool directly with args parsed from the message field as JSON. Validates cron expression and computes nextRun.

schedules_update

Update a schedule by scheduleId. Recomputes nextRun if cronExpr changes. Pass only the fields you want to change.

schedules_run_now

Dispatch a schedule immediately, bypassing nextRun. Updates lastRun/lastStatus but preserves the existing nextRun so the cron cadence is unaffected.

schedules_delete

Delete a schedule by scheduleId. Removes it permanently from the queue.

schedules_seed

Idempotently seed the standard default schedules: morning_sweep_daily (09:00 UTC daily) and evening_sweep_daily (18:00 UTC daily), both kind=tool. Matches by name — never duplicates; schedules that already exist are left untouched and reported under "existing". Returns { created, existing, updated }.

BUDGETS (read-only)

budgets_status

Snapshot of the gateway LLM-spend budget: month-to-date and today's USD spend, configured caps, downgrade thresholds, and per-channel MTD breakdown when a per-channel cap is configured. Read-only. Returns zero spend with current config when budgets are disabled or MongoDB is unavailable.

No parameters.

budgets_breakdown

Spend breakdown by provider, model, and channel. Defaults to month-to-date (UTC). Pass from/to ISO timestamps to query a different window. Read-only.

USAGE METER (product events, read-only — ADR-014 S2)

usage_summary

Product-usage meter (UsageEvent): summed quantity per group key for the tenant. Unlike budgets_* (LLM spend), this counts billable product units — runner tasks executed, off-hours minutes, apps generated, agents invoked. Group by event type (default), day, or repo. Pass from/to ISO timestamps to bound the window (half-open [from, to)). Read-only; returns empty totals when metering is disabled or MongoDB is unavailable.

SWEEPS / REPORTS

morning_sweep

Daily autonomous sweep: rank managed repos by attention score, ask a specialist agent (default project-manager) for a short brief on each top repo, compose a markdown report, and optionally deliver via Telegram. Designed to run as a cron schedule (kind=tool, target=morning_sweep) or on demand.

evening_sweep

Daily evening summary: tasks completed today, LLM spend, repos worked on, and tomorrow's priority queue preview. Designed to run as a cron schedule (kind=tool, target=evening_sweep, e.g. "0 21 *" for 9pm) or on demand.

HEALTH / MONITORING

health_status

Comprehensive health check of the AI Management gateway and framework. Returns: gateway uptime, MongoDB connection status, vector corpus size, active schedules count, LLM provider status with resilience data (circuit breaker states, rate limiter stats), channel statuses, managed repo count, and memory usage. Use for production monitoring and debugging.

No parameters.

provider_health

Get detailed resilience health for LLM providers. Shows per-provider circuit breaker state (closed/open/half-open), failure/success counts, rate limiter token availability, and total acquired/rejected tokens. Optionally filter to a single provider.

provider_reset

Manually reset a tripped circuit breaker for an LLM provider. Use when a provider has recovered but the circuit breaker has not timed out yet. Requires the provider name.

provider_maintenance_enter

Operator-initiated: put an LLM provider into maintenance mode for planned work. Distinct from the circuit breaker (which trips automatically on errors) — this is a deliberate drain. In-flight calls are left to finish; the provider reports "draining" until they complete, then "maintenance". New calls for that provider queue behind the gate and fail over to the next provider in the mode chain (recoverable error), or resume once maintenance ends if there is no chain. Reflected in provider_health / health_status for a dashboard banner.

provider_maintenance_exit

End an operator-initiated maintenance window for an LLM provider — resumes normal dispatch and immediately releases any calls queued behind the maintenance gate.

ROUTING / DISPATCH

routing_info

Get the current LLM routing decision for a given context. Shows which provider and model would be selected for a specific tier, agent, channel, or tool. Useful for debugging routing decisions and understanding cost implications.

routing_config

Get the full routing configuration including tier definitions, agent-to-tier mappings, channel overrides, and tool routing rules. Read-only inspection of the LLM routing table for dashboards and debugging.

No parameters.

dispatch_cycle

Run one autonomous dispatch cycle: picks pending tasks from the queue, selects appropriate specialist agents, dispatches them, and reports results. Used by the scheduler for daily autonomous work or invoked manually. Respects budget caps.

inline_execute

In-gateway inline execution lane (ADR-018): run short deterministic pending tasks in-process via a whitelisted tool — no CLI-runner fire and no LLM spend. Only tasks carrying an explicit [inline:<op>] marker (op ∈ reprioritize, health, reindex, seed-schedules, usage-summary, repo-status) are eligible. Feature-flagged (INLINE_EXEC_ENABLED, default off → no-op) and quota-bounded (INLINE_EXEC_QUOTA per rolling window). Ineligible tasks are left for the CLI runner / dispatch worker.

FLEET / PATTERNS / STANDING AGENTS

fleet_overview

One-call fleet-wide dashboard: managed repo count + health summary, task queue totals by status, active schedule count, today's LLM spend, and top 3 repos needing attention. Ideal for Telegram status checks or quick session starts. Gracefully degrades if DB is unavailable.

No parameters.

pattern_analyze

Analyze SONA patterns from the memory/patterns/ store. Lists patterns with confidence scores, usage counts, and staleness (days since last used). Sorted by effectiveness (confidence × usageCount). Filter by category, tag, or minimum confidence threshold.

standing_agents_status

Status of all standing agent schedules: which standing agents are configured, their cron expressions, last run time/status, next run time, and whether they are enabled. Cross-references loaded agents against schedules; agents with no schedule are marked "unscheduled".

No parameters.

NOTIFICATIONS

notifications_send

Send a notification to one or more channels (Telegram, Discord, etc.). Formats the message with a level icon, optional title, and source tag. Falls back gracefully if a channel fails — never throws. Returns per-channel send results.

notifications_history

Retrieve recent notification history from the database. Returns an empty array if DB is not connected.

notifications_test

Send a test notification to verify channel connectivity. Sends "Test notification from myAI gateway" with level info.

HEALTH ALERTS

health_alerts_status

Get the latest health check result and alerting status. Returns the most recent HealthCheckResult (or null if never run), plus whether alerting is active, the check interval, dedup window, and tracked alert count.

No parameters.

health_alerts_run

Force an immediate health check cycle. Runs all probes (gateway, MongoDB, LLM providers, repos, scheduler, Docker), evaluates alert deduplication, and sends Telegram alerts for any degraded or unhealthy checks. Returns the full HealthCheckResult.

No parameters.

BRAIN (git-versioned agent memory — BRAIN B2)

brain_status

Brain store status: location, current branch, namespaces, atom counts (sessions/handoffs/memory), open session/idea branches, pending stashes, last commit. The brain is the git-versioned agent memory — sessions = commits, wrap up = merge, main = the consolidated truth agents boot from.

No parameters.

brain_manifest

Control-plane boot manifest (BRAIN B2): "know where what is without reading it." A tiny table-of-contents over the stores the 3-plane router dispatches against (brain-git, repo-sqlite-index, atlas-vectors — each with its fetch tools), this brain's namespaces (name + hasBrief/hasWorking + atom counts, NO bodies), the cross-repo memory atom count, and freshnessSha (the brain main HEAD SHA to anchor a later brain_delta({since})). Extends ADR-020's tiered topic index one level up — which store/namespace to descend into, not which topic within one. Cheap by construction: directory listings + git rev-parse only, never an atom read.

No parameters.

brain_explore

Read-only browsable snapshot of the brain for the dashboard /brain explorer: namespaces with per-kind atom counts, a recent slice of the actual atoms (parsed frontmatter, newest first), open stashes with body previews, session/idea branches, recent commits, and the code↔memory provenance recorded on HEAD. Pure inspection — never checks out, merges, or writes.

brain_commit

Commit one append-only memory atom to the brain on the current branch. Atoms are immutable — identical re-writes dedup to a no-op; changed content becomes a NEW atom. kind=memory atoms are cross-repo (omit repo); session/handoff atoms live under their repo namespace (auto-created). Pass code_* to stamp code↔memory provenance (BRAIN B5): which code branch/HEAD SHA/commits this atom is about — brain_blame answers both directions from those stamps. kind=session atoms get a non-blocking quality lint (too short, no decision/next-step signal, or near-duplicate of the prior session atom) — the atom still commits; check the returned lint.warnings and prompt for enrichment if non-empty. Distinct from any brain health-score composite index.

brain_stash

Freeze a context payload and walk away: the stash is committed to the brain's MAIN branch (not the session branch), so ANY later session — different agent, device, or branch — can brain_pop it and resume. Not git-stash: it survives across processes and machines.

brain_pop

Pop the newest brain stash (or the newest one matching slug): returns the frozen context and removes the entry from main with a normal commit. Use after brain_status shows pending stashes.

brain_branch

Create or resume a brain branch. kind=idea (default): long-lived parallel thinking context idea/<slug> off main. kind=session: today's auto session branch session/<date>-<host>-<slug> (slug acts as the profile, e.g. cli).

brain_checkout

Check out an existing brain branch: main, session/<...> or idea/<...>. Refuses unknown refs and anything outside those families.

brain_merge

Merge a session or idea branch into main (--no-ff) — what wrap-up calls. Session branches are deleted after the merge; idea branches survive (long-lived). Defaults to the CURRENT branch. Conflicts abort cleanly and leave the branch unmerged.

brain_log

Brain commit history (newest first): sha, date, subject. Scope with ref (branch/sha) and/or path (e.g. repos/<name>/sessions).

brain_diff

What changed between two brain refs (default main..HEAD — what the current session has that main doesn't). Returns changed files + shortstat; pass patch=true for the unified diff (truncated at 20k chars).

brain_delta

Diff-only catch-up: "what changed in the brain since <sha>?" Pass the last-seen brain main SHA (since, remembered from a previous boot/delta) to get ONLY the delta — new atoms (content, capped), commits, and which compiled artifacts changed — a ~300-800 token payload instead of a full re-boot. No/unknown since degrades to the blank-agent path: the compiled ~150-token boot brief. Remember the returned sha as the next anchor. Scope with repo to one namespace (+ cross-repo memory/).

brain_blame

Code↔memory provenance lookup (BRAIN B5). Forward: pass code_sha (full or ≥7-char prefix) to find the brain commits whose provenance stamps reference that code commit — "what was the agent thinking when it produced commit X", with the atom files (session logs) to read. Reverse: pass ref (a brain branch/commit, e.g. idea/<slug>) to list every code SHA its commits recorded — "what code did this line of thinking produce". Stamps come from brain_commit code_* args.

brain_entity

Cross-session ENTITY recall — "what changed about X" (BRAIN B10). A lightweight, deterministic temporal/entity layer over the brain (Graphiti-style: entities + time-stamped "touched" edges, extracted by plain regex — NO per-write LLM, no embeddings, no new storage). Pass query to get the entity records whose name matches (case-insensitive substring): each returns its timestamped touches with a snippet from every atom that mentioned it, so you can read what changed each time and when. Omit query to list the most-recently-touched entities (a map of what the brain knows). Entity kinds: repo (namespace), file (path mentioned), feature (atom slug + tag-style names), person (@mention), decision (ADR-*). Scope with repo and/or kind. The verbatim atoms stay the source of truth — this is an augmenting index, computed on read.

brain_timeline

Cross-session TEMPORAL recall — "when did I last touch Y" / recent activity (BRAIN B10). The time-ordered feed over the same lightweight entity index as brain_entity. Pass entity to get that entity's "touched" edges newest-first plus its first/last-touched timestamps — the direct answer to "when did I last touch Y". Omit entity for the recent cross-entity activity feed (optionally scoped by kind/repo) — a temporal overview of what has been worked on lately. Use since (a raw UTC stamp like 20260706T234100Z, e.g. a previous lastTouched) to get only newer events. Deterministic + extractive; augments the verbatim atoms, never replaces them.

brain_communities

GraphRAG-style GLOBAL/THEMATIC recall — "what's been going on with the auth area" without knowing which entity to ask about (BRAIN B-6, the community-summary half of B10 Graphiti: plan/BRAIN_BUILD_PLAN.md day 8). Builds a timestamped entity co-occurrence graph over the same deterministic entity extraction as brain_entity/brain_timeline (two entities edge-connect when an atom mentions both), runs Leiden-style community detection (Louvain modularity optimization + a connectivity-refinement pass), and returns each community as a compact extractive summary — top entities, repos, active time window, and top co-occurrence edges (each with firstSeen/lastSeen) — largest/most-active first. Pass query to filter to communities whose summary or member entities match (substring, case-insensitive) — a thematic search over the community layer instead of scanning every atom. Deterministic + LLM-free, computed on read; augments the verbatim atoms, never replaces them.

brain_revert

Undo a brain commit with an inverse commit — history is never rewritten (atoms stay append-only). Merge commits revert against their first parent. Conflicts abort cleanly, leaving the brain unchanged.

brain_search

Federated recall: one ranked query across this tenant's brain atoms (sessions, handoffs, and cross-repo memory facts — every repo namespace) AND the RAG session corpus (STATE.md/handoff/archive vectors — every repo) at once. Distinct from per-namespace sharing/read-only grants (which expose ONE namespace to another tenant) — this unions and ranks what one tenant already owns across its OWN multiple repo-brains, so "what have we done about X" doesn't require knowing which repo holds the answer. Omit repo to federate across all of them; pass it to narrow to one.

brain_namespace_share

Grant another tenant scoped access to ONE of this tenant's brain namespaces (repos/<namespace>). Role-gated: configure. level is read (browse only) or read-write (browse + append atoms). Re-sharing with the same granteeTenantId updates the level and clears any prior revocation — one active grant per (namespace, grantee). Distinct from team-brain (whole-team sharing); this is a single owner→grantee grant, typically cross-tenant.

brain_namespace_unshare

Revoke a previously granted namespace access. Role-gated: configure. The grant record is kept with revokedAt set (an audit trail, not a delete) — see brain_namespace_grants. Throws if the grantee never held a grant on this namespace; a no-op if already revoked.

brain_namespace_grants

The access list for one of this tenant's namespaces — every grant ever issued (active and revoked), newest first. Role-gated: read. Pass activeOnly to filter out revoked grants.

brain_namespace_read

Read a namespace another tenant (ownerTenantId) has shared with THIS tenant: the compiled boot brief plus recent session/handoff atoms and counts. Requires an active grant of at least read on (ownerTenantId, namespace) — enforced at the gateway boundary against the caller's own server-derived tenant identity. Reads only the owner's main branch (the consolidated truth), never an in-progress session branch.

brain_namespace_write

Append a session/handoff atom into a namespace another tenant (ownerTenantId) has shared with THIS tenant at read-write level. Requires an active read-write grant on (ownerTenantId, namespace) — a read-only grant is refused. The atom is committed into the owner's brain, attributed to this tenant in both the frontmatter (shared-write-by) and the git commit author.

brain_host_provision

Provision (or adopt) this tenant's HOSTED brain remote — a managed, gateway-served, tenant-scoped git repo the brain pushes to, so users who won't self-host git get turnkey cross-device continuity (ADR-017). Gated on the plan's hosted-brain entitlement (Pro/Team; free tier is refused). Returns the remote URL and a one-time access token (the token is never persisted — store it now; use brain_host_rotate to reissue). Point the brain at it once with brain init --remote <url> / git remote set-url origin <url>; sync is invisible thereafter. Self-host remains the default (data-locality).

No parameters.

brain_host_status

This tenant's hosted brain remote status (ADR-017): whether provisioned, the display remote URL (no credential), plan, created/rotated timestamps, encryption-at-rest posture, and quota (used vs plan cap). No secret material is returned.

No parameters.

brain_host_rotate

Rotate this tenant's hosted brain access token (ADR-017) — mints a fresh token and invalidates the old one (leak response / reissue). Returns the new remote URL + one-time token; update the brain's origin URL to match.

No parameters.