sage-wiki：LLM 编译的知识图谱 wiki，让 AI 与人类共同构建可溯源的智能知识库

深夜，一位研究生的知识焦虑

凌晨两点，研究生小张盯着屏幕上的 347 篇 PDF 论文发呆。他知道 Flash Attention 的核心思想分散在不同论文的各个章节中，Nvidia 的 TMA 指令在另一篇，系统性优化又在第三篇。他需要的是一张能回答"Flash Attention 如何在不同硬件上优化显存"的图，而不是翻遍 347 个文件夹。

传统的笔记工具只能帮他存放这些文件，却无法帮他提炼和连接知识。Obsidian 的双链需要他手动输入 [[wikilink]]——347 篇论文意味着手动链接工作根本无法完成。sage-wiki 解决的就是这个问题：你只管往里面扔文档，它帮你编译出一整个互联互通、带溯源的知识维基。

从 Karpathy 的一个念头到生产级系统

sage-wiki 诞生于 2024 年末，最初是创始人 xoai 对 Andrej Karpathy 关于"LLM 编译个人知识库"设想的 Go 实现。它的核心理念简单而深刻：源文档是唯一的事实来源，LLM 编译器从中提炼出概念、写成交叉引用的文章，构建出知识图谱。每一条答案都有引用来源，每一次推理都可以追溯。

不同于 Mem0、NotebookLM 等托管服务，sage-wiki 是完全本地化的单 Go 二进制文件，从个人笔记本到公司服务器都能运行，代码完全开源（MIT 许可证），数据完全自主掌控。

一个文档进去，一个知识图谱出来

sage-wiki 的编译管道（Compiler Pipeline）将这个过程拆解为四个分层级别，每一级消耗的成本递增：

这套分层策略让 sage-wiki 能够支持 10 万文档级别的知识库：先用 Tier 1 快速索引全部内容（10 万文档约 5.5 小时），然后按需触发 Tier 3 编译——不再需要为每篇文档付费。

支持的源文档格式超过 12 种：Markdown、PDF、Word、Excel、PPT、CSV、EPUB、邮件、图片（含视觉描述）、代码文件（Go/Python/JS/TS/Rust 等），甚至音视频字幕（VTT/SRT）。只要往 raw/ 目录一扔，剩下的全部自动完成。

知识图谱：不只是向量相似度

纯向量检索的问题是：只能找到"看起来像"的内容，却无法回答"因果关系"类问题。比如问"Kubernetes 和服务网格是什么关系"，向量相似度无法理解"关系"本身。

sage-wiki 的解决思路是三通道混合检索：BM25 关键词检索 + 向量语义检索 + 图谱关系遍历。查询时，系统先通过关键词找到种子实体，然后沿图谱边进行有限深度遍历，最终融合三个通道的得分返回结果。

图谱本身是编译的副产物——不是另一个需要手动维护的数据库。具体有两种模式：

基础模式（默认开启）：通过关键词共现自动建立实体链接，两个概念在同一段落同时提到某个关系词（如"依赖""实现"）即建立边。

增强模式（可选开启）：通过 LLM 结构化抽取三元组（主体 → 关系 → 客体），每条边携带证据片段、置信度和来源文档；"NASA"和"National Aeronautics and Space Administration"会被消解为同一实体，但消解结果需要人工审核确认后才生效（置信度阈值 0.85）。

MCP 集成：给 AI Agent 装上记忆模块

MCP（Model Context Protocol）允许 AI Agent 把 sage-wiki 当作外部记忆来用。项目暴露了 19 个 MCP 工具，典型的 Agent 工作流是这样的：

wiki_search("attention mechanism papers")  →  找到相关文档片段
wiki_compile_topic("flash attention")        →  按需编译特定主题
wiki_capture(insight)                        →  把新发现存回 wiki
wiki_graph_query("flash attention 相比 naive 优化了什么？")  
                                           →  获得带引用的多跳推理答案

开发者可以把自己的编码助手（Claude Code、Cursor、Windsurf）接入 sage-wiki：运行 sage-wiki skill refresh --target claude-code 即可生成行为指导文件，让 AI 知道何时该搜索、何时该捕获、何时该编译。Python 和 TypeScript 也有官方 SDK，封装了 REST API 的所有能力。

三种界面：TUI、Web UI、命令行

• TUI（终端界面）：4 个标签页（F1 浏览、F2 搜索、F3 问答、F4 编译），用 bubbletea + glamour 渲染 Markdown，支持键盘导航。
• Web UI（需 -tags webui 编译标签）：基于 Preact + Tailwind CSS 的单页应用，内嵌在 Go 二进制中（~420 KB gzip）。提供文章浏览器、交互式力导向图谱可视化、混合搜索、问答（带流式输出）。
• 纯 CLI：不需要任何前端，sage-wiki search/query/compile 满足所有操作。

存储与扩展：从 SQLite 到 PostgreSQL

默认使用单文件 SQLite（FTS5 + 向量 BLOB），零配置即可运行。切换到 PostgreSQL + pgvector 只需改一行 config.yaml，适合团队共享服务器部署。多工作区模式支持一个进程服务多个独立的 wiki 目录，每个目录有自己的认证 token。

数据备份方面，sage-wiki 支持 S3 兼容存储（AWS S3、Cloudflare R2、MinIO）的连续镜像，包含 WAL 预写日志，支持任意时间点恢复，RPO ≤ 1 秒（实测 ~30ms 数据丢失）。

争议与局限

第一，LLM 成本是外部依赖。 sage-wiki 本身免费，但每次 Tier 3 编译和问答都需要调用外部 LLM（OpenAI/Anthropic/Gemini），大文档集的成本不可忽视。项目内置了 Token 计数和价格估算功能，compile --estimate 可以在实际消耗前预览成本。

第二，Web UI 编译门槛。 如果需要图形界面，必须安装 Node.js 22 来构建前端资源，然后用 -tags webui 重新编译 Go 二进制。对于非 Go 开发者来说，这个步骤比 pip install 稍复杂。

第三，输出质量依赖源文档质量。 如果源文档格式混乱、标题不规范、关键概念没有显式表达，编译输出的知识图谱质量也会受限——系统没有魔法，无法从垃圾输入中提炼黄金。

第四，预发布状态。 项目明确标注"pre-1.0"，API 和配置格式在版本间可能发生变化，生产环境建议锁定版本号。

行业意义：知识管理的编译时代

sage-wiki 代表了一种新兴的 AI 应用范式：编译式知识管理。传统 PKM 工具（Notion、Obsidian）需要人工维护链接和标签，LLM 增强工具（NotebookLM、Mem0）主要做问答和检索，而 sage-wiki 把编译管道变成了第一公民——知识图谱不是副产品，而是编译的必然产物。

从基准测试数据看，在 LOCOMO 和 LongMemEval-S 等公开记忆评测集上，sage-wiki 的表现与 Mem0 托管平台持平甚至略优（LOCOMO 92.0% vs 91.8%），同时完全运行在本地，无需向第三方发送数据。

对于个人研究者来说，sage-wiki 解决了"论文读完就忘、找的时候找不到"的长期痛点；对于开发团队来说，它是 AI 编码助手的记忆层；对于企业知识管理场景，它提供了一条从散乱文档到可查询知识图谱的自动化管道。

一句话总结： sage-wiki 把"喂文档 → LLM 编译 → 知识图谱"这套流程做成了一条工业化流水线，从个人笔记到公司知识库都可以用，一个 Go 二进制全搞定。