🇬🇧 English | 🇧🇷 Português | 🇪🇸 Español | 🇮🇹 Italiano | 🇫🇷 Français | 🇩🇪 Deutsch | 🇨🇳 中文 | 🇯🇵 日本語

The Agent Memory Layer for Codebases

Your coding agent stops starting blind.
Local-first. MCP-native. Graph memory, recovery, and change reasoning for agent hosts.

Why Agents Need It · What m1nd Is · What That Intelligence Covers · How m1nd Thinks · What m1nd Is Not · Capability Map · Quick Start · Agent Pack · Agent Demo · Default Agent Workflow · Evidence · Why m1nd · Agent Testimonials · Limits · Architecture · Wiki · Examples · Use Cases

grep finds text. Vector search finds similar chunks. m1nd gives agents a local graph of what connects, what changed, what breaks, what drifted, and where to resume.

Why Agents Need It

Give a coding agent a large repo and it often starts the same way every time: search, open likely files, rebuild context, make a plan, then repeat the whole orientation loop in the next session.

That works for small codebases. It falls apart when the project has generated artifacts, specs, docs, hidden co-change history, multiple agents, and long handoffs.

The problem is not only the agent's reasoning. The agent has no durable model of the codebase's structure.

m1nd gives it one.

What m1nd Is

m1nd is a local MCP runtime that gives coding agents graph-native memory of a codebase: structure, docs, decisions, change impact, recovery state, and investigation continuity.

It ingests repositories, documentation, history, runtime-adjacent signals, and graph-native knowledge into a local graph. That graph becomes the operational model the agent works against instead of rebuilding context from scratch on every task.

It is not only a query surface. It is an operational layer: answers and edit surfaces can carry proof state, next-step guidance, recovery hints, observable execution, verified writes, stateful navigation, and persisted continuity across sessions.

Agents can ask the graph questions that plain file search cannot answer well:

• "What is the authentication flow?" -> activate finds the connected chain, not only files named auth.
• "What breaks if I change this?" -> impact and counterfactual surface blast radius before edits.
• "Where did this decision live?" -> boot_memory, trails, and perspectives recover prior context.
• "Does this spec still match the code?" -> document bindings and drift checks expose stale claims.
• "Is this repo binding trustworthy?" -> trust_selftest, session_handshake, and recovery_playbook tell the agent whether to proceed, ingest, rebind, or fall back.

With m1nd, an agent can:

• build a durable operational model of a codebase from code, docs, history, runtime signals, and graph-native knowledge
• retrieve and navigate the right context by text, path, intent, neighborhood, relationship, route, or failure trace
• explain blocked retrieval with compact graph state and a ready diagnostic payload, so agents know whether to re-ingest, adjust scope, or inspect the active runtime
• detect degraded host MCP surfaces, including sessions where m1nd is visible but recovery tools such as ingest are not exposed
• run a one-call trust selftest that reports whether the current agent should fully trust, re-ingest, recover, or treat m1nd as orientation-only
• reason about change before, during, and after it happens, including blast radius, co-change, missing work, structural claims, plan validity, drift, and counterfactuals
• analyze architecture, quality, security, duplication, type flow, trust boundaries, hidden dependencies, volatility, and refactor opportunities across the graph
• bind specs and docs back to implementation, including universal documents, graph-native L1GHT, provider health, automatic document ingest, and drift detection
• maintain continuity across turns, sessions, baselines, branches, and repo boundaries with perspectives, trails, session coverage, federation, persisted memory, and persisted state
• coordinate many agents against one shared runtime while preserving per-agent navigation state, perspective isolation, and resumable handoff context
• monitor and verify the system over time with audits, graph-vs-disk checks, daemon watches, alerts, metrics, diagrams, panoramic scans, reports, runtime overlays, and persisted state
• prepare, preview, and apply connected edits with graph-aware context, including atomic multi-file writes and post-write verification through apply_batch
• learn from feedback and reinforce useful paths over repeated investigations through automatic plasticity and explicit feedback
• measure savings, inspect the live runtime surface, and route itself with built-in reporting and help

What That Intelligence Covers

• Structure: repo shape, dependencies, neighborhoods, hidden relationships, graph-aware retrieval, type flows, architectural layers, and guided routes beyond raw text matches.
• Change: blast radius, co-change prediction, missing work, structural claims, counterfactuals, drift, simulations, proof states, next-step hints, and graph-aware edit preparation, atomic multi-file execution, or post-write verification.
• Docs: universal document ingestion, graph-native L1GHT, provider health, automatic ingest, bindings between specs and implementation, local-first document runtime behavior, and document drift detection.
• Operations: audits, graph-vs-disk verification, daemon monitoring, alerts, metrics, diagrams, runtime overlays, panoramas, savings, reporting, built-in help, and recovery-oriented workflow routing.
• Continuity: perspectives, trails, session coverage, boot memory, persisted state, feedback-driven reinforcement, multi-agent isolation, and cross-repo or cross-session investigative state.

How m1nd Thinks

Most code intelligence tools treat a repo as a flat index. m1nd treats it as a system of relationships.

• Spreading activation moves signal through topology, semantics, recency, and directed flow so the agent can find connected neighborhoods rather than isolated keyword hits.
• Ghost edges lift hidden coupling from git history, including files that often change together without an explicit import.
• Impact and counterfactuals turn "what if I touch this?" into a graph question before the edit happens.
• Hebbian plasticity reinforces useful paths from repeated feedback, so the graph can preserve local project memory over time.
• L1GHT and universal document ingest let specs, claims, citations, and implementation bindings live in the same graph as code.
• Context Guard and recovery tools keep agents honest when a host is stale, bound to the wrong repo, missing recovery tools, or operating through a dead MCP transport.

The result is not just retrieval. It is structured orientation, change reasoning, and recovery behavior that an agent can call before acting.

What m1nd Is Not

m1nd is not just:

• a code search tool with a larger index
• a repo RAG layer that only retrieves files or chunks
• a graph database that leaves workflow decisions to the client
• a static analysis replacement for the compiler, tests, or security tooling
• an MCP bundle of unrelated utilities

It is the layer that turns those surfaces into an operational system an agent can reason over and act through.

Capability Map

The live MCP surface evolves with releases. Use tools/list for the exact tool count and names in your current build.

Quick Start

If you want the shortest path to value:

git clone https://github.com/maxkle1nz/m1nd.git
cd m1nd
npm install -g .
m1nd doctor

Then install the agent doctrine for your host:

m1nd install-skills codex
m1nd install-skills generic --project /your/project

For the native MCP runtime from the same checkout:

cargo build --release
./target/release/m1nd-mcp

Then connect it to your client using the integration matrix.

The canonical live tool names are the bare names returned by tools/list, such as ingest, activate, and audit.

Then start with this trust loop:

// 0. Trust the binding in one call
{"method":"tools/call","params":{"name":"trust_selftest","arguments":{"agent_id":"dev"}}}

// 0b. If you need the cheaper sub-check only
{"method":"tools/call","params":{"name":"session_handshake","arguments":{"agent_id":"dev"}}}

// 0c. If the task names an absolute repo/scope, pass it so Context Guard can
// detect "active repo A graph, asked about repo B" before retrieval lies by silence.
{"method":"tools/call","params":{"name":"session_handshake","arguments":{"agent_id":"dev","scope":"/your/project"}}}

// If your host only exposes health, read its tool_surface_contract first
{"method":"tools/call","params":{"name":"health","arguments":{"agent_id":"dev"}}}

// 1. If the selftest is not full_trust, ask for the recovery path
{"method":"tools/call","params":{"name":"recovery_playbook","arguments":{"agent_id":"dev"}}}

// 2. Build graph truth
{"method":"tools/call","params":{"name":"ingest","arguments":{"path":"/your/project","agent_id":"dev"}}}

// 3. Get a single-request structural orientation pass
{"method":"tools/call","params":{"name":"audit","arguments":{"agent_id":"dev","path":"/your/project","profile":"auto"}}}

// 4. Ask a structural question
{"method":"tools/call","params":{"name":"activate","arguments":{"query":"authentication flow","agent_id":"dev"}}}

Before risky edits, move to impact, predict, and validate_plan, then use surgical_context_v2 for connected edit prep.

If docs or specs matter too:

{"method":"tools/call","params":{"name":"ingest","arguments":{
  "path":"/your/docs","adapter":"universal","mode":"merge","agent_id":"dev"
}}}

For graph-native semantic docs, use adapter: "light" instead.

Agent Pack Install

m1nd includes a universal agent pack so the same operating model can be used from Codex, Claude, Gemini, Antigravity, Cursor, Cline, Roo, Continue, OpenCode, and other MCP-capable hosts.

Install the beta agent pack:

npm install -g @maxkle1nz/m1nd@beta
m1nd doctor
m1nd pack-check

From a source checkout:

npm install -g .
m1nd install-skills codex
m1nd install-skills claude --project /your/project
m1nd install-skills gemini --project /your/project
m1nd install-skills antigravity --project /your/project

The npm installer currently installs the doctrine, portable host files, config snippets, and diagnostics. The native runtime is still m1nd-mcp; build it from source or point your host at an installed binary.

m1nd mcp-config codex
m1nd mcp-config generic
m1nd restart --source /path/to/m1nd --yes
m1nd pack-check

m1nd restart is the external repair button for agents. It is useful when a host is still launching an old m1nd-mcp, reports Transport closed, or keeps a stale MCP process alive. With --yes, it builds from the source checkout, installs the native runtime to the default m1nd binary path, and stops visible m1nd-mcp processes. The host still needs to restart or rebind afterward so it can launch the updated binary.

In live multi-agent work, use --no-kill when you want to update the managed binary without interrupting active hosts:

m1nd restart --source /path/to/m1nd --yes --no-kill

For every host that supports environment variables, prefer setting M1ND_WORKSPACE_ROOT to the real repository/workspace. It is the portable signal used across Codex, Claude Code, Antigravity, Gemini, Cursor, Windsurf, VS Code, and generic MCP clients.

When an agent is working across repos, pass the intended absolute repo or subtree as scope to session_handshake, trust_selftest, recovery_playbook, doctor, or validate_plan. Context Guard returns wrong_workspace_binding when the host is bound to one workspace but the tool call targets another. That is not graph staleness. Rebind the host with M1ND_WORKSPACE_ROOT set to the requested workspace, ingest that workspace on the same binding, or use explicit federation if the task truly spans repos.

See docs/AGENT-PACKS.md for the full install map.

Windows is part of the universal target. The installer emits Windows-safe MCP paths and resolves the runtime in this order: M1ND_MCP_BINARY, M1ND_MCP_BIN, the managed ~/.m1nd/bin path, then PATH. On Windows the managed path is %USERPROFILE%\.m1nd\bin\m1nd-mcp.exe.

The Windows support boundary is the universal MCP lane: m1nd-core, m1nd-ingest, and m1nd-mcp. The m1nd-openclaw fast path remains a Unix socket lane today.

Try The Agent Demo

The fastest way to see the agent-first loop is to run the local demo transcript:

cargo build -p m1nd-mcp
m1nd smoke --repo . --transport stdio

It starts the MCP server, checks trust_selftest, ingests the repo, runs retrieval, asks for help, calls doctor, and verifies that an empty retrieval returns a recovery path. The JSON mode is useful for CI or client onboarding:

m1nd smoke --repo . --transport stdio --json

See docs/AGENT-FIRST-DEMO.md for the transcript shape and how to read it.

If your local demo sees trust_selftest but your editor or agent host does not, use the MCP host refresh guide to compare the host tool surface against the local runtime.

If a host returns Transport closed, treat it as a dead MCP transport, not a stale graph. Restart/rebind the host MCP client or open a fresh session, then run trust_selftest or session_handshake before relying on retrieval.

If a response includes context_guard.wrong_workspace_binding=true, stop before shell fallback. The current graph may be healthy but bound to the wrong repo. Follow the embedded recovery_playbook payload and rebind or federate intentionally.

Default Agent Workflow

Make m1nd the default investigative layer before rg, filesystem globbing, or manual file reads when the task depends on structure, docs, impact, or change.

exact text                -> `search`
path pattern              -> `glob`
purpose or subsystem      -> `seek` or `activate`
unfamiliar repo           -> `audit`
runtime error or trace    -> `trace`
risky change              -> `impact`, `predict`, `validate_plan`, then usually `surgical_context_v2`
docs or specs             -> `ingest` with `universal` or `light`, then `document_*`
long-lived investigation  -> `perspective_*`, `trail_*`, `coverage_session`, `daemon_*`, `alerts_*`, `persist`
unsure what to call       -> `help(stage=..., intent=...)` or `help(error_text="...")`

Detailed client-by-client setup lives in the canonical wiki, the local integration matrix, and deeper examples in EXAMPLES.md.

Evidence

Why m1nd Over Alternatives

m1nd does not replace grep, embeddings, tests, or compilers. It gives agents the structural layer those tools do not provide by themselves.

Agent Testimonials

Jimi - build agent on SAMBA/DOOB

I used m1nd on a large multi-agent builder system with generated artifacts, documentation, tools, and repeated handoffs across long sessions.

The biggest difference was continuity.

Without m1nd, every session starts by rebuilding context from scratch: searching files, reopening docs, and guessing which parts of the system still matter. m1nd changed that. It gave me a structural memory of the project, so I could re-enter through concepts, follow connected neighborhoods, and verify the exact files that mattered.

It did not replace tests, code review, or judgment. It made them easier to reach without losing the thread.

m1nd gave me working memory for a repo that was too alive to navigate by grep alone.

That is why I would want m1nd early in any serious agentic build: not after the project is clean and obvious, but exactly when it starts becoming too interconnected for one conversation to hold.

Limits

m1nd complements rather than replaces:

• your LSP
• your compiler
• your test runner
• your security scanners
• your observability stack

It is most useful before search, review, or change, and whenever docs, impact, or continuity matter.

It is less useful when:

• exact text search already answers the question
• compiler or runtime truth is the only thing you need
• the task is a trivial local file action with no structural uncertainty

Architecture At A Glance

The workspace is split into three core crates plus one auxiliary bridge crate:

• m1nd-core — graph engine and reasoning primitives
• m1nd-ingest — extraction, routing, and graph construction
• m1nd-mcp — MCP server and operational runtime surface
• m1nd-openclaw — auxiliary OpenClaw integration surface

Current crate versions:

• m1nd-core 0.9.0-beta.2
• m1nd-ingest 0.9.0-beta.2
• m1nd-mcp 0.9.0-beta.2

Learn More

• Canonical wiki
• API reference
• Tool matrix
• Architecture overview
• Examples
• Use Cases
• Deployment & Production Setup
• Docs surface guide
• Release notes

Contributing

Contributions are welcome across:

• extractors and adapters
• MCP/runtime tooling
• benchmarks
• docs
• graph algorithms

See CONTRIBUTING.md.

License

MIT. See LICENSE.