Shared memory and context tools for agentic work.
Code Rooms
# Tool Matrix SSOT
Machine-oriented routing matrix for the current `m1nd` tool surface.
## Source Of Truth
- `m1nd-mcp/src/server.rs` tool schema registry and the live `tools/list` response are the callable surface. Use `tools/list` for the exact count in your current build.
- This matrix is the routing SSOT for the canonical tool surface used by agents and LLMs.
- Any page that advertises a fixed tool count can drift. Treat `tools/list` as counting truth.
## Row Contract
| field | meaning |
|---|---|
| `command` | canonical bare MCP call name returned by `tools/list` |
| `category` | routing bucket |
| `core_function` | shortest truthful description of what the tool does |
| `choose_when` | positive routing trigger |
| `avoid_when` | disqualifier / better alternative |
| `required` | minimum required args |
| `returns` | stable output surface an LLM can plan around |
| `next` | adjacent tools / likely next hop |
## Foundation
| command | core_function | choose_when | avoid_when | required | returns | next |
|---|---|---|---|---|---|---|
| `north` | In-session front door: composed pre-orient — binding trust, task context, prior cross-session memory, sufficiency, one `next_move`, and `honest_gaps`. | Call FIRST, before reading or editing, to orient. Composes trust_selftest + orient + boot_memory + focus. | Avoid only when you need exactly one composed piece; reach for it directly then. | `agent_id` | `trust_mode; task_context; prior_memory; sufficiency; next_move; honest_gaps; needs_ingest?` | `ingest (if needs_ingest) -> seek -> impact` |
| `ingest` | Parse a codebase, markdown docs, or JSON domain graph into the semantic graph. | Start or refresh graph truth for a repo, file, docs corpus, or descriptor before higher-order queries. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | `agent_id; path` | `graph_counts; files_scanned; files_parsed; nodes_created; edges_created; elapsed_ms` | `activate -> impact -> why` |
| `activate` | Spreading activation query — fires signal into the graph and returns a 4D-scored activation pattern. | Use when the query is associative or subsystem-shaped and you want connected structure, not exact text. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | `agent_id; query` | `seeds; activated; ghost_edges; structural_holes; plasticity; elapsed_ms` | `activate -> impact -> why` |
| `impact` | Blast radius of a code change — BFS-propagated signal strength from a source node. | Use before edits to estimate blast radius. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | `agent_id; node_id` | `blast_radius; total_energy; causal_chains` | `activate -> impact -> why` |
| `why` | Shortest path between two nodes — understand how A depends on B. | Use to explain how two nodes are connected. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | `agent_id; source; target` | `path; hops; edge_types; path_weight` | `activate -> impact -> why` |
| `learn` | Hebbian feedback — tell the graph which results were correct or wrong. Edge weights strengthen or weaken accordingly. | Hebbian feedback — tell the graph which results were correct or wrong. Edge weights strengthen or weaken accordingly. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | `agent_id; query; feedback; node_ids` | `edges_modified; trust_records_updated; tremor_observations_recorded` | `activate -> impact -> why` |
| `drift` | What changed in the graph since your last session — structural delta for context recovery. | What changed in the graph since your last session — structural delta for context recovery. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | `agent_id` | `baseline; changed_nodes; weight_drift; summary` | `activate -> impact -> why` |
| `health` | Server diagnostics — verify the MCP server is alive and the graph is loaded. | Server diagnostics — verify the MCP server is alive and the graph is loaded. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | `agent_id` | `node_count; edge_count; sessions; graph_state` | `activate -> impact -> why` |
| `trust_selftest` | One-call agent trust verdict for binding, graph, and recovery readiness. | Use as the degraded/recovery entry when trust looks off; for normal orientation use `north`. | Avoid treating it as repair or as the default front door; it is diagnostic-only and does not ingest or mutate. | `agent_id` | `verdict; checks; binding_fingerprint; session_handshake; recovery_playbook?` | `north -> ingest -> recovery_playbook` |
| `session_handshake` | Cheap sub-check for host tool surface and graph trust mode. | Use when `trust_selftest` is unavailable or when you only need the handshake layer. | Avoid using it as a retrieval probe; it does not test semantic results by default. | `agent_id` | `trust_mode; can_ingest; can_retrieve; tool_surface; graph_state` | `trust_selftest -> recovery_playbook -> ingest` |
| `recovery_playbook` | Ordered recovery steps for empty graphs, degraded hosts, and stale-looking retrieval. | Use when `trust_selftest` or retrieval reports blocked, degraded, or stale-looking state. | Avoid assuming it repaired anything; it only returns next actions. | `agent_id` | `trust_mode; binding_fingerprint; steps; non_claims` | `doctor -> ingest -> session_handshake` |
| `seek` | Find code by natural language intent — more targeted than `activate` for specific lookups. | Use when you know the purpose of code but not its location. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | `agent_id; query` | `tool-specific JSON payload; inspect API reference / tools/list` | `activate -> impact -> why` |
| `scan` | Run structural pattern scanners. Use a predefined pattern ID or a custom pattern string. | Run structural pattern scanners. Use a predefined pattern ID or a custom pattern string. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | `agent_id; pattern` | `tool-specific JSON payload; inspect API reference / tools/list` | `activate -> impact -> why` |
| `timeline` | Temporal evolution of a node — change history, co-change partners, velocity, stability. | Temporal evolution of a node — change history, co-change partners, velocity, stability. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | `agent_id; node` | `tool-specific JSON payload; inspect API reference / tools/list` | `activate -> impact -> why` |
| `diverge` | Structural drift analysis — compare graph state against a baseline reference. | Structural drift analysis — compare graph state against a baseline reference. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | `agent_id; baseline` | `tool-specific JSON payload; inspect API reference / tools/list` | `activate -> impact -> why` |
| `warmup` | Prime the graph for an upcoming task — pre-activates seed nodes to improve subsequent query relevance. | Prime the graph for an upcoming task — pre-activates seed nodes to improve subsequent query relevance. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | `agent_id; task_description` | `tool-specific JSON payload; inspect API reference / tools/list` | `activate -> impact -> why` |
| `federate` | Unify multiple repositories into one graph — cross-repo blast radius and dependency analysis. | Use when you already know the repo list to unify. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | `agent_id; repos` | `tool-specific JSON payload; inspect API reference / tools/list` | `activate -> impact -> why` |
| `federate_auto` | Discover candidate sibling repositories from explicit external path references, local manifest/workspace hints, import/package-name evidence, shared API-route signals, or basic contract artifacts and optionally execute federation in one step. | Use when you suspect neighboring repos matter but only have path/import/contract evidence. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | `agent_id` | `discovered_repos; suggested_repos; executed; federate_result` | `activate -> impact -> why` |
## Document Intelligence
| `document_resolve` | resolve canonical local artifacts for a universally ingested document | Use when a doc already exists in the graph and you need the local canonical artifact paths. | Avoid when you only need a fresh ingest or raw source text. | `agent_id` | `canonical_markdown_path; canonical_json_path; claims_path; producer; binding_count; drift_summary` | `document_bindings -> document_drift -> view` |
| `document_provider_health` | report optional provider availability, mode, detail, and install hints | Use before relying on richer HTML/PDF/office extraction or when a provider lane seems to be falling back unexpectedly. | Avoid when provider setup is irrelevant to the current task. | `agent_id` | `python; providers[]` | `ingest -> document_resolve -> auto_ingest_start` |
| `document_bindings` | show deterministic document-to-code bindings for a universal document | Use when the question is “which code implements this doc?” or “what should I inspect first?” | Avoid when you only need the artifact paths or provider status. | `agent_id` | `bindings[]; source_path` | `document_drift -> impact -> surgical_context_v2` |
| `document_drift` | detect stale, missing, or ambiguous document/code links | Use after refactors, repo moves, or suspected stale specs. | Avoid before the document has been ingested or bound. | `agent_id` | `findings[]; summary` | `document_bindings -> impact -> timeline` |
| `auto_ingest_start` | start local-first document watchers for supported roots and formats | Use when a docs/specs/wiki root should stay synchronized with the graph while you work. | Avoid for one-shot ingest or read-only inspection. | `agent_id; roots` | `running; provider_status; bootstrap` | `auto_ingest_status -> auto_ingest_tick -> document_resolve` |
| `auto_ingest_status` | inspect the document auto-ingest runtime, semantic counts, provider status, and route/fallback counts | Use to monitor watcher state, queue depth, or document runtime telemetry. | Avoid if you only need a direct document refresh or binding result. | `agent_id` | `running; queue_depth; semantic_*; provider_*; recent_events` | `auto_ingest_tick -> document_drift -> document_provider_health` |
| `auto_ingest_tick` | drain queued document changes immediately and apply them to the graph | Use when a caller needs deterministic immediate reconciliation instead of waiting for opportunistic ticks. | Avoid when no watched roots are active. | `agent_id` | `ingested_paths; removed_paths; skipped_paths; errored_paths` | `document_resolve -> document_drift -> lock_diff` |
| `auto_ingest_stop` | stop document watchers and persist manifest state | Use when shutting down or changing watched roots. | Avoid during active watch-driven reconciliation you still need. | `agent_id` | `stopped; manifest_entries` | `auto_ingest_start -> auto_ingest_status` |
## Perspective Navigation
| `perspective_start` | Open a perspective anchored to a node. Perspectives are stateful navigation sessions. | Open a perspective anchored to a node. Perspectives are stateful navigation sessions. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | `agent_id; query` | `tool-specific JSON payload; inspect API reference / tools/list` | `perspective_routes -> perspective_follow -> perspective_inspect` |
| `perspective_routes` | List available navigation routes from the current focus node. | List available navigation routes from the current focus node. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | `agent_id; perspective_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `perspective_routes -> perspective_follow -> perspective_inspect` |
| `perspective_follow` | Move the perspective focus to a route target. | Move the perspective focus to a route target. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | `agent_id; perspective_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `perspective_routes -> perspective_follow -> perspective_inspect` |
| `perspective_back` | Navigate backward to the previous focus node. | Navigate backward to the previous focus node. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `perspective_routes -> perspective_follow -> perspective_inspect` |
| `perspective_peek` | Read source code at the currently focused node (returns file content at the node's location). | Read source code at the currently focused node (returns file content at the node's location). | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | `agent_id; perspective_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `perspective_routes -> perspective_follow -> perspective_inspect` |
| `perspective_inspect` | Deep metadata + 5-factor score breakdown for a route's target node. | Deep metadata + 5-factor score breakdown for a route's target node. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | `agent_id; perspective_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `perspective_routes -> perspective_follow -> perspective_inspect` |
| `perspective_suggest` | AI navigation recommendation — the graph suggests which route to follow next. | AI navigation recommendation — the graph suggests which route to follow next. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | `agent_id; perspective_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `perspective_routes -> perspective_follow -> perspective_inspect` |
| `perspective_affinity` | Check route relevance to the current investigation. | Check route relevance to the current investigation. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | `agent_id; perspective_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `perspective_routes -> perspective_follow -> perspective_inspect` |
| `perspective_branch` | Fork an independent perspective copy for parallel exploration. Two agents can investigate the same starting point independently, then compare findings. | Fork an independent perspective copy for parallel exploration. Two agents can investigate the same starting point independently, then compare findings. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | `agent_id; perspective_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `perspective_routes -> perspective_follow -> perspective_inspect` |
| `perspective_compare` | Diff two perspectives — shared nodes, unique nodes, divergent findings. | Diff two perspectives — shared nodes, unique nodes, divergent findings. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | `agent_id; perspective_id_a; perspective_id_b` | `tool-specific JSON payload; inspect API reference / tools/list` | `perspective_routes -> perspective_follow -> perspective_inspect` |
| `perspective_list` | All active perspectives for this agent, with memory usage. | All active perspectives for this agent, with memory usage. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `perspective_routes -> perspective_follow -> perspective_inspect` |
| `perspective_close` | Release perspective state and free memory. | Release perspective state and free memory. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `perspective_routes -> perspective_follow -> perspective_inspect` |
## Lock System
| `lock_create` | Snapshot a subgraph region. | Snapshot a subgraph region. | Avoid for solo read-only work; use only when coordination or baseline diffs matter. | `agent_id; scope; root_nodes` | `tool-specific JSON payload; inspect API reference / tools/list` | `lock_watch -> lock_diff -> lock_rebase` |
| `lock_watch` | Register a change strategy on a lock. | Register a change strategy on a lock. | Avoid for solo read-only work; use only when coordination or baseline diffs matter. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `lock_watch -> lock_diff -> lock_rebase` |
| `lock_diff` | Compare current graph state against the locked baseline. Returns changes since the lock was created. | Compare current graph state against the locked baseline. Returns changes since the lock was created. | Avoid for solo read-only work; use only when coordination or baseline diffs matter. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `lock_watch -> lock_diff -> lock_rebase` |
| `lock_rebase` | Advance the lock baseline to the current graph state (after reviewing and accepting changes). | Advance the lock baseline to the current graph state (after reviewing and accepting changes). | Avoid for solo read-only work; use only when coordination or baseline diffs matter. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `lock_watch -> lock_diff -> lock_rebase` |
| `lock_release` | Free lock state and release memory. | Free lock state and release memory. | Avoid for solo read-only work; use only when coordination or baseline diffs matter. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `lock_watch -> lock_diff -> lock_rebase` |
## Superpowers
| `hypothesize` | Test a claim against graph structure using Bayesian path scoring. **89% accuracy validated on 10 live claims against a production codebase.** | Test a claim against graph structure using Bayesian path scoring. **89% accuracy validated on 10 live claims against a production codebase.** | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | `agent_id; claim` | `tool-specific JSON payload; inspect API reference / tools/list` | `hypothesize -> validate_plan -> trace` |
| `counterfactual` | Simulate module removal — compute full cascade of what breaks. | Simulate module removal — compute full cascade of what breaks. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | `agent_id; node_ids` | `tool-specific JSON payload; inspect API reference / tools/list` | `hypothesize -> validate_plan -> trace` |
| `missing` | Find structural holes — what *should* exist in a region of the graph but doesn't. | Find structural holes — what *should* exist in a region of the graph but doesn't. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | `agent_id; query` | `tool-specific JSON payload; inspect API reference / tools/list` | `hypothesize -> validate_plan -> trace` |
| `resonate` | Standing wave analysis — find structural hubs where signal reinforces across multiple dimensions simultaneously. | Standing wave analysis — find structural hubs where signal reinforces across multiple dimensions simultaneously. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `hypothesize -> validate_plan -> trace` |
| `fingerprint` | Find structural twins — nodes with identical or near-identical topology. | Find structural twins — nodes with identical or near-identical topology. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `hypothesize -> validate_plan -> trace` |
| `trace` | Map a stacktrace to root cause suspects — ranks files by suspiciousness × centrality. | Map a stacktrace to root cause suspects — ranks files by suspiciousness × centrality. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | `agent_id; error_text` | `tool-specific JSON payload; inspect API reference / tools/list` | `hypothesize -> validate_plan -> trace` |
| `validate_plan` | Pre-flight risk assessment for a set of planned changes — blast radius, gap count, risk score. | Use before editing or merging to pre-flight risk and test impact. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | `agent_id; actions` | `risk_score; gaps; suggested_additions; heuristic_summary` | `hypothesize -> validate_plan -> trace` |
| `predict` | Co-change prediction — given a file you just changed, which other files likely need changes too. | Co-change prediction — given a file you just changed, which other files likely need changes too. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | `agent_id; changed_node` | `tool-specific JSON payload; inspect API reference / tools/list` | `hypothesize -> validate_plan -> trace` |
| `trail_save` | Persist investigation state — hypotheses, conclusions, open questions, visited nodes, and activation boosts. | Persist investigation state — hypotheses, conclusions, open questions, visited nodes, and activation boosts. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | `agent_id; label` | `tool-specific JSON payload; inspect API reference / tools/list` | `hypothesize -> validate_plan -> trace` |
| `trail_resume` | Restore exact investigation context — nodes, weights, hypotheses — from a saved trail. | Restore exact investigation context — nodes, weights, hypotheses — from a saved trail. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | `agent_id; trail_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `hypothesize -> validate_plan -> trace` |
| `trail_merge` | Combine two or more agents' independent investigations. Auto-detects where they converged and flags conflicts on shared hypotheses. | Combine two or more agents' independent investigations. Auto-detects where they converged and flags conflicts on shared hypotheses. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | `agent_id; trail_ids` | `tool-specific JSON payload; inspect API reference / tools/list` | `hypothesize -> validate_plan -> trace` |
| `trail_list` | Browse all saved investigations with optional filters. | Browse all saved investigations with optional filters. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `hypothesize -> validate_plan -> trace` |
| `differential` | Focused structural diff between two graph snapshots — surface what changed structurally between two points in time. | Focused structural diff between two graph snapshots — surface what changed structurally between two points in time. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | `agent_id; snapshot_a; snapshot_b` | `tool-specific JSON payload; inspect API reference / tools/list` | `hypothesize -> validate_plan -> trace` |
## Superpowers Extended
| `antibody_scan` | Scan the graph against all stored bug antibody patterns (known bug shapes). Returns matches with confidence and bindings. | Scan the graph against all stored bug antibody patterns (known bug shapes). Returns matches with confidence and bindings. | Avoid before you have a scoped suspect area; these are deeper risk/simulation tools. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `trust -> tremor -> heuristics_surface` |
| `antibody_list` | List all stored antibodies with match history. | List all stored antibodies with match history. | Avoid before you have a scoped suspect area; these are deeper risk/simulation tools. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `trust -> tremor -> heuristics_surface` |
| `antibody_create` | Create, disable, enable, or delete an antibody pattern. | Create, disable, enable, or delete an antibody pattern. | Avoid before you have a scoped suspect area; these are deeper risk/simulation tools. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `trust -> tremor -> heuristics_surface` |
| `flow_simulate` | Concurrent execution flow simulation — particles travel the graph in parallel, turbulence points are shared mutable state collisions (race conditions). | Concurrent execution flow simulation — particles travel the graph in parallel, turbulence points are shared mutable state collisions (race conditions). | Avoid before you have a scoped suspect area; these are deeper risk/simulation tools. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `trust -> tremor -> heuristics_surface` |
| `epidemic` | SIR epidemiological bug propagation — given known-buggy modules, predict which neighbors are most likely to harbor undiscovered bugs. | SIR epidemiological bug propagation — given known-buggy modules, predict which neighbors are most likely to harbor undiscovered bugs. | Avoid before you have a scoped suspect area; these are deeper risk/simulation tools. | `agent_id; infected_nodes` | `tool-specific JSON payload; inspect API reference / tools/list` | `trust -> tremor -> heuristics_surface` |
| `tremor` | Change frequency acceleration detection — identifies modules with *accelerating* change frequency. Acceleration precedes bugs, not just high churn. | Change frequency acceleration detection — identifies modules with *accelerating* change frequency. Acceleration precedes bugs, not just high churn. | Avoid before you have a scoped suspect area; these are deeper risk/simulation tools. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `trust -> tremor -> heuristics_surface` |
| `trust` | Per-module actuarial trust scores from defect history. More confirmed bugs = lower trust = higher risk weighting in activation queries. | Per-module actuarial trust scores from defect history. More confirmed bugs = lower trust = higher risk weighting in activation queries. | Avoid before you have a scoped suspect area; these are deeper risk/simulation tools. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `trust -> tremor -> heuristics_surface` |
| `layers` | Auto-detect architectural layers from graph topology. Uses BFS longest-path depth assignment + Tarjan SCC for circular groups. Reports dependency violations. | Auto-detect architectural layers from graph topology. Uses BFS longest-path depth assignment + Tarjan SCC for circular groups. Reports dependency violations. | Avoid before you have a scoped suspect area; these are deeper risk/simulation tools. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `trust -> tremor -> heuristics_surface` |
| `layer_inspect` | Inspect a specific architectural layer: nodes, inter-layer connections, health metrics. | Inspect a specific architectural layer: nodes, inter-layer connections, health metrics. | Avoid before you have a scoped suspect area; these are deeper risk/simulation tools. | `agent_id; level` | `tool-specific JSON payload; inspect API reference / tools/list` | `trust -> tremor -> heuristics_surface` |
## RETROBUILDER
| `ghost_edges` | temporal co-change ghost edges from git history | temporal co-change ghost edges from git history | Avoid without git/runtime/security context; use only when that extra plane matters. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `runtime_overlay -> trace -> impact` |
| `taint_trace` | taint propagation over graph structure | taint propagation over graph structure | Avoid without git/runtime/security context; use only when that extra plane matters. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `runtime_overlay -> trace -> impact` |
| `twins` | structural equivalence / near-equivalence discovery | structural equivalence / near-equivalence discovery | Avoid without git/runtime/security context; use only when that extra plane matters. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `runtime_overlay -> trace -> impact` |
| `refactor_plan` | graph-native refactoring proposals | graph-native refactoring proposals | Avoid without git/runtime/security context; use only when that extra plane matters. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `runtime_overlay -> trace -> impact` |
| `runtime_overlay` | runtime heat and error overlays from OTel spans | runtime heat and error overlays from OTel spans | Avoid without git/runtime/security context; use only when that extra plane matters. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `runtime_overlay -> trace -> impact` |
## Surgical
| `heuristics_surface` | Explain why a node/file ranked as risky or important. | Explain why a node/file ranked as risky or important. | Avoid before locating the target surface; use seek/search/impact first. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `heuristics_surface -> batch_view -> apply_batch` |
| `surgical_context` | Return complete context for a file in one call: full source, symbol table, callers, callees, and test coverage neighbours. Use before `apply` for single-file edits. | Use before single-file edits. | Avoid before locating the target surface; use seek/search/impact first. | `agent_id; file_path` | `tool-specific JSON payload; inspect API reference / tools/list` | `heuristics_surface -> batch_view -> apply_batch` |
| `apply` | `apply` now returns `proactive_insights` when a write lands on a risky or historically unstable surface. | Use to write one file and keep the graph coherent. | Avoid before locating the target surface; use seek/search/impact first. | `agent_id; file_path; new_content` | `updated_node_ids; proactive_insights; elapsed_ms` | `heuristics_surface -> batch_view -> apply_batch` |
| `view` | Fast file reader with line numbers and optional auto-ingest. | Use when you already know the file and need bounded line-numbered reading. | Avoid before locating the target surface; use seek/search/impact first. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `heuristics_surface -> batch_view -> apply_batch` |
| `surgical_context_v2` | Superset of `surgical_context` — returns the target file's full contents AND source excerpts of all connected files (callers, callees, tests) in one call. Eliminates the need to read multiple files separately. Use before `apply_batch` when editing a file and its callers/tests together. | Use before multi-file edits where connected source context matters. | Avoid before locating the target surface; use seek/search/impact first. | `agent_id; file_path` | `tool-specific JSON payload; inspect API reference / tools/list` | `heuristics_surface -> batch_view -> apply_batch` |
| `apply_batch` | `apply_batch` now returns `proactive_insights`, and the final `batch_completed` progress event carries the same payload for streaming clients. | Use to write multiple files atomically and optionally verify. | Avoid before locating the target surface; use seek/search/impact first. | `agent_id; edits` | `results; verification; proactive_insights; progress_events` | `heuristics_surface -> batch_view -> apply_batch` |
| `edit_preview` | Preview a write without touching disk. | Preview a write without touching disk. | Avoid before locating the target surface; use seek/search/impact first. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `heuristics_surface -> batch_view -> apply_batch` |
| `edit_commit` | Commit a previewed edit after confirmation and freshness check. | Commit a previewed edit after confirmation and freshness check. | Avoid before locating the target surface; use seek/search/impact first. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `heuristics_surface -> batch_view -> apply_batch` |
## Search & Efficiency
| `search` | Unified literal/regex/semantic search — graph-aware grep replacement. Searches both node labels in the graph and file contents on disk, returning results with line context. | Use for exact text, regex, or semantic grep across graph + file content. | Avoid for write/plan validation; these help orientation and summary, not mutation safety. | `agent_id; query` | `results; total_matches; proof_state; next_suggested_tool` | `search/glob -> batch_view -> coverage_session` |
| `glob` | Graph-aware file globbing over indexed files. | Use when you need files by path pattern, not content. | Avoid for write/plan validation; these help orientation and summary, not mutation safety. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `search/glob -> batch_view -> coverage_session` |
| `help` | Self-documenting tool reference with m1nd's visual identity. Returns a formatted index of all tools or detailed docs for a specific tool — including params, examples, and NEXT suggestions. | Self-documenting tool reference with m1nd's visual identity. Returns a formatted index of all tools or detailed docs for a specific tool — including params, examples, and NEXT suggestions. | Avoid for write/plan validation; these help orientation and summary, not mutation safety. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `search/glob -> batch_view -> coverage_session` |
| `panoramic` | Full module risk panorama — ranked view of every file-level node by combined risk score. Combines blast radius, centrality, and churn into one sorted list. Critical modules (risk ≥ 0.7) trigger alerts. | Full module risk panorama — ranked view of every file-level node by combined risk score. Combines blast radius, centrality, and churn into one sorted list. Critical modules (risk ≥ 0.7) trigger alerts. | Avoid for write/plan validation; these help orientation and summary, not mutation safety. | `agent_id` | `modules; critical_alerts; summary` | `search/glob -> batch_view -> coverage_session` |
| `report` | Session summary — query log, timing statistics, graph size, and the highest-risk heuristic hotspots in the current graph. Provides a markdown-formatted report ready for display or logging. | Session summary — query log, timing statistics, graph size, and the highest-risk heuristic hotspots in the current graph. Provides a markdown-formatted report ready for display or logging. | Avoid for write/plan validation; these help orientation and summary, not mutation safety. | `agent_id` | `recent_queries; heuristic_hotspots; markdown_summary` | `search/glob -> batch_view -> coverage_session` |
| `metrics` | Return structural metrics per file/function/module. | Use when you want ranked structural measures, not semantic retrieval. | Avoid for write/plan validation; these help orientation and summary, not mutation safety. | `agent_id` | `entries; summary` | `search/glob -> batch_view -> coverage_session` |
| `type_trace` | Trace where a type/struct/enum is used across the graph. | Use when following a type across files and callsites. | Avoid for write/plan validation; these help orientation and summary, not mutation safety. | `agent_id` | `usages; file_groups` | `search/glob -> batch_view -> coverage_session` |
| `diagram` | Generate Mermaid or DOT graph diagrams. | Use when you need a visual graph slice for humans or downstream agents. | Avoid for write/plan validation; these help orientation and summary, not mutation safety. | `agent_id` | `format; diagram; node_count` | `search/glob -> batch_view -> coverage_session` |
## Audit & Session
| `batch_view` | multi-file read surface with stable delimiters and summaries | multi-file read surface with stable delimiters and summaries | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `audit -> batch_view -> cross_verify` |
| `scan_all` | run all structural patterns in one call | run all structural patterns in one call | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `audit -> batch_view -> cross_verify` |
| `cross_verify` | graph vs disk verification (`existence`, `loc`, `hash`) | graph vs disk verification (`existence`, `loc`, `hash`) | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `audit -> batch_view -> cross_verify` |
| `coverage_session` | what this agent has visited so far | what this agent has visited so far | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `audit -> batch_view -> cross_verify` |
| `external_references` | explicit paths outside ingest roots | explicit paths outside ingest roots | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `audit -> batch_view -> cross_verify` |
| `audit` | profile-aware one-call audit | profile-aware one-call audit | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `audit -> batch_view -> cross_verify` |
| `daemon_start` | activate the persisted daemon control plane and set watch roots / poll interval | activate the persisted daemon control plane and set watch roots / poll interval | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `audit -> batch_view -> cross_verify` |
| `daemon_stop` | stop the daemon control plane without discarding alert history | stop the daemon control plane without discarding alert history | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | `agent_id` | `tool-specific JSON payload; inspect API reference / tools/list` | `audit -> batch_view -> cross_verify` |
| `daemon_status` | inspect daemon runtime state, watch roots, and alert counts | Use to inspect daemon liveness, tracked files, and recent tick metrics. | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | `agent_id` | `active; tracked_files; tick_count; last_tick_duration_ms; last_tick_changed_files; last_tick_deleted_files; last_tick_alerts_emitted` | `audit -> batch_view -> cross_verify` |
| `daemon_tick` | poll watched roots once, incrementally re-ingest changed files, and emit deletion drift alerts | Use when you want one explicit delta-processing pass over watched roots. | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | `agent_id` | `changed_files_detected; deleted_files_detected; files_reingested; alerts_emitted` | `audit -> batch_view -> cross_verify` |
| `alerts_list` | list persisted daemon/proactive alerts | Use to review durable daemon/proactive alerts. | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | `agent_id` | `alerts; total; active` | `audit -> batch_view -> cross_verify` |
| `alerts_ack` | acknowledge one or more persisted daemon/proactive alerts | Use after reviewing alerts so they do not keep resurfacing. | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | `agent_id` | `acked; requested; acked_at_ms` | `audit -> batch_view -> cross_verify` |
| `persist` | Force graph and sidecar state persistence to disk. | Use when you want to force-save graph and sidecars now. | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | `agent_id` | `status; snapshot_path; plasticity_path` | `audit -> batch_view -> cross_verify` |
| `boot_memory` | Persist small canonical hot-state values next to the graph. | Use for tiny canonical doctrine/state values that should stay hot. | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | `agent_id` | `action; key; value; entries` | `audit -> batch_view -> cross_verify` |
## Routing Rules
1. Pre-orient with `north` before reading or editing. It is the in-session front door; `audit` is the deeper structural pass once you are oriented, and the `trust_selftest` / `session_handshake` / `recovery_playbook` trio is the degraded/recovery lane.
2. Obey the calibrated verdicts instead of overriding them: `act` / `reverify` / `abstain` on retrieval and prediction (`abstain` = insufficient or uncalibrated — a STOP), `closure: blocked` on `why` (unresolved edge), the `trust_envelope` + sufficiency stop-signal on `seek`, and `trust_band: insufficient_evidence` (no evidence, not medium risk).
3. Prefer the cheapest tool that preserves structural truth.
4. Use `search` / `glob` / `view` for exact known targets; use `seek` / `activate` when the question is semantic or subsystem-shaped.
5. Use `impact`, `predict`, `validate_plan`, and the surgical tools before risky edits.
6. Use `audit`, `cross_verify`, `coverage_session`, `batch_view`, and daemon tools to manage long-running sessions.
7. Use perspective and lock tools only when stateful navigation or multi-agent coordination is worth the overhead.
8. Before ending, `memorize` durable findings with `confidence` and repo-relative `evidence` paths so knowledge lives in the same activation space as code.
