Synthadoc

.-+###############+-.
    .##                   ##.
   ##    .----.   .----.    ##
  ##    /######\ /######\    ##
  ##    |######| |######|    ##
  ##    | [SD] | | wiki |    ##
  ##    |######| |######|    ##
  ##    \######/ \######/    ##
   ##    '----'   '----'    ##
    '##                   ##'
      '-+###############+-'
S Y N T H A D O C
    Community Edition  v1.5.0
  ────────────────────────────────
  Domain-agnostic LLM wiki engine

Document version: v1.5.0

Engineered for solo users and enterprises alike, providing a domain-specific knowledge base that scales seamlessly while maintaining accuracy through autonomous self-optimization.

Built for individuals, small teams, and large organizations who need a knowledge base that stays accurate as documents accumulate.

Documentation, FAQ and articles: https://axoviq.com/resources/synthadoc

Synthadoc reads your raw source documents — PDFs, spreadsheets, PPTs, web pages, images, videos, Word files, TXTs, and AI session transcripts (.jsonl) — and uses an LLM to synthesize them into a persistent, structured wiki. Cross-references are built automatically, contradictions are detected and surfaced, orphan pages are flagged, and every answer cites its sources. Outputs are stored as local Markdown files, ensuring seamless integration and autonomous management within Obsidian or any wiki-compliant ecosystem.

▶ From Documents to Wiki

▶ Four Interfaces: CLI, Obsidian, Web UI & MCP

▶ Agentic Maintenance Workflow

📝 Blogs & Media — YouTube · Coderlegion · DEV.to · Medium

📂 End-to-end Example — AquaFlow Capital M&A due diligence walkthrough

Who Is It For?
Inspiration and Vision
Problems Addressed
Why Synthadoc?
Architecture
What's Included
Installation
Quick-Start Guide
Creating Your Own Wiki
Configuration
Command Reference by Use Case
Administrative Reference
Understanding Logs and the Audit Trail
Customization
Links

Who Is It For?

Synthadoc scales from a single researcher to a company-wide knowledge platform:

| Team size | Typical use case | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Solo / 1–2 people | Personal research wiki, freelance knowledge base, indie hacker documentation - run it free on Gemini Flash or a local Ollama model with zero ongoing cost | | Small team (3–20) | Centralized internal knowledge base for startups and departments that aggregates diverse individual data sources into a unified, high-integrity wiki. The system automatically resolves contradictions and scales autonomously, ensuring organizational intelligence grows in tandem with your team | | Medium / enterprise | Compliance-sensitive knowledge bases that must stay local; per-department wikis on separate ports; audit trail for every ingest and cost event; hook system for CI/CD integration; OpenTelemetry for ops dashboards |

Built for large wikis. Measured on wikis of thousands of pages: keyword search finds the pages for an answer in about 20 ms at 2,000 pages; semantic search, on by default for new wikis when installed, puts the right page in the top 5 for 68% of questions asked in your own words, up from 48%; and the knowledge graph opens a 5,000-page wiki as a clickable overview of named topic clusters in about 6 seconds.

!Knowledge graph of a 5,000-page wiki: one bubble per topic cluster, named after its main pages, with a clickable list of clusters below The web UI's Graph tab on a 5,000-page test wiki: 100,801 links summarised as 24 named clusters. Click a cluster to see its pages. How it works

No cloud account. No vendor lock-in. The wiki is plain Markdown — open it in any editor, back it up with git, sync it with any cloud drive.

Inspiration and Vision

"The LLM should be able to maintain a wiki for you."

— Andrej Karpathy, LLM Wiki gist

Most knowledge-management tools retrieve and summarize at query time. Synthadoc inverts this: it compiles knowledge at ingest time. Every new source enriches and cross-links the entire corpus, not just appends a new chunk. The wiki is the artifact — readable, editable, and browsable without any tool running.

Long-term alignment:

| Direction | How Synthadoc moves there | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Agent orchestration | Orchestrator dispatches parallel ingest, query, and lint sub-agents with cost guards and retry backoff | | Sub-agent skills/plugins | Featuring a 3-tier lazy-load capability system, the platform allows for the injection of custom skills and hooks via a plug-and-play interface, ensuring core stability is never compromised during extension | | LLM wiki vs. RAG | Pre-compiled structured knowledge beats query-time synthesis for contradiction detection, graph traversal, and offline access | | CLI / HTTP | A unified interface via CLI and RESTful endpoints, the system streamlines full-spectrum integration: from data ingestion and querying to automated linting, security auditing, and job orchestration | | Local-first | All data stays on your machine; localhost-only network binding; no cloud dependency except the LLM API itself | | Provider choice | LLM backends including free-tier Gemini and Groq, paid Anthropic/OpenAI/DeepSeek/MiniMax/Qwen (DashScope), local Ollama and Qwen, and coding-tool CLI providers (Claude Code, Opencode) — no API key required if you already have a subscription |

Problems Addressed

RAG retrieves document chunks at query time. Synthadoc compiles knowledge at ingest — synthesising sources into a linked, audited wiki graph so contradictions are caught, claims are traced to sources, and the artifact survives outside the tool.

| Problem | Synthadoc approach | | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | Contradictions blended silently | Ingest-time conflict detection; page flaggedstatus: contradicted; auto-resolve or queue for human review | | No links between related content | [[wikilinks]] auto-built on every ingest pass; weighted graph (wikilink + co-source signals) with Louvain clustering in web UI | | Orphan pages never surfaced | Lint reports unreferenced pages with ready-to-paste index entries | | LLM output can be overconfident | Adversarial second-LLM pass flags overstated claims, unsupported superlatives, and contestable facts per page | | Claims lack source traceability | ^[file:L-L] citation on every claim; Source Viewer in Obsidian; PDF page resolution; broken-citation lint | | Knowledge lifecycle invisible | 5-state machine (draft → active → contradicted / stale → archived); auto-transitions via lint; immutable event log | | Repeat ingest is expensive | 3-layer cache (embedding, LLM, provider prompt) — repeat lint on unchanged pages costs near-zero tokens | | Knowledge locked in proprietary tools | Plain Markdown + YAML frontmatter; OKF v0.2 compatible; fully offline-readable in any editor | | Wiki structure drifts with growth | scaffold regenerates index, AGENTS.md, and purpose.md from current wiki state without touching linked pages | | Migration requires full re-ingestion | Single-zip backup + restore with port/domain rewriting; no re-ingestion needed | | Cost and compliance exposure | Localhost-only; per-job token+cost log; configurable soft-warn and hard-gate thresholds |

Citation quality: Generated pages include inline citations linking every claim to its source lines. Pages without citations trigger a model-compatibility warning — use Gemini 2.5 Flash or higher for reliable citation annotation.

> Active page protection: Pages promoted to active status are protected — sources that contradict them are flagged for review rather than overwriting the human-reviewed content.

Why Synthadoc?

Every Yes below is a built-in feature — no add-ons or upgrades required.

Knowledge Quality

Knowledge Structure

Search & Query

Interfaces & Integration

Content Sources

Operations & Trust

| Capability | Synthadoc | Typical RAG | NotebookLM | Notion AI | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------ | ---------------------- | --------------------------------------------------------------------------------------------------- | | Local-first + offline artifact — source documents never leave your machine; compiled wiki is plain Markdown, fully readable offline in any editor without the server | Yes | Varies | No | No | | Portable backup / restore — single zip: wiki pages + audit/lifecycle DB + config; port and domain rewriting on restore; migrate machines without re-ingesting | Yes | No — re-ingest required | No — AI metadata lost | No | | Lifecycle content snapshots + rollback — page body captured at every lifecycle transition (manual CLI/Obsidian, lint-driven auto-transition, or Obsidian vault save); deduplicated so unchanged saves cost nothing; browse per-page version history with lifecycle history (newest-first, with reason); restore any prior version with lifecycle rollback; rollback saves the current body first so it is always undoable | Yes | No | No | Partial — Notion has time-based edit history (plan-gated, no lifecycle tie, no auditable rollback) | | Cost guard + full audit trail — per-job token + cost log; soft-warn and hard-gate thresholds; audit citations validates every claim citation; immutable event log | Yes | No | No | No | | Citation faithfulness audit — on-demand LLM verification that each claim's text is actually supported by its cited source lines; per-page result cache with staleness detection; findings surfaced in the Obsidian source viewer | Yes | No | No | No | | Resumable job queue + retry — every ingest/lint job persisted with status and error; batch a hundred documents and resume after a crash | Yes | No | No | No | | Custom skills + CI hooks — subclass BaseSkill for new file formats; 2 hook events (on_ingest_complete + on_lint_complete); example git auto-commit hook included; blocking hooks can gate operations | Yes | Limited | No | No | | Per-source truncation flag — --max-source-chars caps any source (PDF, DOCX, web page, plain text) before the LLM call; truncated sources flagged with truncated: true in frontmatter and warned in lint output | Yes | No | No | No | | Docker deployment — official chenp/synthadoc image (amd64 + arm64); one container per wiki with HTTP API, Web UI, and MCP on one port; Compose recipes for multi-wiki cross-wiki queries and an Ollama sidecar; non-root, secrets via --env-file only | Yes | Varies — usually DIY | No | No | | Multi-wiki isolation — each wiki on its own port with independent config, audit trail, and job queue; switch with synthadoc use | Yes | No | Partial | No | | Agentic maintenance workflows — eight conversational workflows (stale-page re-ingest, broken wikilinks fix, lint report, scaffold regeneration, contradiction resolver, orphan resolver, broken citation resolver, content health resolver) via web UI or synthadoc workflow CLI; confirm-before-act gate on all writes; graph sidebar chips trigger workflows with one click | Yes | No | No | No | | Sensitive Data Retract — scan all wiki pages for API keys, emails, SSNs, credit cards, and custom patterns; apply [REDACTED] in place; background scan is incremental (only pages modified since the last cycle are checked); server auto-scans ingested pages immediately after each ingest job completes; --changed-only CLI flag for incremental manual runs; synthadoc retract status captures the full retraction audit trail (slug, pattern names, counts — never the sensitive values themselves) | Yes | No | No | No |

Business value

| Value | How | | --------------------- | ------------------------------------------------------------------------------- | | Faster onboarding | New team members query the wiki instead of digging through documents | | Audit trail | Every ingest recorded inaudit.db with source hash, token count, and timestamp | | Cost control | Configurable thresholds; 3-layer cache reduces repeat spend | | Compliance | Local-first — source documents and compiled knowledge never leave your machine | | Extensibility | Hooks fire on every event; custom skills load without a server restart |

Architecture

!Synthadoc Architecture

For full architecture details, data models, API reference, and plugin development guide see docs/design.md.

What's Included

See docs/design.md — Appendix A: Release Feature Index for a full feature list by version.

Installation

Choose one way to run Synthadoc:

| | Install with pip | Run with Docker | | --- | --- | --- | | Host requirements | Python 3.11+ | A container runtime only, with no Python or pip on the host | | Best for | Personal use on one machine | Team or shared servers, CI/CD, isolated or reproducible runtimes | | Steps | Production, then Set your API keys and Install a wiki and start the engine | Docker below, then the Docker Deployment Guide |

Production

Prerequisites: Python 3.11+. No Node.js, no Git, no build steps.

pip install "synthadoc[vectors]"   # recommended — includes semantic search
pip install synthadoc              # lightweight install, no semantic search
synthadoc --version                # confirm it works

The Obsidian plugin is bundled inside the package. New wikis created with synthadoc install have it installed automatically. If you are upgrading an existing Synthadoc installation, run synthadoc plugin upgrade to push the updated plugin binary to all registered wikis.

Docker

Prerequisites: a container runtime only (Docker Engine or Desktop, Apple container, or wslc). No Python, pip, or synthadoc install on the host: every command, including creating the wiki, runs in a container.

For server deployments, team wikis, CI/CD pipelines, and isolated personal use, Synthadoc ships an OCI image, chenp/synthadoc, for linux/amd64 and linux/arm64. It works with Docker Engine and Docker Desktop, the Apple container tool (macOS 26+ Apple Silicon), and WSL Containers (wslc, Windows 11). One container serves one wiki. The HTTP API, Web UI (/app), and MCP over HTTP (/mcp) all share the wiki's port, and the wiki files stay on the host so Obsidian keeps working unchanged.

Commands are shown for Linux / macOS. On Windows, expand the Windows (Command Prompt) block for single-line cmd.exe versions: \ line continuation and ~ in -v paths don't work there. (In PowerShell, replace %USERPROFILE% with $env:USERPROFILE.)

1. Create the wiki in a one-off container. It lands in ~/wikis/history-of-computing; note the port it prints, e.g. 7070. docker run downloads the image on first use. Run docker pull chenp/synthadoc:latest later to update a cached image.

mkdir -p ~/wikis
docker run --rm -v ~/wikis:/wikis chenp/synthadoc:latest \
  synthadoc install history-of-computing --target /wikis --demo

Windows (Command Prompt)

if not exist "%USERPROFILE%\wikis" mkdir "%USERPROFILE%\wikis"
docker run --rm -v "%USERPROFILE%\wikis:/wikis" chenp/synthadoc:latest synthadoc install history-of-computing --target /wikis --demo

2. Put your LLM API key in ~/wikis/.env, never on the command line. Create it with any text editor (Windows: notepad "%USERPROFILE%\wikis\.env"). For example, to use MiniMax:

# ~/wikis/.env
MINIMAX_API_KEY=sk-...
optional — enables web search ingest
TAVILY_API_KEY=tvly-...

Keep comments on their own line; --env-file does not strip a trailing # … from a value.

Then select the same provider in ~/wikis/history-of-computing/.synthadoc/config.toml. Under [agents], comment out the active default = line and uncomment the matching one:

[agents]
default = { provider = "minimax", model = "MiniMax-M3", thinking = "disabled" }

3. Run the server in a container, using the same port on both sides of -p:

docker run -d --name history-of-computing \
  -v ~/wikis/history-of-computing:/wiki \
  -p 7070:7070 \
  --env-file ~/wikis/.env \
  chenp/synthadoc:latest

Windows (Command Prompt)

docker run -d --name history-of-computing -v "%USERPROFILE%\wikis\history-of-computing:/wiki" -p 7070:7070 --env-file "%USERPROFILE%\wikis\.env" chenp/synthadoc:latest

4. Use it. Open the Web UI at http://localhost:7070/app, or run the CLI inside the container (same on every platform):

docker exec history-of-computing synthadoc query "Who was Alan Turing?"
docker exec history-of-computing synthadoc lint run --wait

After editing config.toml, run docker restart history-of-computing. After changing .env, remove and re-create the container (docker rm -f history-of-computing, then step 3 again), because restart does not re-read .env.

See docs/docker-deploy.md for the full deployment guide: architecture, API key setup, platform-native runtimes, Docker Compose (single wiki, multi-wiki with cross-wiki queries, Ollama sidecar), CI/CD, file permissions, security, and maintenance.

Docker users: the rest of this Installation section (Development, Set your API keys with shell exports, and Install a wiki and start the engine) is for the pip install. With Docker, API keys go in the .env file, and any synthadoc … command elsewhere in this README runs as docker exec synthadoc … (no -w needed).

Development

For developers modifying the Python engine, running the test suite, or developing the Obsidian plugin TypeScript.

Additional prerequisites: Git (any). Node.js 18+ only if modifying the plugin TypeScript source.

Step 1 — Clone and install

git clone https://github.com/axoviq-ai/synthadoc.git
cd synthadoc
pip install -e ".[dev]"

[dev] adds pytest, respx, and the other test dependencies. Tests require a source checkout — they are not included in the pip wheel.

Step 2 — Run the test suite

pytest --ignore=tests/performance/ -q

Expected: all tests pass, 0 failures. Performance benchmarks (optional):

pytest tests/performance/ -v --benchmark-disable

Step 3 — Obsidian plugin development (optional)

The compiled plugin is bundled with the package and kept up to date by CI — no build step is needed to work on the Python side or run tests.

If you modify the TypeScript source und

... (README truncated for length)

axoviq-ai/synthadoc: Synthadoc: An open-source LLM knowledge compilation engine that turns raw documents into structured, local-first wikis. A transparent, human-readable alternative to traditional RAG, which can be self-managed and self-improved wit