sage-wiki: A Graph Memory That Turns Documents into a Queryable Wiki

What sage-wiki Solves and Who It Is For

sage-wiki addresses the problem of knowledge that is scattered across documents and hard to query relationally. A vector search can find passages that look like a query, but it cannot answer a question that requires hopping from one concept to another across multiple documents. sage-wiki compiles dropped-in documents into an interlinked wiki and a knowledge graph, so a question like 'which services depend on the authentication module?' can be answered by graph traversal rather than by hoping one chunk contains the whole chain. The intended users are AI agents and humans working on the same corpus: agents query through MCP tools, humans browse Obsidian-native markdown, a TUI, or a web UI. The README positions it for three scales: a personal Obsidian vault with local models, a team hub shared via git or a self-hosted server, and a company knowledge graph backed by PostgreSQL and pgvector. This is not a note-taking app; it is a compiler and a retrieval layer that assumes you have a body of documents worth interlinking.

The Compile Pipeline: From Sources to a Wiki

The core mechanism is a compile pipeline that reads papers, notes, code, and email, then summarizes, extracts concepts, and writes interconnected articles. The README describes it as 'your sources in, a wiki out.' Every new source enriches existing articles, so the wiki compounds as it grows. The pipeline is tiered for scale: it indexes everything fast and spends LLM budget only where it matters, which is how the project claims to scale to 100K+ documents. The graph is built as a compile output, not as a second database you have to keep in sync. That design choice is significant: you do not maintain the graph separately; it is derived from your sources each time you run the compiler. The README also mentions an optional structured-output pass called `ontology.triples` that extracts subject-relation-object triples directly. This pass adds one LLM call per document and is off by default, so the default pipeline never spends your API key without explicit opt-in.

The Evidenced Graph: Relations with Provenance

A standard knowledge graph stores entities and relations, but sage-wiki can go further with what it calls an evidenced graph. Each relation can carry `evidence` (the span that supports it), `confidence` (a number between 0 and 1), and `source_doc`, so a conclusion traces to the sentence that justified the edge rather than to a whole document. The README gives the example that 'K8s' and 'Kubernetes' become one node via entity resolution, and that proposals are review-gated by default rather than silently merged. There is also a concept curation pass (`dedup_strategy: "llm"`) that sees the whole proposed concept set at once, the only stage with a global view, and judges keep, fold, or drop per concept. Semantic restatements fold, but enumerated entities never fold: `mw-3` is not `mw-2` at any similarity. Drops stay logged as proposals until `llm_dedup.allow_drop` opts in. This design favors safety over automation. The cost is that you must review proposals if you want the graph to stay clean, which is a real operational burden.

Hybrid Search and Graph-Aware Retrieval

Retrieval in sage-wiki fuses three channels: lexical BM25, vector, and graph proximity. Query terms seed entities, a bounded traversal ranks their neighborhood, and the three fuse at a configurable weight, `search.hybrid_weight_graph`. The README states that an empty ontology costs nothing and leaves results byte-identical, so the graph earns its place incrementally. That is a pragmatic design: you can start with plain hybrid search and enable graph passes later without changing your results until you do. Graph queries go through `wiki_graph_query`, and answers are grounded only in serialized graph edges. With the evidenced graph enabled, each citation carries its source document and confidence. There is also an optional community detection pass (`ontology.communities.enabled`) that generates cached community summaries for corpus-wide questions, answered via `wiki_graph_query` with `mode: "global"`. The graph is not a side view; it is a retrieval channel that participates in every search, but only if you have built it.

Getting Started: Commands and Configuration

The README points to an Install section and a Quickstart, but the cleaned material does not include the exact install command. What is visible is that the binary is called `sage-wiki`, and you can run commands like `sage-wiki ontology query --entity kubernetes --depth 3 --direction both` to query the graph directly, or `sage-wiki provenance "service mesh"` to see which sources produced a concept. For a personal vault, the README mentions `init --vault` to overlay an existing Obsidian vault. Configuration lives in a `config.yaml`, and the full annotated version is in the Configuration guide. The README names several config keys: `ontology.triples`, `ontology.resolve`, `dedup_strategy`, `llm_dedup.allow_drop`, `search.hybrid_weight_graph`, and `ontology.communities.enabled`. The judgment prompt for concept curation is workspace-overridable at `prompts/curate-concepts.md`. For team use, you can share one wiki via git or a self-hosted server, and for company scale, you move storage to PostgreSQL/pgvector and turn on metrics.

Limitations and Failure Modes

The most obvious limitation is that the evidenced graph is not free. Enabling `ontology.triples` adds one LLM call per document, and the concept curation pass requires a global view, which means it cannot be parallelized across documents in the same way as the tiered compilation. The review gates for entity resolution and output trust mean that someone must look at proposals; if you expect a fully autonomous pipeline, this will disappoint. The README also describes a quarantine mechanism for query outputs until they are verified, which implies that answers can be wrong and need human confirmation. Another failure mode is the reliance on an LLM compiler: if your documents are highly technical or use domain-specific jargon, the extraction quality depends on the model's ability to understand that domain. The README mentions local models for zero cost, but does not specify which models are supported or what quality to expect. Finally, the project is young, with the latest release at v0.2.10, so the API and configuration schema may still change between minor versions.

Alternatives and How They Differ

The closest alternative is a traditional vector database with a retrieval-augmented generation (RAG) pipeline, such as using pgvector directly or a tool like LangChain with a vector store. The difference is that those approaches retrieve passages by similarity and do not build an explicit graph of relations. sage-wiki's graph is a compile output, not a second database you have to keep in sync. Another alternative is a classic wiki or a note-taking tool like Obsidian with backlinks, which lets humans create links manually but gives agents no structured graph to query. sage-wiki automates that linking through LLM compilation, but it adds the cost of running a compiler and reviewing its output. A third alternative is a dedicated knowledge graph database like Neo4j, where you define the schema and load triples yourself. sage-wiki differs by extracting the graph from documents automatically, but it gives you less control over the schema unless you use the configurable relations guide. The trade-off is automation versus control.

Maintenance, License, and Upgrade Considerations

The project is licensed under MIT, which is permissive and allows commercial use, modification, and redistribution with attribution. The repository is actively maintained, with the last push on 2026-08-22 and three releases in August 2026 (v0.2.8, v0.2.9, v0.2.10). That cadence suggests a project that is evolving quickly, which is good for bug fixes but raises the cost of upgrades if configuration keys change. The README mentions a self-hosted server guide and a metrics guide, so operational tooling exists, but there is no mention of a migration path between versions. The graph is bi-temporal, meaning edges are versioned over time, and contradicting a fact invalidates the old edge instead of colliding. That is a sophisticated feature, but it also implies that the storage layer must handle temporal queries, which could add complexity when you upgrade. For a company deployment, you would need to front the server with auth, as the README notes, and manage the PostgreSQL/pgvector backend. The maintenance cost is not trivial: you are running an LLM compiler, reviewing proposals, and keeping the configuration in sync with a fast-moving codebase.

Editorial conclusion

Adopt sage-wiki if you need a self-hosted knowledge base that both humans and AI agents can query, especially if you want provenance-bearing graph relations and are willing to run an LLM compiler. Skip it if you require a fully automated pipeline with no review steps, or if your corpus is small and a plain wiki suffices. Before adopting, verify the configuration guide for storage backends, the local-models guide for offline use, and the output-trust workflow to understand the quarantine and review process. The project is under active development with recent releases, so check the changelog for breaking changes in the 0.2.x series.

Official sources

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