m1nd

为你的编码 Agent 提供一张可核验的地图

m1nd 是面向 MCP 编码 Agent 的本地代码图谱和证据关联记忆。 查找关联代码、检查更改的影响，并将已验证的发现带入下一次会话。答案包含可信度信号和明确的缺口，让你的 Agent 知道哪些内容仍需核查。

专为需要处理陌生代码库、多文件更改或反复进行 Agent 会话的开发者打造。使用你现有的 MCP 宿主；运行时采用 Rust，许可证为 MIT。

开始使用 · 工作流 · 能力边界 · 文档

为什么要将它添加到你的 Agent？

• 从代码库的结构入手。 north 会结合任务上下文、有限范围的源代码摘录、绑定可信度、以往记忆和建议的下一步操作。seek 用于查找候选项；impact 帮助你在编辑前检查它们的关联项。
• 让发现与代码保持关联。 memorize 会将声明与证据路径及来源信息一同保存。下一次会话可以调取这些内容，并检查它们是否仍然适用。
• 在多个 Agent 之间共享上下文。 由本地服务的所有者可以与已连接的客户端共享一个图谱。在线状态和重叠警告有助于 Agent 协调；它们只是建议，不是锁。
• 了解不确定性。 reverify、abstain 和 insufficient_evidence 都是有用的结果。图谱连接是检查代码的理由，并不能证明更改是安全的。

图谱和记忆保存在你的计算机上。m1nd 的图谱查询不需要 LLM API 密钥。安装、更新、可选模型下载以及依赖网络的文档提供方可能会使用网络，或向已配置的端点传输文档；你的 MCP 宿主有自己的数据策略。

开始使用

版本很重要： GitHub/native 1.6.5、crates.io 软件包和 npm 1.6.5 均由不可变提交 363bc97f2336c73e90802916804dccd2109c5746 发布；截至 2026-10-12，npm latest 为 1.6.5。学习事件分离功能在 PR580 中合并，属于 未发布 内容，尽管源代码软件包版本仍标为 1.6.5。

已发布的 1.6.5：获取第一个结果

你需要 Node.js 18+ 和一个可读取的代码库。安装签名的原生 1.6.5 构件，然后在代码库中运行以下 POSIX shell 命令：

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/[email protected] agent first-minute --repo . \
    --binary "$M1ND_BINARY" --query "where is configuration loaded?" --json
)

first-minute 会先查找能够覆盖该代码库的服务所有者。否则，匹配的封装程序／原生运行时只会在外部私有缓存中准备由启动器明确授权的那个代码库。源文件仍是输入。只有在复用自动隔离缓存时，CLI 才会在检索前刷新声明的根目录。已连接所有者的新鲜度遵循所有者自身的语义；请检查该所有者的版本、代码库绑定和新鲜度，不要根据所选客户端二进制文件推断。检查 runtime.boot、返回的源代码位置和缺口。这并不授权你创建共享 brain、移动绑定或调用通用的 ingest。

要连接 MCP 宿主，请参阅 1.6.5 快速入门。直接使用 stdio 需要明确的工作区授权和现有的外部私有运行时；共享所有者有单独的准备和授权要求。请参阅 Agent 自主性。

历史固定版本 1.6.3：安装、准备、连接

你需要 Node.js 18+、一个 MCP 主机和一个代码仓库。首先安装经过签名的原生 1.6.3 制品；该指南使用 cosign 和精确的发布 URL。预构建的 1.6.3 版本支持 Linux x86_64 和 macOS x86_64/ARM64。在你要使用的代码仓库中运行此 POSIX shell 配方；它会有意固定包装器版本：

# 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/[email protected] init --birth . --binary "$M1ND_BINARY"

# Preview your host configuration before applying it.
npx -y @maxkle1nz/[email protected] hosts plan --host claude --project . --binary "$M1ND_BINARY"
npx -y @maxkle1nz/[email protected] hosts apply --host claude --project . --binary "$M1ND_BINARY" --yes

将 claude 替换为你的主机，例如 codex 或 cursor。按照输出的说明操作：某些由主机管理的配置和钩子会打印出来供你安装，而不会自动写入。配置更改后重启或重新连接主机。有关主机特定行为，请参阅主机集成矩阵。

重新连接之前，将 M1ND_RUNTIME_DIR 添加到生成的 MCP 服务环境中，并使用 echo "$M1ND_RUNTIME_DIR" 打印出的同一个绝对路径。保留生成的 M1ND_WORKSPACE_ROOT。hosts apply 不会替你添加运行时选择器；如果缺少该变量，从其他位置启动的主机可能会打开不同的图谱。

此配方针对原生 1.6.3。仅固定 npm 包装器并不能固定 update apply；该命令遵循注册表通道，因此这里有意不包含它。如果所选二进制报告了不同的版本，请先检查该版本的设置约定，再继续操作。创建图谱的命令需要由人在终端中执行，而不是作为 Agent 工具调用。其回执必须报告 brain: "owner_bound_graph"、预期的 born_root、store_dir 中的确切运行时，以及 node_count > 0。如果命令拒绝执行，请遵循其诊断信息，不要替换其他运行时或强制执行 ingest。对于源码构建，请使用下方单独的贡献者流程。

你的第一个实用结果

向已连接的 Agent 提问：

使用 m1nd 帮我了解这个代码仓库。找出配置的加载位置，展示相关源代码位置，并告诉我还需要验证什么。不要编辑文件。

Agent 应先调用 north，然后按需使用 seek 并检查源代码。**成功意味着回复涵盖了正确的代码仓库，并指出了你可以打开的真实代码。**在当前校准隔离机制下，预期会得到 reverify 判定；请检查证据。图谱缺失或绑定到错误的工作区需要恢复处理；结果为空时，可能需要更换查询。

快速入门故障排除涵盖二进制缺失、主机配置和绑定错误。你的第一个查询展示了实际的 MCP 调用。

尚未发布的 main：学习事件分离

对于测试尚未发布的学习修复的贡献者，请明确选择包含 PR580 的 main 修订版，并使用与之匹配的包装器和原生运行时。仅凭版本字符串无法确认修复是否存在。--binary 用于选择 CLI 使用的可执行文件，但默认发现机制仍可能将它连接到旧的覆盖所有者。使用 --no-attach 并清除环境中的运行时/附加覆盖设置，以便在自动隔离缓存中运行此确切修订版：

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 的学习语义已在 main 中提供，但不包含在封存的 1.6.5 制品中。自动隔离准备已在 1.6.5 中发布；它不是 PR580 的预览功能。请参阅启动器约定。贡献者开发工具包为开发提供仅属于当前检出目录的状态。

接下来可以尝试什么

任务	从这里开始	操作前检查
理解不熟悉的代码	north → seek → surgical_context	打开返回的源代码；检查工作区绑定和信任范围。
规划跨文件更改	对返回的节点使用 impact 和 why	使用源代码／编译器工具确认调用方和导入；未解析的边意味着存在缺口。
继续调查	north、boot_memory 或 trail_resume	重新使用某项结论前，先检查证据、作者、时效和任何过期标记。
保留已验证的发现	使用带仓库相对证据路径的 memorize	记录你实际验证过的内容，而非 Agent 未经测试的结论。
协调并行 Agent	一个已服务的所有者和附加客户端	将重叠通知视为协调请求；它们不会阻止编辑。

参见示例、用例和工具参考。默认工具菜单刻意保持精简。help 可发现完整注册表；M1ND_TOOL_TIER=full 会扩展显示的菜单。已发布的 1.6.5 还提供 M1ND_TOOL_TIER=investigate：核心工具加上五个会话本地快照工具。参见初学者与进阶用法。1.6.5 中的图关联搜索会为单文件导入根保留规范节点 ID；存在歧义的文件映射会被省略。列出的工具或可调用的工具仍可能需要当前会话不具备的权限。

它能证明和不能证明的内容

• **最适用场景：**结构导航、变更准备以及在反复工作中保持连续性。对于微小修改或精确字符串查找，读取文件或使用 rg 可能就足够了。
• **提取结果是近似的。**语言支持各不相同，可能会遗漏宏生成的引用和动态引用，外部导入也可能仍未解析。图谱不是编译器的语义模型。
• **信任有条件限制。**已发布的 1.6.5 和当前 main 都将所有 v1 校准行视为未达资格的证据：预测会放弃判断，seek 范围保持在 reverify 或 unprovable，但分数和排名仍可用。运行校准不会启用 act。对于你的更改，请使用源代码、编译器、测试和运行时检查。时钟修复并不能证明统计质量。
• **尚未发布的学习反馈仅用于相关性调整。**在 PR580 之后的 main 上，内部 learn(correct|wrong) 会调整图谱相关性权重；它不会记录缺陷、误报、观察到的协同变更或自动抗体。若反馈含糊不清，系统会拒绝处理 partial，且不进行修改；强度为零时不执行任何操作。此更改未包含在封存的 1.6.5 中。公共学习和校准权限下限仍处于阻止状态。参见事件边界。
• **写入操作有额外限制。**预览／提交工具、证明许可和权限检查与只读检索相互独立。图谱／静态验证不能替代实际执行测试。参见写入参考。
• **本地不等于已认证。**已服务的所有者会拒绝非环回绑定；仅使用环回地址并不能对其他本地进程进行身份验证。参见部署说明和安全说明。
• **高级功能不是设置的前提条件。**文档适配器、结构启发式方法、移植、任务和硬件支持的权限各有其限制。PRD 描述的是设计意图，不能证明某个版本支持所有路径。

共享上下文，由一个本地所有者管理

准备好仓库的运行环境后，使用回执中的确切 store_dir（下方显示为 /absolute/path/to/project/.m1nd）启动一个所有者，并将客户端连接到它：

export M1ND_BINARY="$HOME/.local/share/m1nd/versions/1.6.3/m1nd-mcp"
"$M1ND_BINARY" --serve --no-gui --port 1337 --runtime-dir /absolute/path/to/project/.m1nd
# Run each client from the repository it should query:
"$M1ND_BINARY" --attach auto --stdio

所有者持有图；连接的客户端不会加载另一份副本，也不会获取写入租约。自动发现必须找到一个已覆盖调用方仓库的所有者。它不会授权创建新的共享大脑。该服务所有者也可以呈现 Web UI。配置多个仓库或持久启动前，请遵循部署指南。

可供检查的证据

相比没有限定条件的速度或节省声明，优先查看复现及其适用范围：

• 基准测试方法和 wiki 证据指南区分合成引擎计时、历史语料运行和端到端产品测量。这些都不是通用的投资回报保证。
• 持久化集成测试会在干净启动和中断运行期间，通过真实的 stdio 进程进行测试。
• Agent 自主性测试与契约准确描述了源代码实现的自动启动、身份识别和关闭路径。
• 测试组合说明了范围限定的 PR 门禁和完整集成矩阵。当前的源代码变更并不自动代表已发布版本。

以下演示是 m1nd-mcp 1.4.0 的历史录制内容，并非当前安装流程，也不构成性能承诺：

语言覆盖

专用提取器覆盖二十多种语言，从 Python 和 TypeScript 到 Elixir、Haskell 和 Zig，并由 m1nd-ingest 根据文件扩展名进行路由。下表记录了在多语言导入中测试过的调用边和跨文件导入提取。这并不表示解析完整或达到编译器级别；带限定名的 Rust 调用、宏和动态引用可能会降低精度。

语言	calls	跨文件导入
Rust	✅	✅
Python	✅	✅
JavaScript / TypeScript	✅	✅
Go	✅	✅
Java	✅	✅
C / C++	✅	✅
Kotlin	✅	✅
PHP	✅	✅
Scala	✅	✅
Ruby	⏳	✅
C#	✅	命名空间与文件并非一一对应
Swift	✅	尚未支持

无法解析的导入（外部包、标准库、系统头文件）会保留为无法解析，而不是猜测。其他情况则回退到仅支持 contains 边的通用提取器。

架构与深入文档

Cargo 工作区包含六个 crate：m1nd-core（图引擎）、m1nd-ingest（提取）、m1nd-mcp（MCP 所有者和运行环境）、m1nd-control、m1nd-runnerd（执行通道）和 m1nd-openclaw（桥接）。Web UI 和 npm 封装程序位于 Rust 工作区之外。

• 文档索引：选择一项任务，再查看相应指南
• Wiki：教程、概念和 API 参考
• Agent 安装指南：面向编码 Agent 的设置说明
• 变更日志：发布历史
• 贡献指南：开发与验证

翻译

Português · Español · Italiano · Français · Deutsch · 中文 · 日本語

这些翻译尚未根据此英文版本更新，可能包含过时的设置或功能说明。当前说明请以此英文 README 为准。

许可证

MIT。你的图源自你的代码；记忆文件仍保留在磁盘上。请参阅 LICENSE。