sage-wiki：用一张知识图谱把文档仓库变成可检索、可追溯的团队记忆

它解决的是检索的盲区，不是存储问题

传统向量检索只回答“哪段文字像我的问题”，它不记录事物之间的关系。比如“这个服务依赖哪些内部库”这类需要两跳或三跳的问题，向量检索只能碰运气，希望某个 chunk 恰好包含整条链路。sage-wiki 把文档编译成一张知识图谱，实体之间有类型化关系，查询时通过遍历图谱而不是单纯匹配文本。它面向两类使用者：AI 代理通过 MCP 工具查询，人类则浏览 markdown 文件、TUI 或 web UI。项目从 Andrej Karpathy 关于 LLM 编译个人知识库的想法出发，但实现上把它扩展到了团队和公司规模。

编译管线：从原始文档到带证据的图谱

核心机制是一个 LLM 编译器，它读取论文、笔记、代码、邮件，先做摘要，再抽取概念，最后写成互链的文章。每次新文档进来，都会丰富已有文章，所以 wiki 会随着增长而累积价值。图谱不是单独维护的数据库，而是编译的副产品，这避免了双写同步的问题。可选的结构化输出 pass（ontology.triples）直接从文档抽取 subject → relation → object 三元组，每个文档多一次 LLM 调用，默认关闭，不会偷偷消耗你的 API 额度。实体解析 pass（ontology.resolve）把“K8s”和“Kubernetes”合并成一个节点，但合并提案默认需要人工审核，不会静默执行。

证据链：每条关系都能追溯到具体句子

图谱中的每条关系可以携带 evidence（支撑它的文本片段）、confidence（0 到 1）和 source_doc。这意味着一个结论能追溯到具体句子，而不是整篇文档。更细致的是边的双时态设计：当新文档与旧事实矛盾时，旧边会被标记为失效，而不是直接碰撞。默认答案会排除矛盾，as_of 查询可以回答“今年一月我们相信什么”。如果存在模糊矛盾，系统会通过 output trust 审查机制暴露给用户。这种设计让图谱具备了一定的历史记忆，但代价是复杂度，配置和审查流程需要团队投入精力。

检索是三通道融合，图谱只是其中一路

每次搜索融合三个通道：BM25 词法匹配、向量检索、图谱邻近度。查询词先映射到实体，然后做有界遍历，对实体邻域排序，最后在 search.hybrid_weight_graph 配置的权重下融合。关键设计是：空 ontology 不会影响结果，字节级一致，所以图谱可以逐步增量启用。这意味着你不必一开始就构建完整图谱，可以先跑基础检索，再按需开启图谱 pass。社区检测（ontology.communities.enabled）是可选的全局模式，用于回答“整个语料库的主要主题是什么”，它会生成缓存的社区摘要。

部署与配置：从本地 Obsidian 到 PostgreSQL

安装后，个人用户可以用 init --vault 覆盖现有 Obsidian 仓库，配合本地模型实现零成本运行。团队可以共享一个 wiki，通过 git 或自托管服务器，审核实体解析提案和输出信任。公司级部署需要把存储切换到 PostgreSQL/pgvector，开启 metrics，前端加认证，并用分层编译（tiered compilation）扩展摄取能力。配置集中在 config.yaml，支持多 provider 设置和 serve worker。HTTP API 提供 /v1 REST 接口，包含认证、错误模型、幂等性和异步任务。MCP 有 19 个工具，配合生成的 skill 文件，教导代理何时搜索、捕获和编译。

限制与失败模式：LLM 成本与实时性

最明显的限制是编译不是实时的。文档进入后需要经过 LLM 编译，这个过程是异步的，索引速度取决于硬件和模型。虽然分层编译声称能处理 10 万+ 文档，但成本预算必须仔细计算，因为每个可选 pass 都会增加 LLM 调用。另一个风险是概念去重（dedup_strategy: "llm"）虽然能折叠同义表述，但枚举实体永远不会折叠，比如 mw-3 不会变成 mw-2，这需要人工判断。如果团队不打算维护实体解析的审核流程，图谱的质量会逐渐下降。最后，即使有证据链，默认答案仍然可能包含未验证的生成内容，output trust 机制要求查询输出先隔离，但这一步需要人工参与，不适合追求全自动化的场景。

替代方案：向量数据库与手工知识图谱

最直接的替代是纯向量数据库，比如 pgvector 或专用向量库。它们的优势是部署简单，不需要 LLM 编译步骤，实时索引，但代价是只能做相似性检索，无法回答多跳关系问题。另一种替代是手工维护知识图谱，比如用 Neo4j，这能精确控制关系，但维护成本极高，需要人工抽取三元组，而且很难跟上文档变化。sage-wiki 的中间路线是：用 LLM 自动生成图谱，但保留人工审核点。与向量库相比，它多了关系推理；与手工图谱相比，它省去了人工抽取。但这也意味着它同时继承了 LLM 的不确定性和图谱的维护负担。

编辑结论

sage-wiki 适合已经拥有大量文档、且愿意接受异步编译和 LLM 成本的团队，尤其是那些需要跨文档回答多跳关系问题的场景。个人用户可以用本地模型把成本压到零，但需要接受较慢的编译速度。不适合对实时性要求极高、或无法接受任何 LLM 幻觉风险的组织，因为即使有证据链和置信度，默认答案仍然可能包含未验证的生成内容。在采用前，应先验证三件事：你的文档格式是否被 ingest 管线支持，ontology.triples 和 dedup_strategy: "llm" 这两个可选 pass 的额外 LLM 调用是否符合预算，以及团队是否愿意维护 entity resolution 的审核流程。若这些都能接受，sage-wiki 的图即检索通道设计比传统向量库多了一层可解释的关系推理，值得小规模试点。

官方来源

1. Official README
2. Project repository
3. Release notes