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

relevance  = max(embedding_similarity, keyword_match, trigram)
base_score = keyword_match * 0.4
           + embedding_similarity * 0.3
           + graph_activation * activation_gate(relevance) * 0.2
           + trigram * 0.1
           + path/anchor biases
combined   = (base_score + conformance_boost).max(0.0) * (trust_factor * tremor_factor)

embedding_similarity is the query↔node cosine (static local embeddings; falls back to the trigram TF-IDF signal when embeddings are unavailable). graph_activation is normalized PageRank.

Centrality is gated by relevance. The graph_activation term is scaled by an activation_gate that ramps with the node’s own relevance: a clearly on-topic node keeps its full centrality weight, while a near-zero-relevance node keeps only a small floor of it. This stops a high-PageRank but semantically-irrelevant hub from riding pure centrality to the top and drowning the real targets — centrality remains a full-strength co-ranker and tie-breaker, it just no longer acts alone.

The combined base is then damped multiplicatively by trust × tremor heuristics before ranking.

Conformance composes as an additive term (X-RAY steers attention). When an X-RAY manifesto resolves for the workspace and conformance_aware is on (the default), each node’s grammar-4 state adds a separate conformance_boost to base_score before the trust × tremor damping: a BEDROCK node (proven/grounded) gets +0.20, an EROSION source (a layer/forbid-violating cross-module source) gets −0.30, and everything else is neutral (0.0). Because the term is additive, conformance can raise a proven node’s attention, not only damp a suspect one — and because it composes with (rather than replaces) relevance and the multiplicative damping, no single term dominates: a BEDROCK but semantically-irrelevant node still cannot ride the boost above genuinely relevant results. Conformance only re-orders within the relevance-cleared pool; it never drops a node. With no manifesto or with conformance_aware=false, every boost is 0.0 and ranking is byte-identical to the base formula above. focus rides the same rerank, so it is conformance-aware too.

Example Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "seek",
    "arguments": {
      "agent_id": "agent-1",
      "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": "agent-1",
      "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": "agent-1",
      "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": "agent-1",
      "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": "agent-1",
      "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": "dev",
      "delta": "+45/-12",
      "co_changed": ["stream_parser.py", "chat_routes.py"]
    },
    {
      "date": "2026-03-05",
      "commit": "e4f5g6h",
      "author": "dev",
      "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": "agent-1",
      "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": "agent-1",
      "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