engraph
本地知识图谱工具，为 AI 代理提供 Obsidian 笔记库的语义搜索与上下文访问能力
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
本地知识图谱工具，为 AI 代理提供 Obsidian 笔记库的语义搜索与上下文访问能力
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
凌晨两点，你正在赶一个紧急的项目方案。突然想起三个月前和客户的一次深度沟通中，对方提过一个关键需求——但那个笔记藏在哪来着？翻遍文件夹、搜索关键词，一无所获。几天后它才在某个不起眼的 daily note 里冒出来。
这种情况每个知识工作者都经历过。Obsidian 帮我们建立了笔记库，却始终无法理解笔记之间的关联。engraph 正是来解决这个问题的——它把你的 Obsidian 知识库变成一个可以被 AI 代理直接理解和查询的"知识 API"。
engraph 是一款完全本地运行的 Rust 工具，通过混合搜索、知识图谱和 MCP 协议，让 Claude Code、Cursor 等 AI 编程助手能够真正"读懂"你的笔记库——不是简单的关键词匹配，而是理解笔记之间的语义联系和 wiki 链接关系。
engraph 的作者是 devwhodevs，一个典型的"用 Obsidian 记录一切"的开发者。日常工作中，他积累了大量架构设计笔记、会议纪要和决策记录，但 AI 编程助手对这些笔记完全"视而不见"——它只能靠手动复制粘贴上下文，既费时又容易遗漏。
当时市面上的解决方案各有缺陷：纯向量检索把笔记当作孤立文档，无法理解链接关系；Notion AI / Mem 需要云端上传，数据隐私成疑；Obsidian 内置搜索仅支持关键词匹配。面对这个困境，作者决定自己动手，用 Rust 写一个本地知识图谱工具。
这个选择并非随意——Rust 提供了极致的性能和内存安全保证，而 llama.cpp 的 Rust 绑定（llama-cpp-2）让本地 GGUF 模型推理可以直接集成到工具中，无需任何外部依赖。
engraph 的搜索系统是其核心亮点，采用 5 车道混合检索 + Reciprocal Rank Fusion (RRF) 融合的架构。
第一车道：语义向量搜索。 通过 llama.cpp 加载本地 GGUF 嵌入模型（如 Qwen3-Embedding），将笔记分块后向量化，存入 SQLite + sqlite-vec 插件。查询时计算向量相似度，找到语义上最接近的笔记。macOS 上支持 Apple Silicon 的 Metal GPU 加速，88 个文件索引仅需 70 秒。
第二车道：BM25 全文搜索。 SQLite FTS5 提供了成熟的 BM25 检索能力，处理精确关键词匹配。语义搜索擅长"找相似"，BM25 负责"找准确"——两者互为补充。
第三车道：知识图谱扩展。 这是 engraph 与众不同的关键。当笔记 A 通过 wikilink 链接到笔记 B 时，engraph 会自动构建双向链接图。搜索"认证系统"时，即使笔记 C 没有直接提到这个词，但它被认证架构文档链接了，图谱扩展就能把 C 也找出来。传统的向量检索完全无法做到这一点。
第四车道：Cross-Encoder 重排。 启用"Intelligence"模式后，下载可选的 Qwen3-Reranker 模型（约 1.3GB），对候选结果进行精细的重排打分，进一步提升相关性。
第五车道：时间感知检索。 自然语言时间查询（"上周做了什么"、"2026 年 3 月的笔记"）自动激活时间通道，从 frontmatter 和文件名中提取日期，按时间衰减函数排序。
这五个通道的分数通过 RRF（倒数排名融合） 合并——这是一种在 TREC 评测中被验证有效的融合策略，比简单加权平均更鲁棒。
仅仅堆叠多个检索通道还不够，engraph 还配备了一个 LLM 研究调度器（Research Orchestrator）。它由本地 GGUF 模型驱动（Qwen3-0.6B），负责两项关键任务：
意图分类。 分析用户查询的类型（概念性、事实性、时间性等），据此调整各车道的权重。问"How does the auth system work"被分类为"概念性"查询，语义通道权重自动提升；问"what happened last week"则激活时间通道。
查询扩展。 将用户的自然语言查询扩展为多个子查询，提升召回率。
这使得 engraph 的搜索不再是"把所有通道跑一遍然后机械融合"，而是真正理解用户意图的智能检索系统。
engraph 提供 MCP (Model Context Protocol) 服务端，暴露 25 个结构化工具，让 AI 代理以标准化的方式与知识库交互：
| 类别 | 工具示例 | 说明 |
|---|---|---|
| 读取 | searchVault、readNote、readSection | 搜索和读取笔记内容 |
| 写入 | createNote、editSection、rewriteNote、deleteNote | 创建和编辑笔记 |
| 上下文 | getWho、getProject、topicContext | 获取人物/项目上下文束 |
| 诊断 | vaultHealth | 检测孤立笔记、断链、过期内容 |
| 迁移 | migratePARAPreview/Apply/Undo | PARA 方法论整理 |
Claude Code 用户只需在配置文件中添加 MCP 配置，就能让 AI 在编程时主动查阅你的笔记库——"这个认证模块上次是怎么设计的？"——AI 直接搜索、读取，无需你手动复制粘贴。
HTTP REST API 模式（engraph serve --http）则额外提供 26 个 REST 端点，支持 API Key 认证、速率限制和 CORS 配置，Web 代理和脚本可以直接 curl 查询笔记库。
engraph 还提供了一个实用的 PARA 迁移工具。PARA（Projects / Areas / Resources / Archive）是一种知识管理方法论，提倡按"当前行动相关性"而非主题组织笔记。
engraph 的迁移工具通过启发式规则自动分类笔记：包含待办事项的归入 Projects；涉及健康、财务、职业等持续领域的归入 Areas；人物笔记、参考资料归入 Resources；已完成且无链接的归入 Archive。
支持预览（生成迁移计划）、执行和撤销三步流程，AI 代理可以通过 MCP 工具参与决策。
engraph 的安装非常简洁——Homebrew 一行命令、下载预编译二进制、或 cargo install 从源码编译。首次运行 engraph index ~/path/to/vault 自动下载嵌入模型（约 300MB），后续增量索引仅处理变更文件。
但需要注意的是，项目没有提供 Dockerfile，无法通过容器化方式部署。这对于需要服务器端运行或想在 Docker 环境中集成的用户来说是一个限制。数据存储在 ~/.engraph/ 目录下的单个 SQLite 数据库中。
硬件需求方面：CPU 足以运行基础搜索；macOS Apple Silicon 可享 Metal GPU 加速；Linux 如有 CUDA 可进一步提速；整体磁盘占用约 2GB（含模型）。
没有 Web UI，完全依赖命令行。对于非技术用户门槛较高。
需要自备本地 GGUF 模型，虽然默认下载流程已足够简单，但模型选择和调优不在工具覆盖范围内。
聊天机器人场景有限——engraph 擅长的是"搜出来给我"，而非"帮我总结今天的进展"这类主动推理任务。ChatGPT Actions 集成需要 Cloudflare Tunnel 或 ngrok 建立公网访问，有一定配置复杂度。
隐私与便利的取舍：完全本地运行意味着数据不离开设备，但同时也意味着无法在多设备间同步索引——每个人的 vault 需各自索引一次。
engraph 代表了一个正在壮大的趋势：本地优先的个人知识库 + AI 代理的深度集成。Notion、Obsidian、Logseq 等笔记工具都在探索 AI 能力，但大多数方案需要云端处理或依赖闭源 API。
engraph 的技术栈——Rust + llama.cpp + MCP 协议——恰好踩中了三个技术浪潮的交汇点：本地大模型推理成熟、MCP 协议成为 AI 代理的事实标准、以及开发者对数据隐私的强烈诉求。
从工程角度看，426 个单元测试、详细的 CLAUDE.md 架构文档、积极维护的 CHANGELOG（v1.0 到 v1.7 持续迭代）——这些都体现了作者的工程质量意识。
图1：engraph 5 车道混合搜索演示 — 搜索认证架构，系统通过语义+图谱双通道找到相关笔记，包括通过 wiki 链接间接关联的内容。macOS Metal GPU 加速下，88 个文件索引仅需 70 秒。
分析基于 GitHub 仓库 v1.7.2 版本，主要语言：Rust，License：MIT，Stars：161（数据截至分析时）