适合谁
- 以纯 Markdown 文件为主要知识载体、重视本地优先与 git 版本化的个人。
- 希望把笔记图谱作为代理记忆、并需要结构化检索而非向量相似度猜测的 AI 代理使用者。
- 同时使用编辑器 LSP 与命令行工作流，希望两者操作同一份笔记的开发者或写作者。
- 需要代理写入前必须声明影响范围、并接受 schema 与图谱卫生校验的团队。
I
56FMRS · C
IWE 是一个 Rust 编写、以 Apache-2.0 开源的本地优先知识图谱与记忆系统，它把 Markdown 目录转成图谱，并同时提供编辑器 LSP 与代理用的 CLI 和 MCP 服务器（iwec，经 stdio 通信，也可用 npx 运行 @iwe-org/mcp）。它把模糊/全文搜索与图结构结合，让一次 retrieve 就能拿到父级上下文、子节点与交叉引用，并且对代理写入施加声明式影响范围守卫与 schema 校验。适合以纯 Markdown 管理知识、想让 AI 代理基于结构而非相似度取回上下文的用户；不适合期待云托管、内置 AI 模型或稳定库级 API 的用户。主要风险在于代理对笔记目录的写入权限以及 npx 方式引入的网络依赖。
IWE 是一个面向个人与 AI 代理的记忆系统：它把一个 Markdown 文件目录转成知识图谱。笔记就是本地目录里的 .md 文件，用链接组织成结构，无需云服务、数据库或供应商锁定，可以用 git 版本化管理。同一个图谱有两个接口——编辑器里的 LSP 服务器（VS Code、Neovim、Zed、Helix 等）和供 AI 代理使用的 CLI 与 MCP 服务器（iwec）。MCP 服务器会监视文件变化，编辑器里的改动会立即被反映。IWE 本身不内置 AI，它通过模型上下文协议与 Claude、Codex、Gemini 等工具协同工作。检索方式是结构化取回，而非相似度猜测：find 负责搜索入口，retrieve 与 tree 提供父级上下文、子节点与交叉引用。代理的写入会被校验而非默认信任：通过 MCP 发起的修改必须声明 expect 守卫，说明会触及多少文档与块，任何不匹配都会在写入前中止；同时会按文档 schema 校验 frontmatter 与文档结构，并给出悬挂链接、孤立页面等图谱卫生警告。项目以 Rust 编写，用 Apache-2.0 许可开源。
工具能力
find
用模糊匹配与全文排序搜索笔记，并可按 frontmatter 与图谱边过滤。
retrieve
一次调用返回某文档及其关联上下文。
tree
从任意起点展示笔记的层级结构。
update
带守卫的编辑：修改 frontmatter 与定向的块级操作。
schema
推断存储中的 schema，或按 schema 校验文档。
安装接入
- 安装 CLI 与 LSP/MCP 服务器：Homebrew 执行 brew install iwe-org/iwe/iwe；npm 执行 npm install -g @iwe-org/iwe；Cargo 执行 cargo install iwe iwes iwec；或从 conda-forge 安装 iwe。
- 初始化工作区：进入笔记目录后执行 iwe init。
- 连接 AI 代理：iwec 服务其运行所在目录，因此把工作目录设为你的笔记目录，例如在客户端配置中写 {"mcpServers":{"iwe":{"command":"iwec","cwd":"~/notes"}}}。
- 不想本地安装时可用 npx 按需拉取：把 command 设为 npx，args 设为 ["-y", "@iwe-org/mcp"]，cwd 仍指向笔记目录。
- 可选：为 Claude Code 增加记忆能力，先添加插件市场 /plugin marketplace add iwe-org/skills，再安装 /plugin install iwe@iwe-org，然后在目标仓库运行 /iwe:init。
claude_desktop_config.json
{
"mcpServers": {
"iwe": {
"command": "iwec",
"cwd": "~/notes"
}
}
}
选型与风险
不适合谁
- 希望使用云托管、无需本地文件目录的笔记或记忆服务的人。
- 期待服务器自带 AI 模型或内置推理能力的用户——IWE 本身不含 AI，需搭配外部代理使用。
- 只需要通用向量检索、不关心笔记层级与链接结构的场景。
- 希望依赖稳定库级 API 做二次开发的构建者——liwe 库尚未 API 稳定。
所需权限
- 读取与其运行所在工作目录下的 Markdown 笔记文件。
- 写入与修改该目录下的笔记文件（包括新建、重命名、删除、重构与块级更新）。
- 监视笔记目录的文件变化以即时反映编辑器中的改动。
- 以 stdio 方式与 MCP 客户端通信；通过 npx 运行时需要联网获取 @iwe-org/mcp 包。
风险与副作用
- 代理拥有对笔记目录的写入权限，虽然 MCP 写入需声明 expect 守卫且会在写入前校验，但被允许的改动仍会真实落盘。
- 把 MCP 服务器的工作目录指向错误位置，会让代理读写无关目录中的 Markdown 文件。
- 使用 npx 方式首次运行会从网络拉取 npm 包，存在对上游包与网络的依赖。
- 校验覆盖 schema、frontmatter 与图谱卫生警告，但悬挂链接、孤立页面、近似重复等以警告形式呈现，仍需人工判断。
- 仓库中 liwe 库已发布但尚未 API 稳定，基于其构建的项目需固定版本。
常见排障
- 代理看到的是错误的笔记集合：检查 MCP 配置中的 cwd 是否指向真正的笔记目录，因为 iwec 只服务其运行所在的目录。
- 编辑器中的修改没有立刻被代理感知：确认 MCP 服务器进程在运行，它会监视文件变化。
- MCP 写入被拒绝：查看返回信息中点名的违规项，通常是缺少必填的 expect 守卫或不符合文档 schema（必填字段、枚举、ISO 日期、必需小节）。
- 命令行校验与 MCP 行为不一致：用 iwe schema validate 在 CLI 侧运行同一套检查以复现问题。
- npx 启动失败：确认网络可用，或将 command 改为本地已安装的 iwec 并保证其在 PATH 中。
- 链接或结构异常：关注变更产生的悬挂链接与孤立页面警告，并用 iwe stats similarity 检查近似重复。
- 首次使用无结构可查：先在笔记目录执行 iwe init 完成初始化。
使用场景
把本地 Markdown 笔记目录作为 AI 编码代理或对话代理的长期记忆来源。
在不迁移到数据库的前提下，对笔记做数据库式结构化查询，例如某个子树下的全部草稿、某个季度内所有已接受的决策。
让代理通过 CLI 与 MCP 两种接口执行搜索、取回、创建与重构等相同操作。
在编辑器中获得链接自动补全、跳转定义、反向链接、重命名并自动更新链接、抽取与内联等类 IDE 功能。
以 OKF（Open Knowledge Format）规范搭建、校验并查询带 YAML frontmatter 的知识包。
支持客户端
Claude Code完整支持
Claude Desktop完整支持
Cursor完整支持
Windsurf完整支持