# Frequently Asked Questions

## General

### What is m1nd?

m1nd is a local MCP runtime for coding agents. It turns repos, docs, history, and runtime-adjacent signals into a graph-backed operational model and exposes that model through MCP for structure, impact, connected context, continuity, audit, document grounding, and edit preparation. Built in Rust, it runs locally and works with any MCP-compatible client.

The current differentiator is not just that the graph learns. The runtime also exposes guidance surfaces such as `proof_state`, `next_suggested_tool`, `next_suggested_target`, and `next_step_hint`, plus observable progress for long-running writes like `apply_batch`.

### How is m1nd different from grep / ripgrep?

Grep finds *text*. m1nd finds *structure and relationships*.

Grep tells you which files contain the word "authentication". m1nd tells you which modules are structurally connected to authentication, which ones are likely co-changed when auth changes, which hidden dependencies exist between auth and seemingly unrelated modules, and what would break if you removed the auth module.

Grep is fast and essential. m1nd answers questions that grep cannot even formulate.

### How is m1nd different from RAG?

RAG (Retrieval-Augmented Generation) embeds code chunks into vectors and retrieves the top-K most similar chunks for each query. Each retrieval is independent -- RAG has no memory of previous queries and no understanding of relationships between results.

m1nd maintains a persistent graph where relationships are first-class citizens. The graph learns from feedback, remembers investigations across sessions, and can answer structural questions ("what breaks if I delete X?", "does A depend on B at runtime?") that RAG cannot.

RAG is useful for semantic similarity search. m1nd is useful for structural reasoning. They are complementary, not competing.

### How is m1nd different from static analysis tools (tree-sitter, ast-grep, Sourcegraph)?

Static analysis tools parse code into ASTs and compute call graphs, type hierarchies, and cross-references. These are accurate but frozen -- they represent the code at a single point in time and cannot answer "what if?" questions.

m1nd uses similar structural information as a starting point but adds three things static analysis cannot: (1) Hebbian learning that adapts the graph based on usage, (2) temporal intelligence from co-change history, and (3) simulation engines for hypotheses and counterfactuals.

Sourcegraph is a search engine. m1nd is a reasoning engine.

### Do I need an LLM to use m1nd?

No. m1nd makes zero LLM calls. It is pure Rust computation: graph algorithms, spreading activation, Hebbian plasticity. No API keys, no network calls, no token costs.

m1nd is designed to *work alongside* LLMs (as an MCP tool that agents call), but the graph engine itself is completely self-contained.

### What languages does m1nd support?

m1nd currently has:

- native/manual extractors for Python, Rust, TypeScript/JavaScript, Go, and Java
- 22 additional tree-sitter-backed languages across Tier 1 and Tier 2
- a generic fallback extractor for unsupported text files

Language breadth is broad, but semantic depth still varies by language. Python and Rust currently have more specialized handling than many of the tree-sitter-backed languages.

### Is m1nd open source?

Yes. MIT license. Source at [github.com/maxkle1nz/m1nd](https://github.com/maxkle1nz/m1nd).

---

## Installation

### What platforms does m1nd support?

Any platform where Rust compiles. Tested on:

- macOS (ARM64 and x86_64)
- Linux (x86_64, ARM64)
- Windows (x86_64)

### What is the minimum Rust version?

Rust 1.75 or later. The project uses the 2021 edition.

### How large is the binary?

Approximately 8MB for a release build. No runtime dependencies, no shared libraries. The binary is fully self-contained.

### Can I install from crates.io?

Yes: `cargo install m1nd-mcp` for the current runtime.

---

## Usage

### How many files can m1nd handle?

Tested up to 10,000+ files. At ~2MB of memory for 10,000 nodes, a 100K-file codebase would need roughly 20MB for the graph. This is well within modern machine capacity.

At 400K+ files, the in-memory graph starts to become a consideration (~80MB), but it still works. m1nd was optimized for codebases in the 100 to 50,000 file range.

### Does it work with non-code files?

Yes. The current ingestion surface is not code-only.

m1nd can now ingest:

- structured data through `json`
- text corpora through `memory`
- `L1GHT` specs through `light`
- native document adapters for patents, articles, BibTeX, CrossRef, and RFCs
- best-effort ordinary documents through `universal`

The universal lane can normalize markdown, HTML/wiki pages, office documents, and PDFs into canonical local artifacts and graph-native document structure. That is what powers `document_resolve`, `document_bindings`, `document_drift`, and the document `auto_ingest_*` runtime.

### How much memory does m1nd use?

The graph itself is compact: ~2MB for a 10,000-node graph with 26,000 edges (Compressed Sparse Row format). The MCP server process uses additional memory for the JSON-RPC layer, perspective state, lock baselines, and trail storage. A typical production instance serving a 335-file codebase uses under 50MB total.

### Can I ingest multiple codebases into one graph?

Yes. If you already know the repo list, use `federate`. If the current workspace only contains explicit path evidence to sibling repos, use `federate_auto` first and let m1nd suggest the namespace plan for you.

Direct federation:

```jsonc
{"method":"tools/call","params":{"name":"federate","arguments":{
  "agent_id":"dev",
  "repos":[
    {"name":"backend","path":"/project/backend"},
    {"name":"frontend","path":"/project/frontend"}
  ]
}}}
```

Auto-discovery first:

```jsonc
{"method":"tools/call","params":{"name":"federate_auto","arguments":{
  "agent_id":"dev",
  "scope":"docs",
  "execute":false
}}}
```

### Can I do incremental ingests?

Yes. Pass `"incremental": true` to the `ingest` tool. Incremental ingest only re-processes files that changed since the last ingest, preserving learned edge weights for unchanged regions.

---

## Architecture

### Where is the graph stored?

In memory during runtime. Optionally persisted to JSON files on disk via the `M1ND_GRAPH_SOURCE` and `M1ND_PLASTICITY_STATE` environment variables.

Without persistence configured, the graph is lost when the process exits. Always configure persistence for production use.

### How often does it persist?

By default, every 50 queries. Also on shutdown. The `auto_persist_interval` configuration parameter controls this.

### Can I export the graph?

The persisted graph state is a JSON file (`graph_snapshot.json`). You can read, copy, and process it with standard JSON tools. The format includes all nodes, edges, PageRank scores, and metadata.

The plasticity state is a separate JSON file (`plasticity_state.json`) containing per-edge synaptic records (learned weights).

### What is the graph format?

Compressed Sparse Row (CSR) with forward and reverse adjacency lists. Each node has an external ID (e.g., `file::auth.py`), a type (file, class, function, module), metadata, and a PageRank score. Each edge has a type (imports, calls, inherits, co_change), a base weight, and an optional plasticity weight.

### What is XLR noise cancellation?

Borrowed from professional audio engineering. Like a balanced XLR cable, m1nd transmits the activation signal on two inverted channels and subtracts common-mode noise at the receiver. This reduces false positives in activation queries by cancelling out signals that propagate through generic hub nodes (like `config.py` or `utils.py`) rather than through meaningful structural paths.

XLR is enabled by default. Pass `"xlr": false` to `activate` to disable it for a single query.

---

## MCP Protocol

### What MCP clients work with m1nd?

Any client that speaks MCP over stdio. Tested and verified:

- Claude Code
- Cursor
- Windsurf
- Zed
- Cline
- Roo Code
- Continue
- OpenCode
- GitHub Copilot (MCP mode)
- Amazon Q Developer

### Can I use m1nd without MCP?

The server speaks JSON-RPC over stdio, which is the MCP transport. You can send raw JSON-RPC from any program that can write to stdin and read from stdout. No MCP client library is required -- the protocol is just JSON over pipes.

### What MCP protocol version does m1nd implement?

Protocol version `2024-11-05`. The server reports this in the `initialize` response.

### Does m1nd support MCP notifications?

Yes. The server silently ignores incoming notifications per the MCP specification.

---

## Performance

### How fast is spreading activation?

31-77ms for a 9,767-node graph, returning 15-20 ranked results. The variance depends on query specificity and graph density around the activated region.

### How fast is ingest?

910ms for 335 Python files producing 9,767 nodes and 26,557 edges. This includes parsing, reference resolution, edge creation, and PageRank computation.

### How fast is learning?

Sub-millisecond. A `learn` call with feedback on 2-3 nodes adjusts hundreds of edges in under 1ms.

### What about 100K files?

Ingest would take roughly 30-45 seconds (linear scaling from the 335-file benchmark). Activation would be 100-200ms. The graph would occupy ~20MB in memory. These are estimates -- actual performance depends on code density and language.

### What is the lock diff speed?

0.08 microseconds (80 nanoseconds). Lock diff is a constant-time operation -- it compares fingerprints, not individual nodes. It is essentially free.

### Full benchmark table

All numbers from real execution against a production Python backend (335 files, ~52K lines):

| Operation | Time | Scale |
|-----------|------|-------|
| Full ingest | 910ms | 335 files, 9,767 nodes, 26,557 edges |
| Spreading activation | 31-77ms | 15 results from 9,767 nodes |
| Blast radius (depth=3) | 5-52ms | Up to 4,271 affected nodes |
| Stacktrace analysis | 3.5ms | 5 frames, 4 suspects ranked |
| Plan validation | 10ms | 7 files, 43,152 blast radius |
| Counterfactual cascade | 3ms | Full BFS on 26,557 edges |
| Hypothesis testing | 58ms | 25,015 paths explored |
| Pattern scan (all 8) | 38ms | 335 files, 50 findings per pattern |
| Multi-repo federation | 1.3s | 11,217 nodes, 18,203 cross-repo edges |
| Lock diff | 0.08us | 1,639-node subgraph comparison |
| Trail merge | 1.2ms | 5 hypotheses, 3 conflicts detected |

---

## Plasticity and Learning

### How does Hebbian learning work?

"Neurons that fire together wire together." When you call `learn` with `feedback: "correct"` and a list of node IDs, m1nd identifies all edges on paths between those nodes and increases their weights (Long-Term Potentiation, LTP). When you call with `feedback: "wrong"`, it decreases weights on paths leading to the marked nodes (Long-Term Depression, LTD).

The `strength` parameter (default 0.2) controls how aggressively weights shift. The `learning_rate` server configuration (default 0.08) provides a global scaling factor.

### Can I reset learned weights?

Yes. Delete the `plasticity_state.json` file and restart the server. Alternatively, re-ingest the codebase, which rebuilds the graph from scratch (but does not clear the plasticity state file -- you need to delete it separately or pass `"incremental": false` and delete the plasticity file).

### Does the graph overfit?

Hebbian learning includes homeostatic normalization to prevent runaway weight amplification. Edge weights are bounded and periodically normalized so that heavily-used paths do not completely dominate. The `decay_rate` parameter (default 0.005) provides a slow decay toward baseline weights over time.

In practice, overfitting requires thousands of feedback signals consistently reinforcing the same narrow paths. Normal usage produces a well-distributed weight landscape.

### What is "partial" feedback?

The `learn` tool accepts three feedback types:

- `correct` -- strengthen paths (LTP)
- `wrong` -- weaken paths (LTD)
- `partial` -- mixed signal. Applies a mild strengthening (half the LTP strength) to acknowledged nodes while slightly weakening peripheral paths.

---

## Perspectives

### What are perspectives?

A perspective is a stateful navigation session through the graph. You start one with a query or anchor node, and m1nd synthesizes a "route surface" -- a ranked set of paths you can follow. As you navigate (follow, back, branch), the perspective maintains breadcrumb history and updates the route surface.

Think of it as a browser for the code graph. You have a current "page" (focus node), links (routes), history (back button), and bookmarks (branches).

### How many perspectives can be open simultaneously?

There is no hard limit. Each perspective occupies a small amount of memory (proportional to the number of visited nodes). In practice, 10-20 concurrent perspectives per agent is typical. Close perspectives you are done with to free memory.

### Do perspectives persist across sessions?

Perspectives are in-memory only and are lost when the server restarts. For persistent investigation state, use the trail system (`trail.save` / `trail.resume`).

### Can I branch a perspective?

Yes. `perspective.branch` forks the current navigation state into a new independent perspective. Both the original and the branch have the same history up to the branch point, and diverge afterward. This is useful for exploring "what if I go this way instead?" without losing your current position.

---

## Comparison

### m1nd vs tree-sitter

tree-sitter is a parser. It produces ASTs from source code. m1nd uses structural information similar to what tree-sitter extracts, but builds a *weighted, learning graph* on top of it. tree-sitter tells you what the code *is*. m1nd tells you what the code *means* in context, what changed, what might break, and what is missing.

They are complementary. tree-sitter integration is planned for m1nd to expand language support.

### m1nd vs ast-grep

ast-grep is a structural search tool -- it finds code patterns using AST matching. m1nd does not do pattern matching on syntax trees. Instead, it does graph-level reasoning: spreading activation, hypothesis testing, counterfactual simulation, learning. ast-grep answers "where does this pattern appear?" m1nd answers "what is connected to this, what breaks if it changes, and what am I missing?"

### m1nd vs RAG (Retrieval-Augmented Generation)

RAG embeds code into vectors and retrieves similar chunks. Each retrieval is independent and stateless. m1nd maintains a persistent graph with relationships, learning, and investigation state. RAG cannot answer structural questions, simulate deletions, or learn from feedback.

RAG costs LLM tokens per query. m1nd costs zero tokens per query.

### m1nd vs Sourcegraph / CodeGraph / SCIP

Sourcegraph provides cross-repository code search and navigation based on SCIP (Source Code Intelligence Protocol) indexing. It produces accurate, language-server-quality code intelligence.

m1nd is not a code search engine. It is a reasoning engine. Sourcegraph tells you "function X is defined here and called here." m1nd tells you "if you change function X, here are the 4,189 nodes in the cascade, and the graph predicts these 3 files probably need changes too."

Sourcegraph is a hosted SaaS product. m1nd is a local binary with zero cost per query.

### m1nd vs GitHub Copilot context

Copilot uses a mix of embeddings and heuristics to select context files for the LLM. It does not maintain a persistent graph, does not learn from feedback, and does not support structural queries.

m1nd can be used *alongside* Copilot -- through MCP, Copilot can call m1nd tools to get smarter context before generating code.

---

## Contributing

### How do I contribute?

See [CONTRIBUTING.md](https://github.com/maxkle1nz/m1nd/blob/main/CONTRIBUTING.md). Fork the repo, create a branch, make your changes with tests, and open a PR.

### What is the test suite?

```bash
cargo test --all
```

Tests cover the core graph engine, plasticity, spreading activation, hypothesis engine, all MCP tool handlers, and the JSON-RPC protocol layer.

### What are the code style requirements?

- `cargo fmt` before committing
- `cargo clippy --all -- -D warnings` must pass
- No `unsafe` without an explanatory comment
- All new code needs tests

### What areas need the most help?

1. **Language extractors**: Adding tree-sitter integration or new language-specific extractors
2. **Graph algorithms**: Community detection, better decay functions, embedding-based semantic scoring
3. **Benchmarks**: Running m1nd on diverse codebases and reporting real-world performance numbers
4. **Documentation**: Tutorials, examples, and translations

### Where do I report bugs?

GitHub Issues at [github.com/maxkle1nz/m1nd/issues](https://github.com/maxkle1nz/m1nd/issues). Use the `bug` label.
