sage-wiki: graph memory with evidence on every edge, and a container that refuses to start without a token
sage-wiki is a graph memory and knowledge base that AI agents and humans build and query together. Drop in documents; an LLM compiler turns them into an interlinked wiki with a knowledge graph. One Go binary scales it from a personal vault to a team hub to a company knowledge graph.
At a glance
- What is it?
- sage-wiki is a single Go binary that compiles dropped-in documents into an interlinked markdown wiki with a knowledge graph, queried by agents over MCP and by people as plain files. The graph is opt-in, and when you switch it on each relation carries the sentence that justified it.
- Who is it for?
- sage-wiki suits teams that want their documents to become a queryable graph rather than a folder of summaries, and who are willing to run an LLM compiler pass over their corpus. Before adopting it, decide which graph passes you actually want, since the triples pass costs one LLM call per document and drops need `llm_dedup.allow_drop` before they take effect.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- xoai/sage-wiki657 ★ · +89
| Repository | 2026-07-31 | 2026-11-15 |
|---|---|---|
| xoai/sage-wiki | 568 | 657 |
89 Stars in the last 107 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The container refuses to start without a token
The runtime stage of the image makes a security decision explicit in a comment. The web UI binds `0.0.0.0` for container networking, which is not a loopback address, 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` has to be set to the hostname or address you actually browse to, whether you reach it directly or through a proxy. The documented invocation sets both variables and maps the port:
docker run -e SAGE_WIKI_TOKEN="$(openssl rand -hex 32)" \
-e SAGE_WIKI_ALLOWED_HOST=your-host -p 3333:3333 -v "$PWD:/wiki" <image>The token then travels in the URL as a query string, `http://your-host:3333/?token=`, which is convenient and also puts the credential in browser history. The image itself is built in three stages: a Node 22 stage compiles the web UI, a Go 1.26 stage builds the binary with cgo disabled and a webui build tag, and the runtime is Alpine 3.21 with a non-root user at uid 1000, a `/wiki` volume and port 3333 exposed.
make ci prints what it does not cover
The Makefile is written to be locally reproducible and says so in unusually blunt terms. It calls itself a mirror of the CI quality gate and states that `make ci` is the fast local gate that prints what it does not cover. Hosted-only evidence, the things you cannot reproduce on a laptop, is enumerated: operating system execution, the PostgreSQL and MinIO services, the pinned-container frontend, scheduled fuzz exploration, and exact-SHA publication proof. The reference to that honesty contract is dated and task-numbered in the file itself. Two policy details explain the target list. Build and vet run with cgo disabled, matching a release binary that is pure Go on top of modernc.org/sqlite, while the race targets turn cgo back on because the race detector requires it. Service-backed tests stay environment-gated through `TEST_DATABASE_URL` and `SAGE_TEST_MINIO`, and the lint target pins golangci-lint at v2.12.2 while `lint-new` filters to new issues against a merge base.
Three retrieval channels fuse at one weight
Search does not rely on the graph alone, and the graph is not a separate database to keep in sync: it is a compile output. Every search fuses three channels, lexical BM25, vector similarity, and graph proximity. Query terms seed entities, a bounded traversal ranks their neighbourhood, and the three signals combine at the `search.hybrid_weight_graph` setting. The design commitment worth noting is what happens with nothing to fuse. An empty ontology costs nothing and leaves results byte-identical to a graph-free setup, which means you can adopt the graph passes one at a time without changing what your existing queries return. The same reasoning applies to the graph query interface itself, which can be driven from the command line:
sage-wiki ontology query --entity kubernetes --depth 3 --direction both
sage-wiki provenance "service mesh" # which sources produced this conceptConcept curation never folds an enumerated entity
One opt-in pass, `dedup_strategy: "llm"`, is the only stage that sees the whole proposed concept set at once, and it judges each concept as keep, fold or drop. Its rules are specific in ways that matter. Semantic restatements fold, and when they do the aliases and sources merge. Enumerated entities never fold, with the example given being that `mw-3` is not `mw-2` at any similarity score, so a numbering scheme cannot be collapsed by an embedding. Drops are conservative by default: they stay as logged proposals until `llm_dedup.allow_drop` is turned on, which means an LLM can never silently delete a concept in the default configuration. The judgment prompt is workspace-overridable at `prompts/curate-concepts.md`. Entity resolution is review-gated for the same reason, merging names like K8s and Kubernetes only after a proposal rather than on the spot.
Contradicting a fact invalidates the old edge
Edges are bi-temporal, which changes what happens when two documents disagree. Contradicting a fact invalidates the earlier edge instead of letting the two collide, so default answers come back contradiction-free without you having to filter anything. Time travel is a first-class query: an `as_of` query answers what the graph believed at a past point, which is the mechanism behind asking what was believed in January. Genuinely ambiguous contradictions are not resolved silently either; they surface through the output trust review path. Trust runs through the rest of the system as well. Query outputs are quarantined until verified, and every evidenced relation records which document asserted it, with the supporting span, a confidence value between 0 and 1, and the source document name. For corpus-wide questions there is a separate opt-in community detection pass that generates cached summaries and answers through a global mode of the graph query tool.
Nineteen MCP tools teach an agent when to search
The agent surface is 19 MCP tools plus generated skill files, and the point of the skill files is timing rather than capability. They teach an agent when to search, when to capture something new, and when to compile, which is the behaviour most retrieval tools leave to the caller. Answers are constrained rather than merely cited: graph query answers are grounded only in serialized graph edges, so a hop the graph does not contain is not available to the agent even if the underlying documents mention it. The same binary serves people through Obsidian-native markdown, a terminal interface built with bubbletea, and a web interface compiled from the `web/` directory. There is also a REST surface at `/v1` with authentication, an error model, idempotency and asynchronous jobs, so an agent path and a service path can coexist over one store.
One binary, four deployment shapes, one storage layer that moves
The scale story is a storage story. The same executable covers a personal vault overlaid onto an existing Obsidian directory with `init --vault`, a team hub shared over git or a self-hosted server with federation across wikis, and a company deployment that moves storage to PostgreSQL with pgvector, turns on metrics and puts authentication in front. The Go module targets 1.26 with a pinned toolchain, and its dependency list shows the surface area: pgx and the pgvector driver for the server-backed path, modernc.org/sqlite for the embedded one, mcp-go for the agent protocol, cobra for the command line, prometheus client libraries for metrics, a keyring library for OS credential storage, and yaml.v3 for configuration. Documentation exists in seven languages, and the repository also carries example integrations for embedding, LangGraph and the Vercel AI SDK, an `eval/` directory and a `skills/` directory at the top level. The scale claim is 100K+ documents, where tiered compilation indexes everything quickly and spends model budget only where it matters, and the lineage is stated plainly: the project grew from an idea about an LLM-compiled personal knowledge base and is built on the Sage Framework. Releases are landing weekly at present, v0.2.8 on 2026-08-05, v0.2.9 on 2026-08-14 and v0.2.10 on 2026-08-22, with the last commit to main on 2026-09-25.
Editorial conclusion
sage-wiki suits teams that want their documents to become a queryable graph rather than a folder of summaries, and who are willing to run an LLM compiler pass over their corpus. Before adopting it, decide which graph passes you actually want, since the triples pass costs one LLM call per document and drops need `llm_dedup.allow_drop` before they take effect. Plan the operational side too: the container will not start without a token, the host allowlist has to match how you browse, and `make ci` deliberately does not reproduce the hosted checks. Teams who only need markdown search over a vault get the same binary with the ontology left empty and identical results.
Frequently asked questions
What happens if I run the sage-wiki container without a token?
The server refuses to start. The web UI binds 0.0.0.0, which is not loopback, so a token is required, and the host allowlist means SAGE_WIKI_ALLOWED_HOST has to match the address you browse to.
Does sage-wiki need a graph to answer questions?
No. Search fuses lexical BM25, vector and graph proximity, and an empty ontology costs nothing and leaves results byte-identical, so the graph passes can be enabled one at a time.
How many MCP tools does sage-wiki expose?
Nineteen, along with generated skill files that tell an agent when to search, capture and compile. Graph query answers are grounded only in serialized graph edges.
What does the sage-wiki triples pass cost?
It is opt-in through ontology.triples and adds one LLM call per document. Concept curation drops also stay as logged proposals until llm_dedup.allow_drop is enabled.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/xoai-sage-wiki)Star history chart for your README
[](https://hysenlabs.com/projects/xoai-sage-wiki)Was this useful?