MGI-Mind

MGI-Mind

English | Русский | 中文

最新版本：v2.8.2 · 更新日志 · 讨论 · 问题 · 贡献指南

为 AI 助手提供本地长期记忆。一个 Rust 二进制文件、一个本地 Qdrant 向量数据库，以及本地 ONNX 模型。它支持 MCP，因此 Claude Code 和其他 助手可以自行读取和写入记忆。它也可以作为常规命令行工具使用。

用通俗的话存储一条事实，再用一个不包含任何相同词语的查询回忆它。语义搜索会匹配意图。你的助手也会通过 MCP 自行运行同一个 mind_search。使用 vhs docs/demo.tape 重新生成。

助手中的同一段交互：

You:  what was the deploy server again?

Assistant (calls mind_search "deploy server"):
  -> "Deploy server is 10.0.0.5:8080, SSH as deploy@, key in vault"  (source: infra.md)

You:  right, thanks

所有内容都不会离开本机。嵌入、搜索、重排和保险库 都在本地运行。无需云账户、API 密钥，也没有遥测。

---

目录

• 它是什么
  • 有效性模型
• 为什么要用
• 快速开始
• 使用方法
• 工作原理
• 命令参考
• 配置
• 语言与重排器
• 更改嵌入模型
• 故障排除
• 安全
• 状态与审计
• 项目布局
• 许可证

它是什么

MGI-Mind 位于你和助手之间。助手会在对话过程中写入简短 笔记（“记忆”）和事实，并在需要时取回相关内容。

不仅仅是存储，还能检索：

• 混合搜索。 每条记忆会存储为两个向量：一个用于含义的稠密向量 （multilingual-e5-base，768 维），以及一个用于精确匹配词语的稀疏词频 向量（TF-IDF，BM25 风格）。查询会同时运行这两路搜索， 并使用 Reciprocal Rank Fusion 融合结果。“The server box”可以通过稠密搜索 找到“deploy host”；fossilize_replay 则能通过稀疏搜索找到包含该确切词元的那条笔记。
• 交叉编码器重排。 融合后的候选结果会由 bge-reranker-base 重新评分。它会同时读取查询和每段文本， 准确度高于比较向量。默认启用并针对英语调优； 其他语言的取舍请参阅语言与重排器。
• 单个常驻进程。 mgimind mcp 本身就是 MCP 服务：它会在整个会话期间运行， 模型只加载一次并常驻内存，因此查找只需几毫秒，而不必每次调用都重新加载。

除检索功能外，它还提供用于结构化事实的知识图谱、用于跨会话延续的逐 Agent 会话日志，以及一个仅可通过终端访问的加密保险库，用于存放机密信息。

有效性模型

混合搜索只是基本配置；大多数记忆工具都具备某种形式的混合搜索。 更难找到的是能防止存储内容随着旧有、相互矛盾或不断自我强化的观念逐渐僵化的机制。这些机制大多会自行运行：

• 对决规则。 当新事实与同一主体和谓词上的现有事实相矛盾时，第二次写入会与第一条进行裁决，而不是叠加出第二个“真相”。根基牢固的事实（依赖项多、确认次数多、存在时间长）会占上风；强有力的新事实会将其翻转，并把落败事实降级为隐藏的 stale 状态；势均力敌时则标记为有争议，或转入隔离区。确认次数会实时累积：重新断言同一三元组会增加其自身的 confirmations_count，因此，经过几次确认的事实能够抵御单次新矛盾（标记为有争议，而非翻转），而未经确认的年轻事实仍会像以前一样容易翻转。dependants 仍然只能通过 migrate-v14 dependants --apply 回填得到——尚未实现低成本的实时生成机制（因为这意味着每次写入都要遍历图谱）。不会删除任何内容，因此审计日志会保留落败事实；再次提议已变为 stale 的落败事实时，它会与当前事实重新公平对决，同时保留自身原始的 created_at 和确认历史，而非从头开始。此机制会在常规的 mind_fact add 内自动执行。
• 质疑窗口。 根基牢固的事实必须不断重新证明自身。每次查询事实时，都会测量当前上下文相对于事实写入时上下文的偏移程度；连续检索到偏移上下文五次后，该事实的排序就不再高于仍然站得住脚的事实，而任何一次上下文匹配的检索都会将计数重置。不会隐藏或删除任何内容。由于原始余弦相似度无法在各向异性的嵌入空间中区分主题，因此会先从向量中减去语料库均值，再测量偏移（见下文的 mgimind calibrate）。当前上下文取自运行中进程近期的查询，因此此机制适用于热启动的 mgimind mcp 或 serve-http 会话；一次性 CLI 命令尚无上下文，因此不会惩罚任何事实。此功能以影子模式发布：会测量并记录偏移，但不会更改任何事实；你需要根据自己存储中的数据设置 doubt_drift_threshold，并将 doubt_drift_mode 切换为 "enforce"。后台任务还会单独重新测试已沉寂的根基牢固事实，并遵守严格保障：绝不在工具调用期间运行、每个周期设有上限，并根据负载调整运行频率。
• 继承折扣。 mind_context 的简报（会话启动时看到的内容）会将其呈现的每条事实标记为该进程继承的事实。如果对决中的挑战事实是对其中某条继承事实的重新提议——也就是 Agent 复述收到的信息，而非实时独立确认——该挑战的权重会减半。Agent 实时重新断言该事实并且未产生冲突后，此标记会立即清除。单一来源衰减（同一来源重复确认时，每次确认的权重依次降低）已有计算公式（diversity_weighted_count），但尚无实时调用方——未实现，因此目前不保证“不能由同一来源共同确认”。
• 事实上的两条时间轴。 记录时间（created_at/valid_until：存储何时获知或退役某个值）通过被取代的事实链实现双时态功能：可将谓词注册为（mind_predicate）单值型、时态单值型（只有一个当前值，但会保留先前的值，并可通过 mind_history 按日期查询），或多值型；被取代的值会从默认排序中隐藏，而非删除。可选的第二条时间轴是世界时间（valid_from，可在添加时设置），用于记录事实在现实世界中何时变为真，而非存储何时得知此事；mind_fact action=query 配合 as_of 和 world_time=true 可据此解析特定时间点的查询；若某条事实没有 valid_from，则会回退到记录时间。现有事实无需迁移——它们只是没有 valid_from，行为与以前完全相同。
• 显式失效不可撤销。 mind_fact action=invalidate 是单向操作：此后重新添加相同三元组会被拒绝（裁决结果为 invalidated），而不会悄然恢复。只有 mind_fact action=restore 才能恢复。
• 带类型的结果信号。 mind_outcome 会记录已记住的修复是否确实奏效（test_passed、code_compiled、user_confirmed、cited_by）。实际成功会提高记忆的权重并将操作流程标记为已验证；失败则会降低权重，而非被忽略。 这些是具有研究性质的机制，其调优常量仍在校准中（duel.rs / doubt.rs 中的 TODO(phase-4-calibration) 标记如实反映了这一点）。重点在于这种机制的结构：记忆会自我辩驳，并降低那些经不起检验的内容的权重，而不是无止境地不断累积。

mgimind calibrate 会衡量这种机制是否按预期运行。它会将一组真实的冲突情境输入实际运行的对决公式，并报告有多少情境得出了人们预期的结果：缺乏支持的新主张无法推翻根深蒂固的信念，CI 信号则可以；单纯重复的内容会与现有记忆共存，而不会将其覆盖。目前，15 个情境中有 14 个符合预期；未符合的那一个会连同原因一起显示出来，不会被隐藏，而且测试套件会在 CI 中运行。它还会报告疑问窗口的漂移分布，而这份报告正是因为实际测量发现了问题才加入的。漂移阈值原为 0.4，是在 384 维 MiniLM 空间中选定的；默认模型改为 768 维 multilingual-e5 后，阈值仍未调整。在实时存储中测量 400 条记忆及全部 79800 个配对后，原始余弦值介于 0.666 到 0.972 之间：这个阈值一次也无法触发。语料库均值向量的范数为 0.884，因此这些余弦值几乎全部来自每个嵌入共有的分量。中心化修正了测量方式，而 calibrate 会根据你自己的存储产生的漂移来建议阈值，而不是沿用一个从一种嵌入空间移植到另一种的常量。

这衡量的是有效性模型的结构，与检索召回率（R@k，见 BENCHMARKS.md）分开。两者是不同的数值，绝不能放在同一张表中。

为什么要用

没有记忆的助手每次会话都会询问相同的上下文，也无法在昨天的工作基础上继续推进。常见的变通办法是由你自己维护笔记、标签和文件夹，但助手仍然无法按含义读取它们。

MGI-Mind 与 Obsidian 和 Notion 的不同之处：由系统决定记录什么，而不是由你决定。 MCP 服务会实时读取助手的操作，并通过相关性闸门将事实、决策和修复方案存入存储。你不必归档、不必打标签，也不必判断哪些内容值得保存。低相关性候选内容会进入隔离层（再次确认时可恢复），而不是污染检索结果。

与显而易见的替代方案相比：

• 普通笔记（Obsidian、Notion）。 作为个人笔记本很出色，但助手无法按含义搜索它们，而且对一个 .md 文件文件夹来说，每次按键都同样重要。
• 裸向量数据库。 支持语义搜索，但不支持精确词项匹配、重排、去重、会话、事实、机密信息处理、相关性闸门或程序性记忆。这些都要由你自行组装。
• 托管记忆 API。 数据存放在别人的服务器上。你无法检查内部机制、去重行为，也无法了解相关性闸门实际在做什么。

MGI-Mind 是组装好的本地方案：混合检索与重排、相关性闸门、去重、事实、会话、程序性记忆（“错误 → 修复”手册），以及仅通过终端访问的保险库，全部集成在一个由你自行运行的二进制文件中。

关于如何评估它。BENCHMARKS.md 报告的是检索召回率（在 LongMemEval-S 上测得的 R@k，不调用 API，也不使用大模型评判）：给定一个问题，金标准会话是否出现在前 k 个结果中。在默认 CPU 配置下，R@5 ≈ 98%。这与其他记忆工具发布的问答准确率指标不同（它们会对检索结果运行回答器和评判器），因此不要把它们放在同一张表里比较。该指标衡量的是证据能否被检索到，而不是大模型随后能否正确作答。mgi-mind 不包含回答步骤，因此检索召回率才是它真正负责的指标。

需要坦诚说明的差距：有效性模型（对决规则、疑问窗口、取代机制）才是差异化所在，而检索召回率并不能检验它。可以通过两项测试来检验。mgimind calibrate 会根据预期检查行为特征（目前为 14/15，可自行运行）；它能证明该机制的表现符合读者预期，但无法证明这些参数已根据真实数据调优。外部信念修正基准测试已过时，目前只有一次初步的部分测试（N=155，约 32%，原始判定结果位于 benchmark/results/）。这次测试由某个分支上的测试框架运行，而非 main 上的脚手架；使用了缩减后的候选集，并且当时对决规则可能仍未修复。完整注意事项请参阅 BENCHMARKS.md。应将有效性模型视为一种设计好的机制：其行为特征已通过验证，但参数尚未调优，而不是已在外部数据上证明有效的方案。

快速开始

Docker（一条命令启动完整记忆系统）

该镜像内置二进制文件、打包的 Qdrant、ONNX 运行时和模型，因此无需安装任何内容即可离线运行：

docker run -p 8765:8765 madgodinc/mgi-mind

启动时会打印一个 bearer token。使用该 token，将 Python 客户端或任意 Agent 指向 http://localhost:8765。使用卷在重启后保留记忆，并固定一个稳定的 token：

docker run -p 8765:8765 -e MGIMIND_TOKEN=your-token \
  -v mgimind-data:/data madgodinc/mgi-mind

接入 Agent

为 Agent 提供 recall 和 remember 两个工具，其记忆就能跨进程保留。在服务运行且已安装 Python 客户端的情况下：

from mgimind import Memory

mem = Memory()                         # MGIMIND_URL / MGIMIND_TOKEN from the env
mem.add("Prod DB is Postgres 16 on db-prod:5432")
for hit in mem.search("prod database"):  # structured results: id, score, author
    print(hit["score"], hit["content"])

这层封装就是完整的集成。LangGraph、Pydantic AI、OpenAI Agents SDK 和原始 HTTP（任意语言）的复制粘贴示例位于 docs/integrations。MCP 和 stdio 仍适用于编辑器客户端；HTTP 接口则是 Agent 框架的入口。

npm（适用于任何 MCP 客户端）

使用 Node.js 18 或更高版本时，npm 包会安装适用于你平台的预编译二进制文件，并根据该版本的 SHA-256 校验：

npx -y mgi-mind init          # creates ~/mgimind
npx -y mgi-mind doctor --fix  # downloads Qdrant and the models
claude mcp add mgimind -- npx -y mgi-mind mcp

其他客户端在 MCP 配置中使用相同的命令： "command": "npx", "args": ["-y", "mgi-mind", "mcp"]。

原生安装

只需一条命令。安装程序会将二进制文件放到 PATH 中，并运行 init + doctor --fix（该命令会下载 Qdrant、ONNX Runtime 和模型）。或者，直接让你的编码 Agent 使用 AI_INSTRUCTIONS.md 安装 mgi-mind： 它涵盖了安装本身，而不只是安装后如何使用。

Linux / macOS：

curl -fsSL https://raw.githubusercontent.com/madgodinc/mgi-mind/main/install.sh | sh

Windows（PowerShell）：

irm https://raw.githubusercontent.com/madgodinc/mgi-mind/main/install.ps1 | iex

完成后，打印出的命令会将服务接入 Claude Code：

claude mcp add mgimind -- /home/you/.local/bin/mgimind mcp

mgimind mcp 就是 MCP 服务；它会在整个会话期间运行，使模型保持就绪，并在首次使用时启动捆绑的 Qdrant。让你的助手阅读一次 AI_INSTRUCTIONS.md，使其了解协议（记录会话、回答前先搜索、使用保险库存放密钥）。

doctor --fix 会将模型下载到 ~/mgimind/：嵌入模型（multilingual-e5-base，量化 ONNX，约 270 MB）和重排模型（bge-reranker-base，量化 ONNX，约 280 MB）。ONNX Runtime 和 Qdrant 二进制文件会放在 mgimind 二进制文件旁边，因此 doctor 报告缺少库时，指的是 <install dir>/，而不是 ~/mgimind/。

安装程序标志

• INSTALL_DIR=/opt/mgimind curl ... | sh：安装到 ~/.local/bin 以外的位置。
• MGIMIND_TAG=v2.8.2 curl ... | sh：指定特定版本，而不是使用 latest。
• SKIP_DOCTOR=1 curl ... | sh：仅放置二进制文件；稍后自行运行 init + doctor --fix。

手动安装（不使用安装程序）

如果你不想将脚本传递给 shell，可以从 Releases 获取适用于你操作系统的发布压缩包， 将 mgimind 放到 PATH 中，然后：

mgimind init
mgimind doctor --fix
claude mcp add mgimind -- /absolute/path/to/mgimind mcp

从命令行试用（同一个二进制文件也可以在没有助手的情况下运行）：

mgimind create work
mgimind add work "Deploy server is 10.0.0.5:8080, SSH as deploy@"
mgimind search "how do I reach the deploy box"

各操作系统注意事项

• Linux x86_64、macOS arm64 和 x86_64、Windows x86_64：每个版本都提供预编译二进制文件。安装程序会选择合适的版本。
• macOS PATH：zsh 默认不包含 ~/.local/bin，因此安装程序会将 export PATH 行追加到你的 ~/.zshrc，并告知你已完成此操作。在输入 mgimind 前，请打开一个新终端。设置 MGIMIND_NO_PROFILE=1 可避免安装程序修改你的点文件，你可以自行添加该行。
• macOS Intel 和 ONNX Runtime：1.24 移除了 osx-x86_64，因此 Intel Mac 会获取 ONNX Runtime 1.23.0，其他设备则会获取 1.24.2。二进制文件请求 C API 23，两种运行时均支持该版本。
• macOS 首次运行隔离：安装程序会清除隔离属性，但通过浏览器下载的二进制文件需要运行 xattr -d com.apple.quarantine /path/to/mgimind。发布版本采用临时签名，未经公证；在 Sequoia 及更高版本中，右键 →“打开”的方法不再适用于命令行二进制文件，因此请使用 xattr，或前往“系统设置”→“隐私与安全性”批准一次。
• Windows：SmartScreen 可能会对未签名的 mgimind.exe 发出警告（“Windows 已保护你的电脑”）；请选择 更多信息 → 仍要运行。防病毒软件也可能隔离该二进制文件或它下载的模型；如果 mgimind doctor 报告文件已下载但缺失，请在防病毒软件中允许 mgimind.exe 和 %USERPROFILE%\mgimind 文件夹，然后重新运行 mgimind doctor --fix。移除 SmartScreen 提示的代码签名已列入路线图。

从源代码构建

Rust 工具链（rustup）；无需其他依赖项。

git clone https://github.com/madgodinc/mgi-mind.git
cd mgi-mind
cargo build --release                  # binary: target/release/mgimind

然后运行 target/release/mgimind init && target/release/mgimind doctor --fix， 并使用 claude mcp add mgimind -- /absolute/path/to/target/release/mgimind mcp 将其接入。

使用方法

手动使用（CLI）：

mgimind add notes "Mom's birthday is March 14, she likes peonies" --source personal
mgimind search "when is my mother's birthday"
#  1. [notes] (score: 0.94) Mom's birthday is March 14, she likes peonies
#     source: personal

mgimind fact add "user" "prefers" "Rust"
mgimind fact query "user"
#   user -> prefers -> Rust

mgimind history --limit 3              # the three most recent memories
mgimind stats                          # counts per library, facts, sessions

矛盾时的对决规则。 当两条事实相互矛盾，且谓词为 Single 或 TemporalSingle 时，第二次添加会与第一条进行对决并将其解决，而不是不断累积：

# Tell the system this predicate has one current value at a time:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call",
  "params":{"name":"mind_predicate","arguments":
    {"action":"register","predicate":"lives_in",
     "cardinality":"TemporalSingle"}}}' \
  | mgimind mcp

mgimind fact add "Alice" "lives_in" "Prague"
mgimind fact add "Alice" "lives_in" "Dublin"
mgimind fact query "Alice"
#   Alice -> lives_in -> Dublin
# (Prague is preserved as history, queryable via mind_history / audit log
#  but hidden from default ranking.)

如果你从 v1.7 之前的版本迁移而来，且当时对决规则在读取路径上未生效，请运行一次 mgimind migrate-v14 redo-duels --apply，将旧有矛盾归并为规范答案。此遍历操作具有幂等性，默认以试运行方式执行。

通过助手使用（MCP）。 连接后，直接对话即可：

You:  remember that the staging DB password is in the vault under "staging-db"
Assistant: (mind_add) saved. The secret itself stays in your terminal vault, not here.

You:  what database are we using on staging?
Assistant: (mind_search "staging database") Postgres 16, host db-staging.internal:5432

搜索会分层返回结果，帮助助手谨慎使用 token：--tier 1 返回约 100 个字符的片段，--tier 2（默认值）约为 500 个字符，--tier 3 返回全文。

查看存储

mgimind brain 会将记忆渲染为图：核心代表记忆、事实和区域，它们通过彼此之间的链接相连，并会随着存储内容的变化而闪烁。它只绑定到环回地址，并且需要使用与 URL 一同打印出的 token。

请将它视为控制面板。不限权限的查看器还会提供 DELETE /api/memories/:id、PATCH /api/node/:id 和隔离区提升功能，因此任何携带该 token 访问此端口的对象都可以更改存储。如需使用无法写入的查看器，请将其限制在允许列表内启动：

mgimind viewer --libraries work,personal

此模式会默认拒绝所有变更路由（返回 403），以及跨越所有库的路由（图、审计、脉冲、摄取动态）。mgimind brain 不接受任何标志，因此始终以不限权限的形式运行。

工作原理

  your AI assistant
        |  MCP (JSON-RPC over stdio)
        v
  mgimind mcp  (one Rust process: MCP server + embedder, models stay warm)
        |  starts on first use
        v
  Qdrant (local, loopback only)
        |
        one "memories" collection, two vectors per point:
        dense (e5, meaning) + sparse (TF-IDF, exact terms)

存储。 所有记忆都存储在一个 Qdrant 集合中。每个点上的 library 字段用于区分命名空间（工作、个人或项目），查询时可以筛选单个库，也可以跨所有库搜索。点的 ID 是 library + content 的 UUIDv5，因此重复添加相同文本会覆盖同一个点，不会产生重复项或竞争条件。created_at 日期时间索引可让 history 直接返回最新的 N 条记录，无需扫描。

嵌入。 文本通过 ONNX Runtime 在本地生成嵌入。默认模型为 multilingual-e5-base（768 维），对英语效果良好，也能处理混合语言。嵌入器能够感知模型：池化方式（mean 或 CLS）、token_type_ids 输入以及查询／段落前缀都可配置，因此切换模型无需更改代码。输入上限为 512 个 token；add 会将长文本拆分为多个文本块，因此超过上限的内容不会被悄然丢弃。

搜索。 查询只会生成一次嵌入。Qdrant 通过一次 Query API 调用执行稠密近邻搜索和稀疏搜索，并使用 RRF 融合结果。如果启用了重排，排名靠前的 rerank_top_k 个候选项会由交叉编码器重新评分并排序。若提供了 library 过滤条件，该条件会同时应用于两种搜索。

安全性。 下载时会校验固定的 SHA-256 哈希值（校验失败则拒绝操作）。Qdrant 只绑定到环回地址，也可以要求提供 API key。保险库仅能通过终端访问，主密码和解密后的机密信息绝不会通过 MCP 通道传输。文件写入是原子操作（临时文件、fsync、重命名、对目录执行 fsync），因此崩溃后留下的要么是旧文件，要么是新文件，不会是损坏的文件。

命令参考

记忆

命令	功能
mgimind add <library> <content> [--source <tag>]	存储一条记忆。长文本会被拆分，并打印已存储的文本块数量。
mgimind search <query> [--library <l>] [--limit N] [--tier 1|2|3]	执行混合搜索，然后重排结果。Tier 用于设置返回的文本量。
mgimind history [--limit N]	按时间倒序返回最近的记忆。
mgimind delete <library> <id>	按 ID 删除一条记忆（ID 会显示在搜索结果中）。
mgimind context	紧凑的会话启动简报：上次会话、近期事实和库。

库

命令	功能
mgimind create <name>	注册一个库。
mgimind list	列出所有库。
mgimind drop <name>	删除一个库及其中的所有记忆。
mgimind stats	统计各库、事实、会话和保险库状态。

知识图谱

命令	功能
mgimind fact add <subject> <predicate> <object> [--valid-from <date>]	存储一个事实三元组。再次添加相同三元组会增加其确认次数，而不会重复创建；如果某个三元组已被明确标记为无效，则拒绝添加（不会将其恢复）。--valid-from 可选，用于指定该事实在现实中开始成立的日期。
mgimind fact query <term> [--as-of <date>] [--world-time] [--history]	查找主语、谓语或宾语中包含指定词语的事实；--as-of 可用于回溯时间（默认按记录时间；--world-time 则切换为按 valid_from 查询）。
mgimind fact invalidate <id>	软删除一条事实（保留在磁盘上，标记为无效，并从查询结果中隐藏）。
mgimind fact restore <id>	撤销无效标记——这是唯一的恢复方式。

技能

流程回答“这个问题上次是怎么解决的”。技能回答“我即将执行 X，有没有处理 X 的惯常做法”。两者使用相同的存储和结果信号，只是在不同的时机进行匹配：针对任务，在开始工作之前。 上下文渲染会附带目录（名称和触发条件），让助手无需搜索就能知道有哪些技能，并且只在技能适用时才读取其正文。

命令	功能
mgimind skill set <name> --when <trigger> --body <text>	编写技能。名称是其标识，因此重复编写会修改现有技能并保留历史记录。--body-file <path> 可从文件读取正文。
mgimind skill match <task> [--limit N]	查找适用于某项任务的技能，并按相关性和过往效果排序。
mgimind skill list / mgimind skill show <name>	显示目录，或完整显示一项技能。
mgimind skill outcome <name> [--failed] [--verify]	记录应用该技能的结果。--verify 需要确定性信号，而非凭感觉判断。
mgimind skill rm <name>	删除一项技能及其结果历史记录。

会话

命令	功能
mgimind session start --agent <name>	为 Agent 开始记录会话日志。
mgimind session end --agent <name> --summary <text>	添加摘要并结束会话。
mgimind session last [--agent <name>]	显示最近一次会话（可选指定一个 Agent）。

保险库（仅限终端）

命令	功能
mgimind vault store <key> <value> [--category c] [--desc d]	存储加密密钥。
mgimind vault get <key>	获取密钥（提示输入主密码，然后进行确认）。
mgimind vault list	列出密钥名称（绝不显示密钥值）。
mgimind vault delete <key>	删除一个密钥。

服务和数据

命令	功能
mgimind mcp	通过 stdio 作为 MCP 服务运行（助手连接到此服务）。单个常驻进程；会自动启动 Qdrant。
mgimind serve / mgimind stop	手动启动 / 停止捆绑的 Qdrant（很少需要，mcp 会自动处理）。
mgimind migrate [--purge]	将旧版的各知识库集合重新嵌入到单个 memories 集合中。可幂等执行。--purge 会在之后删除旧集合。
mgimind relibrary --from <lib> --to <lib> (--source-match <re> | --content-match <re> | --ids-file <path>) [--apply]	将记忆移至其他知识库。点 ID 基于内容生成，因此移动时会重新计算目标 ID，原样保留向量和负载，更新任何 cited_by 引用，并删除旧点。默认执行试运行；如果目标 ID 已被无关内容占用，会报告而不会覆盖；中断后可安全重新运行。
mgimind backup <file> / mgimind restore <file>	对数据目录进行 gzip+tar 打包。Qdrant 有响应时，会通过各集合自己的快照 API 捕获数据，而不是直接复制 qdrant/storage，因此并发写入不会损坏备份；始终排除 models/（可通过 doctor --fix 重新下载）。--encrypt 会使用 AES-256-GCM 加密同一归档。
mgimind export [--format json|md] [--output <dir>]	将记忆导出到文件。md 会按顺序将分块文档的片段重新合并为一个块。
mgimind import <obsidian|markdown> <path> [--library <l>]	导入 markdown 文件夹（递归导入，并进行分块）。
mgimind doctor [--fix]	健康检查；--fix 会下载所有缺失内容。

配置

配置文件位于 ~/mgimind/config.json。以下字段会影响检索：

字段	默认值	含义
model_name	multilingual-e5-base	models/ 下的嵌入模型目录。
vector_size	768	嵌入维度。必须与模型匹配。
pooling	mean	mean（e5、MiniLM）或 cls（部分 XLM-R 模型）。
uses_token_type_ids	false	BERT 系列模型设为 true，XLM-R / e5 设为 false。
query_prefix / passage_prefix	query: / passage:	e5 需要这些前缀；不需要前缀的模型则留空。
rerank_enabled	true	启用交叉编码器重排序。请参阅下方的语言说明。
rerank_model	bge-reranker-base	models/ 下的重排序模型目录。
rerank_top_k	20	返回 limit 条结果前要获取并重排序的候选项数量。
qdrant_port	6334	Qdrant gRPC 端口。
qdrant_http_port	none	Qdrant 的 REST 端口，用于 backup/restore 快照和 doctor 报告。未设置时，根据 qdrant_port - 1 推导（Qdrant 自带的默认端口配对）；仅当你的服务不遵循该配对时才设置此项。
qdrant_api_key	none	如果设置，Qdrant 会使用此密钥启动，客户端也会进行身份验证。

语言与重排器

默认技术栈针对英语进行了调优，因为助手本身用英语推理效果最好，而且英语模型表现最强。对于以英语为主的项目，推荐使用此配置。

以下是一些实际情况：

• 嵌入模型（multilingual-e5-base）确实支持多语言。英语查询可以找到俄语笔记，反之亦然，而且仅靠搜索就能很好地跨语言检索。
• 默认重排器（bge-reranker-base）针对英语进行了调优。它能提升英语排序效果，但会降低俄语（以及其他非英语语言）的排序质量。这是默认配置偏向英语的唯一一处。
• **如果你的内容主要是俄语（或其他非英语语言）：**设置 rerank_enabled = false。混合稠密与稀疏搜索本身就能很好地为这些语言排序；会影响效果的是针对英语调优的重排器。或者换用更强的多语言重排器。
• 重排会为每个查询执行一次交叉编码器推理：在仅配备 CPU 的设备上，对 20 个候选项大约需要一到两秒。调低 rerank_top_k 或关闭重排，可以加快搜索速度。

更改嵌入模型

切换模型通常会改变向量维度，因此必须重新嵌入现有记忆：

1. 先备份：mgimind backup ~/mgi-backup.tar.gz。
2. 在 config.json 中为新模型设置 model_name、vector_size、pooling、uses_token_type_ids 和前缀。
3. 运行 mgimind doctor --fix 下载模型。只有随附的默认模型经过固定版本；自定义模型下载时会显示“完整性未经验证”警告。如果需要严格验证，请在 integrity.rs 中固定其 SHA-256。
4. 运行 mgimind migrate，使用新模型重新嵌入存储文本中的所有内容。

故障排除

• “Model not found ... run doctor --fix”：模型不在 ~/mgimind/models/ 中。运行 mgimind doctor --fix。
• “invalid expand shape” / 推理错误：通常是输入远超 512 个 token。add 会自动分块；如果直接调用库，请先分块。
• 搜索速度慢：这是 CPU 上的重排器导致的。调低 rerank_top_k，或设置 rerank_enabled = false。mgimind mcp 进程运行期间，模型会保持热载入状态，因此只有会话中的首次查询需要支付加载开销。
• 安装后工具立即失败：运行 mgimind doctor（助手可以调用 mind_doctor）；它会准确报告缺失项（Qdrant 未运行、模型未下载、缺少 ONNX Runtime、文件被杀毒软件隔离），并且 --fix 会下载能够获取的内容。
• 维度不匹配警告：集合中的向量与 vector_size 不匹配，通常发生在更换模型后。运行 mgimind migrate 重新嵌入。
• 俄语结果不理想：设置 rerank_enabled = false（见上面的语言说明）。
• 运行 mgimind 时 VPN、隧道或代理中断：运行 mgimind doctor 并查看网络占用情况。mgimind 的所有端口都仅绑定到回环地址，而且 mgimind 不会更改路由、DNS 或防火墙设置，因此无法将流量从隧道中导出。请检查与其同时启动的程序：Docker Desktop 和 WSL2 会各自添加虚拟适配器；而使用严格路由的 TUN 客户端可能会在适配器出现或消失时断开隧道。

安全性

• 下载时会根据固定的 SHA-256 校验 ONNX Runtime（linux-x64）、Qdrant 和默认模型（e5 和重排器）；校验失败时会拒绝继续。其他平台和自定义模型会发出警告，而不会盲目信任。
• Qdrant 仅绑定到 127.0.0.1，并支持 API 密钥。
• 保险库使用 AES-256-GCM 和 Argon2id 派生密钥（参数已固定，防止库升级后将你锁在外面）。保险库仅通过终端访问，因此主密码和解密后的密钥不会通过 MCP 通道传输。mind_vault_* MCP 工具返回的是终端操作说明，而不是密钥值。
• 文件写入采用原子操作，并会同步目录，因此崩溃后留下的要么是旧文件，要么是新文件，不会是损坏的文件。

网络足迹

mgi-mind 打开的每个套接字都绑定到环回地址：

组件	端口	绑定地址
Qdrant HTTP	qdrant_http_port，默认由 qdrant_port - 1 推导	127.0.0.1
Qdrant gRPC	qdrant_port，默认值为 6334	127.0.0.1
mind_visualize	4173	127.0.0.1
mgimind viewer	随机端口，启动时打印	127.0.0.1
mgimind serve-http	随机端口，或使用 --port 指定	除非指定 --host，否则为 127.0.0.1

serve-http --host 是绑定到其他网络接口的唯一方式（Docker 的 -p 映射需要此设置）；如果主机不是环回地址，还必须传入 --agent-token，否则请求会被拒绝。

mgimind 不会安装驱动程序、添加网络适配器，也不会更改路由、 DNS 或防火墙设置。mgimind doctor 会打印此网络足迹，并实时探测 每个端口，因此这项声明可以自行验证，而不必盲目信任。

状态与审计

当前版本：2.8.2（自 v1.0.0 起遵循稳定的语义化版本规范）。0.x 系列奠定了 基础：审计日志和临时查看器（0.10）、隔离层和尽力而为的检索策略（0.11）、查看器浪潮（0.12）、 会话存活性（0.13）和程序化记忆（0.14；在 LongMemEval-S 和一个来自 20 个公开仓库、 包含 227 对错误→修复的数据集上完成基准测试）。1.x 系列加入了有效性模型：双决规则、 疑虑窗口及其后台重新测试、双时态事实替代、置信度评分和类型化结果信号（mind_outcome）， 以及安装模式的 CPU/GPU 配置。

在升级到 2.0 之前，MCP 接口只增不减：29 个可用工具，以及为保持兼容性而保留的 15 个 弃用别名。2.x 内不会重命名或移除任何内容；可能会添加新的动词（最近添加的是 mind_skill）。 其他 1.0 合约包括非对称的“Qdrant 现在 → md 声明”对账差异，以及 MGIMIND_MODEL_VARIANT={cpu|gpu|auto} 开关。

项目经过了代码审计；AUDIT_STATUS.md 逐项说明了每个问题的修复位置或推迟原因。 CHANGELOG.md 记录了 1.x 系列各版本的历史以及 v1.7 候选版本章节（1.0 之前的版本见 CHANGELOG-ARCHIVE.md）；而 ROADMAP.md 列出了后续版本中已确定的内容，以及在 v3.0 规划阶段仍属 候选的方向。

项目结构

src/
  cli.rs         command dispatch and output rendering
  storage.rs     Qdrant: single collection, hybrid search, history, stats, migrate, chunking
  embedder.rs    ONNX embedding (model-aware pooling, prefixes, 512-token cap)
  reranker.rs    cross-encoder reranking
  knowledge.rs   knowledge-graph facts + cardinality + supersession
  duel.rs        duel rule: resolve contradicting facts (flip / contested / quarantine)
  doubt.rs       doubt window + background active re-test of entrenched facts
  activity.rs    recent-query buffer, corpus mean (centering), origin-context store
  confidence.rs  per-fact confidence score (dependants / confirmations / signals)
  outcome.rs     typed external signals (test_passed, code_compiled, ...) into weight
  procedure.rs   procedural memory: learn / recall / outcome
  ingest.rs      auto-extract & ingest candidates
  relevance.rs   relevance gate (length, blacklists, decision markers, token novelty)
  retrieval_policy.rs  search-before-answer classifier
  provenance.rs  cited external snippets with mandatory source
  extractor.rs   optional local LLM extraction (off by default)
  consolidate.rs merge duplicates, report cold entries
  md_reconcile.rs md import as reconcile with "md wins"
  audit.rs       append-only audit log for memory/fact/procedure/skill
                 writes, updates, deletes and quarantine transitions (not
                 pinned blocks, kv, vault, or sessions yet)
  http_api.rs    loopback HTTP surface for multi-agent access
  viewer.rs      ephemeral local HTTP viewer (axum, static frontend baked in)
  pulse.rs       live graph pulses for the viewer
  session.rs     per-agent session files
  secrets.rs     secret-scrub on the write path
  vault.rs       encrypted secret vault (terminal only)
  mcp.rs         MCP server over stdio (hand-rolled JSON-RPC; warm in-process models)
  config.rs      configuration + install-mode profiles
  integrity.rs   pinned SHA-256 hashes for downloads
  util.rs        atomic writes, verified downloads
  (plus migrate, install-mode, access/decay, and bench harnesses)
tests/
  cli_integration.rs   black-box tests against a real Qdrant (CLI + MCP round-trip)
  http_integration.rs  the multi-agent HTTP surface end to end

许可证

Apache-2.0。详见 LICENSE。