IWE：把 Markdown 笔记变成可查询的知识图谱，同时服务编辑器和 AI 代理
该项目围绕「Markdown knowledge graph, LSP for your editor, CLI + MCP memory for your AI agents.」构建，适用于实际场景的开源实践，提供可复用的工具链与集成方式。
秒懂
- 它是什么？
- IWE 是一个用 Rust 写的本地优先知识图谱工具，它把目录里的 Markdown 文件变成带结构的图，通过 LSP 和 MCP 分别服务人类编辑器和 AI 代理。本文基于仓库文档和 README，分析它的机制、安装方式、局限和适用人群。
- 适合谁用？
- IWE 适合那些已经用 Markdown 写笔记、并且希望让 AI 代理能按结构而非相似度来检索这些笔记的人。它不适合想要内置 AI 推理、或者希望把笔记托管到云端的用户，因为 IWE 本身没有 AI，所有操作都发生在本地文件上。
- 能商用吗？
- 可以。Apache-2.0 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 3 天前。
- 用什么语言写的？
- 主要是 Rust（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月14日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决什么问题：笔记的数据库式查询，而非文件夹浏览
IWE 解决的是一个具体痛点：当你的笔记散落在几十个 Markdown 文件里，想回答“这个子树下所有草稿”或“第一季度所有已接受的决策”这类问题时，你只能靠文件夹层级或者全文搜索，而这两者都丢失了语义关系。IWE 把目录变成知识图谱，允许你像查数据库一样查询笔记，但文件仍然是纯 Markdown，没有数据库文件，没有云端依赖。它面向的是两类人：一是想在编辑器里获得 IDE 级导航能力的笔记用户，二是想让 AI 代理在对话中引用自己笔记的开发者。对于后者，IWE 明确说它没有内置 AI，它只提供工具，让 Claude、Codex、Gemini 等通过 Model Context Protocol 来导航你的知识。这个定位很清晰，但也是一个限制：如果你期望 AI 能自动理解笔记内容，IWE 不会做这件事。
核心机制：inclusion links 与交叉引用构建的图
IWE 的图模型基于两种链接类型。第一种是 inclusion links，即单独一行上的链接，表示“这个主题包含那个子主题”，由此形成一棵树。第二种是交叉引用，即普通行内链接，连接不同主题的笔记，形成网状的关联。关键设计是多重父节点：同一篇笔记可以同时挂在多个主题下，比如一篇“冥想”笔记可以同时属于“健康”和“生产力”，而不需要复制文件。这种设计让笔记的组织方式从文件夹树变成了图。检索时，IWE 可以从父节点继承上下文，当你获取一篇笔记时，可以选择包含其上层节点的内容。这个机制的实际效果是：一次查询就能拿到一个主题的完整上下文，而不是单个孤立文件。文档里给出的例子是 `iwe retrieve --key authentication --expand-includes 2`，意思是检索键为 authentication 的笔记，并展开两层父级包含。
安装与启动：CLI、插件和 MCP 服务器的实际命令
安装 IWE 的入口是 CLI，通过 crates.io 分发，版本 0.20.0 以上。README 里没有给出 `cargo install iwe` 这样的具体命令，但提到了插件安装方式。对于 Claude Code，你可以在插件市场添加 `iwe-org/skills`，然后运行 `/plugin marketplace add iwe-org/skills` 和 `/plugin install iwe@iwe-org`，接着在仓库里执行 `/iwe:init` 初始化。这个插件本身不包含运行时脚本，它只是调用 `iwe` 子命令，所以唯一依赖是 CLI 在 PATH 中。对于其他 AI 工具，比如 Codex、Cursor、OpenCode，你可以通过 `npx skills add iwe-org/skills` 安装技能，这些技能以普通项目技能的形式提供 `/init`、`/distill`、`/reflect`、`/graph` 四个命令。MCP 服务器叫 `iwec`，它让 Claude Desktop、Cursor、Windsurf 等工具直接连接你的笔记，并且它会监视文件变化，所以你在编辑器里的修改会实时反映给 AI 工具。初始化时，`iwe init --okf` 可以生成符合 Open Knowledge Format 的包结构，`iwe schema validate` 可以机械地检查符合性。
写入保护：expect 守卫、文档 schema 和图卫生检查
IWE 对 AI 代理的写入操作做了多层检查，这是它区别于普通文件编辑器的关键。第一层是声明范围：每次变更操作必须携带 `expect` 守卫，声明它可能影响的文档数和块数。整个更新在写入前会先验证，如果实际影响范围与声明不符，操作会被中止，并指出违规的块。在 MCP 协议下，这些守卫是强制的，一个不声明影响范围的编辑会被直接拒绝。第二层是 schema 验证：每个文档类型可以有对应的 schema，定义必填字段、枚举值、ISO 日期和必需章节。如果 MCP 写入违反了 schema，会被拒绝并指出具体违规项；在 CLI 中你可以用 `iwe schema validate` 手动运行同样的检查。第三层是图卫生：变更后，IWE 会警告它扰动了什么，比如悬空链接、孤立页面，`iwe stats similarity` 可以标记近似重复的笔记。这套机制的设计意图很明确：AI 代理的写入不被信任，而是被检查。但这也意味着，如果你希望 AI 自由地创建和修改笔记，你可能会被这些守卫频繁打断。
性能与实现：Rust 与 20,000 文件的处理能力
README 声称 IWE 在 Rust 中实现，能够在一秒内处理 20,000 个文件，并引用了 docs/benchmark.md 作为依据。这个数字我没有验证，因为我没有运行过项目，但它是仓库提供的唯一性能数据。从实现角度看，Rust 的选择意味着启动时间和内存占用通常比 Node.js 或 Python 实现的同类工具更有优势，尤其当笔记库规模达到数万文件时。不过，性能数据只涉及处理文件，不包含 LSP 交互延迟或 MCP 请求响应时间，这些在实际使用中同样重要。如果你有超大笔记库，应该自己跑一遍 benchmark 脚本，而不是依赖 README 里的数字。另外，IWE 没有内置全文索引或向量搜索，它依赖外部工具如 ripgrep 来找到入口点，然后由它提供图上下文。这种组合方式意味着性能瓶颈可能出现在搜索阶段，而不是图遍历阶段。
局限与错误场景：没有 AI、依赖链接、插件作用域限制
IWE 的第一个局限是它没有内置 AI，这既是设计选择也是功能边界。它不提供任何语义理解或自动摘要，所有检索都依赖结构。如果你的笔记缺少链接，或者链接组织混乱，IWE 的图就会变得稀疏，查询结果会退化为普通全文搜索。第二个局限是插件的作用域控制：README 提到，如果一个仓库没有 `MEMORY.md` 文件，或者 CLI 未安装，所有钩子都会静默退出，插件在该仓库中保持惰性。这意味着你必须在每个需要记忆的仓库里显式初始化，忘记初始化会导致插件不工作，而且没有错误提示，这可能会让用户困惑。第三个局限是写入保护机制可能阻碍快速迭代：在 MCP 下强制要求声明影响范围，如果你让 AI 代理做批量修改，它可能因为无法准确预估影响而频繁被拒绝。最后，IWE 的 LSP 集成虽然支持 VS Code、Neovim、Zed、Helix，但 README 没有提供这些集成的配置细节，实际配置可能需要查阅文档站。
替代方案对比：与 Joplin、Obsidian 和向量数据库的区别
要理解 IWE 的定位，可以把它和三类工具对比。第一类是传统笔记应用如 Joplin 或 Obsidian，它们也支持 Markdown 和链接，但核心是给人类用，AI 集成通常依赖插件或外部 API，而且数据往往存储在应用自己的格式或数据库中。IWE 的不同之处在于它把 LSP 和 MCP 作为一等公民，直接暴露结构化接口给编辑器工具和 AI 代理，而不要求你打开某个特定应用。第二类是向量数据库，比如 Chroma 或 Pinecone，它们用嵌入向量做相似度检索，适合语义搜索，但需要将笔记转换为向量，并且通常需要额外的服务。IWE 明确拒绝这种路径，它说自己的检索是“按结构，而不是按相似度猜测”，这意味着它不需要嵌入模型，也没有云服务，但代价是你必须依赖链接质量。第三类是专门的 AI 记忆系统，比如 Mem0，它们提供 API 来存储和检索对话记忆，但通常绑定特定平台。IWE 则把记忆文件化，用 git 版本控制，让记忆内容可审查。如果你需要语义相似度搜索，IWE 不是正确工具，你应该考虑向量数据库。
维护与升级：Apache-2.0 许可、活跃发布和插件版本依赖
IWE 的许可证是 Apache-2.0，这意味着你可以自由使用、修改和分发，但需要注意，如果你修改了代码并分发，需要保留版权声明。项目最近发布频繁，v0.20.1 在 2026 年 8 月 24 日发布，v0.20.0 和 v0.19.1 分别在 8 月 15 日和 8 月 2 日发布，说明开发活跃。升级成本方面，插件要求 CLI 版本 0.20.0 或更新，这意味着当你升级 CLI 时，可能需要同时更新插件以保持兼容。README 没有提供迁移指南，所以从旧版本升级时，你需要自行查看 changelog。由于 IWE 使用纯 Markdown 文件存储数据，升级通常不会影响你的笔记内容，但如果你使用了 OKF 格式的 schema，升级可能会改变 schema 验证规则，导致旧文件不再通过验证。建议在升级前运行 `iwe schema validate` 检查现有文件。
编辑结论
IWE 适合那些已经用 Markdown 写笔记、并且希望让 AI 代理能按结构而非相似度来检索这些笔记的人。它不适合想要内置 AI 推理、或者希望把笔记托管到云端的用户，因为 IWE 本身没有 AI，所有操作都发生在本地文件上。在采用之前，你应该先确认自己的笔记是否已经包含足够的链接结构，因为 IWE 的核心价值来自 inclusion links 和交叉引用，纯文件夹式的笔记在图上会显得稀疏。你还需要验证 LSP 客户端与你的编辑器（VS Code、Neovim、Zed、Helix）的兼容性，以及 `iwec` MCP 服务器是否能被你的 AI 工具正确调用。如果这些前提都不满足，IWE 的收益会大打折扣。最终判断是：IWE 是一个设计上很克制、对文件所有权极其认真的工具，它把记忆问题还原为结构问题，但这份克制也意味着你必须自己承担建立和维护链接的工作。
社区笔记