Sage-Wiki

With web UI (requires Node.js for building frontend assets)

git clone https://github.com/xoai/sage-wiki.git && cd sage-wiki cd web && npm install && npm run build && cd .. go build -tags webui -o sage-wiki ./cmd/sage-wiki/ ```

Browse in the browser (requires -tags webui build)

sage-wiki serve --ui

Install

```bash

First Compile

sage-wiki compile

First Compile

sage-wiki compile

Docker

```bash

Or from Docker Hub

docker pull xoai/sage-wiki:latest

Or build from source

docker build -t sage-wiki . docker run -d -p 3333:3333 -v ./my-wiki:/wiki -e GEMINI_API_KEY=... sage-wiki ```

Available tags: :latest (main branch), :v1.0.0 (releases), :sha-abc1234 (specific commits). Multi-arch: linux/amd64 and linux/arm64.

See the self-hosting guide for Docker Compose, Syncthing sync, reverse proxy, and LLM provider setup.

Source folders to watch and compile

sources: - path: raw # or vault folders like Clippings/, Papers/ type: auto # auto-detect from file extension watch: true

output: wiki # compiled output directory (_wiki for vault overlay)

The api section configures the primary LLM provider used for all compiler

Multi-Provider Setup

sage-wiki lets you use different LLM providers for different tasks. The api section sets the primary provider for generation (summarize, extract, write, lint, query), while embed can use a completely separate provider for embeddings — each with its own credentials and rate limits.

Use cases: - Cost optimization — cheap model for bulk summarization, quality model for article writing - Best-of-breed — Claude for generation, OpenAI for embeddings, Ollama for local search - Subscription mixing — use your ChatGPT subscription for generation and Gemini subscription for embeddings

Example: Claude for generation + OpenAI embeddings

api:
  provider: anthropic
  api_key: ${ANTHROPIC_API_KEY}

models:
  summarize: claude-haiku-4-5-20251001    # cheap for bulk work
  extract: claude-haiku-4-5-20251001
  write: claude-sonnet-4-20250514         # quality for articles
  lint: claude-haiku-4-5-20251001
  query: claude-sonnet-4-20250514

embed:
  provider: openai
  model: text-embedding-3-small
  api_key: ${OPENAI_API_KEY}

Example: Subscription auth with two providers

sage-wiki auth login --provider anthropic
sage-wiki auth import --provider gemini

api:
  provider: anthropic
  auth: subscription

embed:
  provider: gemini
  # no api_key needed — uses imported Gemini subscription credentials

The models section controls which model is used per task, all within the primary provider. Different models can have very different cost/quality tradeoffs — use smaller models (haiku, flash, mini) for high-volume passes like summarization, and larger models (sonnet, pro) for article writing and Q&A.

Or install and apply to an existing project

sage-wiki pack install academic-research sage-wiki pack apply academic-research --mode merge

Install from a Git URL

sage-wiki pack install https://github.com/someone/their-pack.git

Team Setup

sage-wiki scales from a single-person wiki to a shared knowledge base for teams of 3-50. Three deployment patterns:

Git-synced repo (3-10 people) — the wiki lives in a Git repository. Everyone clones, compiles locally, and pushes. The compiled wiki/ directory is tracked; the database is .gitignored and rebuilt on each compile.

Shared server (5-30 people) — run sage-wiki on a server with the web UI. Team members browse in the browser and connect agents via MCP over SSE.

Hub federation (multi-project) — each project has its own wiki. The hub system federates them into a single search interface with sage-wiki hub search.

```bash

Guides

Quickstart

Edit config.yaml to add api key, and pick LLMs

Edit config.yaml to set source/ignore folders, add api key, pick LLMs

Configuration

config.yaml is created by sage-wiki init. Full example:

```yaml version: 1 project: my-research description: "Personal research wiki"

Embedding provider (optional — auto-detected from api provider)

Ontology types (optional)

Configurable Relations

The ontology has 8 built-in relation types: implements, extends, optimizes, contradicts, cites, prerequisite_of, trades_off, derived_from. Each has default keyword synonyms used for automatic extraction.

You can customize relations via ontology.relations in config.yaml:

• Extend a built-in type — add synonyms (e.g., multilingual keywords) to an existing type. The default synonyms are kept; yours are appended.
• Add a custom type — define a new relation name with its keyword synonyms. Relation names must be lowercase [a-z][a-z0-9_]*.

Relations are extracted using block-level keyword proximity — a keyword must co-occur with a [[wikilink]] in the same paragraph or heading block. This prevents spurious edges from cross-paragraph matches.

You can also restrict which entity types a relation connects:

ontology:
  relation_types:
    - name: curated_by
      synonyms: ["curated by", "organized by"]
      valid_sources: [exhibition, program]
      valid_targets: [artist]

When valid_sources/valid_targets are set, edges are only created if the source/target entity type matches. Empty = all types allowed (default).

Zero config = identical to current behavior. Existing databases are migrated automatically on first open. See the full guide for domain-specific examples, type-restricted relations, and how extraction works.

config.yaml

trust: include_outputs: verified # "false" (exclude all), "verified" (confirmed only), "true" (legacy) consensus_threshold: 3 # confirmations needed for auto-promote grounding_threshold: 0.8 # minimum grounding score similarity_threshold: 0.85 # cosine similarity for question matching auto_promote: true # auto-promote when thresholds met

**How it works:**

1. **Query** — sage-wiki answers your question. The output is written to `wiki/under_review/` as pending.
2. **Consensus** — If the same question is asked again and produces the same answer from different source chunks, confirmations accumulate. Independence is scored via Jaccard distance between chunk sets.
3. **Grounding** — Run `sage-wiki verify` to check claims against source passages via LLM entailment.
4. **Promotion** — When both consensus and grounding thresholds are met, the output is promoted to `wiki/outputs/` and indexed into search.

config.yaml

parsers: external: true # enable external parser loading trust_external: true # acknowledge that parsers run unsandboxed ```

Security: external parsers run with timeout enforcement (30s default, 120s max) and environment stripping (only PATH, HOME, LANG). They require double opt-in: parsers.external: true to load parser definitions, and parsers.trust_external: true to acknowledge that parsers execute as unsandboxed subprocesses. Packs with parsers also require --enable-parsers during pack apply.

See CONTRIBUTING.md for the full parser authoring guide.

Recommended team config

trust: include_outputs: verified # quarantine until verified compiler: default_tier: 1 # index fast, compile on demand auto_commit: true # audit trail ```

See the full team setup guide for source organization, agent integration workflows, knowledge capture pipelines, scaling considerations, and ready-to-use recipes for startups, research labs, and Obsidian vault teams.

CLI only (no web UI)

go install github.com/xoai/sage-wiki/cmd/sage-wiki@latest

Folders to never read or send to APIs (vault overlay mode)

base_url: https://openrouter.ai/api/v1

api_key: ${DASHSCOPE_API_KEY}

api: provider: gemini api_key: ${GEMINI_API_KEY} # env var expansion supported # auth: subscription # use subscription credentials instead of api_key # requires: sage-wiki auth login --provider <name> # supported providers: openai, anthropic, gemini # base_url: # custom endpoint (OpenRouter, Azure, etc.) # rate_limit: 60 # requests per minute # extra_params: # provider-specific params merged into request body # enable_thinking: false # e.g., disable Qwen thinking mode # reasoning_effort: low # e.g., DeepSeek reasoning control

can use a DIFFERENT provider for embeddings — with its own api_key, base_url,

api:

api_key: ${ANTHROPIC_API_KEY}

api_key: ${OPENAI_API_KEY}

#

Or import from an existing CLI tool

sage-wiki auth import --provider claude sage-wiki auth import --provider copilot sage-wiki auth import --provider gemini

Then set `api.auth: subscription` in your `config.yaml`:

All commands will use your subscription credentials. Tokens refresh automatically. If a token expires and can't refresh, sage-wiki falls back to api_key with a warning.

Limitations: Batch mode is unavailable with subscription auth (auto-disabled). Some models may not be accessible via subscription tokens. See the subscription auth guide for details.

MCP Integration

Ask questions

sage-wiki query "How does flash attention optimize memory?"

similarity_threshold: 0.85 # question matching threshold