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

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

Related Tools

• 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

Ingest or re-ingest a codebase, descriptor, or memory/document corpus into the graph. This is the primary way to load data into m1nd. It now supports code-first, structured-document, and universal document adapters.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ingest",
    "arguments": {
      "agent_id": "agent-1",
      "path": "/path/to/project-f/backend",
      "adapter": "code",
      "mode": "replace",
      "incremental": false
    }
  }
}

Example Response

{
  "files_processed": 335,
  "nodes_created": 9767,
  "edges_created": 26557,
  "languages": { "python": 335 },
  "elapsed_ms": 910.0
}

Adapters

Mode Behavior

When to Use

• Session start – ingest the codebase if the graph is empty or stale
• After code changes – re-ingest incrementally to update the graph
• Multi-source – merge a memory corpus into a code graph for cross-domain queries
• Federation preparation – use federate instead for multi-repo ingestion

Side Effects

• replace mode: clears all graph state, invalidates all perspectives and locks, marks lock baselines as stale
• merge mode: adds to graph, increments graph generation, triggers watcher events on affected locks

Related Tools

• health – check graph status before deciding to ingest
• doctor – diagnose graph/session continuity when retrieval looks stale
• drift – see what changed since last session
• federate – multi-repo ingestion
• document_resolve – resolve canonical artifacts for a universal document
• auto_ingest_start – keep document roots synchronized after ingest

document_resolve

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

Parameters

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

Related Tools

• document_bindings
• document_drift

document_provider_health

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

Parameters

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

Related Tools

• ingest
• auto_ingest_status

document_bindings

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

Parameters

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

Related Tools

• document_resolve
• document_drift

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

Related Tools

• document_bindings
• auto_ingest_status

auto_ingest_start

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

Parameters

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.

Related Tools

• auto_ingest_start
• auto_ingest_status
• document_resolve

health

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

Parameters

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

Related Tools

• 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

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.

Related Tools

• 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

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.

Related Tools

• 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

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."
  ]
}

Related Tools

• 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

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

Related Tools

• 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

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

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

Related Tools

• 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

Pin a subgraph region and capture a baseline snapshot for change monitoring. Locks are used to track what changes in a region of the graph while you work. The baseline is compared against the current state when you call lock.diff.

Parameters

Scope Types

Example Request

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "lock_create",
    "arguments": {
      "agent_id": "agent-1",
      "scope": "subgraph",
      "root_nodes": ["file::chat_handler.py"],
      "radius": 2
    }
  }
}

Example Response

{
  "lock_id": "lock_agent1_001",
  "scope": "subgraph",
  "baseline_nodes": 1639,
  "baseline_edges": 707,
  "graph_generation": 42,
  "created_at_ms": 1710300000000
}

Limits

• Max locks per agent: configurable (default: 10)
• Max baseline nodes: configurable (default: 5000)
• Max baseline edges: configurable (default: 10000)
• Total memory budget shared with perspectives

When to Use

• Change monitoring – lock a region before making changes, then diff to see what changed
• Multi-agent coordination – lock regions to detect when other agents’ changes affect your work
• Regression detection – lock a stable region and watch for unexpected changes

Related Tools

• lock_watch – set automatic change detection
• lock_diff – compute what changed since baseline
• lock_release – release the lock when done

lock_watch

Set a watcher strategy on a lock. Watchers determine when the lock automatically detects changes. Without a watcher, you must manually call lock.diff.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "lock_watch",
    "arguments": {
      "agent_id": "agent-1",
      "lock_id": "lock_agent1_001",
      "strategy": "on_ingest"
    }
  }
}

Example Response

{
  "lock_id": "lock_agent1_001",
  "strategy": "on_ingest",
  "previous_strategy": null
}

When to Use

• Automatic monitoring – set on_ingest to detect changes after every code re-ingest
• Learning feedback – set on_learn to detect when learning shifts edge weights in your region
• Manual control – set manual to disable automatic detection

Related Tools

• lock_diff – manually trigger a diff (always available regardless of strategy)
• lock_create – create the lock first

lock_diff

Compute what changed in a locked region since the baseline was captured. Returns new/removed nodes, new/removed edges, weight changes, and watcher event counts. Fast-path: if the graph generation has not changed, returns immediately with no_changes: true.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "lock_diff",
    "arguments": {
      "agent_id": "agent-1",
      "lock_id": "lock_agent1_001"
    }
  }
}

Example Response (changes detected)

{
  "diff": {
    "lock_id": "lock_agent1_001",
    "no_changes": false,
    "new_nodes": ["file::chat_handler.py::fn::new_method"],
    "removed_nodes": [],
    "new_edges": ["chat_handler.py|new_method->stream_parser.py|calls"],
    "removed_edges": [],
    "boundary_edges_added": [],
    "boundary_edges_removed": [],
    "weight_changes": [
      { "edge_key": "chat_handler.py|stream_parser.py|imports", "old_weight": 0.5, "new_weight": 0.72 }
    ],
    "baseline_stale": false,
    "elapsed_ms": 0.08
  },
  "watcher_events_drained": 2,
  "rebase_suggested": null
}

Example Response (no changes)

{
  "diff": {
    "lock_id": "lock_agent1_001",
    "no_changes": true,
    "new_nodes": [],
    "removed_nodes": [],
    "new_edges": [],
    "removed_edges": [],
    "boundary_edges_added": [],
    "boundary_edges_removed": [],
    "weight_changes": [],
    "baseline_stale": false,
    "elapsed_ms": 0.001
  },
  "watcher_events_drained": 0,
  "rebase_suggested": null
}

When to Use

• After ingest – check if your locked region was affected
• After learning – check if feedback shifted weights in your region
• Periodic check – poll for changes during long sessions
• Before committing – verify no unexpected changes in the region

Related Tools

• lock_rebase – re-capture baseline after acknowledging changes
• lock_watch – set automatic change detection

lock_rebase

Re-capture the lock baseline from the current graph without releasing the lock. Use this after calling lock.diff and acknowledging the changes – the new baseline becomes the reference for future diffs.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "lock_rebase",
    "arguments": {
      "agent_id": "agent-1",
      "lock_id": "lock_agent1_001"
    }
  }
}

Example Response

{
  "lock_id": "lock_agent1_001",
  "previous_generation": 42,
  "new_generation": 45,
  "baseline_nodes": 1645,
  "baseline_edges": 712,
  "watcher_preserved": true
}

When to Use

• After acknowledging changes – rebase after reviewing a diff to reset the baseline
• After stale warning – when lock.diff returns baseline_stale: true, rebase to fix it
• Periodic refresh – rebase periodically in long sessions to keep baselines current

Related Tools

• lock_diff – the diff that triggers a rebase
• lock_create – creating a new lock is an alternative to rebasing

lock_release

Release a lock and free its resources. Removes the lock state, cleans up pending watcher events, and frees memory. Irreversible.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "lock_release",
    "arguments": {
      "agent_id": "agent-1",
      "lock_id": "lock_agent1_001"
    }
  }
}

Example Response

{
  "lock_id": "lock_agent1_001",
  "released": true
}

When to Use

• Done monitoring – release when you no longer need change detection
• Memory pressure – locks consume memory proportional to baseline size
• Session end – release all locks before ending a session
• Automatic: locks are also cascade-released when their associated perspective is closed via perspective.close

Related Tools

• lock_create – create a new lock
• perspective_close – cascade-releases associated locks

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

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

Related Tools

• daemon_status
• daemon_tick
• alerts_list

daemon_stop

Stop the daemon control plane without deleting persisted alert history.

Parameters

When to Use

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

Related Tools

• daemon_start
• daemon_status

daemon_status

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

Parameters

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

Related Tools

• daemon_start
• daemon_tick
• alerts_list

daemon_tick

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

Parameters

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

Related Tools

• daemon_status
• alerts_list
• cross_verify

alerts_list

List persisted daemon and proactive alerts.

Parameters

When to Use

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

Related Tools

• alerts_ack
• daemon_status

alerts_ack

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

Parameters

When to Use

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

Related Tools

• alerts_list

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

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

Related Tools

• edit_commit
• apply

edit_commit

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

Parameters

When to Use

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

Related Tools

• edit_preview
• apply

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.

Parameters

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

Related Tools

• transplant_preview
• apply_batch

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

Related Tools

• transplant_commit
• edit_preview

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

Returns

preview_id, receipt, elapsed_ms.

When to Use

• To redeem a transplant_preview handle within its TTL

Related Tools

• transplant_preview
• edit_commit

persist

Force graph and sidecar persistence immediately.

Parameters

When to Use

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

Related Tools

• health
• boot_memory

boot_memory

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

Parameters

When to Use

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

Related Tools

• persist
• trail_save

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

When to Use

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

Related Tools

• validate_plan
• apply_batch
• daemon_tick

audit

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

Parameters

When to Use

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

Related Tools

• batch_view
• cross_verify
• coverage_session