Synthadoc: Beyond Keyword Search -How Combines BM25 and Vector Search to Build a Smarter Domain Wiki

Paul Chen — Mon, 27 Apr 2026 00:21:34 +0000

What is Synthadoc?

Synthadoc is an open-source, LLM-powered wiki engine. Point it at your
organisation's documents - PDFs, PPTX, spreadsheets, DOCX, images, or web pages - and it builds a persistent, structured knowledge base your team can query, audit, and extend over time.

Unlike general-purpose RAG pipelines that retrieve raw chunks at query
time and discard results afterwards, Synthadoc compiles knowledge at
ingest time into a living wiki that grows smarter and more consistent
with every new source. The core lifecycle is:

Ingest: extract and synthesise facts from any source format (PDF, XLSX, PNG, web URL)
Detect: flag contradictions with existing pages and quarantine them for review
Link: connect related pages and surface knowledge gaps
Query: answer questions with hybrid BM25 + optional vector search, citing the pages used
Lint: resolve contradictions and surface orphan pages for human or automated action

Synthadoc is designed for organisations that need domain-specific, auditable knowledge management: legal teams tracking regulatory
precedent, financial analysts maintaining market research, engineering
groups documenting system behaviour, and research teams building
institutional memory that persists beyond individual contributors.

Synthadoc v0.2.0 is released last week, it scales seamlessly while maintaining accuracy through autonomous self-optimization.

👉 Synthadoc GitHub: https://github.com/axoviq-ai/synthadoc

Introduction

Most LLM knowledge tools take one of two approaches to retrieval: pure
keyword search (fast but vocabulary-dependent) or pure vector/semantic
search (flexible but resource-intensive). In practice, both have
meaningful blind spots.

Synthadoc v0.2.0 ships a hybrid retrieval pipeline that uses BM25 as a
fast, precise first-pass filter and optional vector re-ranking as a
semantic second pass. The result is a system that is accurate on
exact-match queries, robust on paraphrased or conceptual queries, and
fast enough to run on a laptop with no cloud dependency.

This post explains how each technique works, where each one falls short
alone, why the hybrid matters for a persistent domain wiki, and how
Synthadoc v0.2.0 layers query decomposition and knowledge gap detection
on top.

What Is BM25?

BM25 (Best Match 25) is a probabilistic ranking function. It scores a
page relative to a query by counting how often query terms appear in the
page, discounting terms that appear in almost every page, and penalising
very long pages for artificially inflated counts. BM25 is the retrieval
backbone of Elasticsearch, Lucene, and most production search systems.

Scoring intuition

Where BM25 falls short

Vocabulary mismatch: query says "contributions", page says "pioneered". Score: near zero.
Synonyms: "ML" and "machine learning" are different tokens.
Conceptual distance: "reasoning under uncertainty" and "probabilistic inference" are semantically identical but lexically distant.

On a domain wiki ingested from diverse sources (papers, docs, blog posts, PDFs), the same concept will be described in many different vocabularies. BM25 alone misses a meaningful fraction of relevant pages.

What Is Vector Search?

Vector (semantic) search encodes text into dense numerical embeddings using a neural language model. Semantically similar texts land close together in that high-dimensional space regardless of surface wording.
Similarity is measured as cosine distance between the query vector and each page vector.

Embedding intuition

The two sentences share almost no keywords, but their vectors point in nearly the same direction because the model understands they describe the same concept.

Where vector search falls short alone

Cold-start penalty: embedding thousands of pages takes time and compute; BM25 is instant.
Exact-match dilution: specific product names or identifiers can be blurred by semantic proximity.
Domain drift: general-purpose models may not distinguish highly specific domain terminology.
Resource requirement: needs a model (~130 MB for bge-small-en-v1.5) and inference at query time.

BM25 vs. Vector Search: Side-by-Side

Dimension	BM25	Vector / Semantic
Matching strategy	Matching strategy Exact term overlap (TF x IDF)	Semantic similarity (cosine distance)
Vocabulary required	Query words must appear in page	Paraphrases and synonyms handled
Speed	Microseconds -- no model needed	Milliseconds -- model inference required
Setup cost	Zero -- pure algorithm	~130 MB model download (one-time)
Exact-match queries	Excellent	Good
Synonym / paraphrase	Often misses	Handles well
Domain terminology	Good if terms match	Depends on model training
Interpretability	Score is explainable	Black-box similarity
Best for	Known vocabulary, structured content	Conceptual queries, diverse sources

How Synthadoc Combines Both

Synthadoc uses a hybrid pipeline where BM25 and vector search are not alternatives - they are sequential layers. BM25 does the heavy filtering; vector re-ranks the survivors.

The retrieval pipeline

Query decomposition: why it matters for retrieval

Before any search happens, Synthadoc v0.2.0 breaks compound questions into focused sub-questions via an LLM call. Each sub-question runs its own BM25 (and vector) search in parallel. Results are merged by best score per page before synthesis. One complex query can retrieve from multiple distinct parts of the wiki simultaneously.

Example: Query: "Compare Turing's contributions with Von Neumann's
architecture"
-> Decomposed: ["Turing contributions computing"] | ["Von Neumann
architecture design"]
-> Two parallel BM25 searches -> merged candidates -> one synthesised
answer

Knowledge gap detection

After retrieval, Synthadoc evaluates three independent signals:

Fewer than 3 pages retrieved - the wiki barely covers the topic
Max BM25 score below configurable threshold (default: 2.0) - weak keyword overlap
Fewer than 2 candidates contain key nouns from the question - off-topic matches

When a gap fires, Synthadoc generates targeted web search suggestions and surfaces them as an Obsidian callout or CLI tip, creating a feedback loop that makes the wiki progressively denser over time.

Practical Examples in Synthadoc

Example 1: BM25 exact match (no vector needed)

Wiki page: "Alan Turing - Enigma and the Bombe Machine"

Query: "Bombe machine Enigma decryption"

BM25 succeeds: BM25 score: HIGH - "Bombe", "machine", "Enigma",
"decryption" all present.
Result: page retrieved correctly. Vector re-ranking not required.`**

Example 2: BM25 misses, vector rescues

Wiki page: "Alan Turing - Theoretical Foundations of Modern Computers"

Query: "What were Turing's contributions to computing?"

BM25 misses, Vector rescues: BM25 score: LOW - "contributions" and
"computing" absent from the page.
Vector cosine score: HIGH - embeddings are semantically close.
Result: page retrieved correctly after re-ranking. BM25 alone would have > missed it.

Example 3: Knowledge gap fires, ingest suggestion generated

Wiki: finance domain. Query: "What is the impact of quantitative easing on inflation?"

Gap detected: BM25: 1 page returned, score 0.8 (below threshold 2.0)
Knowledge gap detected. Synthadoc generates:
synthadoc ingest "search for: quantitative easing inflation impact" -w finance-wiki
synthadoc ingest "search for: central bank monetary policy effects" -w finance-wiki
After ingest and re-query: 7 pages returned, fully synthesised answer.

Enabling Vector Search in Synthadoc

BM25 is the default - zero setup, zero dependencies. To add vector re-ranking:

Step 1: Install fastembed

pip install fastembed

Step 2: Enable in config

[search] vector = true vector_top_candidates = 20 # BM25 pool size before re-ranking

Step 3: Restart the server

synthadoc serve -w my-wiki

On first start, Synthadoc downloads BAAI/bge-small-en-v1.5 (~130 MB) once and embeds existing pages in the background. BM25 stays active throughout - no downtime. If the model is unavailable, the system falls back to BM25 silently.

Synthadoc v0.2.0: Full Feature Summary

Feature	What it does
Query decomposition	Compound questions split into parallel BM25 sub-queries, merged before synthesis
Vector re-ranking	Opt-in semantic re-ranking (BAAI/bge-small-en-v1.5 via fastembed)
Knowledge gap detection	3-signal gap check; auto-generates targeted ingest suggestions as Obsidian callout
Web search decomposition	Broad search topics split into focused Tavily queries; URL deduplication and cap
Per-model cost tracking	Per-token rate table; ingest + query cost in audit.db, CLI, and Obsidian
Query audit trail	Full query history with sub-question count, tokens, cost, timestamp
Obsidian live web search view	Real-time polling panel: phase, pages created, URL errors as fan-out completes
8 new Obsidian commands	15 commands total: lint, auto-resolve, job retry/purge, audit history, scaffold
MiniMax support	M2.5/M2.7 reasoning models with reasoning_content fallback for structured output
Rate-limit requeue	429 responses requeue job (retry budget preserved); fail-fast on daily quota
Job crash recovery	in_progress jobs at shutdown auto-reset to pending on next startup
Bulk job cancel	Cancel all pending jobs in one operation via CLI or API

How Synthadoc Compares to Alternatives

Most LLM knowledge tools are general-purpose RAG pipelines that retrieve raw chunks at query time with no persistent synthesis. Synthadoc compiles knowledge at ingest time, maintains a living wiki, and is designed for domain-specific, auditable deployments.

Capability	Synthadoc v0.2.0	LlamaIndex / LangChain	Notion AI	Obsidian Copilot
Ingest-time synthesis	Compiled wiki	Raw chunks at query time	Page-level only	None
Domain scope filtering	purpose.md	Manual	None	None
Multi-model support	6 providers	Many providers	OpenAI only	OpenAI / Ollama
Audit trail	Full SQLite audit	None built-in	None	None
Cost tracking	Per-token, per-op	Manual / callback	Opaque	None
Offline / local	Fully local	Depends on provider	Cloud only	Ollama
Obsidian-native output	Wikilinks, Dataview	None	Notion-only	Read-only
HTTP API + MCP server	Built-in	Manual wiring	Proprietary API	None
Contradiction detection	Automated	None	None	None
Query decomposition	Parallel BM25	Manual chains	None	None
Knowledge gap detection	Auto-suggestions	None	None	None
Extensible skills	Drop-in folders	Custom loaders	None	None
Licence	AGPL-3.0 open source	Apache-2.0	Proprietary SaaS	MIT

Enterprise and Domain-Specific Readiness

Synthadoc is built for organisations that need a knowledge system they control, audit, and deploy into existing infrastructure - not a SaaS black box.

Concrete use cases:

Legal - track regulatory updates, case precedents, and compliance requirements across jurisdictions. New ruling ingested, old page flagged contradicted, compliance team reviews.
Finance - build a living market research wiki from analyst reports, earnings calls, and regulatory filings. Query with natural language, get cited answers with full audit trail.
Engineering - maintain a persistent runbook that absorbs incident post-mortems, architecture decision records, and API docs. Contradiction detection prevents stale documentation from accumulating.
Research - aggregate papers, datasets, and notes into a structured knowledge base. Knowledge gap detection surfaces what the team does not yet know and generates targeted ingest suggestions.

Domain specificity

Every wiki defines its own scope via purpose.md. The LLM reads this before every ingest decision and rejects out-of-scope sources cleanly. A legal wiki does not absorb marketing copy. A financial wiki does not absorb engineering runbooks.

Auditability

Every ingest, query, contradiction detection, and auto-resolution is written to an append-only SQLite audit trail with token counts, cost, timestamps, and page-level actions -- all queryable from the CLI or Obsidian audit commands.

synthadoc audit history -w my-wiki # ingest records

synthadoc audit cost -w my-wiki # token spend breakdown

synthadoc audit events -w my-wiki # contradiction, gate, resolution
events

Product and grid readiness

Synthadoc exposes the same operations across four surfaces sharing a single agent and storage layer:

CLI: for operators, automation scripts, and CI pipelines
HTTP REST API: for product integrations and custom front-ends
MCP server: for direct agent-to-agent communication
Obsidian plugin: for knowledge workers doing active research

Hook scripts fire on lifecycle events (on_ingest_complete, on_lint_complete), enabling event-driven automation: post a Slack summary when ingest completes, trigger a downstream build when a key page changes, or chain into a broader orchestration pipeline. Cron scheduling is built in, and multi-wiki isolation means each team or domain runs on its own port with its own audit trail.

Synthadoc in Agentic Autonomous Systems

Synthadoc is purpose-built to serve as the persistent knowledge layer for LLM agent systems. Where an agent's context window is ephemeral and limited, Synthadoc's wiki is persistent, structured, and queryable -it gives agents a long-term memory that survives across sessions, scales to millions of tokens of accumulated knowledge, and is fully auditable.

Agent integration via MCP

The built-in MCP (Model Context Protocol) server exposes ingest, query, and lint as native tool calls. An agent running in any MCP-compatible host - Claude, GPT-4o, a custom LangChain pipeline - can:

Call query to retrieve cited, synthesised answers from accumulated knowledge before acting
Call ingest to push new findings, research results, or external documents back into the wiki
Call lint to check for contradictions introduced by new data before committing to a decision

Event-driven agent pipelines

Hook scripts fire on lifecycle events and can trigger downstream agent actions:

on_ingest_complete: a downstream agent reads newly created pages and decides whether to trigger follow-up ingests or alert a human reviewer
on_lint_complete: an orchestrator agent receives contradiction and orphan reports and routes resolution tasks to specialised sub-agents

Example pipeline: a web-crawling agent ingests raw URLs; Synthadoc synthesises and deduplicates; a reporting agent queries the updated wiki and posts a daily briefing - all without human intervention.

Persistent domain memory for multi-agent systems

In multi-agent architectures, shared knowledge is a coordination bottleneck. Synthadoc solves this by acting as a shared, structured memory store:

Multiple agents read from the same wiki via parallel HTTP queries - no shared state management required
One agent's ingest results are immediately available to all agents querying the same wiki
Multi-wiki isolation means separate agent clusters maintain scoped knowledge without interference
The audit trail provides a complete record of which agent ingested what, when, at what cost - making multi-agent systems auditable by design

Because Synthadoc is self-hosted and open-source, teams building autonomous systems retain full control over data residency, model selection, and cost - a critical requirement for enterprise agentic
deployments.

Try Synthadoc v0.2.0

Synthadoc v0.2.0 is available now on GitHub under the AGPL-3.0 licence. BM25 search works out of the box. Vector re-ranking is one pip install away. The Gemini free tier means you can run a full ingest-and-query cycle at zero cost.

Feedback welcome: Feedback, issues, and contributions are very welcome. Open an issue on GitHub or start a discussion - the roadmap is shaped by what users need.

👉 README: https://github.com/axoviq-ai/synthadoc#readme
👉 Quick-start guide: https://github.com/axoviq-ai/synthadoc/blob/main/docs/user-quick-start-guide.md
👉 Design document: https://github.com/axoviq-ai/synthadoc//blob/main/docs/design.md
👉 Release notes: https://github.com/axoviq-ai/synthadoc/releases/tag/v0.2.0

DEV Community: Paul Chen