git clone https://github.com/crow-hq/llm-wiki-v2 && cd llm-wiki-v2
cp .env.example .env          # choose OKF_LLM_PROVIDER and set its key
docker compose up -d --build  # the wiki on :8000 (OKF_PORT to change)

With Docker the settings come from .env; the page shows them but cannot change them.

The web UI at http://localhost:8000 shows the folder tree, renders each note (with its See-also links and sources), answers questions with clickable citations, and shows the tokens spent by the LLM and by the classifier. Drop .txt, .md or .pdf files anywhere on the page and each one is catalogued automatically; PDFs need a text layer (scanned PDFs need OCR first).

The same through the API:

curl -X POST localhost:8000/ingest -H 'content-type: application/json' \
     -d '{"text": "Acme refunds orders within 30 days of delivery.", "title": "Refund policy"}'
curl -X POST 'localhost:8000/upload?filename=minutes.pdf' --data-binary @minutes.pdf
curl -X POST localhost:8000/ask -H 'content-type: application/json' \
     -d '{"question": "How long do customers have to ask for a refund?"}'

The wiki is plain Markdown files you can read, edit and keep in git (./wiki with Docker). The API docs are at http://localhost:8000/docs; with Docker the CLI runs in the same image: docker compose run --rm wiki llmwiki2 check. To file a note elsewhere or reword a folder's description from the terminal: llmwiki2 move finance/pricing.md /sourcing and llmwiki2 describe /finance "Money in and out.". In CROW mode, llmwiki2 audit [--min-confidence 0.7] [--apply] lists the notes the classifier would file in another folder today (no LLM call; it moves them only with --apply), and llmwiki2 health [--min-filed 5] [--max-share 0.3] shows, from log.md, the folders that keep needing new subfolders or the LLM fallback. Every new note carries a stable id in its frontmatter (wiki.find_note(id)).

pip install "llmwiki2[server]"

from llmw2 import Wiki

wiki = Wiki.from_env(bundle="./wiki")        # OKF_* variables and the provider's key, e.g. OPENROUTER_API_KEY
wiki.init()

result = wiki.ingest(open("meeting.md").read(), title="Pricing meeting")
wiki.ingest_file(open("minutes.pdf", "rb").read(), "minutes.pdf")   # .txt, .md or .pdf
print(result.action, result.note, result.created_folders, result.related)

answer = wiki.ask("What did we decide about enterprise pricing?")
print(answer.text, answer.citations)

print(wiki.usage.to_dict())                  # {"llm": …, "classifier": …, "by_model": …}

The same operations are on the command line:

llmwiki2 --bundle ./wiki init
llmwiki2 --bundle ./wiki ingest meeting.md     # or a .txt / .pdf
llmwiki2 --bundle ./wiki sync ~/OneDrive       # file a folder and keep the wiki in step with it
llmwiki2 --bundle ./wiki --mode classic ask "What did we decide about pricing?"
llmwiki2 --bundle ./wiki check        # lint: OKF conformance, index drift, broken links
llmwiki2 --bundle ./wiki serve        # the HTTP API and page (needs the [server] extra); plain `llmwiki2` also opens the browser
llmwiki2 setup                        # provider, key and model, tested and saved
llmwiki2 demo                         # an example wiki, copied to ~/llm-wiki-demo and opened

To keep the wiki in step with a source, hand sync a connector. Each document keeps its Origin (where the original lives), so an unchanged file costs no model call and a deleted one is marked in the raw copy while its notes stay:

from pathlib import Path
from llmw2 import LocalFolderSource, sync

report = sync(wiki, LocalFolderSource(Path("~/OneDrive")))   # a folder, e.g. one rclone keeps in sync
print(report.to_dict())                                      # created, merged, unchanged, removed, skipped, errors

A connector for another service is any object with name, account, changes(cursor) -> ChangeBatch and fetch(change) -> bytes (SourceConnector); the cursor of the last sync is kept in .llmw2/sync/ inside the wiki.

Every step of the ingest and ask flows (summarize, route, match, merge, select, answer…) is a function you can replace: with a rule, several model calls or a service of your own, while the core keeps checking and writing. The guide to the whole library is in docs/library/, the steps in docs/library/steps.md, and runnable programs, some with no key, in examples/.

ingest:  summarize → route → find match → merge or (new folder →) write → relate → link, index, log
ask:     select notes (navigate the tree) → answer from them, with [path.md] citations

Both modes run the same pipeline and write the same kind of wiki: only the decider changes. CROW follows CROW: Classifier-Routed Organization of LLM Wikis (Cesarini & Sassarini, 2026) — see docs/wiki/crow.md for thresholds and fallbacks.

Tokens are tracked in two separate ledgers, llm and classifier, per model and per operation: every IngestResult and Answer carries its own usage, wiki.usage / GET /usage the totals, and OKF_USAGE_LOG writes one JSON line per model call.

The wiki's on-disk format is derived from Google's Open Knowledge Format (OKF) v0.2: every wiki written here is a conformant OKF bundle, with the extra conventions listed below. This project started as a fork of OKF and no longer includes its code.

wiki/
  index.md                     # root index (okf_version "0.2")
  log.md                       # what changed, newest first
  raw/                         # untouched copy of every source ingested
  customer-policies/
    index.md                   # * [Refund policy](refund-policy.md) - How Acme refunds orders…
    refund-policy.md           # type: Note, title, description, tags, generated, sources

Every note is an OKF concept (type: Note) whose description is its one-line summary and whose sources point to the raw copies it was written from. Each folder's one-line description sits in its parent's index.md, where both people and the Librarian read it. Related notes are joined by a # See also section with relative links. llmwiki2 check verifies all of this.

How it relates to OKF v0.2. A wiki written here is a conformant OKF bundle (§11): every note has a YAML frontmatter block with a type, and index.md and log.md follow §8 and §9. On top of that it adds its own conventions:

• every folder has an index.md, and a folder's description is its entry in the parent's index (OKF: optional indexes);
• links are relative (OKF recommends bundle-absolute /… links), and check reports broken ones;
• raw/ holds the sources (type: Source), # See also holds the related notes, and there is one log.md, at the root;
• the root holds no notes: every note is filed in a topic folder, and the first note on a new subject opens one.

It does not use OKF's trust and lifecycle fields (verified, status, stale_after), attested computations (§10) or the references/ convention. Wikis are not checked against later OKF versions.

The settings page and llmwiki2 setup cover provider, key, model, mode and wiki folder. Everything else, and every setting in Docker (.env) or in the library, comes from the environment; it wins over the settings file. The full list is in .env.example.

Providers, the settings file and the classifier route: docs/wiki/providers.md. Prompts, one Markdown file each: docs/wiki/prompts.md.

src/llmw2/            wiki (the Wiki facade), config, settings, errors, cli, server
src/llmw2/models/     the model endpoints: HTTP client, LLM, CROW classifier, token usage
src/llmw2/bundle/     the wiki on disk: OKF documents, the tree in memory, the store that writes it, file text, check
src/llmw2/agents/     the ingest and ask flows (Librarian, Researcher), their steps (classic, CROW), and the prompts
src/llmw2/agents/prompts/  shared/, librarian/, researcher/, classifier/ — one prompt per file
src/llmw2/web/        the web UI: plain ES modules, no build step; vendor/ holds marked, DOMPurify, d3 and the fonts
src/llmw2/demo/       the example wiki behind `llmwiki2 demo` (a fictional roastery)
tests/wiki/              tests for every feature, with scripted fake models (no network)
docs/wiki/               providers, CROW, prompts
docs/library/            the library: API guide and custom steps
examples/                runnable examples of the library

uv sync --extra dev            # the versions pinned in uv.lock
uv run ruff check src tests    # lint
uv run mypy                    # strict types
uv run pytest --cov            # tests, failing under 95% coverage

CI runs the same four checks on Python 3.11 to 3.13, and builds the wheel.

Tests never call a real model: they use the scripted fakes in tests/wiki/fakes.py. Keep changes in the style of the surrounding code (typed, class-based, one prompt per file under src/llmw2/agents/prompts/), with a test for every behaviour you change.