Introduction

m1nd is a local MCP runtime for coding agents. It ingests a repository into a graph-backed operational model so an agent can ask for structure, impact, connected context, continuity, and likely risk instead of reconstructing the repo from raw files every time.

The current public shape of the product is not just “graph search.” It is a guided runtime with:

• graph-grounded retrieval and impact analysis
• proof_state on the main structural flows
• next_suggested_tool, next_suggested_target, and next_step_hint
• actionable continuity through trail_resume
• observable multi-file writes through apply_batch
• recovery loops that teach the next valid move when a tool is used badly

m1nd ships as an MCP server, runs locally, and works with any MCP-compatible client over stdio. The exported schema exposes the live MCP tool surface for your current build; use tools/list for the exact count.

The Problem

Most agent loops still waste time in the same place: navigation.

An LLM can reason about a file once it has the file. The expensive part is getting the right file, the right neighbors, and enough proof to act without reopening half the repo.

Without a structural layer, the loop usually looks like this:

1. grep for a symbol or phrase
2. open a file
3. grep for callers, callees, or related paths
4. open more files
5. repeat until the subsystem shape becomes clear

That cost shows up as:

• more file reads than necessary
• more token burn on repo reconstruction
• weaker stopping rules during triage
• more false starts before editing
• more friction resuming prior investigations

What m1nd Changes

m1nd keeps the graph local and lets an agent ask for structure directly:

• trace maps stacktraces to likely suspects
• impact inspects blast radius before edits
• seek and activate find intent and connected structure
• document_resolve, document_bindings, and document_drift connect docs/specs to likely code targets and surface stale links
• document_provider_health and auto_ingest_* expose the local-first document runtime
• validate_plan and surgical_context_v2 prepare safer multi-file changes
• trail_resume restores investigations with next-focus and next-tool hints
• apply_batch exposes progress, phases, and final handoff signals

The result is less context churn and better decision quality per step.

Documents And Knowledge Artifacts

The public shape of m1nd is no longer just code plus optional markdown memory.

The merged universal lane can ingest and operationalize:

• markdown notes
• HTML/wiki pages
• office documents
• scholarly PDFs
• structured standards and citation corpora

When a document enters through the universal lane, m1nd can preserve canonical local artifacts, bind that document to likely code, and surface document/code drift when the implementation moves faster than the docs.

Current benchmark truth from the recorded warm-graph corpus:

• 10518 -> 5182 aggregate token proxy
• 50.73% aggregate reduction
• 14 -> 0 false starts
• 39 guided follow-throughs
• 12 successful recovery loops

Not every scenario is a token win. Some wins are continuity, recovery, or execution clarity. That is part of the product truth too.

Core Runtime Ideas

Graph-grounded retrieval

The graph is still the foundation. Activation, semantic retrieval, path search, temporal history, and blast-radius analysis all sit on top of a shared structural model rather than a stateless grep loop.

Guided handoff

Several high-value tools now return more than raw results. They can expose:

• proof_state
• next_suggested_tool
• next_suggested_target
• next_step_hint

That turns the server from a catalog of answers into a layer that helps the agent decide what to do next.

Continuity

trail_resume is no longer just bookmark restore. It can return compact resume hints, reactivated nodes, the next focus node, the next open question, and the likely next tool. This is one of the main reasons the benchmark corpus now records fewer false starts.

Observable execution

apply_batch is now an observable write surface:

• status_message
• proof_state
• lifecycle phases such as validate, write, reingest, verify, and done
• coarse progress fields like progress_pct
• structured progress_events
• live SSE progress in serve mode

Recovery loops

Common failures no longer have to be dead ends. Many invalid calls now return hints, examples, and a suggested next step so the agent can repair the call instead of rediscovering the workflow from scratch.

Who This Is For

• agent builders who want a local structural layer for navigation and edit prep
• MCP client users who want better triage, continuity, and connected context
• multi-agent systems that need shared graph truth without shipping code to an API
• teams that want safer workflow around stacktrace triage, blast radius, and multi-file changes

m1nd is not a compiler, debugger, or test runner replacement. It is best when the real bottleneck is structural understanding and repo navigation.

How To Read This Wiki

Architecture explains how the core crates and auxiliary bridge surfaces fit together and how the MCP server turns graph truth into agent-facing runtime behavior.

Concepts covers the underlying graph ideas such as activation, plasticity, and structural holes.

API Reference documents the current MCP surface, including underscore-based canonical tool names, guided outputs, and transport behavior.

Tutorials walks through the main workflows from first ingest to connected edit prep.

The Benchmarks page is the current product-truth layer for token proxy, false starts, guided follow-through, and recovery loops. The Changelog tracks the release history from v0.6.x through v0.8.0 and onward.

System Architecture Overview

m1nd is a local MCP runtime for coding agents. Internally it is still built on a graph-and-analysis system, but the public runtime is organized around an operational contract:

• graph-grounded retrieval and ranking
• proof-aware structural flows
• next-step handoff on high-value tools
• continuity through trails and perspectives
• observable multi-file writes through apply_batch
• repair-friendly errors when a tool call goes wrong

The workspace exposes the live MCP tool surface over JSON-RPC stdio, with an HTTP/UI surface in the default build. Use tools/list for the exact count in your current build.

Four-Crate Workspace

The system is organized as a Cargo workspace with three core crates plus one auxiliary bridge crate:

[workspace]
members = ["m1nd-core", "m1nd-ingest", "m1nd-mcp", "m1nd-openclaw"]
resolver = "2"

[workspace.dependencies]
thiserror = "2"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
smallvec = { version = "1.13", features = ["serde"] }
parking_lot = "0.12"
rayon = "1.10"
static_assertions = "1"

Dependencies flow strictly downward: m1nd-mcp depends on both m1nd-core and m1nd-ingest; m1nd-ingest depends on m1nd-core; m1nd-core has no internal crate dependencies.

Data Flow

graph TD
    subgraph "m1nd-mcp (Transport)"
        STDIO["JSON-RPC stdio<br/>dual: framed + line"]
        DISPATCH["Tool Dispatch<br/>live tool surface"]
        SESSION["SessionState<br/>SharedGraph + Engines"]
        PERSIST["Auto-Persist<br/>every 50 queries"]
    end

    subgraph "m1nd-ingest (Extraction)"
        WALK["DirectoryWalker<br/>walkdir + binary detect"]
        EXTRACT["Parallel Extraction<br/>rayon threadpool"]
        RESOLVE["ReferenceResolver<br/>proximity disambiguation"]
        DIFF["GraphDiff<br/>incremental updates"]
        MEMORY["MemoryAdapter<br/>markdown → graph"]
        UNIVERSAL["Universal + Document Adapters<br/>canonical docs → graph"]
    end

    subgraph "m1nd-core (Engine)"
        GRAPH["CSR Graph<br/>forward + reverse"]
        NODES["NodeStorage (SoA)<br/>hot|warm|cold paths"]
        ACT["Activation Engine<br/>hybrid heap/wavefront"]
        SEM["Semantic Engine<br/>trigram TF-IDF + PPMI"]
        TEMP["Temporal Engine<br/>co-change + decay"]
        PLAST["Plasticity Engine<br/>Hebbian LTP/LTD"]
        XLR["XLR Engine<br/>spectral noise cancel"]
        RES["Resonance Engine<br/>standing waves"]
        SNAP["Snapshot<br/>atomic JSON persist"]
    end

    STDIO --> DISPATCH
    DISPATCH --> SESSION
    SESSION --> PERSIST
    PERSIST --> SNAP

    SESSION -->|ingest| WALK
    WALK --> EXTRACT
    EXTRACT --> RESOLVE
    RESOLVE --> GRAPH
    UNIVERSAL --> GRAPH
    DIFF -->|incremental| GRAPH

    SESSION -->|activate| ACT
    SESSION -->|impact/predict| TEMP
    SESSION -->|learn| PLAST
    SESSION -->|activate+xlr| XLR
    SESSION -->|resonate| RES

    ACT --> GRAPH
    ACT --> SEM
    ACT --> NODES
    SEM --> GRAPH
    TEMP --> GRAPH
    PLAST --> GRAPH
    XLR --> GRAPH
    RES --> GRAPH
    GRAPH --> NODES

Request Lifecycle

A typical structural workflow now has two layers: graph execution and agent handoff.

Example: activate

1. Transport: JSON-RPC message arrives on stdin (either Content-Length framed or raw line JSON).
2. Dispatch: McpServer.serve() parses the JSON-RPC request, matches the tool name, extracts parameters.
3. Session: The tool handler acquires a read lock on SharedGraph (Arc<parking_lot::RwLock<Graph>>).
4. Seed Finding: SeedFinder locates matching nodes via a 5-level cascade: exact label, prefix, substring, tag, fuzzy trigram.
5. Activation: HybridEngine auto-selects heap or wavefront strategy based on seed ratio and average degree.
6. Dimensions: Four dimensions run: Structural (BFS/heap propagation), Semantic (trigram TF-IDF + co-occurrence PPMI), Temporal (decay + velocity), Causal (forward/backward with discount).
7. Merge: merge_dimensions() combines results with adaptive weights [0.35, 0.25, 0.15, 0.25] and resonance bonus (4-dim: 1.5x, 3-dim: 1.3x).
8. XLR: If enabled, AdaptiveXlrEngine runs spectral noise cancellation with dual hot/cold pulses and sigmoid gating.
9. Plasticity: PlasticityEngine.update() runs the 5-step Hebbian cycle on co-activated edges.
10. Response: Results serialized to JSON-RPC response, written to stdout in the same transport mode as the request.

Example: guided structural flow

A more agent-native flow such as trace -> view -> surgical_context_v2 -> validate_plan -> apply_batch adds two extra kinds of behavior on top of the graph work:

1. Cognitive state: tools can expose proof_state such as triaging, proving, or ready_to_edit
2. Next-step guidance: tools can return next_suggested_tool, next_suggested_target, and next_step_hint

This is one of the biggest architectural changes in v0.6.0: the MCP layer is no longer just a transport for graph answers. It is a transport for graph answers plus workflow guidance.

Example: code plus document workflow

The current architecture also supports a second operating loop:

1. ingest code
2. ingest or auto-ingest document roots through the universal lane
3. resolve canonical document artifacts
4. bind documents to likely code
5. inspect document/code drift after implementation moves

This is what turns m1nd from a code-only graph into a local code + knowledge runtime.

Key Design Decisions

Compressed Sparse Row (CSR) Graph

The graph uses CSR format rather than adjacency lists or adjacency matrices. CSR provides O(1) neighbor iteration start, cache-friendly sequential access, and compact memory layout. Edge weights are stored as AtomicU32 (bit-reinterpreted f32) for lock-free plasticity updates via CAS with a 64-retry limit.

Forward and reverse CSR arrays are maintained in parallel, enabling both outgoing and incoming edge traversal without full graph scans.

Struct-of-Arrays Node Storage

NodeStorage uses SoA layout with explicit hot/warm/cold path separation:

• Hot path (every query): activation: Vec<[FiniteF32; 4]>, pagerank: Vec<FiniteF32>
• Warm path (plasticity): plasticity: Vec<PlasticityNode>
• Cold path (seed finding, export): label, node_type, tags, last_modified, change_frequency, provenance

This layout ensures that activation queries touch only hot-path arrays, maximizing L1/L2 cache utilization.

FiniteF32 Type Safety

All floating-point values in the graph are wrapped in FiniteF32, a #[repr(transparent)] newtype that makes NaN and Infinity impossible by construction:

#![allow(unused)]
fn main() {
#[derive(Clone, Copy, Default, PartialEq)]
#[repr(transparent)]
pub struct FiniteF32(f32);

impl FiniteF32 {
    #[inline]
    pub fn new(v: f32) -> Self {
        debug_assert!(v.is_finite(), "FiniteF32::new received non-finite: {v}");
        Self(if v.is_finite() { v } else { 0.0 })
    }
}
}

Because NaN is excluded, FiniteF32 can safely implement Ord, Eq, and Hash – operations that are unsound on raw f32. Related newtypes PosF32 (strictly positive), LearningRate (0, 1]), and DecayFactor (0, 1]) provide compile-time invariant enforcement for their respective domains.

String Interning

All node labels, tags, and relation names are interned via StringInterner. Once interned, string comparisons become u32 == u32 (zero-allocation, single CPU cycle). The interner maps strings to InternedStr(u32) handles and provides O(1) bidirectional lookup.

Parallel Extraction, Sequential Building

Ingestion uses rayon for parallel file reading and language-specific extraction across all CPU cores, but graph construction is single-threaded. This avoids the complexity of concurrent graph mutation while still saturating I/O bandwidth during the most expensive phase (parsing hundreds of files).

Atomic Persistence

Graph and plasticity state are saved via atomic write: serialize to a temporary file, then rename() over the target. This prevents corruption on crash (FM-PL-008). The NaN firewall at the export boundary rejects any non-finite values that might have leaked through.

Performance Characteristics

There are two truths worth separating:

1. engine/runtime timings
2. workflow-level benchmark truth

Engine timings still matter, especially for ingest and structural queries. Workflow benchmarks matter when the goal is to reduce context churn, false starts, and repair loops.

Representative measured engine timings:

Workflow benchmark truth lives on the Benchmarks page. The current recorded warm-graph corpus shows:

• 10518 -> 5182 aggregate token proxy
• 50.73% aggregate reduction
• 14 -> 0 false starts
• 39 guided follow-throughs
• 12 successful recovery loops

Memory footprint scales linearly with graph size. A 10K-node graph with 25K edges uses approximately 15MB of heap (graph + all engine indexes). The CSR representation is 3-5x more compact than equivalent adjacency list representations.

Scaling Bounds

• Node limit: NodeId(u32) supports up to ~4 billion nodes. Practical limit is the max_nodes config (default: 500K).
• Edge weights: AtomicU32 CAS with 64-retry limit. Under high contention (>32 concurrent plasticity updates on the same edge), CAS may exhaust retries and return CasRetryExhausted.
• Co-occurrence index: Disabled above 50K nodes (COOCCURRENCE_MAX_NODES) to avoid O(N * walks * length) random walk cost.
• Co-change matrix: Hard budget of 500K entries with per-row cap of 100 entries.
• Resonance pulse budget: 50K pulses per standing wave analysis to prevent combinatorial explosion in dense subgraphs.

Multi-Agent Model

m1nd runs as a single process serving multiple agents through the same JSON-RPC stdio channel. All agents share one graph and one set of engines. Writes (plasticity updates, ingestion) are immediately visible to all readers through SharedGraph = Arc<parking_lot::RwLock<Graph>>.

Each agent gets its own AgentSession tracking first/last seen timestamps and query count. The perspective system, trail system, and shared runtime state provide isolation where needed without duplicating the underlying graph.

The important modern detail is that agent-facing state is not limited to ownership and transport. Several flows now expose cognitive runtime state directly, including:

• proof_state
• next-step guidance fields
• trail continuation hints
• batch progress and handoff metadata

parking_lot::RwLock is used instead of std::sync::RwLock to prevent writer starvation – a critical property when plasticity updates (writes) must interleave with activation queries (reads).

Graph Engine (m1nd-core)

m1nd-core is the computational core of the graph runtime. It owns the graph data structure, the activation and analysis engines, the plasticity system, and the type-safe numeric primitives that prevent NaN/Inf corruption system-wide.

Source: m1nd-core/src/

Type System

Numeric Primitives

Every floating-point value in m1nd flows through one of four newtype wrappers defined in types.rs:

FiniteF32 is the foundation. In debug builds, constructing one from a non-finite value panics. In release builds, it clamps to 0.0. Because NaN is excluded by construction, FiniteF32 implements Ord, Eq, and Hash – all unsound on raw f32:

#![allow(unused)]
fn main() {
impl Ord for FiniteF32 {
    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
        self.0.total_cmp(&other.0)
    }
}
}

Index Types

Thin #[repr(transparent)] wrappers over u32 provide type-safe indexing:

Node and Edge Classification

#![allow(unused)]
fn main() {
#[repr(u8)]
pub enum NodeType {
    File = 0, Directory = 1, Function = 2, Class = 3,
    Struct = 4, Enum = 5, Type = 6, Module = 7,
    Reference = 8, Concept = 9, Material = 10, Process = 11,
    Product = 12, Supplier = 13, Regulatory = 14, System = 15,
    Cost = 16, Custom(u8),
}

#[repr(u8)]
pub enum EdgeDirection {
    Forward = 0,
    Bidirectional = 1,
}
}

Variants 0-8 are code-domain types. Variants 9-16 support non-code domains (supply chain, manufacturing). Custom(u8) is the extension point for future domains.

Dimension System

Activation operates across four dimensions with fixed weights:

#![allow(unused)]
fn main() {
pub enum Dimension {
    Structural = 0,  // Graph topology (BFS/heap propagation)
    Semantic = 1,    // Text similarity (trigram TF-IDF + co-occurrence)
    Temporal = 2,    // Time-based (decay + velocity)
    Causal = 3,      // Causal chains (forward/backward with discount)
}

pub const DIMENSION_WEIGHTS: [f32; 4] = [0.35, 0.25, 0.15, 0.25];
}

When fewer than 4 dimensions contribute to a result, weights are adaptively redistributed. Results that fire across multiple dimensions receive a resonance bonus: 1.5x for all 4, 1.3x for 3.

Property Graph Model

String Interner

All strings pass through StringInterner before entering the graph. The interner maps strings to InternedStr(u32) handles via a HashMap<String, InternedStr> and resolves handles back via a Vec<String> indexed by the u32 value.

Once interned, all string comparisons become integer comparisons – zero-allocation, single CPU cycle.

#![allow(unused)]
fn main() {
pub struct StringInterner {
    strings: Vec<String>,
    index: HashMap<String, InternedStr>,
}
}

CSR Graph

The graph uses Compressed Sparse Row (CSR) format with both forward and reverse adjacency. For node i, outgoing edges span offsets[i]..offsets[i+1] into parallel arrays for targets, weights, inhibitory flags, relations, directions, and causal strengths.

#![allow(unused)]
fn main() {
pub struct CsrGraph {
    // Forward CSR
    pub offsets: Vec<u64>,              // num_nodes + 1
    pub targets: Vec<NodeId>,           // total_edges
    pub weights: Vec<AtomicU32>,        // bit-reinterpreted f32 for lock-free CAS
    pub inhibitory: Vec<bool>,          // edge polarity
    pub relations: Vec<InternedStr>,    // edge type (interned)
    pub directions: Vec<EdgeDirection>, // forward or bidirectional
    pub causal_strengths: Vec<FiniteF32>,

    // Reverse CSR (built at finalize)
    pub rev_offsets: Vec<u64>,
    pub rev_sources: Vec<NodeId>,
    pub rev_edge_idx: Vec<EdgeIdx>,     // maps back to forward arrays

    // Pre-finalize staging
    pub pending_edges: Vec<PendingEdge>,
}
}

The CSR is immutable after finalization. Edges are added to pending_edges during graph building, then sorted by source and compacted into the CSR arrays by Graph.finalize(). Bidirectional edges are expanded into two forward entries during finalization.

Atomic Weight Updates

Edge weights are stored as AtomicU32 rather than f32. The plasticity engine updates weights concurrently with read queries using Compare-And-Swap:

#![allow(unused)]
fn main() {
pub fn atomic_max_weight(
    &self, edge: EdgeIdx, new_val: FiniteF32, max_retries: u32,
) -> M1ndResult<()> {
    let slot = &self.weights[edge.as_usize()];
    let new_bits = new_val.get().to_bits();
    for _ in 0..max_retries {
        let old_bits = slot.load(Ordering::Relaxed);
        let old_val = f32::from_bits(old_bits);
        if old_val >= new_val.get() { return Ok(()); }
        if slot.compare_exchange_weak(
            old_bits, new_bits, Ordering::Release, Ordering::Relaxed
        ).is_ok() { return Ok(()); }
    }
    Err(M1ndError::CasRetryExhausted { edge, limit: max_retries })
}
}

Two CAS operations are provided: atomic_max_weight (only increases, for activation scatter-max) and atomic_write_weight (unconditional, for plasticity). Both retry up to 64 times (constant CAS_RETRY_LIMIT).

Node Storage (SoA)

All per-node data lives in NodeStorage, organized as Struct-of-Arrays with explicit cache-path separation:

#![allow(unused)]
fn main() {
pub struct NodeStorage {
    pub count: u32,

    // Hot path: activation engine reads every query
    pub activation: Vec<[FiniteF32; 4]>,  // [structural, semantic, temporal, causal]
    pub pagerank: Vec<FiniteF32>,

    // Warm path: plasticity reads per query
    pub plasticity: Vec<PlasticityNode>,

    // Cold path: seed finding, display, export
    pub label: Vec<InternedStr>,
    pub node_type: Vec<NodeType>,
    pub tags: Vec<SmallVec<[InternedStr; 6]>>,
    pub last_modified: Vec<f64>,
    pub change_frequency: Vec<FiniteF32>,
    pub provenance: Vec<NodeProvenance>,
}
}

The SmallVec<[InternedStr; 6]> for tags avoids heap allocation for nodes with 6 or fewer tags (the common case), while still supporting arbitrary tag counts.

Node Provenance

Each node carries source metadata for tracing back to the original code:

#![allow(unused)]
fn main() {
pub struct NodeProvenance {
    pub source_path: Option<InternedStr>,
    pub line_start: u32,
    pub line_end: u32,
    pub excerpt: Option<InternedStr>,
    pub namespace: Option<InternedStr>,
    pub canonical: bool,
}
}

Generation Counter

Generation(u64) tracks graph mutations. The plasticity engine stores the generation at initialization. Every plasticity operation asserts that the current graph generation matches; a mismatch (from concurrent ingestion) causes a controlled rebuild rather than operating on stale state.

Activation Propagation

Engine Selection (HybridEngine)

The HybridEngine auto-selects between two propagation strategies based on graph characteristics:

flowchart TD
    START["HybridEngine.propagate()"]
    CHECK{"seed_ratio < 0.001<br/>AND avg_degree < 8?"}
    HEAP["HeapEngine<br/>(priority queue)"]
    WAVE["WavefrontEngine<br/>(BFS depth-parallel)"]
    MERGE["Collect sparse results"]

    START --> CHECK
    CHECK -->|yes| HEAP
    CHECK -->|no| WAVE
    HEAP --> MERGE
    WAVE --> MERGE

• HeapEngine: Max-heap priority queue. Processes strongest signal first. Early-terminates when the heap top drops below threshold. Uses a double-hashing BloomFilter for O(1) amortized visited checks. Best for sparse queries with few seeds in low-degree graphs.
• WavefrontEngine: BFS depth-parallel. All active nodes at current depth fire simultaneously. Signal accumulated via scatter-max into next depth’s buffer. Best for dense queries or high-degree graphs.

Structural Propagation (D1)

The wavefront engine is the reference implementation. Signal propagates depth by depth:

1. Seed nodes initialized with their scores (capped at saturation_cap).
2. For each depth (up to max_depth=5, hard cap 20):
   • Each frontier node src with activation above threshold=0.04 fires.
   • For each outgoing edge: signal = src_activation * weight * decay(0.55).
   • Inhibitory edges: signal = -signal * inhibitory_factor(0.5), subtracted from target (floored at 0).
   • Excitatory edges: scatter-max into target (keep strongest arrival).
3. Collect all nodes with non-zero activation, sorted descending.

Semantic Dimension (D2)

Two indexes power semantic matching:

CharNgramIndex: FNV-1a 24-bit trigram hashing over node labels with TF-IDF weighting. An inverted index maps trigram hashes to node lists, enabling O(K) query time (K = number of matching trigrams) instead of O(N) full scan.

CoOccurrenceIndex: DeepWalk-lite random walks (20 walks/node, length 10, window 4) generate co-occurrence counts, normalized to Positive Pointwise Mutual Information (PPMI). Sorted vectors enable O(D) merge-intersection for similarity queries. Disabled above 50K nodes to bound walk cost.

The semantic engine also includes a SynonymExpander with 15 default groups covering code terminology and Portuguese domain terms.

Query pipeline: Phase 1 ngram candidates (3x top_k) -> Phase 2 multi-seed co-occurrence re-rank.

Temporal Dimension (D3)

Three scorers combine:

• TemporalDecayScorer: Per-NodeType half-lives (File=7 days, Function=14 days, Module/Directory=30 days). Formula: exp(-ln(2) * age_hours / half_life). Dormant nodes (>35 days) get a resurrection bonus with an additive floor.
• VelocityScorer: Z-score based change velocity. Nodes changing faster than average receive higher scores.
• CoChangeMatrix: Sparse matrix (budget: 500K entries, 100 per row) bootstrapped from BFS depth 3, refined with git co-change observations.

Causal Dimension (D4)

CausalChainDetector: Budget-limited priority-queue DFS along causal_strength edges. Forward propagation follows contains/imports/calls edges; backward propagation reverses direction. Discount factor 0.7 per hop. Chain depth capped at 6 by default.

Dimension Merging

merge_dimensions() combines all four dimension results:

1. For each activated node, compute weighted sum: score = sum(dim_score * DIMENSION_WEIGHTS[dim]).
2. If a dimension produced no results, redistribute its weight proportionally to active dimensions.
3. Apply resonance bonus: 1.5x if all 4 dimensions contributed, 1.3x if 3 contributed.
4. Sort by final score, truncate to top_k.

Seed Finding

SeedFinder resolves query strings to graph nodes via a 5-level matching cascade:

1. Exact label match (highest priority)
2. Prefix match (e.g., “chat_” matches “chat_handler”)
3. Substring match (e.g., “handler” matches “chat_handler”)
4. Tag match (e.g., “#api” tag)
5. Fuzzy trigram (cosine similarity of trigram vectors, lowest priority)

A semantic re-ranking phase (0.6 basic score / 0.4 semantic blend) refines results when multiple candidates match.

Weight Systems

Hebbian Plasticity

The PlasticityEngine implements biological Hebbian learning with 5 phases executed after every activation query:

flowchart LR
    A["1. Hebbian Strengthen<br/>delta_w = lr * act_src * act_tgt"]
    B["2. Synaptic Decay<br/>w *= (1 - decay_rate) for inactive"]
    C["3. LTP/LTD<br/>permanent bonus/penalty<br/>after N consecutive"]
    D["4. Homeostatic Normalize<br/>scale if total > ceiling"]
    E["5. Record Query<br/>ring buffer + bigrams"]

    A --> B --> C --> D --> E

Constants (from plasticity.rs):

Hebbian update: For each edge where both source and target were activated: delta_w = learning_rate * activation_source * activation_target. Applied via atomic CAS (atomic_write_weight).

Homeostatic normalization: If the sum of incoming weights for any node exceeds HOMEOSTATIC_CEILING, all incoming weights are scaled proportionally to bring the total back under the ceiling. This prevents runaway positive feedback.

Query Memory: A ring buffer of 1000 entries tracks recent queries. Each record stores the query text, seed nodes, activated nodes, and timestamp. The memory tracks:

• Node frequency: how often each node appears across recent queries.
• Seed bigrams: co-occurring seed pairs, used for priming signals.

When the buffer wraps, evicted records have their frequency and bigram counts decremented – maintaining accurate sliding-window statistics.

Persistence: Plasticity state (per-edge SynapticState) is exported as JSON using triple-based identity matching (source_label, target_label, relation). This allows plasticity to survive graph rebuilds as long as the semantic structure remains similar.

XLR Differential Processing

XLR (eXcitatory-Lateral-inhibitory Response) is a spectral noise cancellation system that separates signal from noise in activation results.

Constants:

6-step pipeline:

1. Anti-seed selection: Pick nodes dissimilar to seeds (Jaccard similarity < 0.2, degree ratio filter).
2. Immunity computation: BFS 2 hops from seeds. Immune nodes cannot be suppressed.
3. Hot propagation: Spread SpectralPulse with frequency F_HOT=1.0 from seed nodes. Pulses carry amplitude, phase, frequency, and a bounded recent path ([NodeId; 3], not unbounded Vec – FM-RES-007).
4. Cold propagation: Spread from anti-seeds with frequency F_COLD=3.7.
5. Spectral overlap + density modulation: Compute overlap between hot and cold spectra using Gaussian kernel (bw=0.8). Dense neighborhoods get modulated (clamped to [0.3, 2.0]).
6. Sigmoid gating: Apply 1 / (1 + exp(-steepness * (hot - cold))) to produce final scores.

Over-cancellation fallback (FM-XLR-010): If all results score zero after gating (cold dominates everywhere), fall back to hot-only results. This prevents total signal erasure in adversarial topologies.

Standing Wave Resonance

The resonance engine discovers structural harmonics by propagating wave pulses through the graph:

#![allow(unused)]
fn main() {
pub struct WavePulse {
    pub node: NodeId,
    pub amplitude: FiniteF32,   // can be negative for destructive interference
    pub phase: FiniteF32,       // [0, 2*pi)
    pub frequency: PosF32,      // MUST be positive (FM-RES-002)
    pub wavelength: PosF32,     // MUST be positive (FM-RES-001)
    pub hops: u8,
    pub prev_node: NodeId,
}
}

Wave interference: Pulses accumulate at each node as complex numbers (real + imaginary). Constructive interference occurs when pulses arrive in phase; destructive when out of phase. The WaveAccumulator tracks sum(amplitude * cos(phase)) and sum(amplitude * sin(phase)), with resultant amplitude sqrt(real^2 + imag^2).

Reflection rules:

• Dead-end reflection: At leaf nodes (degree 1), pulse reflects with a pi phase shift (REFLECTION_PHASE_SHIFT).
• Hub partial reflection: At hub nodes (degree > 4x average), 30% of amplitude reflects (HUB_REFLECTION_COEFF).

Budget: DEFAULT_PULSE_BUDGET = 50,000 prevents combinatorial explosion in dense subgraphs. Pulses are processed in BFS order via a VecDeque.

Harmonic analysis: HarmonicAnalyzer sweeps across frequencies, groups nodes by harmonic response, and identifies resonant frequencies (local maxima in the sweep). SympatheticResonanceDetector finds nodes that resonate across regions (outside 2-hop seed neighborhood) – indicating structural coupling without direct edges.

PageRank

Computed once at Graph.finalize() via power iteration:

• Damping factor: 0.85
• Max iterations: 50
• Convergence threshold: 1e-6

PageRank scores are stored in NodeStorage.pagerank and used as a static importance signal in seed finding and result ranking.

Persistence

Graph Snapshot

snapshot.rs serializes the graph to JSON format (version 3):

#![allow(unused)]
fn main() {
struct GraphSnapshot {
    version: u32,           // SNAPSHOT_VERSION = 3
    nodes: Vec<NodeSnapshot>,
    edges: Vec<EdgeSnapshot>,
}
}

Each NodeSnapshot includes external_id, label, node_type, tags, timestamps, and optional provenance. Each EdgeSnapshot includes source/target IDs, relation, weight, direction, inhibitory flag, and causal strength.

Atomic write (FM-PL-008): Write to a temporary file, then rename() over the target. The rename is atomic on POSIX filesystems, so a crash mid-write leaves the previous snapshot intact.

NaN firewall: All values are checked for finiteness at the export boundary. Non-finite values are rejected before writing.

Plasticity State

Per-edge SynapticState (original weight, current weight, strengthen/weaken counts, LTP/LTD flags) is serialized to a separate JSON file. Import uses triple-based matching (source_label, target_label, relation) to reconnect state to edges after graph rebuilds.

Auto-Persist

The MCP server triggers persistence every auto_persist_interval queries (default: 50). Ordering: graph first (source of truth), then plasticity. If graph save fails, plasticity save is skipped to prevent inconsistent state.

Ingestion Pipeline (m1nd-ingest)

m1nd-ingest transforms codebases and structured documents into the property graph consumed by m1nd-core. It handles file discovery, language-specific code extraction, cross-file reference resolution, incremental diff computation, and memory/markdown ingestion.

Source: m1nd-ingest/src/

Module Map

Pipeline Overview

flowchart TD
    subgraph "Phase 1: Walk"
        DIR["Directory Root"]
        WALK["DirectoryWalker<br/>walkdir + skip rules"]
        BIN["Binary Detection<br/>NUL in first 8KB"]
        GIT["Git Enrichment<br/>commit counts + timestamps"]
        FILES["DiscoveredFile[]"]
    end

    subgraph "Phase 2: Extract (parallel)"
        RAYON["rayon::par_iter"]
        PY["PythonExtractor"]
        TS["TypeScriptExtractor"]
        RS["RustExtractor"]
        GO["GoExtractor"]
        JAVA["JavaExtractor"]
        GEN["GenericExtractor"]
        RESULTS["ExtractionResult[]"]
    end

    subgraph "Phase 3: Build Graph"
        NODES["Add all nodes<br/>with provenance + timestamps"]
        EDGES["Add resolved edges<br/>with causal strengths"]
        CAUSAL["Causal strength assignment<br/>contains=0.8, imports=0.6, etc."]
    end

    subgraph "Phase 4: Resolve + Enrich"
        REFS["ReferenceResolver<br/>ref:: → actual nodes"]
        PROX["Proximity Disambiguation<br/>same file > same dir > same project"]
        HINTS["Import Hints<br/>module path → target preference"]
        CARGO["Cargo Workspace<br/>workspace/crate/dependency graph"]
        XFILE["Cross-File Enrichment<br/>currently strongest for Python"]
    end

    subgraph "Phase 5: Finalize"
        CSR["Build CSR<br/>sort edges, compact arrays"]
        BIDIR["Expand Bidirectional<br/>contains, implements"]
        REV["Build Reverse CSR"]
        PR["PageRank<br/>power iteration"]
    end

    DIR --> WALK --> BIN --> GIT --> FILES
    FILES --> RAYON
    RAYON --> PY & TS & RS & GO & JAVA & GEN
    PY & TS & RS & GO & JAVA & GEN --> RESULTS
    RESULTS --> NODES --> EDGES --> CAUSAL
    CAUSAL --> REFS --> PROX
    PROX --> HINTS --> CARGO --> XFILE
    XFILE --> CSR --> BIDIR --> REV --> PR

Phase 1: Directory Walking

DirectoryWalker uses the walkdir crate to traverse the filesystem. It applies skip rules, detects binary files, and enriches results with git metadata.

Skip Rules

Default skip directories (configured via IngestConfig):

#![allow(unused)]
fn main() {
skip_dirs: vec![
    ".git", "node_modules", "__pycache__", ".venv",
    "target", "dist", "build", ".next", "vendor",
],
skip_files: vec![
    "package-lock.json", "yarn.lock", "Cargo.lock", "poetry.lock",
],
}

Hidden directories (starting with .) are skipped unless they are the root. Symlinks are not followed.

Binary Detection (FM-ING-004)

After discovering a file, the walker reads the first 8KB and checks for NUL bytes (0x00). Any file containing NUL is classified as binary and skipped. This prevents feeding compiled binaries, images, or other non-text files into the language extractors.

Git Enrichment

If the root is inside a git repository, the walker runs git log --format=%at --name-only to extract:

• Commit count per file: Used to compute change_frequency (1 commit = 0.1, 50+ = 1.0, capped).
• Most recent commit timestamp: Used for temporal decay scoring.
• Commit groups: Sets of files that changed together in the same commit. Fed into the CoChangeMatrix after graph finalization.

The result is a WalkResult containing Vec<DiscoveredFile> and Vec<Vec<String>> commit groups.

#![allow(unused)]
fn main() {
pub struct DiscoveredFile {
    pub path: PathBuf,
    pub relative_path: String,
    pub extension: Option<String>,
    pub size_bytes: u64,
    pub last_modified: f64,
    pub commit_count: u32,
    pub last_commit_time: f64,
}
}

Phase 2: Parallel Extraction

Files are distributed across rayon’s thread pool for concurrent extraction. Each file is assigned a language-specific extractor based on its extension:

This stack is hybrid:

• native/manual extractors for Python, TypeScript/JavaScript, Rust, Go, and Java
• tree-sitter-backed tiers for additional languages
• generic fallback for unsupported files

Extractor Interface

All extractors implement the Extractor trait:

#![allow(unused)]
fn main() {
pub trait Extractor: Send + Sync {
    fn extract(&self, content: &[u8], file_id: &str) -> M1ndResult<ExtractionResult>;
    fn extensions(&self) -> &[&str];
}
}

An ExtractionResult contains:

#![allow(unused)]
fn main() {
pub struct ExtractionResult {
    pub nodes: Vec<ExtractedNode>,
    pub edges: Vec<ExtractedEdge>,
    pub unresolved_refs: Vec<String>,
}
}

Each extracted node carries:

#![allow(unused)]
fn main() {
pub struct ExtractedNode {
    pub id: String,        // e.g. "file::backend/chat_handler.py::ChatHandler"
    pub label: String,     // e.g. "ChatHandler"
    pub node_type: NodeType,
    pub tags: Vec<String>,
    pub line: u32,
    pub end_line: u32,
}
}

Comment and String Stripping

Before extraction, each file’s content passes through strip_comments_and_strings() which removes comments and string literals to prevent false-positive matches from regex extractors. The function preserves import line string content (so from "react" still resolves) but strips string bodies elsewhere.

Comment syntax is per-language:

#![allow(unused)]
fn main() {
pub struct CommentSyntax {
    pub line: &'static str,         // e.g. "//" or "#"
    pub block_open: &'static str,   // e.g. "/*"
    pub block_close: &'static str,  // e.g. "*/"
}
}

Supported: Rust (//, /* */), Python (#, """ """), C-style (//, /* */), Go (//, /* */), Generic (#, none).

Node ID Format

Extracted nodes use a hierarchical ID scheme: file::{relative_path}::{entity_name}. For example:

• file::backend/chat_handler.py (file node)
• file::backend/chat_handler.py::ChatHandler (class node)
• file::backend/chat_handler.py::ChatHandler::handle_message (method node)

Unresolved references use the prefix ref::: ref::Config, ref::react. These are resolved to actual nodes in Phase 4.

Phase 3: Graph Building

After parallel extraction completes, results are collected and processed sequentially (graph mutation is single-threaded).

Node Creation

For each ExtractedNode:

1. Look up the file timestamp from git enrichment (or filesystem mtime).
2. Compute change_frequency from git commit count: (commits / 50).clamp(0.1, 1.0). Default 0.3 for non-git repos.
3. Call graph.add_node() with the external ID, label, node type, tags, timestamp, and change frequency.
4. Set provenance: source_path, line_start, line_end, namespace="code".
5. On DuplicateNode error, increment collision counter and continue.

Edge Creation

For each ExtractedEdge (skipping ref:: targets, which are deferred):

1. Resolve source and target IDs to NodeId.
2. Assign causal strength by relation type:

contains and implements edges are bidirectional so that both parent-to-child and child-to-parent navigation work.

Safety Guards (FM-ING-002)

Two budget checks run between sequential file processing:

• Timeout: If start.elapsed() > config.timeout (default 300s), stop processing.
• Node budget: If nodes >= config.max_nodes (default 500K), stop processing.

Both log a warning and break from the build loop, producing a partial but consistent graph from whatever was processed.

Phase 4: Reference Resolution And Enrichment

ReferenceResolver

Unresolved references (ref::Config, ref::FastAPI, etc.) are resolved to actual graph nodes using the ReferenceResolver.

Multi-value label index (FM-ING-008): The resolver builds a HashMap from labels to lists of matching NodeIds. When multiple nodes share a label (e.g., multiple files define a Config class), proximity disambiguation selects the best match:

Import hint disambiguation: When the extractor sees from foo.bar import Baz, it records an import hint mapping (source_file, "ref::Baz") to the module path foo.bar. The resolver uses this hint to prefer the Baz node under foo/bar/ over a same-named node elsewhere.

Resolution outcome per reference:

• Resolved: Exactly one match (or best proximity match). Edge created with resolved NodeId.
• Ambiguous: Multiple matches with equal proximity. Best guess selected, counted in stats.
• Unresolved: No match found. Counted in stats, no edge created.

Cargo Workspace Enrichment

For Rust repos, cargo_workspace.rs adds a workspace-aware layer before finalization:

• workspace nodes
• crate nodes
• crate -> file contains edges
• crate -> crate depends_on edges for internal workspace dependencies
• external dependency nodes for non-workspace dependencies

This means Rust repos are no longer represented only as file graphs.

Cross-File Enrichment

After reference resolution and Cargo enrichment, cross_file.rs adds a narrower set of shipped cross-file edges.

Today this pass is strongest for Python and focuses on:

• imports
• tests
• registers

It should not be described as a language-uniform cross-file engine yet.

Phase 5: Finalization

Graph.finalize() transforms the mutable graph into its read-optimized CSR form:

1. Sort edges by source: All pending edges are sorted by source.0 (node index).
2. Build forward CSR: Compute offsets array, pack targets/weights/relations/etc into parallel arrays.
3. Expand bidirectional edges: For each bidirectional edge (A, B), ensure both A->B and B->A exist in the CSR.
4. Build reverse CSR: Sort edges by target, build rev_offsets, rev_sources, rev_edge_idx (mapping back to forward array indices).
5. Rebuild plasticity arrays: Allocate PlasticityNode for each node with default ceiling.
6. Compute PageRank: Power iteration with damping 0.85, max 50 iterations, convergence 1e-6.

After finalization, the graph is immutable (except for atomic weight updates by plasticity).

Incremental Ingestion (GraphDiff)

diff.rs enables incremental updates without full re-ingestion.

#![allow(unused)]
fn main() {
pub enum DiffAction {
    AddNode(ExtractedNode),
    RemoveNode(String),
    ModifyNode { external_id, new_label, new_tags, new_last_modified },
    AddEdge(ExtractedEdge),
    RemoveEdge { source_id, target_id, relation },
    ModifyEdgeWeight { source_id, target_id, relation, new_weight },
}
}

GraphDiff::compute() compares old and new extraction results by indexing both into HashMaps by external ID, then classifying each node/edge as added, removed, or modified.

GraphDiff::apply() executes the diff against a live graph. Note: CSR does not support true node/edge removal. “Removed” nodes are tombstoned (zero weight, empty label) rather than physically deleted. A full re-ingest is needed to reclaim space.

When to use incremental vs full:

Memory Adapter

MemoryIngestAdapter converts markdown documents into graph nodes. It implements the IngestAdapter trait with domain "memory".

Supported Formats

Files with extensions .md, .markdown, or .txt are accepted. The adapter walks a directory of memory files and parses each one into:

• Section nodes (NodeType::Concept): Created from markdown headings (#, ##, etc.).
• Entry nodes (NodeType::Process): Created from list items under sections.
• File reference nodes (NodeType::Reference): Created from file paths mentioned in content.

Entry Classification

List items are classified by content patterns:

Edges

The adapter creates:

• contains edges from section to child entries.
• references edges from entries to file reference nodes.
• follows edges between sequential entries in the same section.

This allows the activation engine to traverse from a concept (“plasticity”) through memory entries to referenced code files, bridging the semantic gap between human notes and source code.

IngestAdapter Trait

The IngestAdapter trait enables domain-specific ingestion beyond code:

#![allow(unused)]
fn main() {
pub trait IngestAdapter: Send + Sync {
    fn domain(&self) -> &str;
    fn ingest(&self, root: &Path) -> M1ndResult<(Graph, IngestStats)>;
}
}

Implemented adapters:

The JSON adapter is the escape hatch for importing graphs from external tools. It expects a JSON document with nodes (array of {id, label, type, tags}) and edges (array of {source, target, relation, weight}).

Universal Document Lane

The universal lane is the best-effort document path for sources that are not authored in L1GHT and are not already handled by a stronger native structured adapter.

Its flow is:

1. detect document family
2. normalize into a CanonicalDocument
3. graphify sections, blocks, tables, citations, entities, and claims

Optional providers can enrich the lane when available:

• Trafilatura for HTML/wiki/article extraction
• Docling for office and broad document canonicalization
• MarkItDown as a lightweight fallback lane
• GROBID for scholarly PDFs

This provider stack is intentionally optional. The default green path does not require these providers; richer extraction appears only when the environment supports it.

Document Router (Auto-Detection)

DocumentRouter inspects file content and extension to auto-detect the correct adapter:

#![allow(unused)]
fn main() {
let (format, adapter) = DocumentRouter::detect(path);
let (format, adapter) = DocumentRouter::detect_directory(root); // samples ≤20 files
}

Used via MCP: ingest(adapter="auto"), adapter="document", or adapter="universal" when you want best-effort document normalization directly.

For directory detection, the router samples up to 20 files and returns the dominant format.

Cross-Domain Resolution

CrossDomainResolver merges multiple adapter outputs and discovers cross-domain connections automatically.

Bridge Strategies

Safety Guards

• Keyword cap: Keywords shared by >20 nodes are ignored to prevent hub explosion.
• Cross-domain only: All bridges require nodes from ≥2 different namespaces. Same-domain matches are skipped.
• Self-loop prevention: Citation chains A→B→A do not generate self-loop edges.
• Deduplication: Nodes with identical external IDs are deduplicated (first wins).

Resolution Statistics

#![allow(unused)]
fn main() {
pub struct ResolutionStats {
    pub graphs_merged: usize,
    pub total_nodes: u32,
    pub total_edges: usize,
    pub cross_edges_created: usize,
    pub identity_matches: usize,
    pub author_bridges: usize,
    pub keyword_bridges: usize,
    pub orcid_bridges: usize,
    pub citation_chains: usize,
}
}

Configuration Reference

#![allow(unused)]
fn main() {
pub struct IngestConfig {
    pub root: PathBuf,
    pub timeout: Duration,          // default: 300s
    pub max_nodes: u64,             // default: 500_000
    pub skip_dirs: Vec<String>,     // default: [".git", "node_modules", ...]
    pub skip_files: Vec<String>,    // default: ["package-lock.json", ...]
    pub parallelism: usize,         // default: 8 (rayon threads)
}
}

Statistics

Every ingest run produces IngestStats:

#![allow(unused)]
fn main() {
pub struct IngestStats {
    pub files_scanned: u64,
    pub files_parsed: u64,
    pub files_skipped_binary: u64,
    pub files_skipped_encoding: u64,
    pub nodes_created: u64,
    pub edges_created: u64,
    pub references_resolved: u64,
    pub references_unresolved: u64,
    pub label_collisions: u64,
    pub elapsed_ms: f64,
    pub commit_groups: Vec<Vec<String>>,
}
}

commit_groups is passed to the CoChangeMatrix in m1nd-core after graph finalization, seeding the temporal co-change model with real git history.

MCP Server (m1nd-mcp)

m1nd-mcp is the transport and session layer. It exposes m1nd-core and m1nd-ingest through the live MCP tool surface over JSON-RPC stdio, manages the shared graph lifecycle, handles multi-agent sessions, and turns graph results into a more agent-operational runtime with proof-state, next-step guidance, recovery-oriented errors, observable batch execution, and a local-first document runtime. Use tools/list for the exact count in your current build.

Source: m1nd-mcp/src/

Module Map

Transport Layer

Dual Transport Mode

m1nd-mcp accepts two JSON-RPC transport formats on stdin, auto-detected per message:

Framed mode (HTTP-style headers):

Content-Length: 142\r\n
\r\n
{"jsonrpc":"2.0","method":"tools/call","params":{"name":"activate","arguments":{"query":"chat","agent_id":"jimi"}},"id":1}

Line mode (raw JSON):

{"jsonrpc":"2.0","method":"tools/call","params":{"name":"activate","arguments":{"query":"chat","agent_id":"jimi"}},"id":1}

Detection is based on the first non-whitespace byte: if it is { or [, the message is treated as line-mode JSON. Otherwise, it is parsed as framed with Content-Length headers. Responses are written in the same mode as the incoming request.

#![allow(unused)]
fn main() {
fn read_request_payload<R: BufRead>(
    reader: &mut R,
) -> std::io::Result<Option<(String, TransportMode)>> {
    loop {
        let buffer = reader.fill_buf()?;
        if buffer.is_empty() { return Ok(None); }
        let first_non_ws = buffer.iter().copied()
            .find(|byte| !byte.is_ascii_whitespace());
        let starts_framed = matches!(first_non_ws, Some(byte) if byte != b'{' && byte != b'[');
        // ...
    }
}
}

This dual-mode support allows m1nd to work with both Claude Code (which uses framed headers) and other MCP clients that send raw line JSON.

Request/Response Format

Requests follow the JSON-RPC 2.0 specification with MCP conventions:

{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
        "name": "activate",
        "arguments": {
            "query": "chat handler",
            "agent_id": "jimi",
            "top_k": 20,
            "dimensions": ["structural", "semantic", "temporal", "causal"],
            "xlr": true
        }
    },
    "id": 1
}

Responses:

{
    "jsonrpc": "2.0",
    "result": {
        "content": [{
            "type": "text",
            "text": "..."
        }]
    },
    "id": 1
}

The tools/list method returns the live tool schemas with full inputSchema per MCP spec, enabling auto-discovery by any MCP client. Use it as the source of truth for exact names and count in your current build.

Server Lifecycle

sequenceDiagram
    participant Main as main.rs
    participant Server as McpServer
    participant Session as SessionState
    participant Tokio as tokio runtime

    Main->>Main: load_config()
    Main->>Server: McpServer::new(config)
    Server->>Session: SessionState::initialize(graph, config, domain)
    Session->>Session: Build all engines (orchestrator, temporal, counterfactual, topology, resonance, plasticity)
    Main->>Server: server.start()
    Main->>Tokio: spawn_blocking(server.serve())

    loop Until EOF or SIGINT
        Tokio->>Server: read JSON-RPC request
        Server->>Server: dispatch to tool handler
        Server->>Session: execute tool logic
        Session->>Session: auto-persist check
        Server->>Tokio: write JSON-RPC response
    end

    Tokio->>Server: server.shutdown()
    Server->>Session: final persist

Configuration

Configuration is resolved in priority order: CLI argument (JSON file path) > environment variables > defaults.

#![allow(unused)]
fn main() {
pub struct McpConfig {
    pub graph_source: PathBuf,          // default: "./graph_snapshot.json"
    pub plasticity_state: PathBuf,      // default: "./plasticity_state.json"
    pub auto_persist_interval: u32,     // default: 50 (queries between persists)
    pub learning_rate: f32,             // default: 0.08
    pub decay_rate: f32,                // default: 0.005
    pub xlr_enabled: bool,             // default: true
    pub max_concurrent_reads: usize,    // default: 32
    pub write_queue_size: usize,        // default: 64
    pub domain: Option<String>,         // default: None ("code")
}
}

Environment variables: M1ND_GRAPH_SOURCE, M1ND_PLASTICITY_STATE, M1ND_XLR_ENABLED.

Startup Sequence

1. load_config(): Resolve config from CLI args, env vars, or defaults.
2. McpServer::new(config): Load graph snapshot from disk (or create empty graph). Load plasticity state. Initialize SessionState with all engines.
3. server.start(): Prepare the server for serving (no-op currently, reserved for future setup).
4. tokio::task::spawn_blocking(server.serve()): The serve loop does synchronous stdio I/O in a blocking task.
5. tokio::select! waits for either SIGINT (ctrl_c()) or serve loop completion.

Shutdown

On SIGINT or stdin EOF:

1. server.shutdown(): Final persist of graph and plasticity state.
2. Process exits.

The atomic write pattern (temp file + rename) ensures that even if shutdown is interrupted, the previous snapshot remains intact.

Tool Registration and Dispatch

Schema Registry

tool_schemas() returns a JSON array of the live tool definitions with full inputSchema objects. Each tool specifies:

• name: Canonical live registry name (e.g., activate)
• description: Human-readable purpose
• inputSchema: JSON Schema with properties, required, type, defaults

Some clients may display transport-prefixed compatibility aliases, but the live registry returned by tools/list uses the bare tool names.

The current surface now includes a document runtime in addition to the code graph runtime:

• document_resolve
• document_provider_health
• document_bindings
• document_drift
• auto_ingest_start
• auto_ingest_stop
• auto_ingest_status
• auto_ingest_tick

Example schema entry:

{
    "name": "activate",
    "description": "Spreading activation query across the graph",
    "inputSchema": {
        "type": "object",
        "properties": {
            "query": { "type": "string" },
            "agent_id": { "type": "string" },
            "top_k": { "type": "integer", "default": 20 },
            "dimensions": {
                "type": "array",
                "items": { "type": "string", "enum": ["structural", "semantic", "temporal", "causal"] },
                "default": ["structural", "semantic", "temporal", "causal"]
            },
            "xlr": { "type": "boolean", "default": true }
        },
        "required": ["query", "agent_id"]
    }
}

Tool Categories

The live tool surface is organized into functional groups. Use tools/list for the exhaustive registry in your current build.

Core Query Tools:

Graph Mutation Tools:

Perspective Tools:

Lock Tools:

Trail Tools:

Topology Tools:

Dispatch

All tools require an agent_id parameter. The serve loop matches the tool name from the JSON-RPC request and dispatches to the corresponding handler in tools.rs. The handler extracts parameters from the arguments JSON object, acquires the appropriate lock on SessionState, executes the operation, and returns the result as a JSON-RPC response.

Session Management

SessionState

SessionState is the central state object. It owns the graph, all engines, and all session metadata:

#![allow(unused)]
fn main() {
pub struct SessionState {
    pub graph: SharedGraph,                    // Arc<RwLock<Graph>>
    pub domain: DomainConfig,
    pub orchestrator: QueryOrchestrator,       // activation + XLR + semantic
    pub temporal: TemporalEngine,
    pub counterfactual: CounterfactualEngine,
    pub topology: TopologyAnalyzer,
    pub resonance: ResonanceEngine,
    pub plasticity: PlasticityEngine,

    pub queries_processed: u64,
    pub auto_persist_interval: u32,            // default: 50
    pub start_time: Instant,
    pub last_persist_time: Option<Instant>,
    pub graph_path: PathBuf,
    pub plasticity_path: PathBuf,
    pub sessions: HashMap<String, AgentSession>,

    // Perspective/lock state
    pub graph_generation: u64,
    pub plasticity_generation: u64,
    pub cache_generation: u64,
    pub perspectives: HashMap<(String, String), PerspectiveState>,
    pub locks: HashMap<String, LockState>,
    pub perspective_counter: HashMap<String, u64>,
    pub lock_counter: HashMap<String, u64>,
    pub pending_watcher_events: Vec<WatcherEvent>,
    pub perspective_limits: PerspectiveLimits,
    pub peek_security: PeekSecurityConfig,
    pub ingest_roots: Vec<String>,
}
}

SharedGraph

SharedGraph = Arc<parking_lot::RwLock<Graph>> provides concurrent access:

• Reads (activation, impact, predict, etc.): Acquire read lock. Multiple concurrent reads allowed.
• Writes (ingest, learn): Acquire write lock. Exclusive access. Blocks all readers.

parking_lot::RwLock is used instead of std::sync::RwLock for two reasons:

1. Writer starvation prevention: parking_lot uses a fair queue, so plasticity writes do not starve behind continuous read queries.
2. Performance: parking_lot’s implementation is faster for the read-heavy, write-rare access pattern of m1nd.

Engine Rebuild

After ingestion replaces the graph, all engines must be rebuilt because they hold indexes derived from the old graph:

#![allow(unused)]
fn main() {
pub fn rebuild_engines(&mut self) -> M1ndResult<()> {
    {
        let graph = self.graph.read();
        self.orchestrator = QueryOrchestrator::build(&graph)?;
        self.temporal = TemporalEngine::build(&graph)?;
        self.plasticity = PlasticityEngine::new(
            &graph, PlasticityConfig::default(),
        );
    }
    self.invalidate_all_perspectives();
    self.mark_all_lock_baselines_stale();
    self.graph_generation += 1;
    self.cache_generation = self.cache_generation.max(self.graph_generation);
    Ok(())
}
}

The rebuild also invalidates all perspective and lock state, bumping generation counters so that stale caches are detected.

Auto-Persist

Every auto_persist_interval queries (default 50), the session persists state to disk:

1. Graph first: save_graph() writes the CSR graph to JSON via atomic temp-file-then-rename.
2. Plasticity second: export_state() extracts per-edge SynapticState, then save_plasticity_state() writes to JSON.
3. If graph save fails, plasticity save is skipped (prevents inconsistent state).
4. If plasticity save fails after graph succeeds, a warning is logged but the server continues.

#![allow(unused)]
fn main() {
pub fn persist(&mut self) -> M1ndResult<()> {
    let graph = self.graph.read();
    m1nd_core::snapshot::save_graph(&graph, &self.graph_path)?;
    match self.plasticity.export_state(&graph) {
        Ok(states) => {
            if let Err(e) = save_plasticity_state(&states, &self.plasticity_path) {
                eprintln!("[m1nd] WARNING: plasticity persist failed: {}", e);
            }
        }
        Err(e) => eprintln!("[m1nd] WARNING: plasticity export failed: {}", e),
    }
    self.last_persist_time = Some(Instant::now());
    Ok(())
}
}

Multi-Agent Support

Agent Sessions

Each unique agent_id gets an AgentSession:

#![allow(unused)]
fn main() {
pub struct AgentSession {
    pub agent_id: String,
    pub first_seen: Instant,
    pub last_seen: Instant,
    pub query_count: u64,
}
}

Sessions are created on first query and updated on each subsequent query. The last_seen timestamp enables timeout-based cleanup.

Agent Isolation

All agents share one graph (writes are immediately visible), but isolation is provided through:

• Perspectives: Per-agent branching views with independent route caches. A perspective opened by Agent A is invisible to Agent B.
• Locks: Per-agent change tracking baselines. Each agent can create independent locks to track changes from their perspective.
• Query Memory: The plasticity engine’s ring buffer is global (shared learning), but perspective-level route caches are per-agent.

Generation Counters

Three generation counters detect stale state:

When a perspective’s cached results were computed at a different generation than the current cache_generation, the perspective is marked stale and results are recomputed on next access.

Perspective System

Perspectives are per-agent named branches that cache activation results and enable comparative analysis.

Lifecycle

stateDiagram-v2
    [*] --> Open: perspective_start
    Open --> Active: first query (activate/impact/etc)
    Active --> Active: additional queries
    Active --> Branched: perspective_branch
    Active --> Stale: graph mutation (ingest/learn)
    Stale --> Active: re-query (auto-refresh)
    Active --> [*]: perspective_close
    Open --> [*]: perspective_close

Perspective IDs

Generated as persp_{agent_prefix}_{counter:03}. Each agent has an independent monotonic counter. Example: Agent “jimi” creates perspectives persp_jimi_001, persp_jimi_002, etc.

Resource Limits

PerspectiveLimits caps resource usage:

• Maximum open perspectives per agent
• Maximum total perspectives across all agents
• Maximum locks per agent

Peek Security

perspective_peek allows reading source file content from within a perspective context. Security restrictions:

• Files must be within an ingest_roots allow-list (populated during ingest).
• Path traversal (..) is blocked.
• Symlinks outside the allow-list are rejected.

Lock System

Locks capture a baseline snapshot of graph state for change tracking.

Lock Lifecycle

stateDiagram-v2
    [*] --> Created: lock_create
    Created --> Active: baseline captured
    Active --> Diffed: lock_diff (non-destructive)
    Diffed --> Active: continue tracking
    Active --> Rebased: lock_rebase (new baseline)
    Rebased --> Active: continue tracking
    Active --> Stale: graph mutation
    Stale --> Rebased: lock_rebase
    Active --> [*]: lock_release

Operations

• lock_create: Captures current graph state (generation counter + weight snapshot for tracked edges).
• lock_diff: Compares current state against baseline. Reports weight changes, new/removed edges. Non-destructive.
• lock_rebase: Updates baseline to current state. Clears staleness flag.
• lock_release: Frees the lock.
• lock_watch: Returns pending watcher events (changes that occurred since last check).

When a graph mutation occurs (ingest, learn), all locks are marked baseline_stale = true. lock_diff reports this staleness and suggests lock_rebase.

Engine Operations (Perspective Synthesis)

engine_ops.rs provides read-only wrappers around engine operations for use within perspective synthesis. These wrappers operate under a SynthesisBudget:

• Max calls: 8 engine calls per synthesis operation.
• Wall-clock timeout: 500ms total.

This prevents perspective synthesis from monopolizing the server. Each wrapper (activate_readonly, impact_readonly, etc.) checks budget before executing and returns a budget-exhausted error if limits are exceeded.

Concurrency Model

flowchart TD
    STDIN["stdin (JSON-RPC)"]
    TOKIO["tokio::task::spawn_blocking"]
    SERVE["McpServer.serve()<br/>(synchronous loop)"]
    RW["SharedGraph<br/>Arc&lt;parking_lot::RwLock&lt;Graph&gt;&gt;"]
    READ["Read Lock<br/>(activate, impact, predict, ...)"]
    WRITE["Write Lock<br/>(ingest, graph swap)"]
    PERSIST["Auto-Persist<br/>(write lock on graph)"]

    STDIN --> TOKIO
    TOKIO --> SERVE
    SERVE --> READ
    SERVE --> WRITE
    SERVE --> PERSIST
    READ --> RW
    WRITE --> RW
    PERSIST --> RW

The serve loop is single-threaded (synchronous stdio I/O), but graph access is concurrent-safe through SharedGraph. Within a single request:

• Read operations acquire a read lock (shared, non-blocking with other reads).
• Write operations acquire a write lock (exclusive, blocks all other access).
• Plasticity weight updates use atomic CAS (no lock needed for individual weight writes).

The tokio runtime is used solely for the select! between SIGINT and serve loop completion. All actual tool processing happens synchronously within spawn_blocking.

Spreading Activation

Spreading activation is the core query mechanism in m1nd. Instead of searching for text matches, m1nd fires a signal into a weighted graph and observes where the energy propagates. The resulting activation pattern tells you what is structurally, semantically, temporally, and causally related to your query.

The neuroscience origin

The concept comes from cognitive psychology. In 1975, Allan Collins and Elizabeth Loftus proposed that human semantic memory is organized as a network of interconnected concepts. When you think of “doctor,” activation spreads along weighted connections to “nurse,” “hospital,” “stethoscope” – but not to “bicycle.” The strength of the connection determines how much activation passes through. Distant or weak connections receive less energy. The pattern of activated nodes is the meaning.

m1nd applies this model to code. Files, functions, classes, and modules become nodes. Import relationships, call chains, type references, and co-change history become weighted edges. Querying “authentication” does not find the string “authentication” – it fires signal into nodes that match and watches energy flow outward through the graph’s structure.

Four dimensions of activation

Most spreading activation systems operate on a single graph. m1nd runs four independent activation passes and fuses the results. Each dimension captures a different kind of relationship.

D1: Structural

Graph distance, edge types, and edge weights. This is classical spreading activation – signal decays as it hops along edges. A file that imports another file is one hop away. A function that calls through two intermediate modules is three hops away. The signal strength at each node tells you how structurally close it is to the query.

The structural dimension uses m1nd’s CSR (Compressed Sparse Row) adjacency matrix with forward and reverse indices. PageRank scores computed at ingest time provide a static importance baseline.

D2: Semantic

Token overlap and naming patterns. This dimension scores nodes based on how their identifiers (file names, function names, class names) relate to the query text. m1nd uses a TF-IDF weighted trigram index built at ingest time. The trigrams for “authentication” overlap with “auth_handler,” “authenticate_user,” and “auth_middleware” – without requiring exact string matching.

Co-occurrence embeddings from short random walks on the graph add a second signal: nodes that tend to appear near each other in the graph structure score higher, even if their names share no characters.

D3: Temporal

Recency and change frequency. Files modified recently score higher than files untouched for months. Files that change often (high velocity) score higher than stable ones. The temporal dimension uses exponential decay with a 7-day half-life:

recency = exp(-0.693 * age_seconds / (168 * 3600))
score   = recency * 0.6 + frequency * 0.4

This ensures that recently active parts of the codebase surface in activation results, even if they are structurally distant.

D4: Causal

Forward and backward causal chain traversal. Edges with causal_strength > 0 (derived from call chains, error propagation paths, and stacktrace mappings) form a causal subgraph. Signal propagates forward along causal edges with full strength, and backward with a 0.7 discount factor. This surfaces nodes that cause or are caused by the query target.

The activation wavefront algorithm

m1nd implements two propagation strategies and a hybrid selector that chooses between them at runtime.

WavefrontEngine (BFS)

Breadth-first, depth-parallel propagation. All active nodes at the current depth fire simultaneously. Signal accumulates into the next depth’s buffer via a scatter-max operation: when multiple sources send signal to the same target, only the strongest arrival survives.

for each depth 0..max_depth:
    for each node in current frontier:
        if activation[node] < threshold: skip
        for each outgoing edge (node -> target):
            signal = activation[node] * edge_weight * decay
            if inhibitory: signal = -signal * inhibitory_factor
            if signal > activation[target]:
                activation[target] = signal    // scatter-max
                add target to next frontier
    frontier = next_frontier

This processes all nodes at the same distance in one pass. Optimal when many seeds fire simultaneously or the graph has high average degree.

HeapEngine (priority queue)

Max-heap propagation. The strongest signal fires first. Early-terminates when the heap top drops below threshold. Uses a Bloom filter for fast visited checks (probabilistic, with FPR ~ 1% at typical graph sizes).

Optimal for sparse queries: few seeds, low graph density. The seed-to-node ratio and average degree determine the crossover point.

HybridEngine (auto-select)

The HybridEngine chooses at runtime:

#![allow(unused)]
fn main() {
fn prefer_heap(graph: &Graph, seed_count: usize) -> bool {
    let seed_ratio = seed_count as f64 / graph.num_nodes().max(1) as f64;
    seed_ratio < 0.001 && graph.avg_degree() < 8.0
}
}

If fewer than 0.1% of nodes are seeds and the average degree is below 8, the HeapEngine wins. Otherwise, the WavefrontEngine is faster because it avoids heap overhead for dense propagation.

Seed node selection

Before activation can begin, the query text must be converted into seed nodes. The SeedFinder performs a multi-strategy match against all node labels:

Trigram similarity uses cosine distance between character n-gram frequency vectors. A match threshold of 0.3 catches most typos without generating noise.

For enhanced matching, find_seeds_semantic runs a two-phase process: basic seed finding produces candidates, then the semantic engine re-ranks them with a 0.6/0.4 blend of basic and semantic scores. Maximum 200 seeds are returned (capped by MAX_SEEDS).

Decay and damping

Signal attenuates at every hop:

signal_at_target = signal_at_source * edge_weight * decay_factor

The default decay factor is 0.55 per hop (from DecayFactor::DEFAULT). After 3 hops, the signal has decayed to 0.55^3 = 16.6% of its original strength. After 5 hops (the default max_depth), it is at 5%. The max depth is hard-capped at 20 to prevent runaway propagation.

Additional controls:

• Threshold (default 0.04): signal below this value is discarded. This prunes the wavefront and prevents ghost activations.
• Saturation cap (default 1.0): seeds cannot inject more than this amount of activation. Prevents a single high-PageRank node from dominating.
• Inhibitory factor (default 0.5): inhibitory edges (negative relationships like “replaces,” “deprecates”) apply capped proportional suppression rather than simple negation.

How dimensions are combined

After all four dimensions produce their scored node lists, the merge_dimensions function fuses them into a single ranking.

Weighted sum

Each dimension has a base weight:

#![allow(unused)]
fn main() {
pub const DIMENSION_WEIGHTS: [f32; 4] = [0.35, 0.25, 0.15, 0.25];
//                                        D1     D2     D3     D4
//                                    Struct  Seman  Temp  Causal
}

If a dimension produces no results (e.g., no temporal data available), its weight is redistributed proportionally to the active dimensions. This adaptive redistribution prevents zero-result dimensions from diluting the signal.

Resonance bonus

Nodes that appear in multiple dimensions receive a multiplicative bonus:

#![allow(unused)]
fn main() {
pub const RESONANCE_BONUS_3DIM: f32 = 1.3;  // 3 dimensions agree
pub const RESONANCE_BONUS_4DIM: f32 = 1.5;  // all 4 dimensions agree
}

A node that scores above 0.01 in all four dimensions receives a 1.5x boost. This is a powerful signal: structural proximity, naming similarity, recent change activity, and causal relationship all point to the same node. These are the nodes the agent should examine first.

The check order matters. m1nd checks dim_count >= 4 before dim_count >= 3. The original Python implementation had a dead elif branch that never triggered the 4-dimension bonus – this was fixed during the Rust port (FM-ACT-001).

PageRank boost

After dimension fusion, each node receives a small PageRank boost:

#![allow(unused)]
fn main() {
const PAGERANK_BOOST: f32 = 0.1;
node.activation += node.pagerank * PAGERANK_BOOST;
}

This ensures that structurally important nodes (high PageRank) surface slightly higher in results, all else being equal. The factor is intentionally small (10% of PageRank) to avoid overwhelming the activation signal.

Visual example

Consider a simplified graph of a backend application:

graph LR
    main["main.py<br/>PR: 0.15"]
    auth["auth.py<br/>PR: 0.12"]
    session["session.py<br/>PR: 0.08"]
    middleware["middleware.py<br/>PR: 0.10"]
    user["user_model.py<br/>PR: 0.06"]
    db["database.py<br/>PR: 0.09"]
    routes["routes.py<br/>PR: 0.11"]

    main -->|imports| auth
    main -->|imports| routes
    routes -->|imports| auth
    routes -->|imports| middleware
    auth -->|imports| session
    auth -->|imports| user
    auth -->|imports| db
    session -->|imports| db
    middleware -->|imports| session
    user -->|imports| db

    style auth fill:#ff6b6b,stroke:#333,color:#fff
    style session fill:#ffa07a,stroke:#333
    style middleware fill:#ffa07a,stroke:#333
    style user fill:#ffd700,stroke:#333
    style db fill:#ffd700,stroke:#333
    style routes fill:#ffa07a,stroke:#333
    style main fill:#ffd700,stroke:#333

Query: "authentication"

Step 1: Seed selection. auth.py matches with relevance 0.9 (prefix match). session.py matches with relevance 0.85 (tag “auth” in its tags). These become seeds with activation 0.9 and 0.85 respectively.

Step 2: Structural propagation (D1). From auth.py (0.9), signal flows to:

• session.py: 0.9 * 1.0 * 0.55 = 0.495
• user_model.py: 0.9 * 1.0 * 0.55 = 0.495
• database.py: 0.9 * 1.0 * 0.55 = 0.495

From session.py (already at 0.85 from seed, plus 0.495 from structural – scatter-max keeps the higher):

• database.py: 0.85 * 1.0 * 0.55 = 0.467 (less than existing 0.495, discarded)

Reverse propagation (via reverse CSR):

• routes.py imports auth.py, so routes.py receives: 0.9 * 1.0 * 0.55 = 0.495
• main.py imports auth.py, so main.py receives: 0.9 * 1.0 * 0.55 = 0.495
• middleware.py imports session.py, so middleware.py receives: 0.85 * 1.0 * 0.55 = 0.467

Step 3: Merge. After running all four dimensions, the final ranking (with resonance bonuses for multi-dimension hits) produces:

The result tells the agent: start with auth.py, then examine session.py and user_model.py. The four-dimension resonance bonus pushes middleware.py ahead of database.py even though their structural scores are similar – because middleware was recently modified (temporal) and sits on a causal chain (causal).

What this means in practice

An agent calling activate("authentication") gets back a ranked list of the 20 most relevant nodes in 31ms. It does not need to know file names, directory structure, or grep patterns. The activation pattern encodes structural proximity, naming affinity, temporal relevance, and causal relationships – fused into a single score.

Over time, as the agent provides feedback via learn, the edge weights shift through Hebbian plasticity (see Hebbian Plasticity). The paths that led to useful results strengthen. The paths that led to noise weaken. The same query tomorrow will produce better results.

Hebbian Plasticity

m1nd’s graph learns. Every query changes the edge weights. Paths that lead to useful results get stronger. Paths that lead to noise get weaker. Over time, the graph evolves to match how your team thinks about your codebase. No other code intelligence tool does this.

The neuroscience principle

In 1949, Donald Hebb proposed a theory of synaptic learning: “When an axon of cell A is near enough to excite cell B and repeatedly or persistently takes part in firing it, some growth process or metabolic change takes place in one or both cells such that A’s efficiency, as one of the cells firing B, is increased.”

The popular summary: neurons that fire together wire together.

The converse is equally important: neurons that fire independently weaken their connections. This bidirectional learning – strengthening co-active pathways, weakening inactive ones – is the foundation of how biological neural networks adapt to experience.

m1nd applies this principle to code graphs. Nodes are modules. Edges are relationships. “Firing” means being activated by a spreading activation query. When an agent confirms that a result was useful, the edges connecting those activated nodes strengthen. When the agent marks results as wrong, those paths weaken. The graph remembers what worked.

The five-step learning cycle

Every query that passes through m1nd’s PlasticityEngine triggers a five-step update cycle. This runs automatically – no explicit training phase required.

Step 1: Hebbian strengthening

For every edge where both the source and target were activated in the query results, the weight increases:

delta_w = learning_rate * activation_source * activation_target
new_weight = min(current_weight + delta_w, weight_cap)

The default learning rate is 0.08 (from LearningRate::DEFAULT). The weight cap is 3.0 – no edge can grow stronger than 3x its original weight. This prevents runaway positive feedback.

From the source code:

#![allow(unused)]
fn main() {
// Hebbian: delta_w = lr * act_src * act_tgt
let delta = lr * src_act.get() * tgt_act;
let new_weight = (current + delta).min(cap);
}

The product activation_source * activation_target means that strongly co-activated pairs get the largest boost. A pair where both nodes scored 0.8 gets 0.08 * 0.8 * 0.8 = 0.051 added to their edge weight. A pair where one scored 0.2 gets only 0.08 * 0.8 * 0.2 = 0.013. This is faithful to Hebb’s rule: the strength of the update is proportional to the correlation of the firing.

Step 2: Synaptic decay

Edges whose source nodes were not activated in this query decay slightly:

new_weight = max(current_weight * (1 - decay_rate), weight_floor)

The default decay rate is 0.005 per query (0.5%). The weight floor is 0.05 – edges never decay below 5% of their original weight. This ensures that even unused paths retain some connectivity, preventing the graph from fragmenting.

#![allow(unused)]
fn main() {
let decay_factor = 1.0 - self.config.decay_rate.get(); // 0.995
let new_weight = (current * decay_factor).max(floor);
}

The asymmetry is intentional. Strengthening applies a fixed delta (additive). Decay applies a multiplicative factor. This means strong edges resist decay (a weight-3.0 edge loses 0.015 per query) while weak edges decay faster in relative terms (a weight-0.1 edge loses 0.0005 per query). Frequently activated paths grow monotonically. Rarely activated paths slowly fade but never disappear.

Step 3: Long-Term Potentiation / Long-Term Depression

After an edge has been strengthened 5 consecutive times (the LTP threshold), it receives a one-time +0.15 bonus:

#![allow(unused)]
fn main() {
if !graph.edge_plasticity.ltp_applied[j]
    && graph.edge_plasticity.strengthen_count[j] >= self.config.ltp_threshold
{
    let new_weight = (current + self.config.ltp_bonus.get()).min(cap);
    graph.edge_plasticity.ltp_applied[j] = true;
}
}

Conversely, after an edge has been weakened 5 consecutive times (the LTD threshold), it receives a one-time -0.15 penalty:

#![allow(unused)]
fn main() {
if !graph.edge_plasticity.ltd_applied[j]
    && graph.edge_plasticity.weaken_count[j] >= self.config.ltd_threshold
{
    let new_weight = (current - self.config.ltd_penalty.get()).max(floor);
    graph.edge_plasticity.ltd_applied[j] = true;
}
}

These thresholds model biological LTP/LTD – the transition from short-term to long-term memory. Five consecutive activations is a signal of sustained relevance, not a fluke. The one-time bonus/penalty is permanent: it does not reset, and it does not apply again for the same edge. This prevents unbounded weight inflation from repeated queries.

Step 4: Homeostatic normalization

After strengthening and LTP/LTD, the total incoming weight for each node is checked against a ceiling of 5.0:

#![allow(unused)]
fn main() {
if total_incoming > ceiling {
    let scale = ceiling / total_incoming;
    for each incoming edge:
        new_weight = current * scale;
}
}

This is homeostatic plasticity – a biological mechanism that prevents individual neurons from becoming over-stimulated. In m1nd, it prevents hub nodes (like config.py or main.py) from accumulating so much incoming weight that they dominate every activation query regardless of the actual query content.

The normalization is proportional: all incoming edges are scaled by the same factor. This preserves relative strengths while enforcing an absolute ceiling. A node with 10 incoming edges at weight 1.0 each (total 10.0) would have all edges scaled to 0.5, bringing the total to 5.0.

Step 5: Query memory recording

The query, its seeds, and its activated nodes are recorded in a bounded ring buffer (capacity: 1000 queries). This memory serves two purposes:

1. Priming signal: future queries that share seeds with past queries get a boost from nodes that frequently appeared in those past results. This implements a form of associative memory – “things I looked at near authentication tend to be relevant when I look at authentication again.”

2. Seed bigrams: pairs of seeds that co-occur across multiple queries are tracked. This supports the warmup tool, which uses query memory to pre-activate frequently queried paths.

How learn works

The automatic plasticity cycle runs on every activate call. But agents can also provide explicit feedback via learn:

Positive feedback: learn(feedback="correct", node_ids=[...])

When an agent confirms that specific nodes were useful:

1. The edges connecting those nodes are strengthened with an amplified Hebbian update (the activation values are set to 1.0 for the confirmed nodes, producing maximum delta_w).
2. The strengthen counters increment, moving edges closer to the LTP threshold.
3. Query memory records the confirmed nodes with high weight, boosting them in future priming signals.

Negative feedback: learn(feedback="wrong", node_ids=[...])

When an agent marks results as irrelevant:

1. The edges connecting those nodes receive decay as if they were inactive, even though they were activated.
2. The weaken counters increment, moving edges closer to the LTD threshold.
3. Query memory records the rejection, reducing the priming signal for those nodes.

This feedback loop is what makes m1nd adaptive. A team that mostly works on the payment system will gradually strengthen all paths around payment-related modules. An agent investigating authentication will produce different results than an agent investigating billing – even on the same codebase – because their feedback histories have shaped different edge weight landscapes.

Plasticity state persistence

The learned weights are valuable. Losing them means losing the graph’s adaptation to your workflow. m1nd persists plasticity state in two ways:

Per-edge state (SynapticState)

Each edge’s plasticity state is captured as a serializable record:

#![allow(unused)]
fn main() {
pub struct SynapticState {
    pub source_label: String,
    pub target_label: String,
    pub relation: String,
    pub original_weight: f32,
    pub current_weight: f32,
    pub strengthen_count: u16,
    pub weaken_count: u16,
    pub ltp_applied: bool,
    pub ltd_applied: bool,
}
}

This is exported via PlasticityEngine::export_state() and persisted to M1ND_PLASTICITY_STATE (a JSON file). The export includes a NaN firewall (FM-PL-001): any non-finite weight falls back to the original weight. The write is atomic (temp file + rename, FM-PL-008) to prevent corruption on crash.

Importing state

When m1nd restarts, import_state restores learned weights. Edge identity matching uses (source_label, target_label, relation) triples – not numeric indices – because re-ingesting the codebase may produce different node numbering. This means plasticity survives codebase re-ingestion: if auth.py -> session.py was strengthened, that strengthening persists even if auth.py gets a different NodeId after re-ingest.

Weights are clamped to [weight_floor, weight_cap] on import. Invalid JSON triggers a schema validation error (FM-PL-007) rather than corrupting the graph.

Persistence frequency

The graph auto-persists every 50 queries and on server shutdown. This is a balance between durability (don’t lose too much learning) and disk I/O (don’t write on every query).

The drift tool

After persistence, the natural question is: how much has the graph changed? The drift tool answers this.

drift compares the current edge weights against their original (ingest-time) baselines and reports:

• Total edges changed: how many edges have weights different from their original values.
• Average weight change: the mean absolute delta across all modified edges.
• Top strengthened edges: the edges that have grown the most relative to their baseline.
• Top weakened edges: the edges that have decayed the most.
• LTP/LTD counts: how many edges have crossed the long-term potentiation or depression thresholds.

This is designed for session recovery. When an agent starts a new session, drift tells it what has changed since the graph was last loaded. The agent can see that “paths around the payment module strengthened significantly since yesterday” and adjust its investigation accordingly.

Session 1:
  ingest -> activate("auth") -> agent uses results -> learn(correct)
  → 740 edges strengthened, 12,340 edges decayed slightly

Session 2:
  drift(since=session_1) -> auth paths now 15% stronger on average
  activate("auth") -> better results, faster convergence to useful nodes

Session N:
  the graph has adapted to how your team thinks about auth

How this makes the graph adapt

The combination of automatic Hebbian updates, explicit feedback, LTP/LTD thresholds, and homeostatic normalization creates a self-tuning system:

1. Short-term adaptation (within a session): edges on frequently queried paths strengthen immediately. The next query about the same topic converges faster.

2. Long-term memory (across sessions): edges that cross the LTP threshold receive a permanent bonus. Persistent investigation patterns are encoded in the graph structure.

3. Forgetting (controlled decay): paths that are never queried slowly fade toward the weight floor. This prevents the graph from becoming saturated with historical patterns that no longer reflect the codebase’s structure.

4. Stability (homeostatic normalization): no node can accumulate unbounded incoming weight. Hub nodes stay important but do not become black holes that absorb all activation energy.

The result is a graph that starts generic (all edges at their ingest-time weights, reflecting code structure) and gradually becomes specific (edges weighted by how you use the codebase). Two teams working on the same repository will develop different plasticity landscapes. This is a feature: the graph models the team’s mental model, not just the code’s static structure.

Constants reference

XLR Noise Cancellation

Every code graph is noisy. Utility modules, shared constants, logging wrappers – they connect to everything, and they show up in every activation query whether they are relevant or not. m1nd solves this with a technique borrowed from professional audio engineering: differential signal processing with inverted channels. The same principle that makes balanced XLR cables immune to electromagnetic interference makes m1nd’s activation queries immune to structural noise.

The origin: balanced audio cables

In a recording studio, audio signals travel over long cables. The cable acts as an antenna, picking up electromagnetic interference (EMI) from power supplies, lighting, and radio transmissions. An unbalanced cable delivers a noisy signal: the audio you want plus the interference you do not.

A balanced XLR cable solves this by carrying two copies of the audio signal: one normal (hot, pin 2) and one inverted (cold, pin 3). Both signals travel the same physical path, so they pick up the same interference. At the receiving end, the cold signal is flipped back and added to the hot signal. The audio doubles in strength. The interference – identical on both channels – cancels out.

Hot channel:  signal + noise
Cold channel: -signal + noise

At receiver:  hot - cold = (signal + noise) - (-signal + noise) = 2 * signal

The noise vanishes. The signal survives.

The problem in code graphs

When you ask m1nd “what is related to the payment system?”, structural spreading activation fires from payment-related seed nodes and propagates outward. The result includes genuinely relevant modules (billing, invoicing, refunds) but also noisy modules that connect to everything:

• config.py – imported by 40+ files
• logger.py – called from every module
• database.py – the persistence layer for everything
• utils.py – helper functions used everywhere
• __init__.py – package marker files

These modules score high in structural activation not because they are relevant to payments, but because they are structurally central. They are the electromagnetic interference of code graphs: noise that correlates with structure, not with the query.

Text search (grep, ripgrep) cannot solve this. It finds files that contain the word “payment,” which misses files that handle payments but never use that string. Static analysis cannot solve it either – the call graph from payment modules genuinely includes config.py and logger.py.

The problem is not that these edges are wrong. They are structurally correct. The problem is that they carry noise mixed in with signal, and the noise is stronger.

How m1nd implements differential processing

m1nd’s AdaptiveXlrEngine implements a six-stage pipeline that mirrors the physics of balanced XLR cables.

Stage 1: Select anti-seeds

The cold channel needs its own starting points – nodes that represent “not the query.” m1nd calls these anti-seeds. Good anti-seeds are structurally similar to the seeds (similar degree, similar graph position) but semantically distant (low neighborhood overlap).

The selection criteria:

#![allow(unused)]
fn main() {
// Degree ratio filter: anti-seed must have similar connectivity
if avg_seed_degree > 0.0 {
    let ratio = degree / avg_seed_degree;
    if ratio < 0.3 { continue; }  // Too peripheral
}

// Jaccard similarity: anti-seed must have different neighbors
let jaccard = intersection as f32 / union_size as f32;
if jaccard > 0.2 { continue; }  // Too similar to seeds
}

A node with similar degree but different neighbors is the ideal anti-seed. It will activate the same noisy hub nodes (because it has similar connectivity) but different domain-specific nodes (because it lives in a different part of the graph).

By default, 3 anti-seeds are selected.

Stage 2: Compute seed immunity

Nodes close to the seeds – within 2 BFS hops – are marked as immune to cold-channel cancellation. This prevents the anti-seed signal from cancelling legitimate results near the query target.

#![allow(unused)]
fn main() {
// BFS from seeds, mark everything within immunity_hops as immune
while let Some((node, d)) = queue.pop_front() {
    if d >= self.params.immunity_hops { continue; }
    for each neighbor:
        immune[neighbor] = true;
        queue.push_back((neighbor, d + 1));
}
}

Immunity is the key insight that prevents over-cancellation. Without it, the cold channel could erase results that are genuinely close to the query. With it, only distant noise gets cancelled.

Stage 3: Propagate hot signal

Spectral pulses propagate from the seed nodes at frequency F_HOT = 1.0. Each pulse carries an amplitude, a phase, and a frequency. The signal decays along edges and attenuates at inhibitory edges (by INHIBITORY_COLD_ATTENUATION = 0.5).

#![allow(unused)]
fn main() {
let pulse = SpectralPulse {
    node: seed,
    amplitude: seed_activation,
    phase: 0.0,
    frequency: F_HOT,  // 1.0
    hops: 0,
    prev_node: seed,
};
}

Propagation is budget-limited (default 50,000 total pulses across hot and cold channels) to prevent runaway computation on dense graphs.

Stage 4: Propagate cold signal

The same propagation runs from the anti-seed nodes at frequency F_COLD = 3.7. The cold frequency is intentionally different from the hot frequency. This spectral separation allows m1nd to distinguish which contributions came from which channel.

#![allow(unused)]
fn main() {
let cold_freq = PosF32::new(F_COLD).unwrap();  // 3.7
let anti_seed_pairs: Vec<(NodeId, FiniteF32)> = anti_seeds
    .iter()
    .map(|&n| (n, FiniteF32::ONE))
    .collect();
let cold_pulses = self.propagate_spectral(
    graph, &anti_seed_pairs, cold_freq, config, half_budget
)?;
}

Stage 5: Adaptive differential

At each node, the hot and cold amplitudes are combined. Immune nodes receive the full hot signal with no cold cancellation. Non-immune nodes get the differential:

#![allow(unused)]
fn main() {
let effective_cold = if immune { 0.0 } else { cold_amp[i] };
let raw = hot - effective_cold;
}

The raw differential is then modulated by local graph density. Nodes with degree near the graph average get density 1.0. High-degree nodes (hubs) get density > 1.0, amplifying the differential effect. Low-degree nodes (leaves) get density < 1.0, attenuating it. This is density-adaptive strength – a hub with both hot and cold signal has its differential amplified because hubs are the primary source of noise.

#![allow(unused)]
fn main() {
let density = if avg_deg > 0.0 {
    (out_deg / avg_deg).max(DENSITY_FLOOR).min(DENSITY_CAP)
} else {
    1.0
};
}

Density is clamped to [0.3, 2.0] to prevent extreme values from distorting results.

Stage 6: Sigmoid gating

The density-modulated differential passes through a sigmoid gate:

#![allow(unused)]
fn main() {
pub fn sigmoid_gate(net_signal: FiniteF32) -> FiniteF32 {
    let x = net_signal.get() * SIGMOID_STEEPNESS;  // * 6.0
    let clamped = x.max(-20.0).min(20.0);
    let result = 1.0 / (1.0 + (-clamped).exp());
    FiniteF32::new(result)
}
}

The sigmoid converts the raw differential (which can be any value) into a smooth activation in [0, 1]. The steepness factor of 6.0 creates a sharp transition: small positive differentials map close to 0.5, strong positive differentials map close to 1.0, and negative differentials (more cold than hot) map close to 0.0 and are effectively suppressed.

graph LR
    subgraph "XLR Pipeline"
        S["Seeds<br/>F=1.0 (hot)"] --> HP["Hot<br/>propagation"]
        AS["Anti-seeds<br/>F=3.7 (cold)"] --> CP["Cold<br/>propagation"]
        HP --> DIFF["Differential<br/>hot - cold"]
        CP --> DIFF
        DIFF --> DEN["Density<br/>modulation"]
        DEN --> SIG["Sigmoid<br/>gating"]
        SIG --> OUT["Clean<br/>activation"]
    end

    subgraph "Immunity"
        IMM["2-hop BFS<br/>from seeds"] -.->|"immune = true"| DIFF
    end

    style S fill:#ff6b6b,stroke:#333,color:#fff
    style AS fill:#4dabf7,stroke:#333,color:#fff
    style OUT fill:#51cf66,stroke:#333,color:#fff
    style IMM fill:#ffd43b,stroke:#333

Over-cancellation fallback

If the cold channel is too aggressive – cancelling all hot signal and leaving zero results – m1nd triggers a fallback (FM-XLR-010):

#![allow(unused)]
fn main() {
let fallback = all_zero && !hot_pulses.is_empty();
if fallback {
    // Return hot-only (no cancellation)
    activations.clear();
    for i in 0..n {
        if hot_amp[i] > 0.01 {
            activations.push((NodeId::new(i as u32), FiniteF32::new(hot_amp[i])));
        }
    }
}
}

This ensures that XLR noise cancellation never makes results worse than plain activation. It can either improve them (by removing noise) or fall back to the unfiltered result. The xlr_fallback_used flag in the activation result tells the caller that this happened.

Before and after

Without XLR

Query: “payment processing”

Signal-to-noise ratio: 4 relevant out of 10.

With XLR

The anti-seeds (e.g., nodes from the user management subsystem) produce cold signal that reaches the same hub nodes – config.py, database.py, logger.py, utils.py, middleware.py, routes.py. These hubs receive both hot and cold signal. The differential cancels them.

Payment-specific nodes (payment_handler.py, billing.py, invoice.py, refund.py) receive hot signal but little cold signal, because the anti-seeds live in a different part of the graph. Their differential stays high.

Signal-to-noise ratio: 6 relevant out of 8.

The hub nodes did not disappear entirely – they still have small positive differentials. But they dropped from ranks 1, 3, 4, 6 to ranks 7, 8. The payment-specific nodes rose to the top.

Why the spectral model matters

The use of different frequencies for hot (1.0) and cold (3.7) channels enables a richer cancellation model than simple subtraction. The spectral_overlap function measures how much the hot and cold frequency distributions overlap at each node:

#![allow(unused)]
fn main() {
// Overlap = sum(min(hot_buckets, cold_buckets)) / sum(hot_buckets)
}

Nodes where hot and cold signals arrive at similar frequencies have high spectral overlap – these are the noise nodes that respond to any query. Nodes where the hot signal dominates a different frequency band than the cold signal have low spectral overlap – these are the signal nodes that respond specifically to this query.

This is directly analogous to common-mode rejection in electrical engineering: the interference is the component that appears identically on both channels, and the signal is the component that differs.

Constants reference

Structural Holes

Most developer tools find things that exist. m1nd finds things that should exist but do not. A missing error handler. A test file that was never written. A validation function that every sibling module has except one. These are structural holes – gaps in the code graph that reveal omissions, risks, and design inconsistencies.

The network theory origin

The concept of structural holes comes from sociologist Ronald Burt’s 1992 book Structural Holes: The Social Structure of Competition. Burt observed that in social networks, the most valuable positions are not the most connected ones – they are the ones that bridge otherwise disconnected groups. The gap between two groups is a structural hole. The person who spans it controls information flow.

Burt was studying people and organizations, but the insight transfers directly to code. In a codebase graph, a structural hole is a place where a connection should exist based on the surrounding structure but does not. The module that imports five out of six modules in a cluster but skips the sixth. The service that handles create, read, update, but not delete. The directory where every file has a test except one.

These gaps are invisible to text search. You cannot grep for something that is absent. You cannot find a missing test by scanning the test directory – you have to know what should be there and check whether it is there. This requires structural reasoning over the graph, not pattern matching over text.

How m1nd detects structural holes

m1nd detects structural holes through a combination of activation context and neighborhood analysis. The detection is embedded in the query pipeline and can also be invoked directly via the missing tool.

The algorithm

The core insight is: a node surrounded by activated neighbors but not activated itself is probably missing something.

After a spreading activation query produces its ranked results, the structural hole detector scans every node in the graph:

#![allow(unused)]
fn main() {
pub fn detect_structural_holes(
    &self,
    graph: &Graph,
    activation: &ActivationResult,
    min_sibling_activation: FiniteF32,
) -> M1ndResult<Vec<StructuralHole>> {
    // Build activation lookup
    let mut act_map = vec![0.0f32; n];
    for a in &activation.activated {
        act_map[a.node.as_usize()] = a.activation.get();
    }

    for each node i:
        // Skip if already activated (it is in the results)
        if act_map[i] > 0.01: continue

        // Count activated neighbors
        for each neighbor of i:
            if act_map[neighbor] > min_sibling_activation:
                activated_neighbors += 1
                neighbor_act_sum += act_map[neighbor]

        // If 2+ neighbors are activated but this node is not: structural hole
        if activated_neighbors >= 2:
            holes.push(StructuralHole {
                node: i,
                sibling_avg_activation: neighbor_act_sum / activated_neighbors,
                reason: format!("{} activated neighbors (avg={:.2}) but node inactive",
                    activated_neighbors, avg),
            })
}

The threshold of 2 activated neighbors prevents false positives from nodes that happen to touch one activated node. The min_sibling_activation parameter (default 0.3) filters out weakly activated neighbors. Results are sorted by the average activation of the surrounding neighbors – the higher the average, the more conspicuous the absence.

Why this works

Consider a query about “authentication.” The activation pattern covers auth.py, session.py, middleware.py, user_model.py, and their neighbors. Now suppose auth_test.py does not exist. The test files for every other module in the auth cluster exist and are activated (because they have edges to the modules they test). auth_test.py is absent from the graph entirely. But if it did exist, it would be surrounded by activated nodes. Its absence is detectable by the gap it leaves.

In the more subtle case, auth_test.py exists but lacks tests for the password reset flow. The test file node exists and is activated, but password_reset_handler.py is activated while auth_test.py’s test coverage edges do not include it. The neighborhood analysis detects this: password_reset_handler.py’s siblings all have test edges, but this one does not.

The missing tool

The missing tool wraps structural hole detection in a purpose-built interface. Instead of requiring the caller to run an activation query first, missing accepts a natural-language query, runs internal activation, and returns only the holes.

The tool exposes the detection through the MCP protocol. Behind the scenes, it:

1. Finds seed nodes matching the query text.
2. Runs full four-dimension spreading activation (structural, semantic, temporal, causal).
3. Analyzes the activation pattern for structural holes using the neighborhood algorithm.
4. Returns the top 10 holes sorted by surrounding activation strength.

Each hole includes:

• node_id: the node at the center of the gap.
• label: human-readable identifier.
• node_type: file, function, class, etc.
• reason: a description of why this is a hole (e.g., “4 activated neighbors (avg=0.72) but node inactive”).
• sibling_avg_activation: quantifies how strongly the surrounding nodes were activated.

Real examples

Missing error handler

Query: “error handling in the payment flow”

Activation lights up: payment_handler.py, billing.py, refund.py, payment_errors.py, retry_logic.py.

Structural hole detected: webhook_handler.py has 3 activated neighbors (payment_handler.py, billing.py, payment_errors.py) but is itself not activated. Investigation reveals: the webhook handler processes Stripe callbacks but has no error handling – raw exceptions propagate to the caller. Every other module in the payment cluster catches and wraps errors via payment_errors.py. The webhook handler does not.

StructuralHole {
    node: "file::webhook_handler.py",
    sibling_avg_activation: 0.71,
    reason: "3 activated neighbors (avg=0.71) but node inactive"
}

Missing test file

Query: “authentication testing”

Activation lights up: test_auth.py, test_session.py, test_middleware.py, auth.py, session.py.

Structural hole detected: password_reset.py has 4 activated neighbors but zero activation itself. The module handles password reset logic. It imports from auth.py and session.py (both activated). It is imported by routes.py (activated). But there is no test_password_reset.py in the graph, and password_reset.py has no test-relationship edges. Every sibling module in the auth cluster has a corresponding test file. This one does not.

StructuralHole {
    node: "file::password_reset.py",
    sibling_avg_activation: 0.68,
    reason: "4 activated neighbors (avg=0.68) but node inactive"
}

Missing validation

Query: “input validation for API endpoints”

Activation lights up: validate_user_input.py, validate_payment_input.py, validate_search_params.py, schema_validator.py.

Structural hole detected: admin_routes.py has 3 activated neighbors (the validation modules it shares with other route handlers) but is not activated itself. Investigation reveals: user routes, payment routes, and search routes all import and call validation functions. Admin routes do not. The admin API accepts raw input without validation – a security risk hidden in a structural gap.

StructuralHole {
    node: "file::admin_routes.py",
    sibling_avg_activation: 0.65,
    reason: "3 activated neighbors (avg=0.65) but node inactive"
}

Why no other tool can do this

Text search (grep, ripgrep)

Text search finds strings. It cannot find the absence of a string. You cannot grep for “the test file that should exist but does not.” You would need to know in advance what you are looking for, which defeats the purpose.

Static analysis (AST, linters)

Linters can enforce specific rules (“every function must have a docstring”) but cannot detect structural patterns across the graph (“every module in this cluster has a test file except this one”). They operate on individual files, not on the relationships between files.

RAG / embedding search

Embedding search finds documents similar to a query. It cannot detect the gap between documents. If test_password_reset.py does not exist, there is no document to embed. The absence is invisible.

Code coverage tools

Coverage tools tell you which lines of code are executed during tests. They can identify untested code within a file. They cannot identify missing files – a test file that was never created has zero coverage, indistinguishable from a file that exists but is not run.

m1nd’s advantage

m1nd operates on the graph structure, not on file contents. It reasons about the topology of relationships: which nodes connect to which other nodes, and where those connections are unexpectedly absent. The spreading activation query establishes a context (“what is related to authentication?”), and the structural hole detector finds gaps within that context.

This is a fundamentally different capability. It is not better text search, or better static analysis, or better coverage. It is structural reasoning about the shape of the code graph – something that requires a graph in the first place, and an activation pattern to establish context.

Connection to other concepts

Structural hole detection works best when combined with other m1nd capabilities:

• Spreading activation (see Spreading Activation) provides the activation context that defines “which neighbors count.” Without activation, every node would be checked against every other node – too noisy to be useful.

• Hebbian plasticity (see Hebbian Plasticity) sharpens the detection over time. As edges on well-tested paths strengthen and edges on untested paths weaken, the contrast between activated and inactive nodes increases. Holes become more conspicuous.

• XLR noise cancellation (see XLR Noise Cancellation) removes hub-node noise from the activation pattern before hole detection runs. Without XLR, config.py being activated might cause false-positive holes in unrelated modules that happen to import config. With XLR, the activation pattern is cleaner, and the holes that surface are more meaningful.

Interpreting results

A structural hole is not necessarily a bug. It is a signal that something deviates from the surrounding pattern. Possible interpretations:

The sibling_avg_activation score helps prioritize. A hole where surrounding nodes have an average activation of 0.85 is more suspicious than one at 0.35. The former means the node is deeply embedded in a strongly activated cluster and conspicuously absent. The latter means the surrounding nodes were only weakly related to the query – the “hole” may just be a node in a different domain.

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. Use tools/list for the exact count in your current build.

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.

Tool Index

Core Activation

Analysis

Memory, Trails, and Learning

Exploration

Perspectives

Lifecycle, Search, and Surgical

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:

Agent IDs are free-form strings. Convention: use the agent’s name or role identifier (e.g. "jimi", "hacker-auth", "forge-build").

JSON-RPC Request Format

m1nd uses the MCP protocol over JSON-RPC 2.0 via stdio. All tool calls use the tools/call method.

Request structure

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
        "name": "activate",
    "arguments": {
      "agent_id": "jimi",
      "query": "session management"
    }
  }
}

Successful response

{
  "jsonrpc": "2.0",
  "id": 1,
  "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.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ \"error\": \"...\", \"hint\": \"...\", \"suggested_next_step\": \"...\" }"
      }
    ],
    "isError": true
  }
}

Error response (protocol error)

JSON-RPC protocol errors use standard error codes:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found: bad_method"
  }
}

Error Codes

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:

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": { "name": "m1nd-mcp", "version": "0.8.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.

Activation Tools

Three tools for querying the graph through spreading activation, task-based priming, and resonance analysis.

activate

Spreading activation query across the graph. The primary structural search tool – propagates signal from seed nodes through the graph across four dimensions (structural, semantic, temporal, causal), with XLR noise cancellation and optional ghost edge / structural hole detection.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "activate",
    "arguments": {
      "agent_id": "jimi",
      "query": "session pool management",
      "top_k": 5,
      "include_ghost_edges": true
    }
  }
}

Example Response

{
  "query": "session pool management",
  "seeds": [
    { "node_id": "file::session_pool.py", "label": "session_pool.py", "relevance": 0.95 }
  ],
  "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": ["session", "pool"],
      "provenance": {
        "source_path": "backend/session_pool.py",
        "line_start": 1,
        "line_end": 245,
        "canonical": true
      }
    },
    {
      "node_id": "file::session_pool.py::class::SessionPool",
      "label": "SessionPool",
      "type": "class",
      "activation": 0.84,
      "dimensions": { "structural": 0.88, "semantic": 0.91, "temporal": 0.72, "causal": 0.65 },
      "pagerank": 0.412,
      "tags": ["pool", "session"],
      "provenance": {
        "source_path": "backend/session_pool.py",
        "line_start": 15,
        "line_end": 180,
        "canonical": true
      }
    }
  ],
  "ghost_edges": [
    {
      "source": "session_pool.py",
      "target": "healing_manager.py",
      "shared_dimensions": ["semantic", "causal"],
      "strength": 0.34
    }
  ],
  "structural_holes": [],
  "plasticity": {
    "edges_strengthened": 12,
    "edges_decayed": 3,
    "ltp_events": 1,
    "priming_nodes": 5
  },
  "elapsed_ms": 31.2
}

When to Use

• Primary search – the default way to ask “what in the codebase relates to X?”
• Exploration – when you know a topic but not the specific files
• Context building – before working on a feature, activate its topic to find all related code
• Gap detection – enable include_structural_holes to find missing connections

Side Effects

Activate has plasticity side effects: it strengthens edges between activated nodes and decays inactive edges. This makes the graph learn from usage patterns over time.

Related Tools

• warmup – activate + prime for a specific task
• seek – intent-aware search (finds code by purpose, not just keywords)
• perspective_start – wraps activate into a navigable perspective
• learn – explicitly provide feedback on activation results

warmup

Task-based warmup and priming. Activates the graph around a task description and applies a temporary boost to relevant nodes, preparing the graph for focused work. The boost decays naturally over time.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "warmup",
    "arguments": {
      "agent_id": "jimi",
      "task_description": "Refactor the WhatsApp message routing to support group chats",
      "boost_strength": 0.2
    }
  }
}

Example Response

{
  "task": "Refactor the WhatsApp message routing to support group chats",
  "primed_nodes": 23,
  "top_primed": [
    { "node_id": "file::whatsapp_routes.py", "label": "whatsapp_routes.py", "boost": 0.2 },
    { "node_id": "file::whatsapp_manager.py", "label": "whatsapp_manager.py", "boost": 0.18 },
    { "node_id": "file::whatsapp_models.py", "label": "whatsapp_models.py", "boost": 0.15 },
    { "node_id": "file::chat_handler.py", "label": "chat_handler.py", "boost": 0.12 }
  ],
  "elapsed_ms": 18.5
}

When to Use

• Session start – warm up before a focused work session to bias the graph toward relevant code
• Context switch – when changing tasks, warm up the new topic
• Before complex queries – warmup biases subsequent activate, impact, and why queries toward the warmed-up region

Side Effects

Applies temporary priming boosts to node activations. These boosts decay naturally and are NOT persisted across server restarts.

Related Tools

• activate – raw activation query without the priming boost
• trail_resume – restores a full investigation context including activation boosts

resonate

Resonance analysis: standing waves, harmonics, sympathetic pairs, and resonant frequencies in the graph. Identifies nodes that form natural clusters of mutual reinforcement.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "resonate",
    "arguments": {
      "agent_id": "jimi",
      "query": "authentication flow",
      "top_k": 10
    }
  }
}

Example Response

{
  "seed": "authentication flow",
  "harmonics": [
    {
      "node_id": "file::auth_discovery.py",
      "label": "auth_discovery.py",
      "amplitude": 0.92,
      "harmonic_order": 1
    },
    {
      "node_id": "file::middleware.py",
      "label": "middleware.py",
      "amplitude": 0.71,
      "harmonic_order": 2
    },
    {
      "node_id": "file::principal_registry.py",
      "label": "principal_registry.py",
      "amplitude": 0.68,
      "harmonic_order": 2
    }
  ],
  "sympathetic_pairs": [
    { "a": "auth_discovery.py", "b": "principal_registry.py", "coupling": 0.84 }
  ],
  "elapsed_ms": 45.0
}

When to Use

• Deep structural analysis – find natural clusters of mutually reinforcing code
• Pattern discovery – identify which modules form coherent subsystems
• Architecture review – see which modules resonate together (and which do not)
• Refactoring – resonance groups suggest natural module boundaries

Side Effects

Read-only. No plasticity side effects.

Related Tools

• activate – simpler spreading activation without harmonic analysis
• fingerprint – finds structurally equivalent nodes
• missing – finds gaps in the resonance structure

Analysis Tools

Seven tools for impact analysis, prediction, counterfactual simulation, fingerprinting, hypothesis testing, structural diffing, and drift detection.

impact

Impact radius / blast analysis for a node. Propagates signal outward from a source node to determine which other nodes would be affected by a change. Supports forward (downstream), reverse (upstream), and bidirectional analysis.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "impact",
    "arguments": {
      "agent_id": "jimi",
      "node_id": "file::chat_handler.py",
      "direction": "forward",
      "include_causal_chains": true
    }
  }
}

Example Response

{
  "source": "file::chat_handler.py",
  "source_label": "chat_handler.py",
  "direction": "forward",
  "blast_radius": [
    { "node_id": "file::chat_routes.py", "label": "chat_routes.py", "type": "file", "signal_strength": 0.91, "hop_distance": 1 },
    { "node_id": "file::ws_relay.py", "label": "ws_relay.py", "type": "file", "signal_strength": 0.78, "hop_distance": 1 },
    { "node_id": "file::stream_parser.py", "label": "stream_parser.py", "type": "file", "signal_strength": 0.65, "hop_distance": 2 }
  ],
  "total_energy": 4271.0,
  "max_hops_reached": 3,
  "causal_chains": [
    {
      "path": ["chat_handler.py", "chat_routes.py", "main.py"],
      "relations": ["imported_by", "registered_in"],
      "cumulative_strength": 0.82
    }
  ]
}

When to Use

• Before modifying code – understand the blast radius before touching a file
• Risk assessment – high total_energy = high-risk change
• Scope validation – verify that a planned change does not leak beyond expected boundaries
• Reverse analysis – find all upstream dependencies that could cause a bug in a given module

Related Tools

• predict – predicts which files will co-change (more actionable than blast radius)
• counterfactual – simulates deletion rather than change
• validate_plan – validates an entire modification plan

predict

Co-change prediction for a modified node. Given a node that was just changed, predicts which other nodes are most likely to need changes too, ranked by confidence. Uses historical co-change patterns, structural proximity, and velocity scoring.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "predict",
    "arguments": {
      "agent_id": "jimi",
      "changed_node": "file::session_pool.py",
      "top_k": 5
    }
  }
}

Example Response

{
  "changed_node": "file::session_pool.py",
  "predictions": [
    { "node_id": "file::worker_pool.py", "label": "worker_pool.py", "confidence": 0.89, "velocity": 0.72, "reason": "high co-change frequency + structural coupling" },
    { "node_id": "file::process_manager.py", "label": "process_manager.py", "confidence": 0.76, "velocity": 0.65, "reason": "imports session_pool" },
    { "node_id": "file::tests/test_session_pool.py", "label": "test_session_pool.py", "confidence": 0.71, "velocity": 0.80, "reason": "test file" },
    { "node_id": "file::spawner.py", "label": "spawner.py", "confidence": 0.54, "velocity": 0.41, "reason": "2-hop dependency" },
    { "node_id": "file::config.py", "label": "config.py", "confidence": 0.32, "velocity": 0.28, "reason": "shared configuration" }
  ],
  "elapsed_ms": 8.3
}

When to Use

• After modifying a module – find what else needs updating
• Before committing – verify you have not missed a co-change partner
• Code review – check if a PR is missing changes to coupled modules

Related Tools

• impact – blast radius (broader, less actionable)
• timeline – detailed co-change history
• validate_plan – validates an entire plan against co-change predictions

counterfactual

What-if node removal simulation. Simulates removing one or more nodes from the graph and reports the cascade: orphaned nodes, lost activation energy, and the resulting blast radius. Non-destructive – the graph is not modified.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "counterfactual",
    "arguments": {
      "agent_id": "jimi",
      "node_ids": ["file::spawner.py"],
      "include_cascade": true
    }
  }
}

Example Response

{
  "removed_nodes": ["file::spawner.py"],
  "cascade": [
    { "depth": 1, "affected": 23 },
    { "depth": 2, "affected": 456 },
    { "depth": 3, "affected": 3710 }
  ],
  "total_affected": 4189,
  "orphaned_count": 0,
  "pct_activation_lost": 0.41,
  "elapsed_ms": 3.1
}

When to Use

• Before deleting/rewriting modules – understand the full cascade before removing code
• Dependency audit – find modules whose removal would be catastrophic
• Architecture planning – evaluate the cost of removing a subsystem

Related Tools

• impact – change impact (less extreme than removal)
• hypothesize – test a structural claim about dependencies

fingerprint

Activation fingerprint and equivalence detection. Computes a structural fingerprint for a target node (or the entire graph) and finds functionally equivalent or duplicate nodes. Uses probe queries to generate activation patterns and compares them via cosine similarity.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "fingerprint",
    "arguments": {
      "agent_id": "jimi",
      "target_node": "file::session_pool.py",
      "similarity_threshold": 0.7
    }
  }
}

Example Response

{
  "target": "file::session_pool.py",
  "fingerprint": [0.92, 0.45, 0.78, 0.33, 0.67],
  "equivalents": [
    { "node_id": "file::worker_pool.py", "label": "worker_pool.py", "similarity": 0.88, "reason": "similar pool lifecycle pattern" },
    { "node_id": "file::fast_pool.py", "label": "fast_pool.py", "similarity": 0.74, "reason": "shared structural role" }
  ],
  "elapsed_ms": 55.2
}

When to Use

• Duplicate detection – find code doing the same thing in different places
• Consolidation audit – identify candidates for unification
• Post-build review – verify new code does not duplicate existing functionality

Related Tools

• resonate – finds harmonically coupled nodes (complementary, not duplicate)
• activate – simpler search without equivalence scoring

hypothesize

Graph-based hypothesis testing. Takes a natural language claim about the codebase, parses it into a structural query pattern, and returns evidence for and against the claim with a Bayesian confidence score.

Supported claim patterns (auto-detected from natural language): NEVER_CALLS, ALWAYS_BEFORE, DEPENDS_ON, NO_DEPENDENCY, COUPLING, ISOLATED, GATEWAY, CIRCULAR.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "hypothesize",
    "arguments": {
      "agent_id": "jimi",
      "claim": "worker_pool depends on whatsapp_manager at runtime"
    }
  }
}

Example Response

{
  "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 process_manager.cancel",
      "likelihood_factor": 3.5,
      "nodes": ["file::worker_pool.py", "file::process_manager.py", "file::whatsapp_manager.py"],
      "relations": ["calls", "imports"],
      "path_weight": 0.68
    }
  ],
  "contradicting_evidence": [],
  "paths_explored": 25015,
  "elapsed_ms": 58.0
}

Verdict Values

When to Use

• Architecture validation – test claims about module boundaries and dependencies
• Bug investigation – test whether a suspected dependency exists
• Code review – verify architectural invariants are maintained
• Security audit – test isolation claims (e.g. “auth module is isolated from user input”)

Related Tools

• why – finds the path between two specific nodes
• impact – measures downstream impact rather than testing a claim
• scan – structural analysis with predefined patterns

differential

Focused structural diff between two graph snapshots. Compares edges, weights, nodes, and coupling between snapshot A and snapshot B, optionally narrowed by a focus question.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "differential",
    "arguments": {
      "agent_id": "jimi",
      "snapshot_a": "/path/to/before.json",
      "snapshot_b": "current",
      "question": "what new coupling was introduced?"
    }
  }
}

Example Response

{
  "snapshot_a": "/path/to/before.json",
  "snapshot_b": "current",
  "new_edges": [
    { "source": "whatsapp_routes.py", "target": "chat_handler.py", "relation": "calls", "weight": 0.45 }
  ],
  "removed_edges": [],
  "weight_changes": [
    { "source": "session_pool.py", "target": "worker_pool.py", "relation": "imports", "old_weight": 0.5, "new_weight": 0.78, "delta": 0.28 }
  ],
  "new_nodes": ["file::whatsapp_chat_bridge.py"],
  "removed_nodes": [],
  "coupling_deltas": [
    { "community_a": "whatsapp", "community_b": "chat", "old_coupling": 0.2, "new_coupling": 0.65, "delta": 0.45 }
  ],
  "summary": "1 new edge, 1 new node, 1 weight change, 1 coupling increase",
  "elapsed_ms": 120.5
}

When to Use

• Pre/post refactor comparison – snapshot before, refactor, then diff against current
• PR review – compare graph before and after a branch’s changes
• Architecture drift monitoring – periodic snapshot comparison

Related Tools

• diverge – higher-level drift analysis with anomaly detection
• lock_diff – diff within a locked region (no snapshot file needed)

diverge

Structural drift detection between a baseline and the current graph state. Higher-level than differential – includes anomaly detection (test deficits, velocity spikes, new coupling), coupling matrix changes, and a Jaccard-based structural drift score.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "diverge",
    "arguments": {
      "agent_id": "jimi",
      "baseline": "2026-03-01",
      "scope": "backend/stormender*"
    }
  }
}

Example Response

{
  "baseline": "2026-03-01",
  "baseline_commit": "a1b2c3d",
  "scope": "backend/stormender*",
  "structural_drift": 0.23,
  "new_nodes": ["file::stormender_v2_runtime_guard.py"],
  "removed_nodes": [],
  "modified_nodes": [
    { "file": "stormender_v2.py", "delta": "+450/-30", "growth_ratio": 1.85 }
  ],
  "coupling_changes": [
    { "pair": ["stormender_v2.py", "stormender_v2_routes.py"], "was": 0.4, "now": 0.72, "direction": "strengthened" }
  ],
  "anomalies": [
    { "type": "test_deficit", "file": "stormender_v2_runtime_guard.py", "detail": "New file with 0 test files", "severity": "warning" },
    { "type": "velocity_spike", "file": "stormender_v2.py", "detail": "450 lines added in 12 days", "severity": "info" }
  ],
  "summary": "23% structural drift. 1 new file (untested). Stormender coupling strengthened.",
  "elapsed_ms": 85.0
}

Anomaly Types

When to Use

• Session start – drift shows weight-level changes; diverge shows structural-level changes
• Sprint retrospective – how much did the architecture change this sprint?
• Quality gate – flag files with test deficits before merging

Related Tools

• drift – weight-level drift (lighter, faster)
• differential – lower-level snapshot diff
• timeline – single-node temporal history

ghost_edges

Parse git history and surface temporal co-change ghost edges: files that move together without an explicit static dependency.

Parameters

When to Use

• To find hidden temporal coupling
• Before refactors in churn-heavy areas

Related Tools

• timeline
• predict

taint_trace

Inject taint at entry points and trace propagation through the graph to expose missed validation, auth, or sanitization boundaries.

Parameters

When to Use

• Security reviews on trust boundaries
• Input validation and auth flow audits

Related Tools

• scan
• trace

twins

Find structurally similar or identical nodes by topology signature.

Parameters

When to Use

• Duplicate logic detection
• Consolidation/refactor candidate discovery

Related Tools

• fingerprint
• refactor_plan

refactor_plan

Graph-native refactoring proposals: community detection and extraction candidates for a scoped region.

Parameters

When to Use

• Before modularization/extraction work
• To identify communities with high internal cohesion

Related Tools

• twins
• impact

runtime_overlay

Overlay OpenTelemetry span activity onto the graph to paint runtime heat, latency, and error signals onto nodes.

Parameters

When to Use

• Correlating runtime hotspots with structural risk
• Prioritizing where to inspect first after a production incident

Related Tools

• trace
• impact
• daemon_tick

metrics

Return structural metrics per file, function, class, struct, or module.

Parameters

When to Use

• To rank hot modules by size/degree/centrality
• To anchor audits with hard structural numbers

Related Tools

• panoramic
• diagram

type_trace

Trace where a type, struct, or enum is used across the graph.

Parameters

When to Use

• Following type spread before edits
• Understanding where a central data model is consumed

Related Tools

• search
• impact

diagram

Generate Mermaid or DOT graph diagrams from a query or node-centered slice.

Parameters

When to Use

• Human-readable architecture explanations
• Sharing graph context with another agent or reviewer

Related Tools

• metrics
• perspective_inspect

Memory & Learning Tools

Seven tools for feedback-based learning, drift analysis, path explanation, and investigation trail management.

learn

Explicit feedback-based edge adjustment. After using activate or other query tools, call learn to tell m1nd whether the results were correct, wrong, or partial. This applies Hebbian learning to strengthen or weaken edges between the query seeds and the reported nodes.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "learn",
    "arguments": {
      "agent_id": "jimi",
      "query": "session pool management",
      "feedback": "correct",
      "node_ids": ["file::session_pool.py", "file::worker_pool.py"],
      "strength": 0.3
    }
  }
}

Example Response

{
  "query": "session pool management",
  "feedback": "correct",
  "edges_adjusted": 8,
  "nodes_affected": 2,
  "plasticity_delta": 0.3,
  "elapsed_ms": 2.1
}

When to Use

• After every activate where results were used – always provide feedback to improve future results
• After investigation – report which activated nodes were actually relevant
• Continuous improvement – the graph learns from your feedback over time

Side Effects

Modifies edge weights in the graph. Changes are persisted on the next auto-persist cycle (every 50 queries) and on shutdown.

Related Tools

• activate – the query tool whose results you are providing feedback on
• drift – see cumulative weight changes from learning

drift

Weight and structural drift analysis. Compares the current graph state against a baseline (typically "last_session") to show what changed – new edges, removed edges, and weight drift. Useful for context recovery at session start.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "drift",
    "arguments": {
      "agent_id": "jimi",
      "since": "last_session",
      "include_weight_drift": true
    }
  }
}

Example Response

{
  "since": "last_session",
  "node_count_delta": 15,
  "edge_count_delta": 42,
  "new_nodes": ["file::forem_publisher.py", "file::forem_routes.py"],
  "removed_nodes": [],
  "top_weight_drifts": [
    { "edge": "session_pool.py -> worker_pool.py", "old": 0.45, "new": 0.72, "delta": 0.27 },
    { "edge": "chat_handler.py -> stream_parser.py", "old": 0.60, "new": 0.48, "delta": -0.12 }
  ],
  "elapsed_ms": 12.0
}

When to Use

• Session start – first tool to call after health to recover context
• After ingest – see what the new ingest changed
• After extended learning – track cumulative drift from feedback

Related Tools

• diverge – higher-level structural drift with anomaly detection
• health – basic server health (call before drift)

why

Path explanation between two nodes. Finds and explains the relationship paths connecting a source node to a target node. Returns all paths up to max_hops, ranked by cumulative edge strength.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "why",
    "arguments": {
      "agent_id": "jimi",
      "source": "file::worker_pool.py",
      "target": "file::whatsapp_manager.py",
      "max_hops": 4
    }
  }
}

Example Response

{
  "source": "file::worker_pool.py",
  "target": "file::whatsapp_manager.py",
  "paths": [
    {
      "nodes": ["worker_pool.py", "process_manager.py", "whatsapp_manager.py"],
      "relations": ["calls::cancel", "imports"],
      "cumulative_strength": 0.68,
      "hops": 2
    },
    {
      "nodes": ["worker_pool.py", "spawner.py", "chat_handler.py", "whatsapp_manager.py"],
      "relations": ["imported_by", "calls", "imports"],
      "cumulative_strength": 0.31,
      "hops": 3
    }
  ],
  "total_paths_found": 2,
  "elapsed_ms": 15.0
}

When to Use

• Understanding dependencies – “why are these two modules connected?”
• Tracing influence – find the relationship chain between distant modules
• Bug investigation – understand how a change in A could affect B

Related Tools

• hypothesize – tests a claim about the relationship (more powerful)
• impact – finds all affected nodes (broader scope)

trail_save

Persist the current investigation state – nodes visited, hypotheses formed, conclusions reached, and open questions. Captures activation boosts for later restoration.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "trail_save",
    "arguments": {
      "agent_id": "jimi",
      "label": "auth-leak-investigation",
      "hypotheses": [
        {
          "statement": "Auth tokens leak through session pool",
          "confidence": 0.7,
          "supporting_nodes": ["file::session_pool.py", "file::auth_discovery.py"]
        },
        {
          "statement": "Rate limiter missing from auth chain",
          "confidence": 0.9,
          "supporting_nodes": ["file::middleware.py"]
        }
      ],
      "open_questions": ["Does the rate limiter apply to WebSocket connections?"],
      "tags": ["security", "auth", "session"],
      "activation_boosts": {
        "file::session_pool.py": 0.8,
        "file::auth_discovery.py": 0.6
      }
    }
  }
}

Example Response

{
  "trail_id": "trail_jimi_001_a1b2c3",
  "label": "auth-leak-investigation",
  "agent_id": "jimi",
  "nodes_saved": 47,
  "hypotheses_saved": 2,
  "conclusions_saved": 0,
  "open_questions_saved": 1,
  "graph_generation_at_creation": 42,
  "created_at_ms": 1710300000000
}

When to Use

• End of investigation session – save your work before ending a session
• Before context compaction – checkpoint your investigation state
• Cross-session continuity – resume exactly where you left off

Related Tools

• trail_resume – restore a saved trail
• trail_list – find saved trails
• trail_merge – combine trails from parallel investigations

trail_resume

Restore a saved investigation. Re-injects activation boosts into the graph, validates that saved nodes still exist, detects staleness, and optionally downgrades hypotheses whose supporting nodes are missing.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "trail_resume",
    "arguments": {
      "agent_id": "jimi",
      "trail_id": "trail_jimi_001_a1b2c3"
    }
  }
}

Example Response

{
  "trail_id": "trail_jimi_001_a1b2c3",
  "label": "auth-leak-investigation",
  "stale": false,
  "generations_behind": 3,
  "missing_nodes": [],
  "nodes_reactivated": 47,
  "hypotheses_downgraded": [],
  "trail": {
    "trail_id": "trail_jimi_001_a1b2c3",
    "agent_id": "jimi",
    "label": "auth-leak-investigation",
    "status": "active",
    "created_at_ms": 1710300000000,
    "last_modified_ms": 1710300000000,
    "node_count": 47,
    "hypothesis_count": 2,
    "conclusion_count": 0,
    "open_question_count": 1,
    "tags": ["security", "auth", "session"],
    "summary": "Investigating auth token leaks through session pool"
  },
  "elapsed_ms": 22.5
}

When to Use

• Session start – restore a previous investigation
• Cross-agent handoff – agent B resumes agent A’s trail
• After re-ingest – check if investigation nodes survived the graph update

Related Tools

• trail_save – save a trail to resume later
• warmup – simpler priming without full trail restoration

trail_list

List saved investigation trails with optional filters. Returns compact summaries suitable for selecting a trail to resume.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "trail_list",
    "arguments": {
      "agent_id": "jimi",
      "filter_status": "saved",
      "filter_tags": ["security"]
    }
  }
}

Example Response

{
  "trails": [
    {
      "trail_id": "trail_jimi_001_a1b2c3",
      "agent_id": "jimi",
      "label": "auth-leak-investigation",
      "status": "saved",
      "created_at_ms": 1710300000000,
      "last_modified_ms": 1710300000000,
      "node_count": 47,
      "hypothesis_count": 2,
      "conclusion_count": 0,
      "open_question_count": 1,
      "tags": ["security", "auth", "session"]
    }
  ],
  "total_count": 1
}

When to Use

• Session start – see what investigations are available to resume
• Multi-agent coordination – see trails from other agents
• Cleanup – find stale or merged trails

Related Tools

• trail_resume – resume a trail from this list
• trail_merge – combine related trails

trail_merge

Combine two or more investigation trails. Merges visited nodes, hypotheses, and conclusions. Uses confidence+recency scoring for conflict resolution. Discovers cross-connections between independently explored areas.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "trail_merge",
    "arguments": {
      "agent_id": "jimi",
      "trail_ids": ["trail_jimi_001_a1b2c3", "trail_analyst_002_d4e5f6"],
      "label": "combined-auth-investigation"
    }
  }
}

Example Response

{
  "merged_trail_id": "trail_jimi_003_g7h8i9",
  "label": "combined-auth-investigation",
  "source_trails": ["trail_jimi_001_a1b2c3", "trail_analyst_002_d4e5f6"],
  "nodes_merged": 83,
  "hypotheses_merged": 5,
  "conflicts": [
    {
      "hypothesis_a": "Session pool leaks tokens",
      "hypothesis_b": "Session pool tokens are properly scoped",
      "resolution": "resolved",
      "winner": "Session pool leaks tokens",
      "score_delta": 0.35
    }
  ],
  "connections_discovered": [
    {
      "type": "bridge_edge",
      "detail": "auth_discovery.py connects the auth trail to the session trail",
      "from_node": "file::auth_discovery.py",
      "to_node": "file::session_pool.py",
      "weight": 0.72
    }
  ],
  "elapsed_ms": 45.0
}

Conflict Resolution

When merging hypotheses that contradict each other:

• confidence+recency scoring determines the winner
• If the score delta is too small, the conflict is marked "unresolved" for human review
• Source trails are set to "merged" status after a successful merge

When to Use

• Multi-agent investigation – combine findings from parallel agents
• Investigation continuation – merge an old investigation with new findings
• Consolidation – clean up related but separate investigation threads

Related Tools

• trail_save – save individual trails
• trail_list – find trails to merge

Exploration Tools

Six tools for intent-aware search, pattern-based scanning, structural hole detection, stacktrace analysis, temporal history, and multi-repository federation.

seek

Intent-aware semantic code search. Finds code by purpose, not text pattern. Combines keyword matching, graph activation (PageRank), and trigram similarity for ranking.

Unlike activate (which propagates signal through edges), seek scores every node independently against the query, making it better for finding specific code when you know what it does but not where it lives.

Parameters

Scoring Formula (V1)

combined = keyword_match * 0.6 + graph_activation * 0.3 + trigram * 0.1

V2 upgrade path will replace keyword matching with real embeddings (fastembed-rs + jina-embeddings-v2-base-code).

Example Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "seek",
    "arguments": {
      "agent_id": "jimi",
      "query": "code that validates user credentials",
      "top_k": 5,
      "node_types": ["function", "class"]
    }
  }
}

Example Response

{
  "query": "code that validates user credentials",
  "results": [
    {
      "node_id": "file::auth_discovery.py::fn::validate_credentials",
      "label": "validate_credentials",
      "type": "function",
      "score": 0.87,
      "score_breakdown": {
        "embedding_similarity": 0.92,
        "graph_activation": 0.78,
        "temporal_recency": 0.65
      },
      "intent_summary": "Validates user credentials against provider store",
      "file_path": "backend/auth_discovery.py",
      "line_start": 45,
      "line_end": 82,
      "connections": [
        { "node_id": "file::principal_registry.py", "label": "principal_registry.py", "relation": "calls" }
      ]
    }
  ],
  "total_candidates_scanned": 9767,
  "embeddings_used": false,
  "elapsed_ms": 25.0
}

When to Use

• “Find the code that does X” – when you know the purpose, not the filename
• Codebase onboarding – exploring unfamiliar code by intent
• Pre-modification search – find all code related to a feature before changing it

Related Tools

• activate – graph-propagation search (better for exploring neighborhoods)
• scan – pattern-based structural analysis (finds anti-patterns, not features)

scan

Pattern-aware structural code analysis with graph-validated findings. Detects structural issues using predefined patterns, then validates each finding against the graph to filter false positives. Works across file boundaries.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "scan",
    "arguments": {
      "agent_id": "jimi",
      "pattern": "error_handling",
      "scope": "backend/",
      "severity_min": 0.5
    }
  }
}

Example Response

{
  "pattern": "error_handling",
  "findings": [
    {
      "pattern": "error_handling",
      "status": "confirmed",
      "severity": 0.78,
      "node_id": "file::spawner.py::fn::spawn_agent",
      "label": "spawn_agent",
      "file_path": "backend/spawner.py",
      "line": 89,
      "message": "Bare except clause catches all exceptions including KeyboardInterrupt",
      "graph_context": [
        { "node_id": "file::process_manager.py", "label": "process_manager.py", "relation": "calls" }
      ]
    }
  ],
  "files_scanned": 77,
  "total_matches_raw": 23,
  "total_matches_validated": 8,
  "elapsed_ms": 150.0
}

Finding Status Values

When to Use

• Code quality audit – scan for anti-patterns across the codebase
• Security review – use "auth_boundary" to find auth bypass paths
• Pre-deploy check – scan for "error_handling" and "resource_cleanup" issues
• Test gaps – use "test_coverage" to find untested code

Related Tools

• hypothesize – test a specific structural claim
• trace – analyze a specific error (not patterns)

missing

Detect structural holes and missing connections. Given a topic query, finds areas where the graph suggests something should exist but does not. Identifies absent abstractions, missing connections, and incomplete patterns.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "missing",
    "arguments": {
      "agent_id": "jimi",
      "query": "database connection pooling",
      "min_sibling_activation": 0.3
    }
  }
}

Example Response

{
  "query": "database connection pooling",
  "holes": [
    {
      "node_id": "structural_hole_1",
      "label": "connection lifecycle",
      "type": "structural_hole",
      "reason": "No dedicated connection pool abstraction -- 4 adjacent modules manage connections independently"
    },
    {
      "node_id": "structural_hole_2",
      "label": "pool metrics",
      "type": "structural_hole",
      "reason": "No pool health monitoring -- 3 adjacent modules expose metrics but pool does not"
    }
  ],
  "total_holes": 9,
  "elapsed_ms": 67.0
}

When to Use

• Gap analysis – “what am I missing?” before implementing a feature
• Pre-spec – identify areas that need design before building
• Architecture review – find missing abstractions or connections
• Feature completeness – after building, check for structural holes around the feature

Related Tools

• activate – activate with include_structural_holes: true for inline hole detection
• hypothesize – test a specific claim about missing structure

trace

Map runtime errors to structural root causes via stacktrace analysis. Parses the stacktrace, maps frames to graph nodes, and scores each node’s suspiciousness using trace depth, modification recency, and centrality. Also finds co-change suspects (files modified around the same time as the top suspect).

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "trace",
    "arguments": {
      "agent_id": "jimi",
      "error_text": "Traceback (most recent call last):\n  File \"backend/chat_handler.py\", line 234, in handle_message\n  File \"backend/session_pool.py\", line 89, in acquire\n  File \"backend/worker_pool.py\", line 156, in submit\nTimeoutError: pool exhausted",
      "language": "python",
      "top_k": 5
    }
  }
}

Example Response

{
  "language_detected": "python",
  "error_type": "TimeoutError",
  "error_message": "pool exhausted",
  "frames_parsed": 3,
  "frames_mapped": 3,
  "suspects": [
    {
      "node_id": "file::worker_pool.py::fn::submit",
      "label": "submit",
      "type": "function",
      "suspiciousness": 0.91,
      "signals": { "trace_depth_score": 1.0, "recency_score": 0.85, "centrality_score": 0.88 },
      "file_path": "backend/worker_pool.py",
      "line_start": 150,
      "line_end": 175,
      "related_callers": ["session_pool.py::acquire"]
    },
    {
      "node_id": "file::session_pool.py::fn::acquire",
      "label": "acquire",
      "type": "function",
      "suspiciousness": 0.78,
      "signals": { "trace_depth_score": 0.67, "recency_score": 0.72, "centrality_score": 0.65 },
      "file_path": "backend/session_pool.py",
      "line_start": 80,
      "line_end": 110,
      "related_callers": ["chat_handler.py::handle_message"]
    }
  ],
  "co_change_suspects": [
    { "node_id": "file::config.py", "label": "config.py", "modified_at": 1710295000.0, "reason": "Modified within 2h of top suspect" }
  ],
  "causal_chain": ["worker_pool.py::submit", "session_pool.py::acquire", "chat_handler.py::handle_message"],
  "fix_scope": {
    "files_to_inspect": ["backend/worker_pool.py", "backend/session_pool.py", "backend/config.py"],
    "estimated_blast_radius": 23,
    "risk_level": "medium"
  },
  "unmapped_frames": [],
  "elapsed_ms": 3.5
}

Suspiciousness Scoring

When to Use

• Bug investigation – paste an error and get ranked suspects
• Root cause analysis – the causal chain shows the error propagation path
• Fix scoping – fix_scope tells you which files to inspect and the risk level

Related Tools

• hypothesize – test a hypothesis about the root cause
• impact – assess the blast radius of a fix
• validate_plan – validate your fix plan before implementing

timeline

Git-based temporal history for a node. Returns the change history, co-change partners, velocity, stability score, and churn data for a specific file or module.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "timeline",
    "arguments": {
      "agent_id": "jimi",
      "node": "file::backend/chat_handler.py",
      "depth": "30d",
      "top_k": 5
    }
  }
}

Example Response

{
  "node": "file::backend/chat_handler.py",
  "depth": "30d",
  "changes": [
    {
      "date": "2026-03-10",
      "commit": "a1b2c3d",
      "author": "cosmophonix",
      "delta": "+45/-12",
      "co_changed": ["stream_parser.py", "chat_routes.py"]
    },
    {
      "date": "2026-03-05",
      "commit": "e4f5g6h",
      "author": "cosmophonix",
      "delta": "+120/-30",
      "co_changed": ["session_pool.py", "worker_pool.py"]
    }
  ],
  "co_changed_with": [
    { "file": "stream_parser.py", "times": 8, "coupling_degree": 0.72 },
    { "file": "chat_routes.py", "times": 6, "coupling_degree": 0.55 },
    { "file": "session_pool.py", "times": 4, "coupling_degree": 0.38 }
  ],
  "velocity": "accelerating",
  "stability_score": 0.35,
  "pattern": "churning",
  "total_churn": { "lines_added": 580, "lines_deleted": 120 },
  "commit_count_in_window": 12,
  "elapsed_ms": 45.0
}

Velocity Values

Pattern Values

When to Use

• Hotspot detection – find files that change too frequently (stability_score < 0.3)
• Co-change discovery – find files that always change together (coupling_degree > 0.6)
• Refactoring signals – churning files may need redesign

Related Tools

• diverge – structural drift across the whole codebase
• predict – predict co-changes for a given modification

federate

Ingest multiple repositories into a unified federated graph with automatic cross-repo edge detection. After federation, all existing query tools (activate, impact, why, etc.) traverse cross-repo edges automatically.

Node IDs in the federated graph use {repo_name}::file::path format.

Parameters

Cross-Repo Edge Types

Example Request

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "federate",
    "arguments": {
      "agent_id": "jimi",
      "repos": [
        { "name": "backend", "path": "/project/backend" },
        { "name": "frontend", "path": "/project/frontend" },
        { "name": "mcp-server", "path": "/project/mcp-server", "adapter": "code" }
      ],
      "detect_cross_repo_edges": true,
      "incremental": false
    }
  }
}

Example Response

{
  "repos_ingested": [
    { "name": "backend", "path": "/project/backend", "node_count": 9767, "edge_count": 26557, "from_cache": false, "ingest_ms": 910.0 },
    { "name": "frontend", "path": "/project/frontend", "node_count": 1200, "edge_count": 3500, "from_cache": false, "ingest_ms": 320.0 },
    { "name": "mcp-server", "path": "/project/mcp-server", "node_count": 250, "edge_count": 680, "from_cache": false, "ingest_ms": 85.0 }
  ],
  "total_nodes": 11217,
  "total_edges": 30737,
  "cross_repo_edges": [
    {
      "source_repo": "frontend",
      "target_repo": "backend",
      "source_node": "frontend::file::src/lib/apiConfig.ts",
      "target_node": "backend::file::main.py",
      "edge_type": "api_contract",
      "relation": "calls_api",
      "weight": 0.85,
      "causal_strength": 0.72
    },
    {
      "source_repo": "mcp-server",
      "target_repo": "backend",
      "source_node": "mcp-server::file::src/mcp-server.js",
      "target_node": "backend::file::main.py",
      "edge_type": "mcp_contract",
      "relation": "calls_api",
      "weight": 0.78,
      "causal_strength": 0.65
    }
  ],
  "cross_repo_edge_count": 18203,
  "incremental": false,
  "skipped_repos": [],
  "elapsed_ms": 1315.0
}

When to Use

• Multi-repo projects – analyze dependencies across frontend, backend, and infrastructure repos
• Monorepo decomposition – understand how packages depend on each other
• API impact analysis – find which repos are affected by an API change

Related Tools

• ingest – single-repo ingestion
• impact – blast radius analysis (works across federated repos)
• why – path explanation (traverses cross-repo edges)

federate_auto

Turn explicit external path evidence, local manifest/workspace hints, import/package-name evidence, shared API-route signals, or contract artifacts such as .proto, MCP tools, and OpenAPI into repo candidates, namespace suggestions, and an optional one-shot federate call.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "federate_auto",
    "arguments": {
      "agent_id": "jimi",
      "scope": "docs",
      "execute": false
    }
  }
}

Example Response

{
  "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
}

When to Use

• Cross-repo audits – when audit or external_references already surfaced sibling repo paths
• Manifest-driven workspaces – when Cargo.toml, package.json, pnpm-workspace.yaml, pyproject.toml, or go.work already point at sibling repos
• Import-driven discovery – when code already imports a sibling package/crate name but the current repo has no explicit path hint
• Contract-driven discovery – when nearby repos expose .proto or MCP tool contracts that the current workspace already references by name
• OpenAPI-driven discovery – when the current workspace references operationIds or routes defined in a nearby OpenAPI/Swagger spec
• Schema-driven discovery – when the current workspace references message/component names defined in .proto or OpenAPI schemas
• Planning/doc hubs – when docs point to runtime repos and you want a namespace plan without manual copy-paste
• Worktree-heavy setups – when the current workspace path is a worktree but you still want repo-shaped namespace suggestions

Related Tools

• external_references – raw external path evidence
• federate – explicit multi-repo federation
• audit – broader audit that can surface the evidence before auto-federation

batch_view

Read multiple files or glob-resolved files in one call with stable delimiters, optional summaries, and optional auto-ingest.

Parameters

When to Use

• Audit proof packets
• Compact multi-file reading after search/glob
• Agent handoff packages

Related Tools

• glob
• coverage_session
• audit

scan_all

Run all structural scan patterns in one call and return grouped findings by pattern.

Parameters

When to Use

• Broad first-pass quality/security audit
• Pre-hardening sweep before prioritizing fixes

Related Tools

• scan
• batch_view
• audit

cross_verify

Compare graph state against filesystem truth: existence, LOC drift, and optional hash mismatches.

Parameters

When to Use

• To verify graph and disk still agree
• After daemon drift alerts
• Before trusting an audit result on a changing repo

Related Tools

• audit
• external_references

coverage_session

Report what the current agent session has already read or touched.

Parameters

When to Use

• To avoid re-reading files during long sessions
• To build a compact unread-next list after search/audit sweeps

Related Tools

• batch_view
• search

external_references

Find explicit path references that point outside current ingest roots.

Parameters

When to Use

• Before federation when docs/config already point outside the repo
• To surface repo-boundary evidence in audits

Related Tools

• federate_auto
• audit

glob

Graph-aware file globbing over already indexed files.

Parameters

When to Use

• When you need filenames by pattern, not content
• Before batch_view on a file family

Related Tools

• search
• batch_view

view

Fast line-numbered file inspection with optional auto-ingest if the file is not yet in the graph.

Parameters

When to Use

• Quick inspection when you already know the file
• Narrow, bounded reads before a surgical context call

Related Tools

• batch_view
• surgical_context

Perspective Tools

Twelve tools for stateful, navigable exploration of the code graph. Perspectives are m1nd’s primary interface for guided codebase exploration – they synthesize routes (weighted navigation suggestions) from a query, then let you follow, inspect, branch, and compare routes.

Core Concepts

Perspective: A stateful exploration session. Created from a query, it synthesizes a set of routes from the current graph state. The agent navigates by following routes, which moves the focus and generates new routes.

Route: A suggested direction of exploration. Each route points to a target node and carries a score, a family classification, and a path preview.

Focus: The current node the perspective is centered on. Following a route moves the focus. back restores the previous focus.

Mode: Either "anchored" (routes stay related to an anchor node) or "local" (routes synthesized purely from the current focus). Anchored mode degrades to local if navigation moves more than 8 hops from the anchor.

Route Set Version: A version counter for the current route set. Clients must pass this in subsequent calls for staleness detection. If the graph changes between calls, the version changes and stale requests are rejected.

Lens: Optional filtering configuration for perspectives (dimension weights, node type filters, etc.).

perspective_start

Enter a perspective: creates a navigable route surface from a query. Returns the initial set of routes.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "perspective_start",
    "arguments": {
      "agent_id": "jimi",
      "query": "session management and connection pooling",
      "anchor_node": "file::session_pool.py"
    }
  }
}

Example Response

{
  "perspective_id": "persp_jimi_001",
  "mode": "anchored",
  "anchor_node": "file::session_pool.py",
  "focus_node": "file::session_pool.py",
  "routes": [
    {
      "route_id": "R_a1b2c3",
      "index": 1,
      "target_node": "file::worker_pool.py",
      "target_label": "worker_pool.py",
      "family": "structural_neighbor",
      "score": 0.89,
      "path_preview": ["session_pool.py", "worker_pool.py"],
      "reason": "High structural coupling with anchor"
    },
    {
      "route_id": "R_d4e5f6",
      "index": 2,
      "target_node": "file::process_manager.py",
      "target_label": "process_manager.py",
      "family": "causal_downstream",
      "score": 0.76,
      "path_preview": ["session_pool.py", "process_manager.py"],
      "reason": "Causal dependency via imports"
    }
  ],
  "total_routes": 12,
  "page": 1,
  "total_pages": 2,
  "route_set_version": 100,
  "cache_generation": 42,
  "suggested": "inspect R_a1b2c3 for structural details"
}

When to Use

• Guided exploration – when you want to explore a topic interactively
• Codebase navigation – start from a known file and discover related code
• Investigation – anchor to a suspicious file and follow routes to find related issues

Related Tools

• activate – one-shot query without navigation state
• perspective_routes – paginate through routes
• perspective_follow – follow a route to navigate

perspective_routes

Browse the current route set with pagination.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "perspective_routes",
    "arguments": {
      "agent_id": "jimi",
      "perspective_id": "persp_jimi_001",
      "page": 2,
      "page_size": 6,
      "route_set_version": 100
    }
  }
}

Example Response

{
  "perspective_id": "persp_jimi_001",
  "mode": "anchored",
  "mode_effective": "anchored",
  "anchor": "file::session_pool.py",
  "focus": "file::session_pool.py",
  "lens_summary": "all dimensions, no type filter",
  "page": 2,
  "total_pages": 2,
  "total_routes": 12,
  "route_set_version": 100,
  "cache_generation": 42,
  "routes": [
    {
      "route_id": "R_g7h8i9",
      "index": 7,
      "target_node": "file::config.py",
      "target_label": "config.py",
      "family": "configuration",
      "score": 0.42,
      "path_preview": ["session_pool.py", "config.py"],
      "reason": "Shared configuration key"
    }
  ],
  "suggested": null,
  "page_size_clamped": false
}

When to Use

• Pagination – browse all available routes when the first page was not enough
• Full route survey – see the complete landscape before deciding which route to follow

Related Tools

• perspective_inspect – expand a specific route for detail
• perspective_follow – follow a route to navigate

perspective_inspect

Expand a route with fuller path, metrics, provenance, affinity candidates, and score breakdown. Does not change the perspective state – purely informational.

Specify the route by either route_id (stable, content-addressed) or route_index (1-based position on the current page). Exactly one must be provided.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "perspective_inspect",
    "arguments": {
      "agent_id": "jimi",
      "perspective_id": "persp_jimi_001",
      "route_id": "R_a1b2c3",
      "route_set_version": 100
    }
  }
}

Example Response

{
  "route_id": "R_a1b2c3",
  "route_index": 1,
  "family": "structural_neighbor",
  "target_node": "file::worker_pool.py",
  "target_label": "worker_pool.py",
  "target_type": "file",
  "path_preview": ["session_pool.py", "spawner.py", "worker_pool.py"],
  "family_explanation": "Direct structural neighbor via import chain",
  "score": 0.89,
  "score_breakdown": {
    "local_activation": 0.92,
    "path_coherence": 0.88,
    "novelty": 0.75,
    "anchor_relevance": 0.95,
    "continuity": 0.82
  },
  "provenance": {
    "source_path": "backend/worker_pool.py",
    "line_start": 1,
    "line_end": 312,
    "namespace": null,
    "provenance_stale": false
  },
  "peek_available": true,
  "affinity_candidates": [
    { "node_id": "file::fast_pool.py", "label": "fast_pool.py", "strength": 0.72, "reason": "Similar pool pattern" }
  ],
  "response_chars": 450
}

When to Use

• Before following – understand what a route leads to before committing
• Score analysis – see why a route was ranked high or low
• Provenance check – verify the source file exists and is not stale

Related Tools

• perspective_peek – extract actual code content
• perspective_follow – navigate to the route target
• perspective_affinity – deeper affinity analysis

perspective_peek

Extract a small relevant code or documentation slice from a route’s target node. Reads the actual source file and returns the relevant excerpt. Security-checked: only reads files within the ingested graph scope.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "perspective_peek",
    "arguments": {
      "agent_id": "jimi",
      "perspective_id": "persp_jimi_001",
      "route_index": 1,
      "route_set_version": 100
    }
  }
}

Example Response

{
  "route_id": "R_a1b2c3",
  "route_index": 1,
  "target_node": "file::worker_pool.py",
  "content": {
    "excerpt": "class WorkerPool:\n    \"\"\"Manages a pool of CLI subprocess workers.\"\"\"\n    def __init__(self, max_workers=8):\n        self.pool = {}\n        self.max_workers = max_workers\n        ...",
    "file_path": "backend/worker_pool.py",
    "line_start": 15,
    "line_end": 45,
    "truncated": true
  }
}

When to Use

• Quick preview – see the actual code at a route target without leaving m1nd
• Decision making – peek at code to decide whether to follow a route
• Investigation – read suspicious code without opening a file

Related Tools

• perspective_inspect – structural information about the route (no code content)
• perspective_follow – navigate to the route target

perspective_follow

Follow a route: move focus to the target node and synthesize new routes from the new position. This is the primary navigation action in a perspective. Updates the navigation history for back.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "perspective_follow",
    "arguments": {
      "agent_id": "jimi",
      "perspective_id": "persp_jimi_001",
      "route_id": "R_a1b2c3",
      "route_set_version": 100
    }
  }
}

Example Response

{
  "perspective_id": "persp_jimi_001",
  "previous_focus": "file::session_pool.py",
  "new_focus": "file::worker_pool.py",
  "mode": "anchored",
  "mode_effective": "anchored",
  "routes": [
    {
      "route_id": "R_j1k2l3",
      "index": 1,
      "target_node": "file::process_manager.py",
      "target_label": "process_manager.py",
      "family": "causal_downstream",
      "score": 0.85,
      "path_preview": ["worker_pool.py", "process_manager.py"],
      "reason": "Direct caller of worker pool submit"
    },
    {
      "route_id": "R_m4n5o6",
      "index": 2,
      "target_node": "file::spawner.py",
      "target_label": "spawner.py",
      "family": "structural_neighbor",
      "score": 0.71,
      "path_preview": ["worker_pool.py", "spawner.py"],
      "reason": "Co-manages subprocess lifecycle"
    }
  ],
  "total_routes": 8,
  "page": 1,
  "total_pages": 2,
  "route_set_version": 101,
  "cache_generation": 42,
  "suggested": "inspect R_j1k2l3 -- high causal relevance"
}

When to Use

• Navigation – this is the primary way to move through the graph
• Guided exploration – follow high-scoring routes to discover related code
• Investigation – follow causal chains to trace a bug

Related Tools

• perspective_back – undo a follow
• perspective_branch – fork before following to explore alternatives

perspective_suggest

Get the next best move suggestion based on navigation history. Analyzes the routes, the current focus, and the history of followed routes to recommend what to do next.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "perspective_suggest",
    "arguments": {
      "agent_id": "jimi",
      "perspective_id": "persp_jimi_001",
      "route_set_version": 101
    }
  }
}

Example Response

{
  "perspective_id": "persp_jimi_001",
  "suggestion": {
    "action": "follow",
    "route_id": "R_j1k2l3",
    "reason": "High-scoring causal route not yet explored. process_manager.py is a hub node connecting to 47 downstream modules.",
    "confidence": 0.82
  }
}

When to Use

• Undecided – when you are not sure which route to follow
• Systematic exploration – let m1nd guide you through the most informative path
• Investigation – follow the suggestion trail to efficient root cause discovery

Related Tools

• perspective_follow – follow the suggested route
• perspective_inspect – inspect the suggested route first

perspective_affinity

Discover probable connections a route target might have. Returns affinity candidates – nodes that are not directly connected to the target but show structural affinity (similar neighborhoods, shared patterns).

Epistemic notice: these are probable connections, not verified graph edges.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "perspective_affinity",
    "arguments": {
      "agent_id": "jimi",
      "perspective_id": "persp_jimi_001",
      "route_id": "R_j1k2l3",
      "route_set_version": 101
    }
  }
}

Example Response

{
  "route_id": "R_j1k2l3",
  "target_node": "file::process_manager.py",
  "notice": "Probable connections, not verified edges.",
  "candidates": [
    { "node_id": "file::healing_manager.py", "label": "healing_manager.py", "strength": 0.68, "reason": "Similar lifecycle management pattern" },
    { "node_id": "file::autonomous_daemon.py", "label": "autonomous_daemon.py", "strength": 0.52, "reason": "Shared subprocess management trait" }
  ]
}

When to Use

• Discovery – find non-obvious connections that the graph does not yet have
• Architecture analysis – identify modules that should be connected but are not
• Ghost edge validation – affinity candidates often become confirmed edges after investigation

Related Tools

• missing – finds structural holes (broader scope)
• perspective_inspect – affinity candidates are also included in inspect output

perspective_branch

Fork the current navigation state into a new perspective branch. The branch starts at the same focus with the same route set, but future navigation in the branch is independent. Useful for exploring alternatives without losing your place.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "perspective_branch",
    "arguments": {
      "agent_id": "jimi",
      "perspective_id": "persp_jimi_001",
      "branch_name": "auth-path"
    }
  }
}

Example Response

{
  "perspective_id": "persp_jimi_001",
  "branch_perspective_id": "persp_jimi_002",
  "branch_name": "auth-path",
  "branched_from_focus": "file::worker_pool.py"
}

When to Use

• Alternative exploration – explore two different paths from the same point
• Comparative analysis – branch, follow different routes, then compare
• Safe investigation – branch before following a risky route

Related Tools

• perspective_compare – compare the branch with the original
• perspective_follow – navigate within the branch

perspective_back

Navigate back to the previous focus, restoring the checkpoint state. Like browser back navigation. Pops the latest navigation event from the history stack.

Parameters

Example Request

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "perspective_back",
    "arguments": {
      "agent_id": "jimi",
      "perspective_id": "persp_jimi_001"
    }
  }
}

Example Response

{
  "perspective_id": "persp_jimi_001",
  "restored_focus": "file::session_pool.py",
  "restored_mode": "anchored",
  "routes": [
    {
      "route_id": "R_a1b2c3",
      "index": 1,
      "target_node": "file::worker_pool.py",
      "target_label": "worker_pool.py",
      "family": "structural_neighbor",
      "score": 0.89,
      "path_preview": ["session_pool.py", "worker_pool.py"],
      "reason": "High structural coupling with anchor"
    }
  ],
  "total_routes": 12,
  "page": 1,
  "total_pages": 2,
  "route_set_version": 102,
  "cache_generation": 42
}

When to Use

• Undo navigation – go back after following a wrong route
• Breadth-first exploration – follow a route, come back, follow another

Related Tools

• perspective_follow – the forward navigation that back undoes
• perspective_branch – alternative: branch instead of back+follow

perspective_compare

Compare two perspectives on shared/unique nodes and dimension deltas. Both perspectives must belong to the same agent (V1 restriction).

Parameters