m1nd

<p align="center">
  <img src=".github/m1nd-logo.svg" alt="m1nd" width="340" />
</p>

**m1nd** gives your coding agent a brain per repository: a local code graph served over MCP, memory anchored to the code it cites, and a trust verdict on every answer. "Insufficient evidence" is a real answer here. So is "don't trust this yet, and here is how to repair it".

Nothing leaves your machine. One Rust binary. MIT.

Think of it as an X-ray of your repo that your agent can read: one structure that combines everything and says where each thing lives, what that program is for, what is being worked on, what is done and what is still open. That panorama is the thing no other tool hands your agent.

<p align="center">
  <a href="https://www.npmjs.com/package/@maxkle1nz/m1nd"><img src="https://img.shields.io/npm/v/@maxkle1nz/m1nd.svg?color=00f5ff&label=npm" alt="npm" /></a>
  <a href="https://crates.io/crates/m1nd-mcp"><img src="https://img.shields.io/crates/v/m1nd-mcp.svg?label=crates.io" alt="crates.io" /></a>
  <a href="https://github.com/maxkle1nz/m1nd/actions"><img src="https://github.com/maxkle1nz/m1nd/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License" /></a>
  <a href="https://registry.modelcontextprotocol.io/?search=io.github.maxkle1nz/m1nd"><img src="https://img.shields.io/badge/MCP_Registry-official-6d28d9" alt="MCP Registry" /></a>
</p>

<p align="center">Four commands to install: <a href="#sixty-seconds">Sixty seconds</a>. Reasons to close the tab first: <a href="#when-not-to-use-m1nd">When not to use m1nd</a>.</p>

<p align="center">
  <img src="docs/assets/demo.gif" width="760" alt="A real m1nd session: north returns trust, focus and honest gaps; seek answers with a reverify verdict; memorize anchors the finding to code" />
</p>

<p align="center"><em>A real session on this repo's 6,453-node graph (m1nd-mcp 1.4.0): <code>north</code> orients, <code>seek</code> answers wearing a <code>reverify</code> verdict, <code>memorize</code> anchors the finding to code.</em></p>

## The audit your agent stops paying for

You know the ritual. The agent opens a file, greps, opens another file, greps again, burns most of its context reconstructing what the repo even is, and only then starts the actual task. With m1nd that sweep becomes one question. In under a second the agent has the map: what calls what, what breaks what, where everything lives. Not a pile of matches to interpret. The connected structure, already assembled.

And it remembers. Between sessions, and between agents. What one agent learns tonight, another agent inherits tomorrow, with the evidence attached and a flag if the code moved on since. Every conclusion leaves a trail, so you, or any agent that comes after, can always see what happened to that code and why.

Then l1ght takes it further: papers, articles, RFCs, drafts and notes connect to the parts of your code they explain, inside the same structure. The agent gets the RIGHT context instead of the nearest-sounding one, and inventing code that does not exist stops being the path of least resistance: the structure says what exists, and the verdict says how much to trust even that.

Before m1nd, a function was just a function, lost in some manual. Now it lives inside the agent's intelligence, combined with the code, its history, its documents and its risks. I have not found anything like that anywhere else.

## grep answers good questions. m1nd answers the deeper ones.

Questions your agent can now ask and get a structural answer for:

- What breaks if I touch this function?
- Where does token refresh actually happen in this repo?
- Why are these two files connected, and is that path solid or a guess?
- What did the last session learn about this code, and is it still true?
- What always changes together here, even with no import between them?
- Does this edit cross an architecture boundary I should not cross?
- Which claim in this paper does this function implement?
- Is the bug I just fixed hiding anywhere else, as a shape?
- What is missing here that this pattern usually has?
- Am I even in the right repo?
- Should I act on this answer, or verify it first?

Each one is a verb on the MCP surface (`impact`, `seek`, `why`, `north`, `ghost_edges`, `xray_gate`, `antibody_scan`, `missing`, `trust_selftest`, `predict`), not a prompt trick.

## And it does not stop at showing structure

Antibodies: a fixed bug becomes a named structural pattern, and every later session scans for that shape across the repo. Fix it once, hunt it forever.

Ghost edges: files that always change together with no import between them, mined from your git history. The invisible coupling that breaks refactors.

Structural holes: `missing` looks for the code that is not there. The guard, the retry, the timeout this pattern usually carries and this instance lacks.

Hypotheses against the graph: state a claim in plain language ("settings can reach boot without validation") and have it tested against the live structure.

Tremor: files whose change velocity is accelerating get flagged before anyone files the bug report.

A warm graph: confirmed results reinforce their edges, Hebbian style, so the paths that proved useful rank higher for the next agent.

Every one of those flags and suggests; your compiler and tests still do the proving.

## m1nd does not just search. It writes.

Here is the part people take a second to believe. The graph that reads your repo can also operate on it. Your agent names a symbol and a destination, about 48 tokens, and `transplant` computes the whole move from the graph: the widened region (doc comments and attributes travel along), dependencies classified by their call edges (private ones travel, shared ones stay and gain a back-import), every referencer re-qualified across every file that names it. Then it writes atomically, re-ingests, and hands back an honest receipt: what moved, what stayed, what it could not resolve. `refs_unresolved` is never silently empty when something went wrong.

It is two-phase, `transplant_preview` before `transplant_commit`, and the commit re-validates the hash of every file it planned to touch, so nothing lands on a repo that changed underneath it. The money zone of your repo (backend, schema, payments, CI) is protected server-side and fails closed. A refusal never touches a byte and teaches the retry: a collision names the occupant, an invalid module path names itself, a cross-crate move names both crate roots.

Measured on the real case: the whole-file edit cost 12,235 output tokens; the transplant cost 48 in and wrote 3 files in 1.3 seconds, with the crate compiling on the other side. rust-analyzer has had an issue open asking for cross-file moves since 2019.

v1 boundaries, stated plainly: Rust only, top-level `fn` only, same crate, the destination file must already exist, and references born inside macros are invisible to it. Each boundary is deliberate and written down in [docs/TRANSPLANT-PRD.md](docs/TRANSPLANT-PRD.md), next to 13 test files that hold the verb to it.

## And when it is not one agent but five?

Run several agents on the same repo and the graph becomes the place they coordinate. Every session registers as a presence, and when two of them are about to touch overlapping work, both get warned in their next orientation packet, before either lands a change. The system warns; you decide.

Bounded work runs as missions, and missions answer for themselves in a way most human teams skip: every mission tool reports `non_claims`, the list of what was NOT proven. A claim cannot close on graph evidence alone. It takes a file read, a test run or a runtime probe, and the test that enforces this is named `graph_only_evidence_is_not_enough`.

And the guardrails do not cry wolf. `xray_gate` can say `blocked` only from a boundary manifest a human ratified. Everything else arrives as a warning with a reason, so the agent never learns to ignore its own safety rail.

Every brain also has a mailbox. An agent that finds a real defect outside its own mission does not fix it on the spot and does not swallow it: it drops a letter in that repo's box, on disk, next to the code. The next agent working that brain sweeps the box and starts out already knowing the defects other agents found, context attached. Knowledge of what is broken stops dying in chat scrollback. The sweep is a deliberate gesture (CLI or REST, never inside the query loop), so the letters inform the work instead of interrupting it.

## Born agent-first

No account, no telemetry, and no API in the way, which is also why the graph answers in microseconds.

The development of m1nd is not very normal either. Building it meant building a whole workflow where agents direct, verify and prove the work, and the logic of the product is aimed at the agent's pain, not the human's dashboard. When m1nd misbehaves in the field, the agents using it file the report, and a confirmed bug becomes a red test before the fix lands. Very few programs start from that in their initial design. So m1nd is born different: the verbs, the refusals and the packets are shaped for the reader that actually uses them, and you do not even have to remind the model the tool exists. `m1nd hosts apply` installs session hooks (`SessionStart`, `agentSpawn`, `TaskStart`, per host) that inject the orientation at spawn: your agent, and every subagent it spawns, starts oriented before anyone types a word.

A brain per repository holds it together: one graph, its own memory, its own persistence, bound to one repo root. A served owner hosts many brains and routes each session to the right one; a session from a repo it does not host gets a typed refusal instead of wrong answers.

## What your agent gets

m1nd wraps the agent's whole loop around a graph of your repo that outlives the session:

```mermaid
flowchart LR
    B["<b>BEFORE</b><br/>born oriented<br/>map + memory + t