Shared memory and context tools for agentic work.
Code Rooms
# API Reference
This mirror summarizes the live 93-tool MCP surface. The exhaustive canonical reference lives in `docs/wiki/src/api-reference/` and the generated `wiki-build/` site. Each tool is callable via JSON-RPC stdio as `m1nd_<tool_name>`.
All tools require an `agent_id` string parameter (use any stable identifier — your editor session ID, agent name, etc.).
Jump to:
- [Foundation](#foundation-13-tools)
- [Document Intelligence](#document-intelligence-8-tools)
- [Perspective Navigation](#perspective-navigation-12-tools)
- [Lock System](#lock-system-5-tools)
- [Superpowers](#superpowers-13-tools)
- [Superpowers Extended](#superpowers-extended-9-tools)
- [RETROBUILDER](#retrobuilder-5-tools)
- [Surgical](#surgical-4-tools)
- [Search & Efficiency](#v050--search--efficiency-5-tools)
- [Audit & Session Ergonomics](#audit--session-ergonomics-13-tools)
---
## Document Intelligence (8 tools)
These tools expose the local-first document runtime that now sits on top of universal ingest:
- `m1nd_document_resolve` — resolve canonical local artifacts for a universal document
- `m1nd_document_provider_health` — inspect optional provider availability, detail, and install hints
- `m1nd_document_bindings` — show likely deterministic document-to-code bindings
- `m1nd_document_drift` — detect stale, missing, or ambiguous document/code links
- `m1nd_auto_ingest_start` — start local-first watchers for docs/specs/wiki roots
- `m1nd_auto_ingest_status` — inspect watcher state, semantic counts, provider routes, and fallbacks
- `m1nd_auto_ingest_tick` — drain queued document changes immediately
- `m1nd_auto_ingest_stop` — stop watchers and persist manifest state
Use these after `m1nd_ingest(adapter="universal")` or when a caller needs document/runtime observability rather than only graph nodes.
## RETROBUILDER (5 tools)
These tools are implemented in the live registry and exposed through `tool_schemas()`:
- `m1nd_ghost_edges` — temporal co-change ghost edges from git history
- `m1nd_taint_trace` — taint propagation over graph structure
- `m1nd_twins` — structural equivalence / near-equivalence discovery
- `m1nd_refactor_plan` — graph-native refactoring proposals
- `m1nd_runtime_overlay` — runtime heat and error overlays from OTel spans
## Audit & Session Ergonomics (13 tools)
These tools reduce orchestration overhead for real agent sessions:
- `m1nd_batch_view` — multi-file read surface with stable delimiters and summaries
- `m1nd_scan_all` — run all structural patterns in one call
- `m1nd_cross_verify` — graph vs disk verification (`existence`, `loc`, `hash`)
- `m1nd_coverage_session` — what this agent has visited so far
- `m1nd_external_references` — explicit paths outside ingest roots
- `m1nd_federate_auto` — turn external paths, manifest/workspace hints, import/package-name evidence, shared API-route signals, or contract artifacts such as `.proto` messages/enums, MCP tools, and OpenAPI schema/components into repo candidates and optional federation
- `m1nd_audit` — profile-aware one-call audit
- `m1nd_daemon_start` — activate the persisted daemon control plane and set watch roots / poll interval
- `m1nd_daemon_stop` — stop the daemon control plane without discarding alert history
- `m1nd_daemon_status` — inspect daemon runtime state, watch roots, and alert counts
- `m1nd_daemon_tick` — poll watched roots once, incrementally re-ingest changed files, and emit deletion drift alerts
- `m1nd_alerts_list` — list persisted daemon/proactive alerts
- `m1nd_alerts_ack` — acknowledge one or more persisted daemon/proactive alerts
## Foundation (13 tools)
Core graph operations: ingest, query, learn, and navigate.
### `m1nd_ingest`
Parse a codebase, markdown docs, or JSON domain graph into the semantic graph.
**Inputs:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | yes | Caller identity |
| `path` | string | yes | Filesystem path to ingest |
| `adapter` | string | no | `"code"` (default), `"memory"`, or `"json"` |
| `namespace` | string | no | Node ID namespace prefix (default: none, auto-set to `"memory"` for memory adapter) |
| `mode` | string | no | `"replace"` (default, clears graph) or `"merge"` (overlay) |
| `incremental` | bool | no | Only re-ingest changed files (default: false) |
**Output:**
```json
{
"mode": "replace",
"adapter": "code",
"namespace": null,
"files_scanned": 335,
"files_parsed": 335,
"nodes_created": 9767,
"edges_created": 26557,
"elapsed_ms": 910,
"node_count": 9767,
"edge_count": 26557
}
```
**Benchmark:** 910ms / 335 files (code) · 138ms / 82 docs (memory adapter)
**Example — ingest code:**
```jsonc
{"method":"tools/call","params":{"name":"m1nd_ingest","arguments":{
"agent_id":"dev","path":"/your/project","incremental":false
}}}
**Example — ingest docs + merge with existing code graph:**
"agent_id":"dev","path":"/your/docs","adapter":"memory","namespace":"docs","mode":"merge"
// After merge: activate() returns both code files AND relevant docs in one pass
**Example — ingest domain-agnostic JSON:**
// /your/domain.json:
// {"nodes": [{"id":"svc::auth","label":"AuthService","type":"module"}],
// "edges": [{"source":"svc::auth","target":"svc::user","relation":"calls","weight":0.8}]}
"agent_id":"dev","path":"/your/domain.json","adapter":"json"
### `m1nd_activate`
Spreading activation query — fires signal into the graph and returns a 4D-scored activation pattern.
| `query` | string | yes | Natural language query |
| `top_k` | int | no | Number of results (default: 20) |
| `dimensions` | array | no | Activation dimensions (default: all 4: `["structural","semantic","temporal","causal"]`) |
| `xlr` | bool | no | Enable XLR noise cancellation (default: true) |
| `include_ghost_edges` | bool | no | Include ghost edge detection (default: true) |
| `include_structural_holes` | bool | no | Include structural hole detection (default: false) |
"query": "session handling",
"seeds": [
{"node_id": "file::session_pool.py", "label": "session_pool.py", "relevance": 0.91}
],
"activated": [
"node_id": "file::session_pool.py",
"label": "session_pool.py",
"type": "File",
"activation": 0.89,
"dimensions": {
"structural": 0.92,
"semantic": 0.95,
"temporal": 0.78,
"causal": 0.71
},
"pagerank": 0.635,
"tags": [],
"provenance": {
"source_path": "backend/session_pool.py",
"line_start": 1,
"line_end": 312,
"canonical": true
"ghost_edges": [
{"source": "file::session_pool.py", "target": "file::healing_manager.py",
"shared_dimensions": ["structural","temporal"], "strength": 0.34}
"structural_holes": [],
"plasticity": {
"edges_strengthened": 0,
"edges_decayed": 0,
"ltp_events": 0,
"priming_nodes": 0
"elapsed_ms": 45.2
Ghost edges are inferred undocumented connections — invisible to grep.
**Benchmark:** 1.36µs (bench, 1K nodes) · 31–77ms (production, 9,767 nodes)
**Scoring:** 4 dimensions, default weights `[structural=0.35, semantic=0.25, temporal=0.15, causal=0.25]`. 3D resonance match = 1.3x bonus. 4D = 1.5x bonus. Hebbian plasticity shifts weights based on `learn()` feedback.
### `m1nd_impact`
Blast radius of a code change — BFS-propagated signal strength from a source node.
| `node_id` | string | yes | Starting node (e.g. `"file::payment.py"`) |
| `direction` | string | no | `"forward"` (default), `"backward"`, or `"both"` |
| `include_causal_chains` | bool | no | Include causal chain detection (default: true) |
"source": "file::chat_handler.py",
"source_label": "chat_handler.py",
"direction": "forward",
"blast_radius": [
{"node_id": "file::session_pool.py", "label": "session_pool.py", "type": "File", "signal_strength": 0.72, "hop_distance": 1},
{"node_id": "file::whatsapp_manager.py", "label": "whatsapp_manager.py", "type": "File", "signal_strength": 0.51, "hop_distance": 2}
"total_energy": 0.635,
"max_hops_reached": 3,
"causal_chains": [
{"path": ["file::chat_handler.py", "file::session_pool.py"], "relations": ["calls"], "cumulative_strength": 0.72}
]
**Benchmark:** 543ns (bench) · 5–52ms (production)
**Note:** There is no `depth` parameter. Use `direction` to control traversal direction.
**Example:**
{"method":"tools/call","params":{"name":"m1nd_impact","arguments":{
"agent_id":"dev","node_id":"file::chat_handler.py"
### `m1nd_why`
Shortest path between two nodes — understand how A depends on B.
| `source` | string | yes | Source node ID |
| `target` | string | yes | Target node ID |
| `max_hops` | int | no | Maximum hops (default: 6) |
"path": ["file::worker_pool.py", "file::process_manager.py::fn::cancel", "file::whatsapp_manager.py"],
"hops": 2,
"edge_types": ["calls", "calls"],
"path_weight": 0.61
**Benchmark:** 5–6ms
{"method":"tools/call","params":{"name":"m1nd_why","arguments":{
"agent_id":"dev",
"source":"file::worker_pool.py",
"target":"file::whatsapp_manager.py"
// → 2-hop dependency via cancel function. Invisible to grep.
### `m1nd_learn`
Hebbian feedback — tell the graph which results were correct or wrong. Edge weights strengthen or weaken accordingly.
| `query` | string | yes | Original query this feedback relates to |
| `feedback` | string | yes | `"correct"`, `"wrong"`, or `"partial"` |
| `node_ids` | array | yes | Node IDs that were used/discarded |
| `strength` | float | no | Feedback strength for edge adjustment (default: 0.2) |
{"edges_strengthened": 740, "ltp_applied": true}
**Benchmark:** <1ms
**When to call:** After every `activate` where you used the results. After every `hypothesize` where you confirmed a verdict. This is what makes the graph smarter over time.
### `m1nd_drift`
What changed in the graph since your last session — structural delta for context recovery.
| `since` | string | no | Timestamp or `"last_session"` (default: `"last_session"`) |
| `include_weight_drift` | bool | no | Include edge weight drift analysis (default: true) |
"nodes_added": 12,
"nodes_removed": 3,
"edges_strengthened": 47,
"edges_weakened": 8,
"top_changed": ["file::worker_pool.py", "file::session_pool.py"]
**Benchmark:** 23ms
**When to call:** At session start, to recover context from the previous session without re-reading files.
### `m1nd_health`
Server diagnostics — verify the MCP server is alive and the graph is loaded.
"status": "ok",
"edge_count": 26557,
"queries_processed": 142,
"uptime_seconds": 342,
"memory_usage_bytes": 48234496,
"plasticity_state": "active",
"last_persist_time": "2026-03-14T19:00:00Z",
"active_sessions": []
### `m1nd_seek`
Find code by natural language intent — more targeted than `activate` for specific lookups.
| `query` | string | yes | Natural language description of what to find |
| `top_k` | int | no | Maximum results (default: 20) |
| `scope` | string | no | File path prefix to limit search scope |
| `node_types` | array | no | Filter by node type: `"function"`, `"class"`, `"struct"`, `"module"`, `"file"` |
| `min_score` | float | no | Minimum combined score (default: 0.1) |
| `graph_rerank` | bool | no | Run graph re-ranking on embedding candidates (default: true) |
**Benchmark:** 10–15ms
### `m1nd_scan`
Run structural pattern scanners. Use a predefined pattern ID or a custom pattern string.
**Predefined patterns:** `"error_handling"`, `"resource_cleanup"`, `"api_surface"`, `"state_mutation"`, `"concurrency"`, `"auth_boundary"`, `"test_coverage"`, `"dependency_injection"`
| `pattern` | string | yes | Pattern ID or custom ast-grep pattern string |
| `scope` | string | no | File path prefix to limit scan scope |
| `severity_min` | float | no | Minimum severity threshold [0.0, 1.0] (default: 0.3) |
| `graph_validate` | bool | no | Validate findings against graph edges (default: true) |
| `limit` | int | no | Maximum findings to return (default: 50) |
**Note:** `scan` takes a single `pattern` (not a `patterns` array). Run once per pattern, or use the predefined IDs for the 8 built-in scanners.
**Benchmark:** 3–5ms per pattern · 38ms for all 8 (production, 335 files)
### `m1nd_timeline`
Temporal evolution of a node — change history, co-change partners, velocity, stability.
| `node` | string | yes | Node external_id (e.g. `"file::backend/chat_handler.py"`) |
| `depth` | string | no | Time depth: `"7d"`, `"30d"`, `"90d"`, `"all"` (default: `"30d"`) |
| `include_co_changes` | bool | no | Include co-changed files with coupling scores (default: true) |
| `include_churn` | bool | no | Include lines added/deleted churn data (default: true) |
| `top_k` | int | no | Max co-change partners (default: 10) |
**Note:** The input parameter is `node` (not `node_id`).
**Benchmark:** ~ms
### `m1nd_diverge`
Structural drift analysis — compare graph state against a baseline reference.
| `baseline` | string | yes | Baseline reference: ISO date (`"2026-03-01"`), git ref (SHA/tag), or `"last_session"` |
| `scope` | string | no | File path glob to limit scope |
| `include_coupling_changes` | bool | no | Include coupling matrix delta (default: true) |
| `include_anomalies` | bool | no | Detect anomalies (test deficits, velocity spikes) (default: true) |
**Note:** `diverge` takes a single `baseline` parameter (not `ref_a`/`ref_b`). It compares current graph state against one baseline point.
**Benchmark:** Varies with git history size
### `m1nd_warmup`
Prime the graph for an upcoming task — pre-activates seed nodes to improve subsequent query relevance.
| `task_description` | string | yes | Description of upcoming work |
| `boost_strength` | float | no | Priming boost strength (default: 0.15) |
**Note:** The input parameter is `task_description` (not `task`).
{"seeds_primed": 50, "elapsed_ms": 89}
**Benchmark:** 82–89ms
**When to call:** Before a focused work session (e.g., "refactor payment flow"). Subsequent `activate` and `impact` calls return better results.
### `m1nd_federate`
Unify multiple repositories into one graph — cross-repo blast radius and dependency analysis.
| `repos` | array | yes | List of `{name, path, adapter}` objects |
| `detect_cross_repo_edges` | bool | no | Auto-detect cross-repo edges (default: true) |
| `incremental` | bool | no | Only re-ingest repos that changed (default: false) |
**Repo object fields:** `name` (string, required — namespace prefix), `path` (string, required — absolute path), `adapter` (string, optional, default: `"code"`)
**Note:** The repo object field is `name` (not `label`).
"repos_ingested": [
{"name": "backend", "path": "/app/backend", "node_count": 9767, "edge_count": 26557, "from_cache": false, "ingest_ms": 910}
"total_nodes": 11217,
"total_edges": 18203,
"cross_repo_edges": [],
"cross_repo_edge_count": 0,
"incremental": false,
"skipped_repos": [],
"elapsed_ms": 1300
**Benchmark:** 1.3s for 2 repos (11,217 nodes, 18,203 cross-repo edges)
{"method":"tools/call","params":{"name":"m1nd_federate","arguments":{
"repos":[
{"name":"backend","path":"/app/backend"},
{"name":"frontend","path":"/app/frontend"}
// → activate("API contract") returns both backend handlers AND frontend consumers
### `m1nd_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.
| `scope` | string | no | Limit discovery to a file path prefix |
| `current_repo_name` | string | no | Optional namespace override for the current workspace |
| `max_repos` | integer | no | Maximum discovered repos to include (default: 8) |
| `detect_cross_repo_edges` | bool | no | Whether `execute=true` should auto-detect cross-repo edges (default: true) |
| `execute` | bool | no | If true, immediately run `federate` with the current repo plus discovered candidates |
"current_repo": {"namespace": "m1nd", "repo_root": "/repo/m1nd"},
"discovered_repos": [
"namespace": "runtime",
"repo_root": "/repo/runtime",
"marker": ".git",
"confidence": "high",
"evidence_types": ["markdown_link"],
"source_nodes": ["file::docs/architecture.md"],
"source_files": ["/repo/m1nd/docs/architecture.md"],
"sampled_paths": ["/repo/runtime/docs/ARCH.md"],
"suggested_action": "run federate_auto with execute=true or pass suggested_repos into federate"
"suggested_repos": [
{"name": "runtime", "path": "/repo/runtime", "adapter": "code"}
"skipped_paths": [],
"executed": false,
"federate_result": null,
"elapsed_ms": 42.0
{"method":"tools/call","params":{"name":"m1nd_federate_auto","arguments":{
"scope":"docs",
"execute":false
## Perspective Navigation (12 tools)
Navigate the graph like a filesystem. Open a perspective anchored to a node, follow routes, peek at source code, branch explorations, compare findings between agents.
### `m1nd_perspective_start`
Open a perspective anchored to a node. Perspectives are stateful navigation sessions.
| `query` | string | yes | Starting query |
| `anchor_node` | string | no | Pin perspective to a specific node |
| `lens` | object | no | Custom ranking: `{dimensions, route_families, xlr, top_k, namespaces, node_types}` |
"perspective_id": "persp-4f2a",
"mode": "Local",
"anchor_node": null,
"focus_node": "file::auth.py",
"routes": [...],
"total_routes": 9,
"page": 1,
"total_pages": 2,
"route_set_version": 1741982400000,
"cache_generation": 42,
"suggested": "inspect R01"
Modes: `"Local"` (query-driven) or `"Anchored"` (pinned to `anchor_node`). Anchored mode degrades to local after 8 hops. Routes paginate at 6/page.
### `m1nd_perspective_routes`
List available navigation routes from the current focus node.
| `perspective_id` | string | yes | Perspective to query |
| `page` | int | no | Page number, 1-based (default: 1) |
| `page_size` | int | no | Routes per page, clamped to [1, 10] (default: 6) |
| `route_set_version` | int | no | Version from previous response for staleness check |
**Output:** Array of routes with type (Structural, Causal, Hole, etc.), target node, and relevance score.
### `m1nd_perspective_follow`
Move the perspective focus to a route target.
| `perspective_id` | string | yes | Perspective to navigate |
| `route_id` | string | no | Stable content-addressed route ID |
| `route_index` | int | no | 1-based page-local route index |
| `route_set_version` | int | no | Version from previous response |
Provide either `route_id` or `route_index`.
### `m1nd_perspective_back`
Navigate backward to the previous focus node.
**Inputs:** `agent_id`, `perspective_id`
### `m1nd_perspective_peek`
Read source code at the currently focused node (returns file content at the node's location).
| `perspective_id` | string | yes | Perspective to peek |
| `route_id` | string | no | Route ID to peek |
| `route_index` | int | no | Route index to peek |
| `route_set_version` | int | no | Version check |
"node_id": "file::worker_pool.py::fn::submit",
"source": "async def submit(self, task: Task) -> str:\n ...",
"file_path": "worker_pool.py",
"start_line": 42,
"end_line": 67
### `m1nd_perspective_inspect`
Deep metadata + 5-factor score breakdown for a route's target node.
| `perspective_id` | string | yes | Perspective |
| `route_id` | string | no | Stable route ID |
**Output:** PageRank, in-degree, out-degree, temporal score, causal score, per-dimension breakdown.
### `m1nd_perspective_suggest`
AI navigation recommendation — the graph suggests which route to follow next.
**Note:** `suggest` does not take a `goal` parameter.
### `m1nd_perspective_affinity`
Check route relevance to the current investigation.
| `route_id` | string | no | Route ID |
| `route_index` | int | no | Route index |
**Note:** `affinity` does not take a `goal` string parameter. It checks affinity of a specific route.
**Output:** `{"affinity": 0.74, "reason": "shares 3 causal ancestors with current focus"}`
### `m1nd_perspective_branch`
Fork an independent perspective copy for parallel exploration. Two agents can investigate the same starting point independently, then compare findings.
| `perspective_id` | string | yes | Source perspective |
| `branch_name` | string | no | Optional branch name |
**Output:** `{"new_perspective_id": "persp-9b1c"}`
### `m1nd_perspective_compare`
Diff two perspectives — shared nodes, unique nodes, divergent findings.
| `perspective_id_a` | string | yes | First perspective |
| `perspective_id_b` | string | yes | Second perspective |
| `dimensions` | array | no | Dimensions to compare (empty = all) |
"shared_nodes": ["file::auth.py", "file::session_pool.py"],
"unique_to_a": ["file::middleware.py"],
"unique_to_b": ["file::jwt_utils.py"],
"convergence_score": 0.62
### `m1nd_perspective_list`
All active perspectives for this agent, with memory usage.
**Inputs:** `agent_id`
### `m1nd_perspective_close`
Release perspective state and free memory.
## Lock System (5 tools)
Pin a subgraph region and watch for changes. Useful for teams working in parallel — detect structural conflicts before they become merge conflicts.
`m1nd_lock_diff` runs in **0.08µs** — essentially free.
### `m1nd_lock_create`
Snapshot a subgraph region.
| `scope` | string | yes | Lock scope: `"node"`, `"subgraph"`, `"query_neighborhood"`, `"path"` |
| `root_nodes` | array | yes | Root nodes for the lock region |
| `radius` | int | no | BFS radius for `subgraph` scope (1–4) |
| `query` | string | no | Query for `query_neighborhood` scope |
| `path_nodes` | array | no | Ordered nodes for `path` scope |
**Note:** `lock.create` does NOT take a `center` parameter. Use `scope` + `root_nodes` instead of `center` + `radius`.
{"lock_id": "lock-7c3d", "scope": "subgraph", "baseline_nodes": 1639, "baseline_edges": 707, "graph_generation": 42, "created_at_ms": 1741982400000}
**Benchmark:** 24ms
### `m1nd_lock_watch`
Register a change strategy on a lock.
**Inputs:** `agent_id`, `lock_id`, `strategy`
Strategy options: `"manual"`, `"on_ingest"`, `"on_learn"`. Note: `"OnAnyChange"` and `"Periodic"` are NOT valid — they do not exist.
### `m1nd_lock_diff`
Compare current graph state against the locked baseline. Returns changes since the lock was created.
**Inputs:** `agent_id`, `lock_id`
"diff": {
"changed": false,
"nodes_added": 0,
"nodes_removed": 0,
"edges_changed": 0
"watcher_events_drained": 0
**Benchmark:** 0.08µs (fast-path when `graph_generation` unchanged)
// Lock a region before starting work
{"name":"m1nd_lock_create","arguments":{"agent_id":"dev","scope":"subgraph","root_nodes":["file::chat_handler.py"],"radius":2}}
// → lock_id: "lock-7c3d", baseline_nodes: 1639
// Check if another agent changed the region (runs in 0.08µs)
{"name":"m1nd_lock_diff","arguments":{"agent_id":"dev","lock_id":"lock-7c3d"}}
// → {"diff": {"changed": false}} — safe to proceed
### `m1nd_lock_rebase`
Advance the lock baseline to the current graph state (after reviewing and accepting changes).
**Benchmark:** 22ms
### `m1nd_lock_release`
Free lock state and release memory.
**Benchmark:** ~0ms
## Superpowers (13 tools)
Advanced reasoning: hypothesis testing, counterfactual simulation, structural hole detection, standing wave analysis, investigation trails, and more.
### `m1nd_hypothesize`
Test a claim against graph structure using Bayesian path scoring. **89% accuracy validated on 10 live claims against a production codebase.**
| `claim` | string | yes | Natural language claim to test |
| `max_hops` | int | no | Max BFS hops for evidence search (default: 5) |
| `include_ghost_edges` | bool | no | Include ghost edges as weak evidence (default: true) |
| `include_partial_flow` | bool | no | Include partial flow when full path not found (default: true) |
| `path_budget` | int | no | Budget cap for all-paths enumeration (default: 1000) |
"claim": "worker_pool depends on whatsapp_manager at runtime",
"claim_type": "depends_on",
"subject_nodes": ["file::worker_pool.py"],
"object_nodes": ["file::whatsapp_manager.py"],
"verdict": "likely_true",
"confidence": 0.72,
"supporting_evidence": [
"type": "path_found",
"description": "2-hop path via cancel function",
"likelihood_factor": 0.72,
"nodes": ["file::worker_pool.py","file::process_manager.py::fn::cancel","file::whatsapp_manager.py"],
"relations": ["calls","calls"],
"contradicting_evidence": [],
"paths_explored": 25015,
"elapsed_ms": 42.1
Verdicts: `"likely_true"` (>0.8 confidence), `"likely_false"` (<0.2), or `"inconclusive"`.
**Benchmark:** 28–58ms (25,015 paths explored)
{"method":"tools/call","params":{"name":"m1nd_hypothesize","arguments":{
"agent_id":"dev","claim":"worker_pool depends on whatsapp_manager at runtime"
// → likely_true, 72% confidence, 2-hop path via cancel function
### `m1nd_counterfactual`
Simulate module removal — compute full cascade of what breaks.
| `node_ids` | array | yes | Nodes to simulate removing |
| `include_cascade` | bool | no | Return full depth-by-depth breakdown (default: true) |
"cascade": [
{"depth": 1, "affected": 23},
{"depth": 2, "affected": 456},
{"depth": 3, "affected": 3710}
"total_affected": 4189,
"orphaned_count": 0,
"pct_activation_lost": 0.41
Multi-node removal detects synergy:
"synergy_factor": 1.42,
"reachability_before": 0.91,
"reachability_after": 0.49
`synergy_factor > 1.0` means removal is super-additive — the nodes are architecturally coupled and should be deleted together.
**Benchmark:** 3ms (single node) · 8ms (multi-node with synergy)
### `m1nd_missing`
Find structural holes — what *should* exist in a region of the graph but doesn't.
| `query` | string | yes | Region to analyze |
| `min_sibling_activation` | float | no | Minimum sibling activation threshold (default: 0.3) |
"holes": [
{"region": "connection lifecycle", "adjacent_nodes": 4, "description": "No dedicated connection pool abstraction"},
{"region": "pool metrics", "adjacent_nodes": 3, "description": "No pool health monitoring"}
"total_holes": 9
**Benchmark:** 44–67ms
**Use for:** Gap analysis before writing specs. Finding orphaned specs in memory adapter graphs. Pre-code review.
### `m1nd_resonate`
Standing wave analysis — find structural hubs where signal reinforces across multiple dimensions simultaneously.
| `query` | string | no | Search query to find seed nodes (alternative to `node_id`) |
| `node_id` | string | no | Specific node to use as seed (alternative to `query`) |
At least one of `query` or `node_id` must be provided.
**Output:** Nodes with highest resonance score + sympathetic pairs + resonant frequency breakdown.
**Benchmark:** 37–52ms (production) · 8.17µs (bench)
### `m1nd_fingerprint`
Find structural twins — nodes with identical or near-identical topology.
| `target_node` | string | no | Node to find equivalents for (if omitted, scans all pairs) |
| `similarity_threshold` | float | no | Cosine similarity threshold (default: 0.85) |
| `probe_queries` | array | no | Optional probe queries for targeted matching |
**Note:** The parameter is `target_node` (not `node_id`).
**Output:** Pairs with similarity score. Use for duplicate detection, consolidation candidates, pattern matching.
**Benchmark:** 1–107ms
### `m1nd_trace`
Map a stacktrace to root cause suspects — ranks files by suspiciousness × centrality.
| `error_text` | string | yes | Full error output (stacktrace + error message) |
| `language` | string | no | Language hint: `"python"`, `"rust"`, `"typescript"`, `"javascript"`, `"go"` (auto-detected if omitted) |
| `window_hours` | float | no | Temporal window for co-change suspect scan (default: 24.0) |
| `top_k` | int | no | Max suspects to return (default: 10) |
**Note:** The parameter is `error_text` (not `stacktrace`).
"language_detected": "python",
"error_type": "AttributeError",
"error_message": "...",
"frames_parsed": 5,
"frames_mapped": 4,
"suspects": [
{"node_id": "file::worker_pool.py", "label": "worker_pool.py", "type": "File",
"suspiciousness": 0.89,
"signals": {"trace_depth_score": 0.9, "recency_score": 0.8, "centrality_score": 0.72},
"related_callers": []}
"co_change_suspects": [],
"causal_chain": ["file::worker_pool.py"],
"fix_scope": {"files_to_inspect": ["worker_pool.py"], "estimated_blast_radius": 47, "risk_level": "high"},
"unmapped_frames": [],
"elapsed_ms": 4.2
**Benchmark:** 3.5–5.8ms (5 frames → 4 suspects ranked)
### `m1nd_validate_plan`
Pre-flight risk assessment for a set of planned changes — blast radius, gap count, risk score.
| `actions` | array | yes | Ordered list of planned actions |
| `include_test_impact` | bool | no | Analyze test coverage for modified files (default: true) |
| `include_risk_score` | bool | no | Compute composite risk score (default: true) |
**Action object fields:** `action_type` (required: `"modify"`, `"create"`, `"delete"`, `"rename"`, or `"test"`), `file_path` (required), `description` (optional), `depends_on` (optional array of file_paths)
**Note:** The parameter is `actions` (not `files`). Each action has `action_type` + `file_path`, not just filenames.
"actions_analyzed": 7,
"actions_resolved": 6,
"actions_unresolved": 1,
"gaps": [],
"risk_score": 0.70,
"risk_level": "high",
"test_coverage": {"modified_files": 6, "tested_files": 4, "untested_files": ["billing.py"], "coverage_ratio": 0.67},
"suggested_additions": [],
"blast_radius_total": 43152,
"elapsed_ms": 10.1
**Benchmark:** 0.5–10ms · 10ms for 7 files (43,152 blast radius)
### `m1nd_predict`
Co-change prediction — given a file you just changed, which other files likely need changes too.
| `changed_node` | string | yes | Node ID that was changed (e.g. `"file::billing.py"`) |
| `top_k` | int | no | Number of predictions (default: 10) |
| `include_velocity` | bool | no | Include velocity scoring (default: true) |
"predictions": [
{"node": "file::billing.py", "probability": 0.84},
{"node": "file::invoice.py", "probability": 0.71}
### `m1nd_trail_save`
Persist investigation state — hypotheses, conclusions, open questions, visited nodes, and activation boosts.
| `label` | string | yes | Human-readable label |
| `hypotheses` | array | no | List of `{statement, confidence, supporting_nodes, contradicting_nodes}` objects |
| `conclusions` | array | no | List of `{statement, confidence, from_hypotheses, supporting_nodes}` objects |
| `open_questions` | array | no | List of open question strings |
| `tags` | array | no | Tags for organization and search |
| `summary` | string | no | Free-form summary (auto-generated if omitted) |
| `visited_nodes` | array | no | Explicitly listed visited nodes with annotations |
| `activation_boosts` | object | no | Map of `node_external_id → boost_weight [0.0, 1.0]` |
**Note:** There is no `notes` parameter — use `summary` instead.
**Output:** `{"trail_id": "trail-abc123", "nodes_saved": 12, "hypotheses_saved": 2, "conclusions_saved": 1, "open_questions_saved": 0}`
### `m1nd_trail_resume`
Restore exact investigation context — nodes, weights, hypotheses — from a saved trail.
| `trail_id` | string | yes | Trail ID to resume |
| `force` | bool | no | Resume even if trail is stale (>50% missing nodes) (default: false) |
"trail_id": "trail-abc123",
"label": "race condition investigation",
"stale": false,
"generations_behind": 0,
"missing_nodes": [],
"nodes_reactivated": 47,
"hypotheses_downgraded": [],
"trail": {...},
"elapsed_ms": 0.2
Stale nodes = nodes that were deleted since the trail was saved.
**Benchmark:** 0.2ms
### `m1nd_trail_merge`
Combine two or more agents' independent investigations. Auto-detects where they converged and flags conflicts on shared hypotheses.
| `trail_ids` | array | yes | Two or more trail IDs to merge |
| `label` | string | no | Label for merged trail (auto-generated if omitted) |
**Note:** The parameter is `trail_ids` (an array). There are no separate `trail_id_a`/`trail_id_b` parameters. Supports merging 2+ trails simultaneously.
"merged_trail_id": "trail-merged-xyz",
"label": "merged investigation",
"source_trails": ["trail-a", "trail-b"],
"nodes_merged": 23,
"hypotheses_merged": 5,
"conflicts": [
{"hypothesis_a": "...", "hypothesis_b": "...", "resolution": "unresolved", "score_delta": 0.12}
"connections_discovered": [
{"type": "shared_node", "detail": "file::worker_pool.py appears in both trails"}
"elapsed_ms": 1.2
**Benchmark:** 1.2ms (5 hypotheses, 3 conflicts detected)
### `m1nd_trail_list`
Browse all saved investigations with optional filters.
| `filter_agent_id` | string | no | Filter to a specific agent's trails |
| `filter_status` | string | no | Filter by status: `"active"`, `"saved"`, `"archived"`, `"stale"`, `"merged"` |
| `filter_tags` | array | no | Filter by tags (any match) |
**Output:** Array of `{trail_id, label, status, created_at_ms, hypothesis_count, conclusion_count, node_count}`.
### `m1nd_differential`
Focused structural diff between two graph snapshots — surface what changed structurally between two points in time.
| `snapshot_a` | string | yes | Path to snapshot A, or `"current"` |
| `snapshot_b` | string | yes | Path to snapshot B, or `"current"` |
| `question` | string | no | Focus question to narrow the diff output |
| `focus_nodes` | array | no | Limit diff to the neighborhood of specific node IDs |
"snapshot_a": "...",
"snapshot_b": "current",
"new_edges": [],
"removed_edges": [],
"weight_changes": [
{"source": "file::auth.py", "target": "file::session.py", "relation": "calls", "old_weight": 0.4, "new_weight": 0.8, "delta": 0.4}
"new_nodes": ["file::new_module.py"],
"removed_nodes": [],
"coupling_deltas": [],
"summary": "14 nodes added, 3 removed, 47 edges changed",
"elapsed_ms": 8.1
**Benchmark:** ~ms (varies with snapshot size)
## Superpowers Extended (9 tools)
Immune memory, concurrent flow simulation, epidemic propagation, tremor detection, trust scoring, and architectural layer analysis.
### `m1nd_antibody_scan`
Scan the graph against all stored bug antibody patterns (known bug shapes). Returns matches with confidence and bindings.
| `scope` | string | no | `"all"` (default) or `"changed"` (only recently changed nodes) |
| `antibody_ids` | array | no | Only scan specific antibodies (default: all) |
| `max_matches` | int | no | Cap on total results (default: 50) |
| `min_severity` | string | no | `"info"` (default), `"warning"`, or `"critical"` |
| `similarity_threshold` | float | no | Minimum match confidence (default: 0.7) |
| `match_mode` | string | no | Label match mode: `"exact"`, `"substring"` (default), `"regex"` |
| `max_matches_per_antibody` | int | no | Cap per antibody (default: 50) |
**Note:** `min_severity` default is `"info"`. Severity scale is `"info"`, `"warning"`, `"critical"` — not `"low"`, `"medium"`, `"high"`.
"matches": [
"antibody_id": "ab-0012",
"label": "TOCTOU is_alive check",
"severity": "high",
"confidence": 0.84,
"matched_at": "file::worker_pool.py::fn::submit",
"bindings": [
{"pattern_node": "check", "matched_node": "file::worker_pool.py::fn::is_alive"},
{"pattern_node": "use", "matched_node": "file::worker_pool.py::fn::send"}
"total_scanned": 47,
"total_matches": 2,
"elapsed_ms": 45
**Benchmark:** 2.68ms (50 patterns, bench) · <100ms full registry scan (10ms budget per pattern)
**When to call:** After every `ingest` to auto-check for recurring bug classes.
### `m1nd_antibody_list`
List all stored antibodies with match history.
| `include_disabled` | bool | no | Include disabled antibodies (default: false) |
**Output:** Array of `{antibody_id, label, severity, match_count, last_matched}`.
### `m1nd_antibody_create`
Create, disable, enable, or delete an antibody pattern.
| `action` | string | no | `"create"` (default), `"disable"`, `"enable"`, `"delete"` |
| `name` | string | create only | Human-readable name |
| `description` | string | no | What bug this catches |
| `severity` | string | no | `"info"`, `"warning"` (default), `"critical"` |
| `pattern` | object | create only | `{nodes, edges, negative_edges}` |
| `antibody_id` | string | non-create | Target antibody for action |
**Pattern node schema:** `{role (string), node_type? (string), required_tags? (array), label_contains? (string)}`
**Pattern edge schema:** `{source_idx (int), target_idx (int), relation? (string)}`
**Important:** Pattern nodes use `role` (not `id`). Pattern edges use `source_idx`/`target_idx` (integer indices into the nodes array, not string references). There is no `label_pattern` or `match_mode` field on nodes — use `label_contains`.
**Pattern schema:**
"nodes": [
{"role": "check", "label_contains": "is_alive"},
{"role": "use", "label_contains": "send"}
"edges": [
{"source_idx": 0, "target_idx": 1, "relation": "calls"}
"negative_edges": [
{"source_idx": 0, "target_idx": 2, "relation": "calls"}
`negative_edges` = structural **absence** detection. The pattern matches ONLY when the negative edge's target is NOT present. This is what grep cannot do.
**Example — teach m1nd a new bug shape:**
{"method":"tools/call","params":{"name":"m1nd_antibody_create","arguments":{
"action":"create",
"name":"CancelledError swallowed",
"severity":"warning",
"pattern":{
"nodes":[
{"role":"handler","label_contains":"CancelledError"},
{"role":"body", "label_contains":"pass"}
"edges":[{"source_idx":0,"target_idx":1,"relation":"contains"}],
"negative_edges":[{"source_idx":0,"target_idx":2,"relation":"contains"}]
// → antibody_id: "ab-0031", specificity: 0.68
### `m1nd_flow_simulate`
Concurrent execution flow simulation — particles travel the graph in parallel, turbulence points are shared mutable state collisions (race conditions).
| `entry_nodes` | array | no | Starting nodes (auto-discovered if empty) |
| `num_particles` | int | no | Particles per entry point (default: 2, max: 100) |
| `lock_patterns` | array | no | Regex patterns for lock/mutex detection |
| `read_only_patterns` | array | no | Regex patterns for read-only operations |
| `max_depth` | int | no | Maximum BFS depth (default: 15) |
| `turbulence_threshold` | float | no | Minimum score to report (default: 0.5) |
| `include_paths` | bool | no | Include particle paths in output (default: true) |
| `max_total_steps` | int | no | Global step budget across all particles (default: 50000) |
| `scope_filter` | string | no | Substring filter to limit which nodes particles can enter |
"turbulence_points": [
"node": "file::session_pool.py::fn::_registry",
"severity": "critical",
"collision_count": 6,
"entry_pairs": [
["file::chat_handler.py::fn::handle_message", "file::ws_relay.py::fn::broadcast"]
"valve_points": [
{"node": "file::worker_pool.py::fn::acquire", "particle_throughput": 0.12, "label": "lock bottleneck"}
"summary": {
"turbulence_count": 1,
"valve_count": 1,
"steps_total": 312
"elapsed_ms": 92
`turbulence` = race condition hotspot. `valve` = lock contention bottleneck.
**Benchmark:** 552µs (4 particles, bench) · 92ms (production)
### `m1nd_epidemic`
SIR epidemiological bug propagation — given known-buggy modules, predict which neighbors are most likely to harbor undiscovered bugs.
| `infected_nodes` | array | yes | Known-buggy node IDs |
| `recovered_nodes` | array | no | Already-fixed node IDs (default: empty) |
| `infection_rate` | float | no | Uniform infection rate (if omitted, derived from edge weights) |
| `recovery_rate` | float | no | SIR recovery rate (default: 0) |
| `iterations` | int | no | SIR simulation steps (default: 50, max: 500) |
| `direction` | string | no | `"forward"`, `"backward"`, or `"both"` (default: `"both"`) |
| `top_k` | int | no | Predictions to return (default: 20) |
| `auto_calibrate` | bool | no | Auto-tune infection rates (default: true) |
| `scope` | string | no | Filter predictions: `"files"`, `"functions"`, `"all"` (default: `"all"`) |
| `min_probability` | float | no | Minimum infection probability threshold (default: 0.001) |
{"node": "file::process_manager.py", "probability": 0.81, "state": "infected"},
{"node": "file::chat_handler.py", "probability": 0.67, "state": "infected"}
"R0": 2.3,
"peak_infected": 12,
"final_infected": 8
"elapsed_ms": 38
`R0 > 1.0` = bug pattern is spreading through the codebase.
Transmission rates by edge type: `imports=0.8`, `calls=0.7`, `inherits=0.6`, `refs=0.4`, `contains=0.3`.
**Benchmark:** 110µs (50 iterations, bench) · 38ms (production)
### `m1nd_tremor`
Change frequency acceleration detection — identifies modules with *accelerating* change frequency. Acceleration precedes bugs, not just high churn.
| `window` | string | no | `"7d"`, `"30d"` (default), `"90d"`, `"all"` |
| `threshold` | float | no | Minimum magnitude to report (default: 0.1) |
| `top_k` | int | no | Top accelerating modules (default: 20) |
| `node_filter` | string | no | Filter to nodes matching this prefix |
| `include_history` | bool | no | Return observation history (default: false) |
| `min_observations` | int | no | Minimum data points to compute tremor (default: 3) |
| `sensitivity` | float | no | Multiplier on acceleration threshold (default: 1.0) |
**Note:** `window` uses lowercase values (`"7d"`, `"30d"`, `"90d"`, `"all"`), not PascalCase (`"Days7"` etc.). Path filtering uses `node_filter`, not a variant of `threshold`.
"alerts": [
"node": "file::stormender_v2_runtime.py",
"direction": "Accelerating",
"magnitude": 8.4,
"risk": "Critical",
"recent_slope": 0.72,
"history": [0.3, 0.5, 0.9, 1.4, 2.1]
"stable_count": 142,
"decelerating_count": 7
Risk tiers: `Critical` (magnitude > 5 AND slope > 0.5), `High`, `Medium`.
**Benchmark:** 236µs (500 nodes, bench) · 14ms (production)
### `m1nd_trust`
Per-module actuarial trust scores from defect history. More confirmed bugs = lower trust = higher risk weighting in activation queries.
| `scope` | string | no | Node type: `"file"` (default), `"function"`, `"class"`, `"all"` |
| `top_k` | int | no | Modules to return (default: 20) |
| `sort_by` | string | no | `"trust_asc"` (default), `"trust_desc"`, `"defects_desc"`, `"recency"` |
| `min_history` | int | no | Minimum defect events required (default: 1) |
| `decay_half_life_days` | float | no | Recency decay in days (default: 30.0) |
| `risk_cap` | float | no | Maximum risk multiplier cap (default: 3.0) |
**Note:** `sort_by` uses snake_case (`"trust_asc"`, `"defects_desc"`, `"recency"`), not PascalCase. `scope` filters by node type; use `node_filter` for path prefix filtering.
"node": "file::worker_pool.py",
"trust_score": 0.23,
"tier": "HighRisk",
"defect_count": 7,
"last_defect_hours_ago": 48
"high_risk_count": 3,
"medium_risk_count": 11,
"avg_trust": 0.71
Tiers: `HighRisk` (< 0.4), `MediumRisk` (< 0.7), `LowRisk` (>= 0.7).
**Benchmark:** 70µs (500 nodes, bench) · 6ms (production)
**Keep scores current:** call `m1nd_learn` with `feedback="correct"` and `node_ids=[buggy_file]` after confirming a bug.
### `m1nd_layers`
Auto-detect architectural layers from graph topology. Uses BFS longest-path depth assignment + Tarjan SCC for circular groups. Reports dependency violations.
| `scope` | string | no | Path prefix to filter |
| `max_layers` | int | no | Maximum layers to detect (default: 8) |
| `include_violations` | bool | no | Report upward/circular/skip-layer violations (default: true) |
| `min_nodes_per_layer` | int | no | Minimum nodes for a layer to be reported (default: 2) |
| `node_types` | array | no | Filter by node types |
| `naming_strategy` | string | no | `"auto"` (default), `"path_prefix"`, `"pagerank"` |
| `exclude_tests` | bool | no | Exclude test files from layer detection (default: false) |
| `violation_limit` | int | no | Maximum violations to return (default: 100) |
**Note:** `naming_strategy` default is `"auto"` (not `"heuristic"`).
"layers": [
{"level": 0, "name": "entry", "nodes": ["file::main.py"], "node_count": 4},
{"level": 1, "name": "routes", "nodes": ["file::chat_routes.py"], "node_count": 23},
{"level": 2, "name": "handlers", "nodes": ["file::chat_handler.py"], "node_count": 31},
{"level": 3, "name": "services", "nodes": ["file::session_pool.py"], "node_count": 18},
{"level": 4, "name": "core", "nodes": ["file::config.py"], "node_count": 9}
"violations": [
"from": "file::config.py",
"to": "file::chat_routes.py",
"type": "UpwardDependency",
"severity": "high"
"total_violations": 1,
"layer_count": 5
Violation types: `UpwardDependency`, `CircularDependency`, `SkipLayer`.
**Benchmark:** 862µs (500 nodes, bench) · 71ms (production)
### `m1nd_layer_inspect`
Inspect a specific architectural layer: nodes, inter-layer connections, health metrics.
| `level` | int | yes | Layer level to inspect |
| `include_edges` | bool | no | Return inter-layer edges (default: true) |
| `top_k` | int | no | Max nodes per layer (default: 50) |
"level": 2,
"name": "handlers",
{"node": "file::chat_handler.py", "pagerank": 0.51, "outgoing_violations": 0}
"health": {
"layer_separation_score": 0.81,
"violation_count": 1,
"avg_internal_coupling": 0.23,
"avg_external_coupling": 0.61
"edges_to_upper_layers": [
{"from": "file::whatsapp_manager.py", "to": "file::chat_routes.py", "violation": true}
`layer_separation_score`: 1.0 = perfectly layered, 0.0 = spaghetti.
**Benchmark:** ~22ms
**Workflow:** `layers()` to detect violations → `layer_inspect(level=N)` to triage the offending layer.
## Surgical (4 tools)
Precision tools for reading and writing individual code nodes with full context awareness. v0.3.0 added `surgical_context_v2` and `apply_batch`.
### `m1nd_surgical_context`
Return complete context for a file in one call: full source, symbol table, callers, callees, and test coverage neighbours. Use before `m1nd_apply` for single-file edits.
| `file_path` | string | yes | Absolute or workspace-relative path to the file |
| `symbol` | string | no | Narrow context to a specific symbol (function/struct/class name) |
| `radius` | int | no | BFS radius for graph neighbourhood (default: 1) |
| `include_tests` | bool | no | Include test files in neighbourhood (default: true) |
**Note:** The parameter is `file_path` (not `node_id`).
"file_path": "/abs/path/backend/chat_handler.py",
"file_contents": "# full file source...",
"line_count": 201,
"node_id": "file::backend/chat_handler.py",
"symbols": [
{"name": "handle_message", "type": "function", "line_start": 42, "line_end": 89}
"focused_symbol": null,
"callers": [
{"node_id": "file::backend/ws_relay.py", "label": "ws_relay.py", "file_path": "backend/ws_relay.py", "relation": "calls", "edge_weight": 0.81}
"callees": [
{"node_id": "file::backend/session_pool.py", "label": "session_pool.py", "file_path": "backend/session_pool.py", "relation": "calls", "edge_weight": 0.72}
"tests": [
{"node_id": "file::tests/test_chat.py", "label": "test_chat.py", "file_path": "tests/test_chat.py", "relation": "tests", "edge_weight": 0.9}
"elapsed_ms": 12
### `m1nd_apply`
`m1nd_apply` now returns `proactive_insights` when a write lands on a risky or
historically unstable surface.
Write LLM-edited code back to a file and trigger incremental re-ingest so the graph stays coherent. Always call `m1nd_surgical_context` or `m1nd_surgical_context_v2` first to get the current file contents.
| `file_path` | string | yes | Absolute or workspace-relative path of the file to overwrite |
| `new_content` | string | yes | New file contents (full replacement, UTF-8) |
| `description` | string | no | Human-readable description of the edit (logged) |
| `reingest` | bool | no | Re-ingest the file after writing (default: true) |
**Note:** The parameter is `new_content` (not `content`). Path can be absolute or workspace-relative.
"file_path": "/abs/path/to/file.py",
"bytes_written": 4821,
"lines_added": 12,
"lines_removed": 3,
"reingested": true,
"updated_node_ids": ["file::backend/worker_pool.py", "file::backend/worker_pool.py::fn::submit"],
"elapsed_ms": 145
{"method":"tools/call","params":{"name":"m1nd_apply","arguments":{
"file_path":"/app/backend/worker_pool.py",
"new_content":"# edited file contents...",
"description":"Fix race condition in submit()",
"reingest":true
### `m1nd_surgical_context_v2`
Superset of `m1nd_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 `m1nd_apply_batch` when editing a file and its callers/tests together.
| `file_path` | string | yes | Absolute or workspace-relative path to the target file |
| `include_tests` | bool | no | Include test files in the neighbourhood (default: true) |
| `max_connected_files` | int | no | Maximum connected files to include source for (default: 5) |
| `max_lines_per_file` | int | no | Maximum lines per connected file excerpt (default: 60) |
**Note:** The parameter is `file_path` (not `node_id`). The primary file is returned in full; connected files are capped at `max_lines_per_file`.
"file_path": "/abs/path/backend/worker_pool.py",
"line_count": 312,
"node_id": "file::backend/worker_pool.py",
{"name": "submit", "type": "function", "line_start": 42, "line_end": 67}
"connected_files": [
"label": "chat_handler.py",
"relation_type": "caller",
"edge_weight": 0.81,
"source_excerpt": "# first 60 lines...",
"excerpt_lines": 60,
"truncated": true
"total_lines": 372,
"elapsed_ms": 18.4
`total_lines` = sum of all lines returned (primary file + all excerpts). Use to manage context budget.
**When to use:** Before any multi-file edit. One call replaces 3–6 separate file reads. The `connected_files` give you callers' context so you can update call sites in the same `apply_batch` call.
{"method":"tools/call","params":{"name":"m1nd_surgical_context_v2","arguments":{
"max_connected_files":5,
"max_lines_per_file":80
**HTTP bridge:**
```bash
curl -s http://localhost:1337/api/tools/m1nd_surgical_context_v2 \
-H 'Content-Type: application/json' \
-d '{"agent_id":"dev","file_path":"/app/backend/worker_pool.py"}'
### `m1nd_apply_batch`
`m1nd_apply_batch` now returns `proactive_insights`, and the final
`batch_completed` progress event carries the same payload for streaming clients.
Atomically write multiple files and trigger a single bulk re-ingest. All-or-nothing by default — if any file fails, all writes are rolled back. Optionally runs post-write verification (5-layer analysis: graph diff, anti-pattern detection, BFS blast radius, test execution, compile check). **12/12 accuracy validated.**
| `edits` | array | yes | List of `{file_path, new_content, description?}` objects |
| `atomic` | bool | no | Rollback all on partial failure (default: true) |
| `reingest` | bool | no | Re-ingest all modified files after writing (default: true) |
| `verify` | bool | no | Run post-write verification (default: false) |
**Edit object fields:** `file_path` (required), `new_content` (required — full replacement UTF-8), `description` (optional string for the apply log)
**Note:** The edit field is `new_content` (not `content`). Use `atomic=true` (default) to guarantee all-or-nothing.
**Output (verify=false):**
"all_succeeded": true,
"files_written": 3,
"files_total": 3,
"results": [
"file_path": "/abs/path/worker_pool.py",
"success": true,
"diff": "@@ -42,6 +42,8 @@...",
"lines_added": 8,
"lines_removed": 2
"total_bytes_written": 14632,
"elapsed_ms": 287
**Output (verify=true) — adds `VerificationReport`:**
"results": [...],
"verification": {
"verdict": "SAFE",
"high_impact_files": [],
"antibodies_triggered": [],
"layer_violations": [],
"total_affected_nodes": 12,
{"file_path": "worker_pool.py", "reachable_files": 3, "risk": "low", "top_affected": ["chat_handler.py"]}
"tests_run": 47,
"tests_passed": 47,
"tests_failed": 0,
"compile_check": "ok",
"verify_elapsed_ms": 1840
"elapsed_ms": 2127
**Verdicts:** `SAFE` (no issues), `RISKY` (warnings or medium blast radius), `BROKEN` (compile failure or test failures).
**Verification layers:**
- Layer A: graph-diff (pre vs post node sets)
- Layer B: anti-pattern detection (todo!() removal, unwrap, error handling patterns)
- Layer C: real BFS blast radius per file (2-hop reachability via CSR edges)
- Layer D: affected test execution (cargo test / pytest / go test)
- Layer E: compilation check (first project type detected)
**Example — multi-file atomic edit:**
{"method":"tools/call","params":{"name":"m1nd_apply_batch","arguments":{
"edits":[
{"file_path":"/app/backend/worker_pool.py","new_content":"...","description":"Fix race condition"},
{"file_path":"/app/backend/chat_handler.py","new_content":"...","description":"Update call site"}
"atomic":true,
"verify":true
curl -s http://localhost:1337/api/tools/m1nd_apply_batch \
-d '{"agent_id":"dev","edits":[{"file_path":"/app/f.py","new_content":"..."}],"verify":true}'
## v0.5.0 — Search & Efficiency (5 tools)
New in v0.5.0: unified search across graph and source files, self-documenting help, panoramic risk analysis, and token economy tracking.
### `m1nd_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.
| `query` | string | yes | Search term, regex pattern, or natural language query |
| `mode` | string | no | `"literal"` (default), `"regex"`, or `"semantic"` |
| `top_k` | int | no | Maximum results (default: 50, max: 500) |
| `case_sensitive` | bool | no | Case-sensitive matching for literal/regex (default: false) |
| `context_lines` | int | no | Lines of context around each match (default: 2, max: 10) |
"query": "async def.*cancel",
"mode": "regex",
"label": "backend/worker_pool.py",
"type": "FileContent",
"line_number": 142,
"matched_line": " async def cancel_task(self, task_id: str) -> bool:",
"context_before": [" # Cancellation handler", ""],
"context_after": [" \"\"\"Cancel a running task by ID.\"\"\"", " if task_id not in self._tasks:"],
"graph_linked": true
"total_matches": 7,
"scope_applied": false,
"elapsed_ms": 12.4
**Modes:**
- **`literal`** — exact substring match on node labels + file contents. Fastest. Use for identifiers, strings, known symbols.
- **`regex`** — linear-time regex (Rust `regex` crate) on node labels + file contents. Supports `(?i)` for case-insensitive. Safe against catastrophic backtracking.
- **`semantic`** — delegates to the seek engine (trigram TF-IDF + graph re-ranking). Use for natural language queries: "code that validates user credentials".
**When to use `search` vs other tools:**
- `search(mode="literal")` — fastest path to a known symbol or string
- `search(mode="regex")` — structural patterns across files (e.g. `async def.*cancel`)
- `search(mode="semantic")` → same as `seek` but via unified interface
- `activate` — spreading activation with 4D scoring; best for exploration, not exact lookup
**Example — literal:**
{"method":"tools/call","params":{"name":"m1nd_search","arguments":{
"agent_id":"dev","query":"session_pool","mode":"literal","context_lines":3
**Example — regex:**
"agent_id":"dev","query":"async def.*cancel","mode":"regex","scope":"backend/"
**Example — semantic:**
"agent_id":"dev","query":"code that validates user credentials","mode":"semantic"
curl -s http://localhost:1337/api/tools/m1nd_search \
-d '{"agent_id":"dev","query":"async def","mode":"regex","top_k":20}'
### `m1nd_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.
| `tool_name` | string | no | Tool name to look up (`"activate"`, `"m1nd_activate"`). Omit for full index. Pass `"about"` for visual identity banner. |
"formatted": "...(ANSI-colored terminal text)...",
"tool": "m1nd_activate",
"found": true,
"suggestions": []
The `formatted` field contains ANSI box-drawing and color codes using m1nd's visual identity palette:
| Glyph | Unicode | Meaning |
|-------|---------|---------|
| `⍌` | U+234C | Spreading activation signal |
| `⍐` | U+2350 | Paths through the graph |
| `⍂` | U+2342 | Structural analysis |
| `𝔻` | U+1D53B | 4D dimensional scoring |
| `⟁` | U+27C1 | Graph connections, edges |
When `tool_name` is unknown, `found: false` and `suggestions` contains the closest matching tool names.
**Example — full index:**
{"method":"tools/call","params":{"name":"m1nd_help","arguments":{
"agent_id":"dev"
**Example — specific tool:**
"agent_id":"dev","tool_name":"hypothesize"
**Example — visual identity:**
"agent_id":"dev","tool_name":"about"
### `m1nd_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.
**Risk formula:** `combined_risk = blast_normalized × 0.5 + centrality × 0.3 + churn × 0.2`
| `scope` | string | no | File path prefix to limit scope |
| `top_n` | int | no | Maximum modules to return (default: 50, max: 1000) |
"modules": [
"label": "backend/chat_handler.py",
"file_path": "backend/chat_handler.py",
"blast_forward": 48,
"blast_backward": 12,
"centrality": 0.74,
"combined_risk": 0.83,
"is_critical": true
"total_modules": 285,
"critical_alerts": [
"reason": "high combined risk (0.83): blast_fwd=48, blast_bwd=12, centrality=0.74"
"elapsed_ms": 18.7
**When to use:** Start every audit session with `panoramic()` to instantly identify the highest-risk modules without reading any files. Critical alerts = where to look first.
{"method":"tools/call","params":{"name":"m1nd_panoramic","arguments":{
"agent_id":"dev","top_n":20
curl -s http://localhost:1337/api/tools/m1nd_panoramic \
-d '{"agent_id":"dev","top_n":20}'
### `m1nd_savings`
Token economy report — session and global tracking of tokens saved by using m1nd instead of grep/glob, with CO2 estimation.
**Estimation model:** Every m1nd query replaces an average of ~500 tokens of grep output + LLM re-reading. CO2 rate: 0.0002g per avoided token. Cost rate: $0.003/1K tokens saved.
"session_tokens_saved": 14200,
"global_tokens_saved": 482000,
"global_co2_grams": 96.4,
"cost_saved_usd": 1.446,
"recent_sessions": [
"agent_id": "dev",
"session_start_ms": 1741987200000,
"queries": 28,
"tokens_saved": 14200,
"co2_grams": 2.84
"formatted_summary": "...(ANSI-colored efficiency report)..."
The `formatted_summary` field displays a colored terminal report with session and global totals.
{"method":"tools/call","params":{"name":"m1nd_savings","arguments":{
### `m1nd_report`
Session summary — query log, timing statistics, tokens saved, and graph state for the calling agent. Provides a markdown-formatted report ready for display or logging.
| `agent_id` | string | yes | Caller identity (report is scoped to this agent) |
"session_queries": 34,
"session_elapsed_ms": 1240.5,
"queries_answered": 34,
"tokens_saved_session": 17000,
"tokens_saved_global": 499000,
"co2_saved_grams": 99.8,
"recent_queries": [
{"tool": "m1nd_activate", "query": "session handling", "elapsed_ms": 45.2, "m1nd_answered": true},
{"tool": "m1nd_hypothesize", "query": "session_pool leaks on cancel", "elapsed_ms": 58.1, "m1nd_answered": true}
"markdown_summary": "## m1nd Session Report\n\n| Metric | Value |\n..."
The `markdown_summary` is pre-formatted for display in chat or documentation. The `recent_queries` field shows the last 10 tool calls for this agent.
{"method":"tools/call","params":{"name":"m1nd_report","arguments":{
## Benchmark Summary
**End-to-end (production, 335–380 files, ~52K lines):**
| Operation | Time |
|-----------|------|
| Full ingest (code) | 910ms–1.3s |
| Full ingest (docs/memory) | 138ms |
| Spreading activation | 31–77ms |
| Blast radius (forward) | 5–52ms |
| Stacktrace analysis | 3.5ms |
| Plan validation | 10ms |
| Counterfactual cascade | 3ms |
| Hypothesis testing | 28–58ms |
| Pattern scan (all 8) | 38ms |
| Antibody scan | <100ms |
| Multi-repo federation | 1.3s |
| Lock diff | 0.08µs |
| Trail merge | 1.2ms |
**Criterion micro-benchmarks (isolated, 1K–500-node graphs):**
| Benchmark | Time |
| `activate` 1K nodes | 1.36 µs |
| `impact` depth=3 | 543 ns |
| `graph build` 1K nodes | 528 µs |
| `flow_simulate` 4 particles | 552 µs |
| `epidemic` SIR 50 iterations | 110 µs |
| `antibody_scan` 50 patterns | 2.68 ms |
| `tremor` detect 500 nodes | 236 µs |
| `trust` report 500 nodes | 70 µs |
| `layer_detect` 500 nodes | 862 µs |
| `resonate` 5 harmonics | 8.17 µs |
## Related Pages
- [Home](Home) — overview, key numbers, common workflows
- [Getting Started](Getting-Started) — installation, Claude Code setup, config, adapters
- [EXAMPLES.md](../EXAMPLES.md) — raw output from production codebase runs
