Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Lifecycle, Document & Lock Tools

This page covers the in-session front door, graph ingestion, document runtime operations, health monitoring, plan validation, persistence, and subgraph locking with change detection.


north

The in-session front door. Call north(task) before reading or editing anything. In one round-trip it composes binding trust, task context (focus nodes + PageRank anchors), prior cross-session memory (each claim with its real age and author — absent, never faked, when unknown), a sufficiency signal, one next_move, and honest_gaps (what m1nd does not yet know).

The packet also carries memory_exists — the ground-truth count of durable L1GHT claims in the on-disk store. It exists so a beat that surfaces no task-relevant memory (memory: []) never lies about an empty store: when the store holds claims that simply did not match this task, memory_exists is > 0 and honest_gaps says the store has memory that did not match — the false “no durable memory yet” line is emitted only when the store is truly empty.

Packet budget. The binding block is fixed-cost: it may not grow with the brain, because north runs on every session and every task. binding.graph_state carries only the ingest_root_count, never a copy of the array. binding.fingerprint carries at most the first 10 ingest roots (the array is ordered oldest → newest, so the head is the identity-bearing prefix and stays stable across writes, which is what makes cross-seam fingerprint comparison meaningful) and always states the real total in ingest_root_count. Truncation is declared, never silent: ingest_roots_truncated (bool, always present), ingest_roots_omitted (how many entries are not shown), and ingest_roots_full_surface — the pointer to the surface that serves the whole array, doctor under runtime_state.ingest_roots (null when nothing was omitted). Measured on a live owner 2026-07-24: 380 roots cost 25,907 bytes (~6.5k tokens) on every north before the head-truncation; the same fingerprint now serializes in under 2,000 bytes. Durable memory sidecars in the agent-memory store also collapse into the single store-directory root rather than minting one ingest root per .light.md file, so the packet stays within its 2,000-token MCP budget as the memory store grows.

On first contact the packet may also carry a reception field (First-Contact Reception, degraded mode): reception.match == "caller_root_mismatch" means the bound graph does not cover your current repo (its root ≠ your resolved caller root) — do not trust retrieval for this repo; read reception.options[]. The public brain-bootstrap consumer is not installed: ingest does not accept project_root (the parameter is absent from the published schema), and cross-root bootstrap is POSITIVE_SOVEREIGN — it fails closed with brain_bootstrap_consumer_not_installed. Continue only against the bound graph with the mismatch warning intact, or reconnect to an owner that already hosts the intended repo. It is null when your root matches the brain serving you (silent bind is legal only on a match) or when the caller root is unknown (direct-HTTP callers).

north composes trust_selftest + orient + boot_memory + focus. Reach for those pieces directly only when you need just one.

When a SystemBlock store exists, north also carries its coherence vital sign through honest_gaps. A mismatch names both the serving brain’s expected slug and the skeleton’s found slug as a signal only; it never blocks reads or writes. No store means no coherence line.

The trust_selftest / session_handshake / recovery_playbook trio is the degraded/recovery lane — use it when trust looks off, retrieval is blocked, or a binding is stale — not the default front door.

Parameters

ParameterTypeRequiredDefaultDescription
agent_idstringYes–Calling agent identifier.
taskstringNo–Natural-language description of what you are about to do. Focuses task context and the next_move.

When to Use

  • Session start – the first call before any read or edit, to pre-orient
  • Task switch – re-orient when the goal changes
  • After needs_ingest – follow the packet’s next_move, then call north again. needs_ingest is a real answer for an empty or unbound graph, not a failure. A repo with no brain yet is the HUMAN’s one-time m1nd init --birth <repo> (offer it, never run it); a stale declared root is ingest {mode:"refresh"}, which is yours
  • ingest – mode:"refresh" after needs_ingest on a root this brain already declares; a repo with no brain at all needs the human’s m1nd init --birth <repo>
  • trust_selftest – the degraded/recovery entry when trust looks off
  • seek – first retrieval pass after orientation

ingest

The engine supports several ingestion modes and adapters, but the public tool is constrained by authority. Default/replace and merge are policy-disabled for clients. A schema describing a mode is not permission to call it. Do not use this tool to bootstrap a missing graph, attach another repository, or merge documents.

For first setup, use Quick Start. A person prepares a shared/served brain in a terminal. The current source-preview isolated path uses an explicit launcher workspace grant before serving tools; it is not a generic ingest exception.

Refresh an already declared exact root

{"method":"tools/call","params":{"name":"ingest","arguments":{"agent_id":"dev","path":"/absolute/path/to/already-declared-repo","mode":"refresh"}}}

refresh requires the caller’s exact canonical root to already be declared by the selected brain. It refuses unresolved paths, subdirectory/root mismatches, overlapping refreshes, changed root sets, and a candidate graph below the shrink guard. It does not mint or rebind a brain. The graph mutation can be expensive; read its result instead of assuming the current graph is fresh.

Inspect the installed schema for supported adapter and payload fields. Document-engine capabilities include code, structured data, memory, and universal/document adapters, but their existence does not expose public merge authority. For existing document nodes, see the read-oriented document tools below.

Related: health, doctor, and agent autonomy.


document_resolve

Resolve the canonical local artifact set for a universally ingested document by source path or universal node id.

Parameters

ParameterTypeRequiredDescription
agent_idstringYesCalling agent identifier.
pathstringNoOriginal source path or canonical markdown path.
node_idstringNoUniversal graph node id for the document.

Example Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "document_resolve",
    "arguments": {
      "agent_id": "agent-1",
      "path": "docs/specs/auth.md"
    }
  }
}

Example Response

{
  "source_path": "docs/specs/auth.md",
  "canonical_markdown_path": "/tmp/m1nd-runtime/l1ght-cache/sources/abcd/canonical.md",
  "canonical_json_path": "/tmp/m1nd-runtime/l1ght-cache/sources/abcd/canonical.json",
  "claims_path": "/tmp/m1nd-runtime/l1ght-cache/sources/abcd/claims.json",
  "producer": "universal:internal",
  "section_count": 4,
  "claim_count": 3,
  "binding_count": 2
}

When to Use

  • when an agent needs the durable local artifact path
  • when a doc has already been ingested and you want its canonical projection
  • before opening canonical.md or claims.json directly

document_provider_health

Report availability, mode, detail, and install hints for optional universal-document providers.

Parameters

ParameterTypeRequiredDescription
agent_idstringYesCalling agent identifier.

Example Response

{
  "python": "python3",
  "providers": [
    { "name": "docling", "available": true, "mode": "broad-spectrum canonicalizer" },
    { "name": "grobid", "available": false, "mode": "scholarly pdf lane", "install_hint": "Set M1ND_GROBID_URL to a reachable GROBID service." }
  ]
}

When to Use

  • before assuming richer HTML/PDF/office extraction exists
  • during environment setup
  • when a provider-backed lane seems to be falling back unexpectedly

document_bindings

Resolve deterministic document-to-code bindings for a universal document.

Parameters

ParameterTypeRequiredDescription
agent_idstringYesCalling agent identifier.
pathstringNoOriginal source path or canonical markdown path.
node_idstringNoUniversal graph node id for the document.
top_kintegerNoMaximum bindings to return.

Example Response

{
  "source_path": "docs/specs/auth.md",
  "bindings": [
    {
      "target_node_id": "file::src/auth/session.rs",
      "target_label": "SessionPool",
      "relation": "mentions_symbol",
      "score": 0.92,
      "confidence": "parsed",
      "reason": "exact label match"
    }
  ]
}

When to Use

  • when the question is “which code implements this doc?”
  • when preparing an implementation map from a spec, paper, or note
  • before editing code to match a document

document_drift

Analyze stale, missing, or ambiguous document/code bindings for a universal document.

Example Response

{
  "source_path": "docs/specs/auth.md",
  "summary": {
    "total_findings": 1,
    "stale_bindings": 1,
    "missing_targets": 0,
    "ambiguous_targets": 0,
    "unbacked_claims": 0,
    "code_change_unreflected": 1
  }
}

When to Use

  • after refactors or repo moves
  • when document claims may no longer be backed by current code
  • when a spec feels “probably stale” and you want a grounded first pass

auto_ingest_start

Start local-first document watchers for one or more roots and supported document families.

Parameters

ParameterTypeRequiredDescription
agent_idstringYesCalling agent identifier.
rootsstring[]YesFilesystem roots to watch recursively.
formatsstring[]NoSupported document formats to auto-ingest.
debounce_msintegerNoMinimum quiet period before a change is eligible for ingestion.
namespacestringNoOptional namespace for non-code document nodes.

Example Request

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "auto_ingest_start",
    "arguments": {
      "agent_id": "agent-1",
      "roots": ["/project/docs", "/project/wiki"],
      "formats": ["universal", "light"],
      "debounce_ms": 200
    }
  }
}

auto_ingest_status

Inspect the current auto-ingest runtime, queue depth, semantic counts, provider status, and provider route/fallback counts.

Example Response

{
  "running": true,
  "queue_depth": 0,
  "semantic_document_count": 12,
  "semantic_claim_count": 34,
  "drift_document_count": 1,
  "provider_status": { "docling": true, "trafilatura": true, "grobid": false }
}

auto_ingest_tick

Drain queued document changes immediately and apply them to the active graph.

Example Response

{
  "ingested_paths": ["/project/docs/specs/auth.md"],
  "removed_paths": [],
  "skipped_paths": [],
  "errored_paths": []
}

auto_ingest_stop

Stop active document watchers and persist the manifest state.


health

Server health and statistics. Returns node/edge counts, query count, uptime, memory usage, plasticity state, and active sessions.

Parameters

ParameterTypeRequiredDefaultDescription
agent_idstringYes–Calling agent identifier.

Example Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "health",
    "arguments": {
      "agent_id": "agent-1"
    }
  }
}

Example Response

{
  "status": "healthy",
  "node_count": 9767,
  "edge_count": 26557,
  "queries_processed": 142,
  "uptime_seconds": 3600.5,
  "memory_usage_bytes": 52428800,
  "plasticity_state": "active",
  "last_persist_time": "2026-03-13T10:30:00Z",
  "active_sessions": [
    { "agent_id": "agent-1", "last_active": "2026-03-13T11:25:00Z" }
  ]
}

When to Use

  • Session start – verify the server is alive and the graph is loaded (prefer north to pre-orient; health is the raw liveness check)
  • Monitoring – periodic health checks in long sessions
  • Debugging – check memory usage and query counts
  • north – composed in-session front door for orientation
  • ingest – load data if the graph is empty
  • trust_selftest – one-call startup verdict for the degraded/recovery lane
  • session_handshake – classify whether this binding is trustworthy
  • recovery_playbook – return ordered recovery steps
  • doctor – explain empty graphs, blocked retrieval, and binding/session continuity
  • drift – check what changed since last session

trust_selftest

Returns a one-call trust verdict for agents. It composes the current binding fingerprint, graph state, host-visible tool evidence, session_handshake, and an optional recovery_playbook.

This is the degraded/recovery entry, not the default front door — reach for it when trust looks off (blocked retrieval, wrong_workspace_binding, a Transport closed error) or when you only need the trust layer. For normal in-session orientation, call north, which composes this check with orient, boot_memory, and focus.

The tool is diagnostic-only: it does not ingest, repair, run shell commands, mutate files, refresh host bindings, or probe retrieval automatically.

Parameters

ParameterTypeRequiredDefaultDescription
agent_idstringYes–Calling agent identifier.
observed_tool_countintegerNo–Tool count returned by the host client’s tools/list.
available_toolsarray<string>No[]Tool names exposed by the host client.
missing_toolsarray<string>No[]Required tool names missing from the host client surface.
observed_toolstringNo–Tool that produced a suspicious result.
observed_proof_statestringNo–Observed proof state, such as blocked.
observed_candidatesintegerNo–Candidate count from suspicious retrieval.
scopestringNo–Repo or scope path associated with the incident.
error_textstringNo–Error text or host message.

Example Request

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "trust_selftest",
    "arguments": {
      "agent_id": "agent-1"
    }
  }
}

Example Response

{
  "schema": "m1nd-trust-selftest-v0",
  "ok": true,
  "status": "ok",
  "verdict": "full_trust",
  "next_action": "proceed_with_m1nd_first",
  "binding_fingerprint": {
    "schema": "m1nd-binding-fingerprint-v0",
    "process_id": 12345,
    "node_count": 9767
  },
  "checks": {
    "graph_populated": true,
    "host_surface_complete": true,
    "stale_binding_suspected": false,
    "recovery_playbook_attached": false
  },
  "recovery_playbook": null
}

Verdicts

  • full_trust – graph has content and the required recovery surface is present.
  • needs_ingest – graph is empty; the playbook names who repairs it (the human’s m1nd init --birth <repo> for a repo with no brain, ingest {mode:"refresh"} for a declared root).
  • orientation_only – graph is empty and the current host surface cannot ingest.
  • degraded_host_tool_surface – the host is hiding required recovery tools.
  • wrong_workspace_binding – the requested scope points at a different workspace than the active binding. Rebind with M1ND_WORKSPACE_ROOT, ingest the requested workspace on the same binding, or use explicit federation for intentional cross-repo work.
  • stale_binding_suspected – populated graph plus blocked/zero-candidate evidence suggests host/session split-brain.
  • session_handshake – cheaper sub-check used by the selftest
  • recovery_playbook – attached when the verdict needs action
  • doctor – deeper runtime diagnosis when recovery asks for it
  • ingest – mode:"refresh" only, and only after needs_ingest on a declared root

session_handshake

Classifies whether the current MCP binding is trustworthy before an agent leans on retrieval. The tool is diagnostic-only: it does not ingest, repair, run shell commands, or execute a retrieval probe.

Pass the host’s tools/list evidence when available. That lets m1nd distinguish a genuinely empty graph from a host surface that is hiding recovery tools such as ingest.

Parameters

ParameterTypeRequiredDefaultDescription
agent_idstringYes–Calling agent identifier.
observed_tool_countintegerNo–Tool count returned by the host client’s tools/list.
available_toolsarray<string>No[]Tool names exposed by the host client.
missing_toolsarray<string>No[]Required tool names missing from the host client surface.
scopestringNo–Absolute or repo-relative scope/path to validate against the active workspace binding.

Example Request

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "session_handshake",
    "arguments": {
      "agent_id": "agent-1"
    }
  }
}

Example Response

{
  "schema": "m1nd-session-handshake-v0",
  "trust_mode": "full_trust",
  "can_ingest": true,
  "can_retrieve": true,
  "can_recover": true,
  "next_action": "continue with m1nd-first retrieval; use compiler/tests for runtime truth",
  "binding_fingerprint": {
    "schema": "m1nd-binding-fingerprint-v0",
    "process_id": 12345,
    "runtime_root": "/tmp/m1nd-runtime",
    "graph_path": "/tmp/m1nd-runtime/graph.json",
    "graph_generation": 1,
    "node_count": 9767
  },
  "tool_surface": {
    "status": "ok",
    "degraded_host_tool_surface": false
  },
  "used_probe": false,
  "probe": null
}

Trust Modes

  • full_trust – graph has content and the required recovery surface is present.
  • needs_ingest – graph is empty; the playbook names who repairs it (the human’s m1nd init --birth <repo> for a repo with no brain, ingest {mode:"refresh"} for a declared root).
  • orientation_only – graph is empty and the current host surface cannot ingest.
  • degraded_host_tool_surface – the host is hiding required recovery tools.
  • wrong_workspace_binding – the requested scope belongs to a different workspace than the active binding. Follow context_guard and doctor_recovery before retrieval.
  • trust_selftest – preferred one-call startup verdict
  • recovery_playbook – what to do when trust mode is not full
  • ingest – mode:"refresh" reloads a declared root after needs_ingest
  • doctor – inspect the recovery payload under suspicion
  • seek – first retrieval pass after full_trust

recovery_playbook

Returns deterministic next steps for a degraded host surface, empty graph, orientation-only binding, or stale-looking retrieval. The tool is diagnostic-only: it does not ingest, repair, run shell commands, mutate files, or probe retrieval.

Use it after session_handshake reports anything other than full_trust, or after a retrieval response reports blocked or zero candidates when the graph should be populated.

If the incident involves an absolute path or another repository, pass it as scope. The playbook returns trust_mode=wrong_workspace_binding and next_action=select_or_bind_workspace when the active graph is healthy but the call targeted a different workspace.

Parameters

ParameterTypeRequiredDefaultDescription
agent_idstringYes–Calling agent identifier.
trust_modestringNo–Prior handshake trust mode to preserve in the diagnostic trail.
observed_toolstringNo–Tool that produced a suspicious result.
observed_proof_statestringNo–Observed proof state, such as blocked.
observed_candidatesintegerNo–Candidate count from the suspicious retrieval.
observed_tool_countintegerNo–Tool count returned by the host client’s tools/list.
available_toolsarray<string>No[]Tool names exposed by the host client.
missing_toolsarray<string>No[]Required tool names missing from the host client surface.
scopestringNo–Repo or scope path associated with the incident.
error_textstringNo–Error text or host message.

Example Request

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "recovery_playbook",
    "arguments": {
      "agent_id": "agent-1",
      "observed_tool": "seek",
      "observed_proof_state": "blocked",
      "observed_candidates": 0
    }
  }
}

Example Response

{
  "schema": "m1nd-recovery-playbook-v0",
  "status": "warn",
  "trust_mode": "stale_binding_suspected",
  "recovery_goal": "Prove whether host, binary, runtime, or graph identity drift is causing split-brain retrieval.",
  "next_action": "call_doctor",
  "steps": [
    {
      "id": "call_doctor",
      "tool": "doctor",
      "action": "Call doctor with the blocked or zero-candidate observation."
    },
    {
      "id": "compare_binding_fingerprint",
      "action": "Compare this binding_fingerprint with the host, repo-local stdio, and repo-local HTTP handshake outputs."
    }
  ],
  "non_claims": [
    "No automatic repair was performed.",
    "No ingest or graph mutation was performed."
  ]
}
  • session_handshake – classify the binding first
  • doctor – inspect active graph/session/runtime clues
  • ingest – run only when the playbook says the graph needs it

doctor

Diagnoses active graph, runtime, session, and stale-binding symptoms. Use it when an agent just ingested a repo but retrieval returns blocked, zero candidates, or a graph that feels empty.

seek, search, and activate include a ready recovery payload when they return blocked or zero actionable candidates. An agent can pass recovery.arguments directly to doctor.

Use the same tool for degraded host surfaces. If tools/list is missing required recovery tools such as ingest, pass the observed count, available tool names, and missing tool names to doctor. It will flag diagnostics.degraded_host_tool_surface and explain whether the current host binding should be treated as orientation-only.

If the suspicious call included a path from another repo, pass it as scope. doctor will surface context_guard.wrong_workspace_binding=true and suggest rebinding with M1ND_WORKSPACE_ROOT, same-binding ingest, or explicit federation instead of diagnosing a stale graph.

doctor is also the surface that serves the complete ingest_roots array, under runtime_state.ingest_roots. The north binding fingerprint is budget-capped and carries only a head plus the count (see Packet budget); when you need every root, ask doctor.

Parameters

ParameterTypeRequiredDefaultDescription
agent_idstringYes–Calling agent identifier.
observed_toolstringNo–Tool that returned a suspicious result.
observed_proof_statestringNo–Observed proof state, such as blocked.
observed_candidatesintegerNo–Candidate count from the suspicious retrieval.
observed_tool_countintegerNo–Tool count returned by the host client’s tools/list.
available_toolsarray<string>No[]Tool names exposed by the host client.
missing_toolsarray<string>No[]Required tool names missing from the host client surface.
scopestringNo–Scope/path used by the suspicious call.
error_textstringNo–Error text or host message.

Example Request

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "doctor",
    "arguments": {
      "agent_id": "agent-1",
      "observed_tool": "seek",
      "observed_proof_state": "blocked",
      "observed_candidates": 0
    }
  }
}

Degraded Tool Surface Request

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "doctor",
    "arguments": {
      "agent_id": "agent-1",
      "observed_tool": "tools/list",
      "observed_proof_state": "blocked",
      "observed_tool_count": 3,
      "available_tools": ["seek", "audit", "doctor"],
      "missing_tools": ["ingest"]
    }
  }
}

Example Response

{
  "schema": "m1nd-doctor-v0",
  "status": "warn",
  "diagnostics": {
    "graph_has_nodes": true,
    "agent_session_known": true,
    "stale_binding_suspected": true,
    "wrong_workspace_binding": false
  },
  "warnings": [
    "seek reported blocked/zero-candidate retrieval while the active graph is populated"
  ],
  "next_actions": [
    "verify the same binding with stdio and HTTP smokes before declaring the graph stale"
  ]
}

When to Use

  • After suspicious retrieval – distinguish empty graph from stale binding
  • After incomplete tools/list – identify a degraded host tool surface
  • After transport changes – confirm HTTP and stdio see the same session
  • Before shell fallback – give the agent a precise recovery path
  • health – basic server health and graph counts
  • ingest – refresh graph state
  • help – tool guidance and examples

validate_plan

Validate a proposed modification plan against the code graph. Detects gaps (affected files missing from the plan), risk level, test coverage, and suggested additions. Designed to be called before implementing a plan.

Parameters

ParameterTypeRequiredDefaultDescription
agent_idstringYes–Calling agent identifier.
actionsobject[]Yes–Ordered list of planned actions. Each object has: action_type (string, required – "modify", "create", "delete", "rename", "test"), file_path (string, required – relative path), description (string, optional), depends_on (string[], optional – other file_paths this action depends on).
include_test_impactbooleanNotrueAnalyze test coverage for modified files.
include_risk_scorebooleanNotrueCompute composite risk score.
scopestringNo–Optional repo or scope path for multi-repo binding diagnostics.

Example Request

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "validate_plan",
    "arguments": {
      "agent_id": "agent-1",
      "actions": [
        { "action_type": "modify", "file_path": "backend/session_pool.py", "description": "Add connection timeout" },
        { "action_type": "modify", "file_path": "backend/worker_pool.py", "description": "Update pool acquire to use timeout" },
        { "action_type": "test", "file_path": "backend/tests/test_session_pool.py" }
      ]
    }
  }
}

Example Response

{
  "actions_analyzed": 3,
  "actions_resolved": 3,
  "actions_unresolved": 0,
  "gaps": [
    {
      "file_path": "backend/config.py",
      "node_id": "file::config.py",
      "reason": "imported by modified file session_pool.py -- timeout config likely needed here",
      "severity": "warning",
      "signal_strength": 0.72
    },
    {
      "file_path": "backend/process_manager.py",
      "node_id": "file::process_manager.py",
      "reason": "in blast radius of worker_pool.py -- calls worker_pool.submit",
      "severity": "info",
      "signal_strength": 0.45
    }
  ],
  "risk_score": 0.52,
  "risk_level": "medium",
  "test_coverage": {
    "modified_files": 2,
    "tested_files": 1,
    "untested_files": ["backend/worker_pool.py"],
    "coverage_ratio": 0.5
  },
  "suggested_additions": [
    { "action_type": "modify", "file_path": "backend/config.py", "reason": "Timeout configuration likely needed" },
    { "action_type": "test", "file_path": "backend/tests/test_worker_pool.py", "reason": "Modified file has no test action in plan" }
  ],
  "blast_radius_total": 47,
  "elapsed_ms": 35.0
}

Risk Levels

LevelScore RangeMeaning
"low"< 0.3Small, well-tested change
"medium"0.3 – 0.6Moderate scope, some gaps
"high"0.6 – 0.8Large scope or missing tests
"critical">= 0.8Very high risk – review carefully

When to Use

  • Before implementing – validate your plan catches all affected files
  • PR review – validate that a PR’s changes are complete
  • Planning – estimate risk and scope before committing to a plan
  • Quality gate – reject plans with risk_score > threshold
  • impact – blast radius for a single node
  • predict – co-change prediction for a single node
  • trace – validate a fix plan for a specific error

lock_create

Unreleased source-build restoration. These five graph-tracking tools are in full registry/help discovery and the opt-in M1ND_TOOL_TIER=investigate menu. The released 1.6.3 menu does not include this restoration. Restart/reconnect the host after changing its server environment. Default core remains unchanged.

Capture an ephemeral graph baseline; this is not a filesystem lock, reservation, source-content diff, or mutual exclusion. All calls use the same agent_id and running session. Copy live canonical node IDs from seek/search, then save the returned lock_id. Baselines do not survive restart.

ParameterTypeRequiredDescription
agent_idstringYesCalling agent identifier; owns the baseline.
scopestringYesnode, subgraph, or path.
root_nodesstring[]YesNonempty exact canonical IDs or unique exact labels. Unknown/ambiguous IDs refuse.
radiusintegerNoSubgraph only: outgoing BFS depth 1–4, default 2.
path_nodesstring[]NoPath only: additional explicit nodes. Does not calculate or validate connectivity.

query_neighborhood and query refuse. node uses the explicit roots; subgraph expands them; path combines roots and optional path nodes. The snapshot observes scoped nodes and every incident edge, including incoming and outgoing boundary edges. baseline_edges counts directed CSR arcs, so a bidirectional logical edge counts twice. Parallel arcs use deterministic weight-sorted multiset pairing, not persistent edge-instance attribution. Treat edge keys as opaque JSON tuples. Output includes lock_id, scope, baseline counts, generation and creation time. See the beginner and advanced recipe.

lock_watch

Required: agent_id, returned lock_id, and strategy. manual buffers no notifications; on_ingest and on_learn buffer coalesced trigger notifications. They do not run a background scheduler, watch source files, or authorize graph updates. periodic refuses. In particular, configuring on_learn does not make an authority-gated learn call executable. Output includes the strategy and the previous strategy when one was replaced.

lock_diff

Required: agent_id and returned lock_id. Compares the current scoped graph against the baseline. Reports canonical node additions/removals, internal and boundary edge additions/removals, weight changes, and generation staleness. Weight changes require an absolute delta greater than 0.001; no_changes means no detected change above that tolerance. diff_truncated flags capped added-node, added-internal-edge and added-boundary-edge previews only. no_changes is computed before those caps. It drains pending watcher notifications but does not advance the baseline. watcher_events_drained counts coalesced notification batches, not mutations. An empty diff is not proof that source text is unchanged: source changes only appear here after an independently authorized graph update.

lock_rebase

Required: agent_id and returned lock_id. After reviewing the diff, replace the comparison point with the current scoped graph. Watch configuration is preserved. Output includes previous/new generations, baseline counts and watcher_preserved. Rebasing discards the old comparison point; it does not grant permission to modify files or ingest roots. If the entire observed scope has vanished, rebase refuses and preserves the old baseline for inspecting removals or releasing it.

lock_release

Required: agent_id and returned lock_id. Discard the baseline, watcher and queued notifications. Output includes the ID and released. All five operations retain existing authority checks; ownership by agent ID is not authentication against a caller choosing another agent ID.


daemon_start

Arm the per-brain code daemon: persist the watched roots (empty = the brain’s own ingest roots) and initialize the daemon counters. Arming is a per-brain opt-in — the durable state lives in the brain’s own store dir, survives owner restarts AND LRU eviction (the daemon re-arms on the next warm-boot/resolve), and the factory default is OFF.

Freshness is honest, not continuous. On a served (HTTP) owner ticks advance BY TRAFFIC — any non-recall verb touching the brain runs a due tick (“fresh when seen”) — or via an explicit daemon_tick. Only a stdio owner additionally holds a live watch-event consumer and an idle clock. No surface claims a free-running monitor; watch_backend reports native_fs only while a real notify watcher exists.

Bursts coalesce: a branch checkout becomes ONE detection whose full changed set enters a persisted backlog, drained a bounded slice per tick (max_files) — no file is lost to truncation. After a burst settles (45 s quiet window, pushed by every activity tick), the daemon auto-reconciles the RATIFIED system-blocks store: it yields voluntarily to a live candidate_lease, keys the write on a fresh store_version, and gives OCC exactly one retry before raising an auto_reconcile_conflict alert.

Parameters

ParameterTypeRequiredDefaultDescription
agent_idstringYes–Calling agent identifier.
watch_pathsstring[]Nocurrent ingest rootsPaths the daemon should watch (the per-brain default is the brain’s own ingest roots).
poll_interval_msintegerNo500Traffic/idle tick due-interval in milliseconds.

When to Use

  • Opting a brain into standing freshness (per-brain, durable, default OFF)
  • Before relying on daemon alerts or daemon_tick
  • Before background/idle reconciliation should run

daemon_stop

Stop the daemon control plane without deleting persisted alert history.

Parameters

ParameterTypeRequiredDescription
agent_idstringYesCalling agent identifier.

When to Use

  • End of a daemon-backed session
  • Before shutting down a host that should not keep reconciling

daemon_status

Inspect daemon liveness and runtime counters. Returns watched roots, tracked files, recent tick metrics, and alert counts.

Parameters

ParameterTypeRequiredDescription
agent_idstringYesCalling agent identifier.

Typical Output Fields

  • active
  • watch_paths
  • poll_interval_ms
  • tracked_files
  • tick_count
  • last_tick_duration_ms
  • last_tick_changed_files
  • last_tick_deleted_files
  • last_tick_alerts_emitted
  • alert_count

When to Use

  • To verify daemon startup worked
  • To inspect whether reconciliation is actually happening
  • To debug daemon slowness or alert silence

daemon_tick

Run one explicit daemon reconciliation pass. Polls watched roots, re-ingests changed files, detects deletions, and emits drift alerts.

Parameters

ParameterTypeRequiredDefaultDescription
agent_idstringYes–Calling agent identifier.
max_filesintegerNo32Maximum changed files to process in one tick.

Typical Output Fields

  • changed_files_detected
  • deleted_files_detected
  • files_reingested
  • ingested_files[]
  • alerts_emitted
  • alert_ids[]
  • tick_at_ms

When to Use

  • To force one reconciliation before reading daemon status
  • To debug watched-root drift deterministically
  • To reproduce daemon ingest issues outside background ticking

alerts_list

List persisted daemon and proactive alerts.

Parameters

ParameterTypeRequiredDefaultDescription
agent_idstringYes–Calling agent identifier.
include_ackedbooleanNofalseInclude already acknowledged alerts.
limitintegerNo50Maximum alerts to return.

When to Use

  • Reviewing daemon findings after a session
  • Building an alert inbox for an agent or UI

alerts_ack

Acknowledge one or more persisted daemon/proactive alerts so they stop resurfacing in the unread queue.

Parameters

ParameterTypeRequiredDescription
agent_idstringYesCalling agent identifier.
alert_idsstring[]YesAlert IDs to acknowledge.

When to Use

  • After reviewing or actioning daemon findings
  • To keep the alert queue focused on new drift

edit_preview

Preview a full-file write without touching disk. Returns a diff, freshness snapshot, and validation report so the caller can inspect before committing.

Parameters

ParameterTypeRequiredDescription
agent_idstringYesCalling agent identifier.
file_pathstringYesAbsolute or workspace-relative file path.
new_contentstringYesCandidate replacement content.
descriptionstringNoHuman-readable summary of the edit.

When to Use

  • Before risky writes
  • When you want a two-phase edit protocol
  • When a human or another agent should inspect the diff first

edit_commit

Commit a previously previewed edit after freshness re-check and explicit confirmation.

Parameters

ParameterTypeRequiredDescription
agent_idstringYesCalling agent identifier.
preview_idstringYesPreview handle returned by edit_preview.
confirmbooleanYesMust be true to commit the preview.
reingestbooleanNoRe-ingest the modified file after commit.

When to Use

  • After a human/agent approves an edit_preview
  • When stale-source protection matters more than speed

transplant

Move a top-level Rust fn to another file of the SAME crate by reference. The server computes the whole move from the graph — the item’s real extent (doc comments and attributes travel), the dependency trichotomy from calls edges (a private dependency travels; a shared one stays, gains pub(crate) and is back-imported), and every referencer re-qualified — then writes source, destination and referencers atomically and re-ingests. A refusal writes nothing and names what blocked it. Design and proof addresses: docs/TRANSPLANT-PRD.md (archived at tag archive/pre-cleanup-379fb0d6).

Parameters

ParameterTypeRequiredDescription
agent_idstringYesCalling agent identifier.
symbolstringYesBare name of the top-level fn to move.
source_filestringYesFile the symbol currently lives in.
dest_filestringYesFile the symbol moves into; must exist and share the source’s crate root.
allow_protectedstringNoExplicit reason for crossing a ci/protected-zones.json path. Absent means a zone match refuses instead of writing.

Returns

moved_symbol, files_changed, deps_travelled, deps_shared, referencing_files, refs_rewritten, refs_unresolved, imports_carried, moved_visibility_bumped, source_back_imported, dependency_source, referencer_source, rustfmt, blocks_touched, state_left_behind, protected_zone, elapsed_ms.

When to Use

  • The change IS a move — you send four fields instead of whole file contents
  • You want the referencers found and rewritten from the graph, not by hand
  • You want a receipt that names what it could not do

v1 Boundaries

  • top-level fn only; module = file stem; same crate; the destination file must already exist
  • grouped/nested use in the source file is reported in refs_unresolved, never rewritten
  • macro-generated references are invisible to the parser

transplant_preview

Stage a transplant without touching disk: the complete multi-file plan (each planned file with its base hash and line deltas), the candidate receipt, and a handle valid for five minutes.

Parameters

Same as transplant.

Returns

preview_id, ttl_ms, files, candidate, elapsed_ms.

When to Use

  • When the move should be inspected or approved before it lands

transplant_commit

Land a staged plan after re-validating the on-disk hash of EVERY planned file — source, destination and each derived referencer. Any drift since the preview refuses the commit as stale, and nothing is written.

Parameters

ParameterTypeRequiredDescription
agent_idstringYesCalling agent identifier.
preview_idstringYesHandle returned by transplant_preview.
confirmbooleanYesMust be true to land the staged plan.

Returns

preview_id, receipt, elapsed_ms.

When to Use

  • To redeem a transplant_preview handle within its TTL

persist

Force graph and sidecar persistence immediately.

Parameters

ParameterTypeRequiredDescription
agent_idstringYesCalling agent identifier.
actionstringYesPersistence action, such as save/load semantics supported by the current implementation.

When to Use

  • Before shutdown
  • Before risky host lifecycle transitions
  • When you want an explicit persistence checkpoint

boot_memory

Persist small canonical hot-state values next to the graph without polluting larger investigation trails.

Parameters

ParameterTypeRequiredDescription
agent_idstringYesCalling agent identifier.
actionstringYesMemory action (set, get, list, delete, etc.).
keystringNoCanonical key to address.
valuejsonNoJSON value to store.

When to Use

  • Short doctrine/state values that should stay hot
  • Session bootstrapping facts an agent should retrieve quickly

heuristics_surface

Explain why a node or file is currently ranked as risky or important. Surfaces trust/tremor/antibody/blast-style heuristic factors in one payload.

Parameters

ParameterTypeRequiredDescription
agent_idstringYesCalling agent identifier.
node_idstringNoGraph node to inspect.
file_pathstringNoFile path to inspect.

When to Use

  • After predict, validate_plan, or surgical flows rank something unexpectedly high
  • When an agent needs explainability before editing or escalating

audit

Profile-aware one-call audit over topology, scans, verification, filesystem truth, and git state.

Parameters

ParameterTypeRequiredDescription
agent_idstringYesCalling agent identifier.
pathstringYesRoot path to audit.
profilestringNoAudit profile such as auto, quick, coordination, or production.
depthstringNoAudit depth.
cross_verifybooleanNoInclude graph-vs-disk verification.
external_refsbooleanNoInclude explicit external reference discovery.

When to Use

  • First pass on an unfamiliar repo
  • Long-running session orientation
  • Pre-handoff or pre-merge structural review