Welcome to m1nd. Use #general for project chat, #help for questions, and #showcase for what you build.
Shared memory and context tools for agentic work.
README from GitHub
A local code graph served over MCP — the map an agent reads before it touches your code.
Start here — the five verbs I reach for first:
north to orient ·
seek to find by purpose ·
impact to see what a change touches ·
health to check the graph ·
help to reach every other verb
m1nd is an MCP server, written in Rust, that turns a repository into a graph of files, symbols, and the edges between them, then answers an agent's questions about that graph: where a behavior lives, what reaches a function, whether the graph even covers the repository the agent is standing in. The graph and its memory sidecar stay on your machine, and graph queries need no LLM API key. Installation, updates, optional model downloads, and network-backed document providers can use the network; your MCP host has its own data policy.
It is built for agents first. The default menu is 15 verbs. seek and north answers say how far to trust them. absent, abstain, and insufficient_evidence are answers, not failures.
I run coding agents every day, and the expensive part is never the edit. It is the agent reading whole files to find where something lives, then changing a function without knowing what calls it. m1nd's own repository is 18,078 nodes. No agent holds that in context, and none should have to. So the agent asks the graph, gets a file and a line span, opens the span, and confirms. The graph locates. The source decides.
Ask seek a question in plain language — "where is retry backoff decided" — and it returns ranked files with a trust envelope and a sufficiency signal. On the main source tree (2.0, unreleased), each of the first ten file rows also carries up to three symbols with line_start and line_end, best first (#602), so the agent opens a span instead of a whole file. On two fixed question sets, the facts whose span came back rose from 10 to 17 of 24 and from 5 to 11 of 24; packets shrank by about 8%; file ranking stayed identical in 16 of 16 questions. Since #601 (2.0, unreleased) the ranking no longer depends on hash order, so the same graph ranks the same way twice. Since #607 (2.0, unreleased) a default row carries only what the agent acts on — file, span, symbols, score — and per-row diagnostics come back with detail: true: on 16 registered questions the median packet fell from 10,736 to 4,270 tokens (−60%), ranking identical 16 of 16, facts unchanged. PROVEN (n=16 questions, 48 facts).
impact walks the graph out from one node. With direction: "reverse" it follows the edges that point into the node — for a function, the code that reaches it, which is what breaks when it changes. Aim it at a function seek returned, not at a type or a file, where same-named methods blur together. Before the cap, one call on a whole file answered 3.6 MB, two thirds of it causal chains; the chains now stop at the strongest 20 (2.0, unreleased; max_causal_chains asks for more), and the same call answers about 40 KB with the same blast radius. Routing "who calls / what breaks" questions to impact added one or two facts out of 24 over seek alone. That is a small gain on a small sample: a direction, not a law. Confirm callers with your compiler or a literal search before you edit. PROVEN (small n).
"Grep finds what exists. m1nd finds what's missing." was this project's first promise; today it has one honest meaning. On main (2.0, unreleased; #606), when the brain's root is a git repository, impact carries co_change: up to five files that changed in the same commits as the target's file and that the graph does not link to it directly, each with its joint-commit count and the short sha of the latest — git show it to watch the pair move. Offline, with thresholds registered before the run, on three repositories (m1nd, gin, express): 34–58% of co-changed pairs were partners neither grep nor import edges reach, precision at 5 ran 0.49–0.85, and all three passed. Restricted to source files, it failed in two of the three. So it finds the sibling manifest, the coupled doc, the release metadata — the files an agent forgets to change together — not hidden code-to-code coupling, one Go repository aside. On m1nd's own pull request it named two skill files the change had left behind, 19 joint commits each. PROVEN (n=3 repositories; source-only failed 2 of 3).
north takes the task as a sentence and answers in one round trip: focus nodes, bounded source excerpts of the top ones (up to 3 files and 2,000 characters by default; code_budget_chars widens it), whether the graph is bound to the repository you are in, prior memory with author and real age, a suggested next move, and honest_gaps — what it could not see. It is the one verb agents picked up on their own in real traffic, without being told to. That is adoption, not a measured benefit. OBSERVED.
m1nd says what it does not know. Under the current calibration every seek envelope stays at reverify or unprovable — open the source and check — and prediction abstains: all v1 calibration rows are unqualified evidence, and running calibration does not enable act. A verb above the generic authority floor refuses with generic_action_authority_required instead of trying. A graph bound to another repository answers with caller_root_mismatch, and the write laws forbid writing through it. The default menu is 15 verbs; help is one of them, and it catalogs every registered verb — on the menu or not — with its schema and its POLICY-DISABLED mark where one applies. On main (2.0, unreleased), help routes an agent only to verbs that same caller can call, and no tool response carries ANSI escapes (#604, #605). RULE.
Run one served owner per runtime and attach every other session to it: they read one graph instead of each building its own. A second plain stdio process on an owned runtime exits before the handshake rather than race the owner on disk; today it exits without naming the owner (a typed error is in progress), so attach instead. One owner can host several project brains and routes each attached client to its own by caller root. m1nd's repository — 18,078 nodes, 78,981 edges — ingests in 19 s; an exact-root refresh of a ~2.6k-node repository took 0.49 s. The graph is as fresh as your last refresh; there is no continuous watcher. On main (2.0, unreleased), north and health say when it is behind (#608): a graph_drift note with the indexed commit, HEAD, commits behind, files changed, and the exact refresh call — 234 bytes on this repository, nothing at HEAD, +1.1 ms median in a paired warm run. It reports; it does not refresh. PROVEN (sandbox).
What I measured, on how much, and where it stops.
| Claim | Measure | n | Caveat |
|---|---|---|---|
Symbol spans on seek (#602, 2.0, unreleased) |
Facts whose span is returned: 10→17 of 24 and 5→11 of 24; packets ~8% smaller; file ranking identical 16/16 | 16 questions, 48 facts | Two fixed question sets with a check fixed in advance; not a blind benchmark |
| Stable ranking (#601, 2.0, unreleased) | Before the fix, two runs of one binary agreed on 14/16 and 13/16 questions; sums now run in a fixed order and ties break by node id | 16 questions | Every ranking change now runs a bracketed old/new/old comparison |
Lean seek rows (#607, 2.0, unreleased) |
Median packet 10,736 → 4,270 tokens (−60%); ranking identical 16/16; facts with their span unchanged | 16 questions | Bracketed against main with frozen plasticity; diagnostics need detail: true |
Blast radius with impact |
Relation questions routed to impact: +1/+2 facts of 24 (11/24 against 10/24 with symbols alone) |
24 facts | Small sample; re-measure before treating it as a rule |
Causal-chain cap on impact (2.0, unreleased) |
Reverse impact on a large file: 3.6 MB → 40 KB; blast radius identical on 2 files and 3 functions |
5 targets | Answer size, not accuracy; max_causal_chains returns the full list |
Co-change partners on impact (#606, 2.0, unreleased) |
Partners that neither grep nor import edges reach: 34–58% of co-changed pairs; precision at 5: 0.49–0.85; thresholds registered before the run; passed 3/3 | 3 repositories (m1nd, gin, express) | Offline, on history. Restricted to source files it failed 2 of 3: it finds files changed together (manifests, docs, release metadata), not hidden code coupling |
| Graph drift note (#608, 2.0, unreleased) | 234 bytes when the graph is behind; 0 bytes at HEAD; paired warm latency +1.1 ms median |
one repository | It reports drift and names the refresh call; it does not refresh |
| Ingest and refresh | 18,078 nodes and 78,981 edges in 19 s; exact-root refresh 0.49 s | one machine | Sandbox; the refresh was measured on a ~2.6k-node repository |
| Standing decisions | A decisions block in AGENTS.md answered 5/5 by cold sessions on three hosts; the same facts through memorize: 0/5 |
5 per channel | This is why I do not claim memory carries decisions |
| Orientation | north is the only verb agents adopted unprompted |
real traffic | An observation; the benefit is not measured |
Not measured yet: whether m1nd beats grep and plain file reads on real tasks. That experiment has not run, so I make no such claim. The co-change experiment measured reach on history, not whether agents finish tasks better.
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. Everything merged after that release, from the learning-event separation in PR580 to the 2.0.0 source tree now on main, is Unreleased. The npm wrapper and the m1nd-core, m1nd-ingest, and m1nd-mcp source versions on main say 2.0.0, but no 2.0.0 artifact, crate, or npm package is published.
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.
Then 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 seek and source reads 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 a 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.
Everything in this section is unreleased: it describes the current main source tree, not the published 1.6.5 artifacts. main adds PR580's learning-event separation, stable ranking (#601), symbol spans and lean rows on seek (#602, #607), help that routes only to callable verbs (#604, #605), co_change on impact (#606) and a cap on its causal chains, the graph_drift note on north and health (#608), automatic-freshness guards, a leaner tree, and a reworked host installer; see the 2.0.0 changelog entry and the release proposal. The dependency security updates change the source lockfile; they do not update the published 1.6.5 binaries.
A version string alone does not establish which changes a binary contains, so select an exact main revision and use its matching wrapper and native runtime. m1nd-mcp --version reports the commit it was built from.
To test PR580's learning fix by itself, pin the commit that merged it. --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.
You need Node.js 18+ (for the dependency-free @maxkle1nz/m1nd CLI/installer) and Rust (stable) to build the native m1nd-mcp binary from a main checkout:
git clone https://github.com/maxkle1nz/m1nd.git
cd m1nd
cargo build --release -p m1nd-mcp
./target/release/m1nd-mcp --version
node npm/bin/m1nd.js version
node npm/bin/m1nd.js doctor
Place ./target/release/m1nd-mcp on your PATH or pass --binary /path/to/m1nd-mcp. The commands below use the checkout's own wrapper, node npm/bin/m1nd.js. Until a 2.0.0 package is published, npx @maxkle1nz/m1nd resolves to 1.6.5, which does not include the installer changes described here.
hosts status and hosts plan are read-only; hosts apply is a dry run unless you pass --yes:
node npm/bin/m1nd.js hosts status --host claude --project ~/src/my-repo
node npm/bin/m1nd.js hosts plan --host claude --project ~/src/my-repo --binary /path/to/m1nd-mcp
node npm/bin/m1nd.js hosts apply --host claude --project ~/src/my-repo --binary /path/to/m1nd-mcp --yes
The installer writes skills, MCP config, and host-owned hooks for Claude Code (claude), Codex (codex), and Antigravity (antigravity); pass --no-skills, --no-config, or --no-hooks to skip a step. Every config write is atomic, and existing files are backed up under ~/.m1nd/backups/ with private 0700/0600 permissions on Unix. For Claude Code it writes <project>/.mcp.json, never modifies ~/.claude.json, and prints the SessionStart hook for you to paste instead of writing it. Exact targets for every host are in the host integration matrix. Restart or reconnect the host after a change, then verify the binding in-session with trust_selftest or session_handshake.
A fresh repository needs a graph before retrieval works:
m1nd-mcp --stdio --no-gui with M1ND_WORKSPACE_ROOT=~/src/my-repo and a private writable runtime, startup prepares the empty bound graph automatically (see agent autonomy).node npm/bin/m1nd.js init --birth ~/src/my-repo --binary /path/to/m1nd-mcp. An agent offers this command; it never runs it.node npm/bin/m1nd.js agent first-minute --repo ~/src/my-repo --binary /path/to/m1nd-mcp --query "where is configuration loaded?" --json. Add --no-attach --state-dir /path/to/private-cache (outside the repository) to force an isolated cache. See storage selection and sandbox limits.# 1. Start one persistent owner on loopback (default port 1337; drop --no-gui for the web UI)
m1nd-mcp --serve --no-gui --port 1337 --runtime-dir /path/to/runtime
# 2. Point each agent session at the owner (run from inside a covered repo)
m1nd-mcp --attach auto --stdio
--attach auto loads no graph and takes no writer lease. It looks first for a live owner of the same runtime root, then for one whose declared roots cover the caller's repository, resolving git worktrees to their main repository and refusing when several owners match. m1nd-mcp --discover-owner prints that decision as JSON; --attach http://127.0.0.1:1337 --stdio or M1ND_ATTACH_URL overrides it. Do not export M1ND_WORKSPACE_ROOT or the other *_ROOT variables globally: they override the working directory and route every session to one project. Service templates for launchd and systemd are in deployment.
| Task | Start with | Check before acting |
|---|---|---|
| Understand unfamiliar code | north → seek → open the returned span |
Is the graph bound to this repository? Read honest_gaps. |
| Find where a behavior lives | seek with a plain-language question |
Open the symbol span. A top score near 0.4 with unrelated hits usually means the concept is absent; confirm with a literal search. |
| Plan a cross-file change | impact with direction: "reverse" on a function |
Confirm callers with the compiler, tests, or a literal search; unresolved edges are gaps. |
| Check that the graph is current | health once, then ingest {"mode": "refresh"} from the exact declared root |
On main, north and health carry graph_drift, with the exact call, when the graph is behind. On 1.6.5, compare git rev-parse HEAD with the commit you last ingested. |
| Call a change done | impact on a function in each file you touched; read co_change (2.0, unreleased) |
A partner outside your diff is a question: git show its last commit and decide whether it moves too. |
| Find a verb that is not on the menu | help with tool_name |
Read its POLICY-DISABLED mark before planning around it. |
See worked examples, use cases, and the tool reference. Published 1.6.5 also offers M1ND_TOOL_TIER=investigate: the core plus five session-local snapshot tools (recipe). A listed or callable tool may still require authority the current session does not have.
If you are an agent, this section is yours. The full manual is docs/AGENT-BEST-PRACTICES.md; every practice in it carries PROVEN, OBSERVED, or RULE. The short version:
agent_id on every call — <host>-<role>, not a random id.north to orient, seek for where and how, impact with direction: "reverse" on a function — never a whole file — for who calls. Open the span before you quote it: m1nd locates, your file read confirms.health once per session, not per question. On main, a graph_drift note on north or health means the graph is behind your checkout: run its refresh call, or read lines as of indexed. On 1.6.5, compare HEAD yourself.reverify means open the source. absent and abstain are answers.help with tool_name. Builds before #604 suggest learn, ghost_edges, audit, or ingest with merge or replace: ignore them, they refuse every generic client.impact's co_change for the files you touched (2.0, unreleased). Partners outside your diff are the files agents forget: manifests, docs, release metadata.AGENTS.md, CLAUDE.md), not in memorize: 5/5 against 0/5.Host packs ship in skills/ (m1nd-first, m1nd-guardian, m1nd-operator); setup for coding agents is in the agent installation guide.
latest — from the commit named in Install.main after it, including PR580's learning-event separation, #601 through #608, the impact causal-chain cap, and the 2.0.0 host installer. Versions on main say 2.0.0; no 2.0.0 artifact, crate, or npm package is published or signed, and legacy brain upgrade/rollback is not qualified.grep on real tasks (the experiment has not run); that north helps beyond being adopted; that the impact gain holds beyond a small sample; that co_change reveals hidden code coupling (restricted to source files, it failed in 2 of 3 repositories); that memory carries decisions (measured 0/5).seek stays at reverify or unprovable; running calibration does not enable act. Source, compiler, and tests remain the final truth.learn, ghost_edges, apply, the daemon and auto-ingest controls, generic ingest with replace or merge, and others — refuse every generic MCP or REST caller, and no payload lifts that. Creating a brain on a shared runtime is the human terminal command m1nd init --birth <repo>. So I make no claim that m1nd learns from use — the learn feedback verb sits behind the floor. Before #606, predict's git half was empty for every generic caller; on main the history behind co_change seeds it, and that has not been measured.main, graph_drift says when it is behind; it does not refresh it. A git worktree binds to its main repository's brain, so a worktree on another commit reads main's lines; re-read spans in your own checkout.--serve binds loopback only and refuses anything else; loopback does not authenticate other processes of the same user. See SECURITY.md.help included, is the stable surface. Hidden verbs stay reachable by name through help but are unstable: one may leave in a minor release, with a CHANGELOG note.MIT licensed — fork it. The documentation index, examples, and changelog go deeper; contributions follow CONTRIBUTING.md, and security reports follow SECURITY.md. Found a wrong answer? Open an issue with the call, the response, and what the source says. That is the proof I need.
The workspace: five Rust crates (m1nd-core, m1nd-ingest, m1nd-mcp, m1nd-control, m1nd-runnerd), the embedded web UI (m1nd-ui/), the npm wrapper (npm/), and the agent skills (skills/).
An m1nd graph by DEViance Intelligence — beyond the edge · by Max Kle1nz
Room context
Read the project first. The room is where the next question becomes a conversation.
Room chat
Join the room to talk.
Read the room now, then continue with GitHub when you want to post.