sage-wiki: an LLM-compiled knowledge graph that agents and humans share

What sage-wiki is for, and who ends up using it

Most retrieval setups answer a question by finding a passage that looks like it. That works until the answer needs two or three hops: a person, the project they worked on, the tool that project used. No single chunk contains the chain, so vector search returns something adjacent and the model fills the gap.

sage-wiki takes the position that the chain should be written down at compile time. Documents go in, an LLM compiler summarizes them, extracts concepts, and writes interconnected markdown articles. The README describes the result as a wiki that compounds: every new source enriches existing articles rather than sitting beside them.

The intended audience is split, and the split is the interesting part. Agents reach the same data through 19 MCP tools plus generated skill files that tell them when to search, capture, and compile. Humans get Obsidian-native markdown, a TUI, and a web UI. There is no export step between the two views, because there is only one store.

The README frames the deployment ladder as personal vault, team hub, company knowledge graph. That ladder is real in the sense that the storage and serving options change at each rung, but the same binary serves all three.

The compile pipeline and where the graph comes from

The compile pipeline is the ingestion layer. It reads papers, notes, code, and email, summarizes, extracts concepts, and writes articles. Entities are typed as concepts, sources, or artifacts, and links between them carry a relation type. The relation vocabulary is not fixed: the README points to a configurable-relations guide, so the schema is yours to define.

The graph is a compile output, not a second database. That is a deliberate architectural choice and it removes a whole class of drift problems, because there is no synchronization job that can fall behind.

Two passes are opt-in. ontology.triples runs a structured-output extraction that produces subject, relation, object directly, at the cost of one extra LLM call per document. ontology.resolve handles entity resolution, so K8s and Kubernetes collapse to one node. The README states that resolution proposals are review-gated by default rather than silently merged. That default is the right one, and it also means a fresh install will accumulate proposals that someone has to look at.

A third opt-in pass, dedup_strategy set to "llm", sees the entire proposed concept set at once and judges keep, fold, or drop per concept. The README is specific about the rules: semantic restatements fold, enumerated entities never fold (mw-3 is not mw-2 at any similarity), and drops remain logged proposals until llm_dedup.allow_drop is enabled. The prompt is overridable at prompts/curate-concepts.md.

Edges are bi-temporal. When a fact is contradicted, the old edge is invalidated rather than overwritten, so as_of queries can answer what was believed at a point in time. Ambiguous contradictions still surface through the output trust review path.

Graph as a retrieval channel, not a side view

The claim worth examining is that the graph participates in search rather than decorating it. Every search fuses three channels: lexical BM25, vector similarity, and graph proximity. Query terms seed entities, a bounded traversal ranks their neighborhood, and the three channels combine at the search.hybrid_weight_graph key.

The README makes a falsifiable statement here: an empty ontology costs nothing and leaves results byte-identical. If that holds, the graph earns its place incrementally and you can enable it later without a migration. If it does not hold, the graph is a permanent tax on every query. That is the first thing to check in your own deployment.

Direct queries are available from the CLI. The README gives two examples, an ontology traversal and a provenance lookup:

Installing sage-wiki and running a first query

The README's own navigation points to an Install section and a Quickstart, but the truncated text does not include their contents, so the exact install commands are not reproduced here. What the repository does show is the Dockerfile, which builds the web UI in a Node stage, builds the Go binary with the webui tag, and produces a runtime image on alpine:3.21 running as an unprivileged wiki user with /wiki as a volume and port 3333 exposed.

The Dockerfile comment is unusually explicit about a security constraint. The web UI binds 0.0.0.0 inside a container, which is non-loopback, so a token is required and the server refuses to start without one. The same bind is subject to a DNS-rebind Host allowlist, so SAGE_WIKI_ALLOWED_HOST must name the host you browse to.

docker run -e SAGE_WIKI_TOKEN="$(openssl rand -hex 32)" \
  -e SAGE_WIKI_ALLOWED_HOST=your-host \
  -p 3333:3333 -v "$PWD:/wiki" <image>

After the container starts, the comment says to open http://your-host:3333/?token=<that token> in a browser. The token travels in the query string, which is worth noticing before you paste it into a shared channel.

For a personal vault, the pattern the README names is init --vault, which overlays an existing Obsidian vault rather than importing it. Local models are documented as a zero-cost option, and the graph passes are enabled afterwards by turning on ontology.triples and ontology.resolve.

Once compiled, the two CLI queries from the README are the fastest way to confirm the graph exists:

sage-wiki ontology query --entity kubernetes --depth 3 --direction both
sage-wiki provenance "service mesh"

The first walks the neighborhood of an entity up to three hops in both directions. The second reports which sources produced a given concept. If the second returns nothing, the evidenced graph is probably still off. Building from source follows the Makefile: make build sets CGO_ENABLED=0, and make build-webui adds the webui tag that the Dockerfile uses.

What sage-wiki does not do well

The graph passes cost an LLM call per document. The README says as much for ontology.triples, and the same economics apply to the concept-curation pass, which needs a whole-set view. On a large corpus that is a real bill, and it is the reason tiered compilation exists: index everything cheaply, spend budget only where it matters. Tiered compilation is described as scaling to 100K+ documents, but the README does not explain the tier boundaries in the text available here, so treat the number as a design target rather than a guarantee.

The review gates are a second cost, and a human one. Entity-resolution proposals and output-trust quarantine both wait for a person. A solo user who wants an unattended pipeline will find the defaults obstructive, and turning them off trades correctness for autonomy. That is a genuine trade-off, not a configuration detail.

The wrong tool cases are clear enough. If you need a graph database you can query with your own Cypher or SPARQL, sage-wiki is not that: the graph is a compile artifact with its own query surface. If your corpus changes constantly and you need answers within seconds of a document landing, a compile pipeline is the wrong shape. And if you want pure vector search over chunks with no LLM in the ingestion path, the whole compile stage is overhead you are paying for nothing.

Finally, the README does not document rollback. There is no described procedure for reverting a bad compile or undoing a merge that should not have happened, beyond the proposal log for drops.

How it differs from wiring a vector store into an agent

The obvious alternative is a vector database plus an embedding model, with the agent calling a search tool. That stack is well understood, cheap to run, and requires no compile step. Its weakness is exactly the case sage-wiki targets: relational questions. A vector store retrieves passages that resemble the query; it has no representation of how things connect, so a three-hop question depends on luck.

A second alternative is a dedicated graph database such as Neo4j or a triple store, populated by your own extraction code. That gives you full control over the schema and a mature query language. The cost is that you now maintain two stores and a synchronization path between them, and the graph drifts from the documents it came from. sage-wiki's answer is to make the graph a compile output so there is nothing to keep in sync. The price is that you query the graph through sage-wiki's surface rather than your own.

The provenance model is where the difference shows most. Every evidenced relation records which document asserted it, and can carry the supporting span and a confidence value between 0 and 1. A citation therefore points at a sentence, not at a file. Vector search cannot produce that without a separate citation-extraction layer.

Maintenance, upgrades and the MIT licence

The repository is not archived and the last push was on 2026-08-22, which is under a month before the date of writing. Releases v0.2.8, v0.2.9 and v0.2.10 landed on 2026-08-05, 2026-08-14 and 2026-08-22, so the cadence across that window was roughly weekly. The version numbers are still 0.2.x, which is worth weighing if you plan to depend on the HTTP API surface.

The Makefile describes make ci as a local mirror of the CI quality gate, and its comment includes what it calls an honesty contract: the local gate prints what it does not cover, including OS execution, PostgreSQL and MinIO service tests, pinned-container frontend checks, scheduled fuzz exploration, and exact-SHA publication proof. That is a useful signal about how the maintainers think about test claims, and it also tells you what a local make ci run will not verify for you.

Upgrade cost is dominated by the compile pipeline rather than the binary. Changing the relation vocabulary or the curation prompt can change output for every document, and the README does not describe a recompile strategy for existing articles. Budget for that before you define a custom ontology.

The licence is MIT, which permits commercial use and modification. The README links to a Sage Framework repository, and it does not state a licence for that dependency or for the model providers you configure. Check those separately; this is a description of what the repository states, not legal advice.

Editorial conclusion

Adopt sage-wiki if you want one artifact that both an agent and a person can read, and you accept that the evidenced graph only appears after you turn on ontology.triples and ontology.resolve. Do not adopt it if you need a graph database you control directly, or if you cannot spend an LLM call per document. Verify first that your model provider is configured, that the server refuses to start without SAGE_WIKI_TOKEN when bound to a non-loopback address, and that an empty ontology leaves search results unchanged as the README claims.

Frequently asked questions

Official sources

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