Kwipu（geode_graph）：把 Markdown 笔记变成可问答的知识图谱

图1：Kwipu 查询界面——自然语言提问，知识图谱跨文件关联作答

痛点场景：你的笔记越多，找起来越痛苦

写笔记是好的，但当笔记数量突破三位数，痛苦就开始了——你需要某条信息，记得在某几个文件里见过，但就是想不起来关键词。用 grep 搜？只能找到字面匹配。用 Notion 搜索？依然停留在关键词层面，跨文件的隐性关联根本抓不住。

Kwipu（项目名 geode_graph）解决的就是这个问题——把你的 Markdown 笔记自动构建成一张知识图谱，用人话提问，AI 帮你把散落在不同文件里的相关知识点串联起来，给出有来源引用的答案。

背景故事：从 Obsidian 重度用户到 Graph RAG 实践者

Kwipu 的开发者 benmaster82 是一个 Obsidian 重度用户，日常积累了大量笔记，涵盖技术文档、会议纪要、项目复盘等多个领域。传统 RAG（检索增强生成）只能做向量相似度匹配，面对"哪些项目在上季度完成了评审"这类需要理解关系语义的查询时表现乏力。

2026 年 4 月，开发者决定基于 LlamaIndex 的 Property Graph Index 构建一个本地 Graph RAG 引擎，目标是：不依赖任何云服务，数据永不离开本机，同时支持 Obsidian 原生的 [[wikilinks]] 和 YAML frontmatter 解析。项目在 GitHub 发布后迅速获得关注，半年内积累 261 颗星，被掘金等技术社区报道。

核心技术：混合检索 + 属性图双引擎

Kwipu 的检索架构是它最值得深入了解的部分——它不是一个简单的向量数据库查询，而是一个四路并行的混合检索系统：

第一路：LLM 同义词扩展检索器（LLMSynonymRetriever）

用 LLM 自己对查询进行同义词改写，然后做向量检索。比如用户问"这个功能是谁负责的"，LLM 可能扩展为"responsible for / developed by / managed by"，让向量检索覆盖更多表达方式。适合 GPU 环境，--fast 模式跳过以节省 CPU 资源。

第二路：向量上下文检索器（VectorContextRetriever）

将笔记分块后用 Ollama 的嵌入模型（默认 nomic-embed-text）编码，存入向量索引。查询时找语义最相似的块，这是 Graph RAG 的基座。

第三路：BM25 关键词检索器（BM25ChunkRetriever，自定义）

这是 Kwipu 的自研组件，实现了多语言适配的 BM25 算法。不同于英文专用实现，Kwipu 接入了自己的 lang_config 多语言分词器，支持意大利语、英语、法语、德语、西班牙语、葡萄牙语六种语言的停用词过滤和词干处理，确保各语言下关键词打分都准确。

第四路：时间/元数据检索器（TemporalMetadataRetriever，自定义）

识别笔记中的日期实体（如"2026-06-15"或各语言月份名），建立时间索引。用户问"最近三个月有哪些进展"时，精确匹配时间维度。这一路还识别各语言的时间关键词（meeting、review、deadline 等），将时间语义纳入检索排序。

四路结果经加权融合后传给 LLM 生成答案，Prompt 严格要求引用来源文件名，杜绝幻觉。

图谱构建：从笔记到知识网络的完整流水线

Kwipu 构建图谱分为三个阶段：

预处理阶段——lang_config.py 自动检测笔记语言，根据语言选择对应的停用词表、月份名映射和关系推理模式。extract_wikilink_triples() 函数解析 Obsidian 风格的 [[双向链接]]，将链接关系转化为图三元组；extract_frontmatter_triples() 解析 YAML 元数据，提取标签、日期、关系字段。

LLM 抽取阶段——SimpleLLMPathExtractor 调用 Ollama，从每个文本块中抽取额外的实体-关系三元组，补充结构化解析无法覆盖的隐含语义。

图索引持久化——PropertyGraphIndex 将所有三元组合并，存储到本地 storage_graph/ 目录。之后每次查询从磁盘加载图，无需重建。

增量更新是另一个亮点：首次建图后，FileWatcher 持续监听笔记目录，文件修改后触发增量重建，单文件更新耗时约 20-60 秒，不会重跑整个图——这对拥有数千笔记的用户至关重要。

MCP 服务器：把知识图谱接入 AI 代理工作流

2026 年的更新为 Kwipu 带来了最重要的新能力——MCP 服务器（Model Context Protocol）。kwipu_mcp_server.py 基于 FastMCP 实现，将知识图谱作为工具暴露给 Claude Desktop、Cursor、Windsurf 等 AI 代理。

配置方式是修改对应产品的 MCP 配置文件，指向 kwipu_mcp_server.py 的 Python 路径即可。所有查询通过本地 Ollama 处理，token 消耗极低（仅传输查询词和答案，无需传输笔记内容）。这使得在 AI 编码助手中直接查询个人笔记库成为可能——问"上次那个性能优化的方案具体怎么做的"，AI 助手直接帮你翻笔记。

上手门槛：命令行优先，深度用户友好

Kwipu 目前是纯命令行工具，没有 Web UI。安装流程：

pip install -r requirements.txt
ollama pull llama3.1:8b          # LLM
ollama pull nomic-embed-text     # 嵌入模型
python geode_graph.py            # 启动

将笔记放入 ./knowledge_base/，或修改 KNOWLEDGE_DIR 指向 Obsidian vault 路径。

最低硬件需求约 8GB 内存（3B 模型，CPU 运行）。推荐 16GB+ 内存配合 GPU，7B Q4 模型处理 20 篇笔记约 7 分钟。文档建议每篇不超过 1000 行，建图时间与笔记规模线性增长。

MCP 模式需额外配置目标编辑器的 MCP 配置文件，步骤略多，非技术用户有一定门槛。

局限与挑战

无 Docker 支持——目前完全依赖 Ollama + Python 环境，多平台兼容性依赖用户自行解决 Python 版本和依赖问题，无一键部署方案。

LLM 质量影响图谱上限——建图阶段用的是什么模型，直接决定三元组抽取质量。用小模型（1B）建图效果有限，建议至少 3B 以上。

仅支持 Markdown——PDF/DOCX 解析在代码中存在扩展支持，但实际以 .md 文件为主，对混合文档支持不足。

Ollama 模型管理手动——切换模型需要改代码中的 MODEL_NAME，没有 CLI 参数化配置（--llm-model 已有但 --embed-model 相对新）。

行业意义：本地 Graph RAG 的轻量化标杆

Kwipu 代表了一个明确的趋势：RAG 正在从云端走向本地，从向量检索走向知识图谱。2026 年 LlamaIndex 的 Property Graph Index 被广泛采用，Kwipu 是其中上手最简单、最贴近笔记用户场景的实现之一。

它没有追求大而全的功能集，而是专注于"让 Obsidian 用户零成本迁移到 Graph RAG"这一细分目标。六种语言的多语言支持、增量更新、MCP 集成，每一项功能都直击真实使用痛点。随着本地 LLM 推理性能持续提升，这类工具的实用价值还在快速增长。

项目采用 MIT 许可证，代码完全开源，适合作为 Graph RAG 二次开发的参考实现。