Shared memory and context tools for agentic work.
Code Rooms
# API Reference Overview
m1nd exposes the live MCP tool surface over JSON-RPC 2.0 via stdio. Every tool requires `agent_id` as a parameter. The exported MCP schema uses underscore-based canonical names such as `trail_resume`, `perspective_start`, and `apply_batch`. `tools/list` returns the selected menu, not the entire registry. Use `help` and `health.tool_surface_contract` for full discovery; `M1ND_TOOL_TIER=full` expands the advertised menu.
A host loads the server instructions and `tools/list` into every session before its first call, so both are kept short. The instructions are an operating card: the loop (`north`, then `seek`, then `impact` and its `co_change`), the honest answers, the write laws and the door. On the default and `investigate` menus each core verb carries a one-to-three-sentence card and an input schema with names, types, enums and required fields only. The rest is one call away:
- `help {"tool_name": "<verb>"}` returns the verb's full description, every optional parameter with its default and description, and the fields of object parameters such as `claims[].evidence`.
- `help {"topic": "<id>"}` returns a doctrine card: `reception`, `menu`, `authority`, `north`, `recall`, `verdicts`, `capture`, `promotion`, `telemetry`, `delegate`, `missions`, `soul`, `write_surface`, `voice` or `verbs`. An unknown topic lists them.
- `M1ND_TOOL_TIER=full` serves every verb with its full registry description.
The grouped pages below still keep historical prefixed anchors for stable links, but executable `tools/call` examples use the canonical bare names returned by `tools/list`.
Several tools now do more than return raw results. On the main structural flows you should expect some combination of:
- `proof_state`
- `next_suggested_tool`
- `next_suggested_target`
- `next_step_hint`
That matters for how you integrate m1nd into an agent loop: treat many responses as workflow guidance, not just data blobs.
Two doctrine points frame the whole surface. First, [`north`](lifecycle.md#m1ndnorth) is the in-session front door — call it before reading or editing to pre-orient in one round-trip; it composes `trust_selftest` + `orient` + `boot_memory` + `focus`, and the `trust_selftest` / `session_handshake` / `recovery_playbook` trio is the degraded/recovery lane, not the default entry. Second, respect the [current calibration limits](../../../CALIBRATION-QUALIFICATION.md): all v1 rows are unqualified, prediction abstains, and the seek envelope stays at `reverify` or `unprovable`. Running calibration does not enable `act`; scores and rankings remain inspectable. `abstain` is a STOP, `why` carries a `closure` verdict (`blocked` = the path rests on an unresolved edge), `seek` carries a `trust_envelope` + sufficiency stop-signal, and `trust_band: insufficient_evidence` means no evidence, not medium risk.
## Authority and version boundaries
Examples on grouped reference pages describe payload shapes, not permission to mutate. Generic `ingest` default/`replace` and `merge` are policy-disabled for clients; only the narrow exact-root `refresh` door is available. Follow [Quick Start](../tutorials/quickstart.md) for bootstrap. Write tools enforce additional proof/authority checks, and hardware-dependent paths may remain unavailable. The removed `resonate` and `savings` tools are not current public APIs. Historical anchors may remain for compatibility.
## Tool Index
### Core Activation
| Tool | Description |
|------|-------------|
| [`activate`](activation.md#m1ndactivate) | Spreading activation query across the graph |
| [`warmup`](activation.md#m1ndwarmup) | Task-based warmup and priming |
### Analysis
| [`impact`](analysis.md#m1ndimpact) | Impact radius / blast analysis for a node |
| [`predict`](analysis.md#m1ndpredict) | Co-change prediction for a modified node |
| [`counterfactual`](analysis.md#m1ndcounterfactual) | What-if node removal simulation |
| [`fingerprint`](analysis.md#m1ndfingerprint) | Activation fingerprint and equivalence detection |
| [`hypothesize`](analysis.md#m1ndhypothesize) | Graph-based hypothesis testing against structural claims |
| [`differential`](analysis.md#m1nddifferential) | Focused structural diff between two graph snapshots |
| [`diverge`](analysis.md#m1nddiverge) | Structural drift between a baseline and current graph state |
### Memory, Trails, and Learning
| [`learn`](memory.md#m1ndlearn) | Explicit feedback-based edge adjustment |
| [`drift`](memory.md#m1nddrift) | Weight and structural drift analysis |
| [`why`](memory.md#m1ndwhy) | Path explanation between two nodes |
| [`trail_save`](memory.md#m1ndtrailsave) | Persist current investigation state |
| [`trail_resume`](memory.md#m1ndtrailresume) | Restore a saved investigation with next-step guidance |
| [`trail_list`](memory.md#m1ndtraillist) | List saved investigation trails |
| [`trail_merge`](memory.md#m1ndtrailmerge) | Combine two or more investigation trails |
### Exploration
| [`seek`](exploration.md#m1ndseek) | Intent-aware semantic code search |
| [`scan`](exploration.md#m1ndscan) | Pattern-aware structural code analysis |
| [`missing`](exploration.md#m1ndmissing) | Detect structural holes and missing connections |
| [`trace`](exploration.md#m1ndtrace) | Map runtime errors to structural root causes |
| [`timeline`](exploration.md#m1ndtimeline) | Git-based temporal history for a node |
| [`federate`](exploration.md#m1ndfederate) | Multi-repository federated graph ingestion |
| [`federate_auto`](exploration.md#m1ndfederate_auto) | Discover repo candidates from external path evidence and optionally federate them |
### Perspectives
| [`perspective_start`](perspectives.md#m1ndperspectivestart) | Enter a perspective: navigable route surface from a query |
| [`perspective_routes`](perspectives.md#m1ndperspectiveroutes) | Browse the current route set with pagination |
| [`perspective_inspect`](perspectives.md#m1ndperspectiveinspect) | Expand a route with metrics, provenance, and affinity |
| [`perspective_peek`](perspectives.md#m1ndperspectivepeek) | Extract a code/doc slice from a route target |
| [`perspective_follow`](perspectives.md#m1ndperspectivefollow) | Follow a route: move focus to target, synthesize new routes |
| [`perspective_suggest`](perspectives.md#m1ndperspectivesuggest) | Get the next best move suggestion |
| [`perspective_affinity`](perspectives.md#m1ndperspectiveaffinity) | Discover probable connections a route target might have |
| [`perspective_branch`](perspectives.md#m1ndperspectivebranch) | Fork navigation state into a new branch |
| [`perspective_back`](perspectives.md#m1ndperspectiveback) | Navigate back to previous focus |
| [`perspective_compare`](perspectives.md#m1ndperspectivecompare) | Compare two perspectives on shared/unique nodes |
| [`perspective_list`](perspectives.md#m1ndperspectivelist) | List all perspectives for an agent |
| [`perspective_close`](perspectives.md#m1ndperspectiveclose) | Close a perspective and release associated locks |
### Lifecycle, Search, and Surgical
| [`north`](lifecycle.md#m1ndnorth) | In-session front door: composed pre-orient (trust + task context + prior memory + sufficiency + `next_move` + `honest_gaps`; plus `reception` on a first-contact caller-root mismatch) |
| [`ingest`](lifecycle.md#m1ndingest) | Ingest or re-ingest a codebase, descriptor, or memory corpus |
| [`document_resolve`](lifecycle.md#m1nddocument_resolve) | Resolve canonical local artifacts for a universal document |
| [`document_provider_health`](lifecycle.md#m1nddocument_provider_health) | Report optional document provider availability and install hints |
| [`document_bindings`](lifecycle.md#m1nddocument_bindings) | Show deterministic document-to-code bindings |
| [`document_drift`](lifecycle.md#m1nddocument_drift) | Detect stale, missing, or ambiguous document/code links |
| [`auto_ingest_start`](lifecycle.md#m1ndauto_ingest_start) | Start local-first document auto-ingest watchers |
| [`auto_ingest_status`](lifecycle.md#m1ndauto_ingest_status) | Inspect the document auto-ingest runtime and counters |
| [`auto_ingest_tick`](lifecycle.md#m1ndauto_ingest_tick) | Drain queued document changes immediately |
| [`auto_ingest_stop`](lifecycle.md#m1ndauto_ingest_stop) | Stop document watchers and persist manifest state |
| [`health`](lifecycle.md#m1ndhealth) | Server health and statistics |
| [`trust_selftest`](lifecycle.md#m1ndtrust_selftest) | One-call startup verdict for agent trust and recovery readiness |
| [`session_handshake`](lifecycle.md#m1ndsession_handshake) | Cheap host-surface and graph trust classification |
| [`recovery_playbook`](lifecycle.md#m1ndrecovery_playbook) | Ordered recovery steps for degraded or stale-looking sessions |
| [`search`](lifecycle.md#m1ndsearch) | Literal, regex, or semantic-graph-aware content search |
| [`glob`](lifecycle.md#m1ndglob) | Graph-aware file globbing |
| [`view`](lifecycle.md#m1ndview) | Fast line-numbered file inspection |
| [`validate_plan`](lifecycle.md#m1ndvalidate_plan) | Validate a modification plan against the code graph |
| [`surgical_context_v2`](lifecycle.md#m1ndsurgicalcontextv2) | Pull connected edit context with proof-oriented options |
| [`apply_batch`](lifecycle.md#m1ndapplybatch) | Atomic multi-file write with progress, verification, and handoff |
| [`transplant`](lifecycle.md#m1ndtransplant) | Move a top-level Rust `fn` across files of one crate, computed from the graph |
The grouped reference pages below still organize the surface by area, but the current best operational map is in `help`, the README tool table, and the live `tools/list` response.
---
## Common Parameters
Every tool requires the `agent_id` parameter:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | `string` | Yes | Identifier for the calling agent. Used for session tracking, perspective ownership, lock ownership, and multi-agent coordination. |
Agent IDs are free-form strings. Convention: use the agent's name or role identifier (e.g. `"agent-1"`, `"hacker-auth"`, `"forge-build"`).
## JSON-RPC Request Format
m1nd uses the [MCP protocol](https://modelcontextprotocol.io/) over JSON-RPC 2.0 via stdio. All tool calls use the `tools/call` method.
### Request structure
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "activate",
"arguments": {
"agent_id": "agent-1",
"query": "session management"
}
```
### Successful response
"result": {
"content": [
"type": "text",
"text": "{ ... pretty-printed JSON result ... }"
]
The `text` field contains the tool-specific output as a pretty-printed JSON string. Parse it to get the structured result.
### Error response (tool execution error)
Tool execution errors are returned as MCP `isError` content, **not** as JSON-RPC errors. Many current errors are recovery-oriented and may include fields such as `hint`, `workflow_hint`, `example`, or `suggested_next_step`.
"text": "{ \"error\": \"...\", \"hint\": \"...\", \"suggested_next_step\": \"...\" }"
],
"isError": true
### Error response (protocol error)
JSON-RPC protocol errors use standard error codes:
"error": {
"code": -32601,
"message": "Method not found: bad_method"
## Error Codes
| Code | Meaning |
|------|---------|
| `-32700` | Parse error -- invalid JSON |
| `-32601` | Method not found -- unknown JSON-RPC method |
| `-32603` | Internal error -- server-level failure |
Tool-specific errors (node not found, perspective not found, lock ownership violation, etc.) are returned via `isError: true` in the content, not as JSON-RPC errors.
## Transport
m1nd supports two stdio transport modes, auto-detected per message:
- **Framed**: `Content-Length: N\r\n\r\n{json}` -- standard MCP/LSP framing. Used by Claude Code, Cursor, and most MCP clients.
- **Line**: `{json}\n` -- one JSON object per line. Used by simple scripts and testing.
The server auto-detects which mode each incoming message uses and responds in the same mode.
## Tool Name Normalization
The exported MCP schema uses underscore-based canonical names, but the server still accepts legacy transport aliases when possible:
- `activate` is canonical
- transport-prefixed aliases are accepted where normalization applies
If you are generating tool calls from an MCP client, prefer the canonical schema names returned by `tools/list`.
## Protocol Handshake
Before calling tools, MCP clients perform a handshake:
{"jsonrpc":"2.0","id":0,"method":"initialize","params":{}}
Response:
"id": 0,
"protocolVersion": "2024-11-05",
"serverInfo": { "name": "m1nd-mcp", "version": "1.2.0" },
"capabilities": { "tools": {} }
Then list available tools:
{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}
This returns the full schema for the live tool surface with `inputSchema` for each entry. Treat `tools/list` as the source of truth for the exact count in your current build.
## Graph change tracking (source preview)
The five `lock_*` tools capture, watch, compare, rebase and release session-local
graph baselines. They are discoverable through full help and listed together by
`M1ND_TOOL_TIER=investigate`. Node, subgraph and explicit path scopes are supported;
query-neighborhood and periodic watching are not. They provide no filesystem
exclusion or extra authority. See [the recipe](../../../GRAPH-CHANGE-TRACKING.md).
### Single-file search identity (unreleased source build)
For an ingested single-file root, graph-linked literal/regex `search` rows retain
that file's canonical graph ID, including when its filesystem path is in native
Windows canonical form. `graph_linked: false` identifies disk fallback, not proof
that a returned ID belongs to the graph. Ambiguous relative identities across
distinct roots omit the file-content mapping; identical canonical root aliases
deduplicate. This correction grants no parent/sibling access and changes no lock
or mutation authority. See [the limits and workflow](../../../GRAPH-CHANGE-TRACKING.md).