Shared memory and context tools for agentic work.
Code Rooms
# Exploration Tools
Six tools for intent-aware search, pattern-based scanning, structural hole detection, stacktrace analysis, temporal history, and multi-repository federation.
---
<a id="m1ndseek"></a>
## `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
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `query` | `string` | Yes | -- | Natural language description of what the agent is looking for. Example: `"code that validates user credentials"`. |
| `agent_id` | `string` | Yes | -- | Calling agent identifier. |
| `top_k` | `integer` | No | `20` | Maximum results to return. |
| `scope` | `string` | No | -- | File path prefix to limit search scope. Example: `"backend/"`. `None` = entire graph. |
| `node_types` | `string[]` | No | `[]` | Filter by node type: `"function"`, `"class"`, `"struct"`, `"module"`, `"file"`. Empty = all types. |
| `min_score` | `number` | No | `0.1` | Minimum combined score threshold. Range: 0.0 to 1.0. |
| `graph_rerank` | `boolean` | No | `true` | Whether to run graph re-ranking (PageRank weighting) on candidates. Disable for pure text matching. |
### 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
```json
{
"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
"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`](activation.md#m1ndactivate) -- graph-propagation search (better for exploring neighborhoods)
- [`scan`](#m1ndscan) -- pattern-based structural analysis (finds anti-patterns, not features)
<a id="m1ndscan"></a>
## `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.
| `pattern` | `string` | Yes | -- | Pattern ID or custom pattern string. Built-in patterns: `"error_handling"`, `"resource_cleanup"`, `"api_surface"`, `"state_mutation"`, `"concurrency"`, `"auth_boundary"`, `"test_coverage"`, `"dependency_injection"`. |
| `scope` | `string` | No | -- | File path prefix to limit scan scope. |
| `severity_min` | `number` | No | `0.3` | Minimum severity threshold. Range: 0.0 to 1.0. |
| `graph_validate` | `boolean` | No | `true` | Validate findings against graph edges (cross-file analysis). Disable for raw pattern matching only. |
| `limit` | `integer` | No | `50` | Maximum findings to return. |
"id": 2,
"name": "scan",
"pattern": "error_handling",
"scope": "backend/",
"severity_min": 0.5
"findings": [
"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
| Status | Meaning |
|--------|---------|
| `"confirmed"` | Graph validation confirms the issue is real |
| `"mitigated"` | The issue exists but is handled by a related module |
| `"false_positive"` | Graph context shows the pattern match is not actually an issue |
- **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
- [`hypothesize`](analysis.md#m1ndhypothesize) -- test a specific structural claim
- [`trace`](#m1ndtrace) -- analyze a specific error (not patterns)
<a id="m1ndmissing"></a>
## `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.
| `query` | `string` | Yes | -- | Search query to find structural holes around. |
| `min_sibling_activation` | `number` | No | `0.3` | Minimum sibling activation threshold. Siblings with activation below this are not considered for hole detection. |
"id": 3,
"name": "missing",
"query": "database connection pooling",
"min_sibling_activation": 0.3
"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",
"reason": "No pool health monitoring -- 3 adjacent modules expose metrics but pool does not"
"total_holes": 9,
"elapsed_ms": 67.0
- **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
- [`activate`](activation.md#m1ndactivate) -- activate with `include_structural_holes: true` for inline hole detection
- [`hypothesize`](analysis.md#m1ndhypothesize) -- test a specific claim about missing structure
<a id="m1ndtrace"></a>
## `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).
| `error_text` | `string` | Yes | -- | Full error output (stacktrace + error message). |
| `language` | `string` | No | -- | Language hint: `"python"`, `"rust"`, `"typescript"`, `"javascript"`, `"go"`. Auto-detected if omitted. |
| `window_hours` | `number` | No | `24.0` | Temporal window (hours) for co-change suspect scan. |
| `top_k` | `integer` | No | `10` | Max suspects to return. |
"id": 4,
"name": "trace",
"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
"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",
"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",
"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
| Signal | Weight | Description |
|--------|--------|-------------|
| `trace_depth_score` | High | 1.0 = deepest frame (most specific); decays linearly |
| `recency_score` | Medium | Exponential decay from last modification time |
| `centrality_score` | Medium | Normalized PageRank centrality |
- **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
- [`hypothesize`](analysis.md#m1ndhypothesize) -- test a hypothesis about the root cause
- [`impact`](analysis.md#m1ndimpact) -- assess the blast radius of a fix
- [`validate_plan`](lifecycle.md#m1ndvalidate_plan) -- validate your fix plan before implementing
<a id="m1ndtimeline"></a>
## `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.
| `node` | `string` | Yes | -- | Node external_id. Example: `"file::backend/chat_handler.py"`. |
| `depth` | `string` | No | `"30d"` | Time depth. Values: `"7d"`, `"30d"`, `"90d"`, `"all"`. |
| `include_co_changes` | `boolean` | No | `true` | Include co-changed files with coupling scores. |
| `include_churn` | `boolean` | No | `true` | Include lines added/deleted churn data. |
| `top_k` | `integer` | No | `10` | Max co-change partners to return. |
"id": 5,
"name": "timeline",
"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",
"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
| Value | Meaning |
|-------|---------|
| `"accelerating"` | Change frequency is increasing |
| `"decelerating"` | Change frequency is decreasing |
| `"stable"` | Consistent change rate |
### Pattern Values
| `"expanding"` | Growing (net positive churn) |
| `"shrinking"` | Reducing (net negative churn) |
| `"churning"` | High add+delete with little net growth |
| `"dormant"` | Few or no changes in the window |
| `"stable"` | Small, consistent changes |
- **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
- [`diverge`](analysis.md#m1nddiverge) -- structural drift across the whole codebase
- [`predict`](analysis.md#m1ndpredict) -- predict co-changes for a given modification
<a id="m1ndfederate"></a>
## `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.
| `repos` | `object[]` | Yes | -- | List of repositories to federate. Each object has: `name` (string, required -- namespace prefix), `path` (string, required -- absolute path), `adapter` (string, default `"code"`). |
| `detect_cross_repo_edges` | `boolean` | No | `true` | Auto-detect cross-repo edges: config, API, import, type, deployment, MCP contract. |
| `incremental` | `boolean` | No | `false` | Only re-ingest repos that changed since last federation. |
### Cross-Repo Edge Types
| Edge Type | Description |
|-----------|-------------|
| `shared_config` | Two repos reference the same configuration key |
| `api_contract` | One repo's API client matches another's API server |
| `package_dep` | Direct package dependency |
| `shared_type` | Same type/interface definition used across repos |
| `deployment_dep` | Deployment configuration dependency |
| `mcp_contract` | MCP tool consumer/provider relationship |
"id": 6,
"name": "federate",
"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
"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",
"source_node": "mcp-server::file::src/mcp-server.js",
"edge_type": "mcp_contract",
"weight": 0.78,
"causal_strength": 0.65
"cross_repo_edge_count": 18203,
"incremental": false,
"skipped_repos": [],
"elapsed_ms": 1315.0
- **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
- [`ingest`](lifecycle.md#m1ndingest) -- single-repo ingestion
- [`impact`](analysis.md#m1ndimpact) -- blast radius analysis (works across federated repos)
- [`why`](memory.md#m1ndwhy) -- path explanation (traverses cross-repo edges)
<a id="m1ndfederate_auto"></a>
## `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.
| `scope` | `string` | No | -- | File path prefix to limit discovery sources. |
| `current_repo_name` | `string` | No | auto | Optional namespace override for the current workspace. |
| `max_repos` | `integer` | No | `8` | Maximum discovered external repos to include. |
| `detect_cross_repo_edges` | `boolean` | No | `true` | Whether `execute=true` should auto-detect cross-repo edges. |
| `execute` | `boolean` | No | `false` | If true, immediately run `federate` with the current repo plus discovered candidates. |
"id": 7,
"name": "federate_auto",
"scope": "docs",
"execute": false
"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
- **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 `operationId`s 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
- [`external_references`](overview.md) -- raw external path evidence
- [`federate`](#m1ndfederate) -- explicit multi-repo federation
- [`audit`](overview.md) -- broader audit that can surface the evidence before auto-federation
<a id="m1ndbatch_view"></a>
## `batch_view`
Read multiple files or glob-resolved files in one call with stable delimiters, optional summaries, and optional auto-ingest.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | `string` | Yes | Calling agent identifier. |
| `files` | `string[]` | Yes | File paths and/or glob patterns to expand. |
| `auto_ingest` | `boolean` | No | Auto-ingest discovered files before reading. |
| `summary_mode` | `boolean` | No | Add inline per-file summaries. |
- Audit proof packets
- Compact multi-file reading after search/glob
- Agent handoff packages
- [`glob`](#m1ndglob)
- [`coverage_session`](#m1ndcoverage_session)
- [`audit`](../api-reference/lifecycle.md#m1ndaudit)
<a id="m1ndscan_all"></a>
## `scan_all`
Run all structural scan patterns in one call and return grouped findings by pattern.
| `scope` | `string` | No | Scope path prefix. |
| `patterns` | `string[]` | No | Subset of scan patterns to run. |
| `limit_per_pattern` | `integer` | No | Maximum findings per pattern. |
- Broad first-pass quality/security audit
- Pre-hardening sweep before prioritizing fixes
- [`scan`](#m1ndscan)
- [`batch_view`](#m1ndbatch_view)
<a id="m1ndcross_verify"></a>
## `cross_verify`
Compare graph state against filesystem truth: existence, LOC drift, and optional hash mismatches.
| `scope` | `string` | No | Path prefix to limit verification. |
| `check` | `string[]` | No | Checks to run such as `existence`, `loc`, `hash`. |
| `include_dotfiles` | `boolean` | No | Include selected dotfiles in verification. |
- To verify graph and disk still agree
- After daemon drift alerts
- Before trusting an audit result on a changing repo
- [`external_references`](#m1ndexternal_references)
<a id="m1ndcoverage_session"></a>
## `coverage_session`
Report what the current agent session has already read or touched.
- To avoid re-reading files during long sessions
- To build a compact unread-next list after search/audit sweeps
- [`search`](../api-reference/lifecycle.md#m1ndsearch)
<a id="m1ndexternal_references"></a>
## `external_references`
Find explicit path references that point outside current ingest roots.
| `scope` | `string` | No | Optional scope prefix. |
- Before federation when docs/config already point outside the repo
- To surface repo-boundary evidence in audits
- [`federate_auto`](#m1ndfederate_auto)
<a id="m1ndglob"></a>
## `glob`
Graph-aware file globbing over already indexed files.
| `pattern` | `string` | Yes | Glob pattern. |
| `scope` | `string` | No | Optional path prefix. |
| `sort` | `string` | No | Sort order such as `path` or `activation`. |
- When you need filenames by pattern, not content
- Before `batch_view` on a file family
<a id="m1ndview"></a>
## `view`
Fast line-numbered file inspection with optional auto-ingest if the file is not yet in the graph.
| `file_path` | `string` | Yes | Absolute or workspace-relative file path. |
| `auto_ingest` | `boolean` | No | Auto-ingest file into the graph if not present. |
| `offset` | `integer` | No | Start line offset. |
| `limit` | `integer` | No | Max lines to return. |
- Quick inspection when you already know the file
- Narrow, bounded reads before a surgical context call
- [`surgical_context`](../api-reference/lifecycle.md#m1ndsurgical_context)
