M1nd

Give your coding agent a map it can check

m1nd is a local code graph and evidence-linked memory for MCP coding agents. Find connected code, inspect the impact of a change, and carry verified findings into the next session. Answers include trust signals and explicit gaps so your agent knows what still needs checking.

Built for developers working across unfamiliar repositories, multi-file changes, or repeated agent sessions. Use your existing MCP host; the runtime is Rust and the license is MIT.

Get started · Workflows · Limits · Documentation

Why add it to your agent?

• Start with the repo's structure. north combines task context, bounded source excerpts, binding trust, prior memory, and a suggested next move. seek finds candidates; impact helps inspect their neighbors before editing.
• Keep findings attached to code. memorize stores claims with evidence paths and provenance. The next session can recall them and check whether they still apply.
• Share context across agents. A served local owner can share one graph with attached clients. Presence and overlap warnings help agents coordinate; they are advisory, not locks.
• See uncertainty. reverify, abstain, and insufficient_evidence are useful results. A graph connection is a reason to inspect code, not proof that a change is safe.

The graph and memory live on your machine. m1nd does not require an LLM API key for graph queries. Installation, updates, optional model downloads, and network-backed document providers can use the network or transmit documents to a configured endpoint; your MCP host has its own data policy.

Get started

Version matters: GitHub/native 1.6.5, crates.io packages, and npm 1.6.5 are published from immutable commit 363bc97f2336c73e90802916804dccd2109c5746; npm latest is 1.6.5 as of 2026-10-12. The learning-event separation merged after that release in PR580 is Unreleased, even though source package versions still say 1.6.5.

Published 1.6.5: get a first result

You need Node.js 18+ and a repository you can read. Install the signed native 1.6.5 artifact, then run this POSIX-shell recipe from your repository:

export M1ND_BINARY="$HOME/.local/share/m1nd/versions/1.6.5/m1nd-mcp"

"$M1ND_BINARY" --version

Require native 1.6.5 at 363bc97f2336c73e90802916804dccd2109c5746.

( unset M1ND_RUNTIME_DIR M1ND_MCP_ARGS npx -y @maxkle1nz/m1nd@1.6.5 agent first-minute --repo . \ --binary "$M1ND_BINARY" --query "where is configuration loaded?" --json )

first-minute discovers a covering served owner first. Otherwise, the matching wrapper/native runtime prepares only the exact launcher-granted repository in an external private cache. Source files remain inputs. Only when reusing the automatic isolated cache does the CLI refresh the declared root before retrieval. Attached-owner freshness follows the owner's own semantics; inspect that owner's version, repository binding, and freshness rather than inferring them from the selected client binary. Check runtime.boot, returned source locations, and gaps. This is not authority to create a shared brain, move a binding, or call generic ingest.

To connect an MCP host, follow the 1.6.5 quick start. Direct stdio needs an explicit workspace grant and an existing external private runtime; a shared owner has separate preparation and authority requirements. See agent autonomy.

Historical pinned 1.6.3: install, prepare, connect

You need Node.js 18+, an MCP host, and a repository. First install the signed native 1.6.3 artifact; that guide uses cosign and an exact release URL. The prebuilt 1.6.3 release covers Linux x86_64 and macOS x86_64/ARM64. Run this POSIX-shell recipe from the repository you want to use; it deliberately pins the wrapper:

# After the signed installation guide, select the exact native binary.

export M1ND_BINARY="$HOME/.local/share/m1nd/versions/1.6.3/m1nd-mcp" "$M1ND_BINARY" --version

Confirm this binary reports native 1.6.3 before continuing.

Bind the human ceremony and host to the same explicit repository runtime.

export M1ND_RUNTIME_DIR="$(pwd -P)/.m1nd"

Run this yourself in a terminal, once for an empty runtime.

npx -y @maxkle1nz/m1nd@1.6.3 init --birth . --binary "$M1ND_BINARY"

Preview your host configuration before applying it.

npx -y @maxkle1nz/m1nd@1.6.3 hosts plan --host claude --project . --binary "$M1ND_BINARY" npx -y @maxkle1nz/m1nd@1.6.3 hosts apply --host claude --project . --binary "$M1ND_BINARY" --yes

Replace claude with your host, such as codex or cursor. Follow the printed instructions: some host-managed configuration and hooks are printed for you to install, not written automatically. Restart or reconnect the host after configuration changes. See the host integration matrix for host-specific behavior.

Before reconnecting, add M1ND_RUNTIME_DIR to the generated MCP server environment with the same absolute path printed by echo "$M1ND_RUNTIME_DIR". Keep the generated M1ND_WORKSPACE_ROOT. hosts apply does not add the runtime selector for you; without it, a host launched elsewhere can open a different graph.

This recipe targets native 1.6.3. Pinning the npm wrapper alone does not pin update apply; that command follows the registry channel and is intentionally excluded here. If the selected binary reports a different version, check that release's setup contract before continuing. The birth command is a human terminal step, not an agent tool call. Its receipt must report brain: "owner_bound_graph", the intended born_root, the exact runtime in store_dir, and node_count > 0. If it refuses, follow its diagnostic rather than replacing another runtime or forcing ingest. For source builds, use the separate contributor path below.

Your first useful result

Ask your connected agent:

Use m1nd to orient on this repository. Find where configuration is loaded, show the relevant source locations, and tell me what you still need to verify. Do not edit files.

The agent should call north first, then use seek and source inspection as needed. Success means the response covers the correct repository and points to real code you can open. A reverify verdict is expected under the current calibration containment: inspect the evidence. A missing graph or wrong-workspace binding needs recovery; an empty result may need a different query.

Quick-start troubleshooting covers missing binaries, host configuration, and binding errors. Your first query shows the actual MCP calls.

Unreleased main: learning-event separation

For contributors testing the unreleased learning fix, select a main revision containing PR580 explicitly and use its matching wrapper and native runtime. A version string alone does not establish that the fix is present. --binary selects the executable used by the CLI, but default discovery can still attach it to an older covering owner. Use --no-attach and clear ambient runtime/attach overrides to run this exact revision in an automatic isolated cache:

git clone https://github.com/maxkle1nz/m1nd.git

cd m1nd git checkout --detach 74d0348c9a5a1e0d5d5e5b5a784ee4f3771d0808 cargo build --release -p m1nd-mcp ./target/release/m1nd-mcp --version ( unset M1ND_RUNTIME_DIR M1ND_MCP_ARGS M1ND_ATTACH_URL node npm/bin/m1nd.js agent first-minute --repo /absolute/path/to/your/repo \ --binary ./target/release/m1nd-mcp --no-attach --query "map this repo" --json )

PR580's learning semantics are available on main but are absent from the sealed 1.6.5 artifacts. Automatic isolated preparation already shipped in 1.6.5; it is not a preview feature of PR580. See the launcher contract. The contributor development kit provides checkout-private state for development.

What to try next

See worked examples, use cases, and the tool reference. The default tool menu is deliberately small. help discovers the full registry; M1ND_TOOL_TIER=full expands the advertised menu. Published 1.6.5 also offers M1ND_TOOL_TIER=investigate: the core plus five session-local snapshot tools. See the beginner and advanced recipe. Graph-linked search in 1.6.5 preserves canonical node IDs for single-file ingest roots; ambiguous file mappings are omitted. A listed or callable tool may still require authority the current session does not have.

What it does and does not prove

• Best fit: structural navigation, change preparation, and continuity across repeated work. For a tiny edit or exact string lookup, a file read or rg may be enough.
• Extraction is approximate. Language support varies, macro-generated and dynamic references can be missed, and external imports may remain unresolved. A graph is not a compiler's semantic model.
• Trust is conditional. Published 1.6.5 and current main treat all v1 calibration rows as unqualified evidence: prediction abstains and the seek envelope stays at reverify or unprovable, while scores and rankings remain available. Running calibration does not enable act. Use source, compiler, tests, and runtime checks for your change. The clock repair does not establish statistical quality.
• Unreleased learning feedback is relevance-only. On main after PR580, internal learn(correct|wrong) adjusts graph relevance weights; it records no defect, false alarm, observed co-change, or automatic antibody. Ambiguous partial feedback is refused without mutation, and zero strength is a no-op. This change is absent from sealed 1.6.5. Public learning and calibration authority floors remain blocked. See the event boundary.
• Writes have extra boundaries. Preview/commit tools, proof permits, and authority checks are separate from read-only retrieval. Gra