Upgrade guide
How to upgrade between llmwiki releases. Most releases are drop-in (pip install -U llm-wiki-plus or brew upgrade llmwiki) — this page documents the exceptions: schema migrations, config changes, and behaviour flips that affect what happens on your next sync.
The canonical per-release detail is CHANGELOG.md — this guide focuses on "what might break".
Unreleased — session Tokens usage store + Cursor CLI capture (#325)
Analytics Tokens now prefer a single vault file usage/session-tokens.json (lifetime + per-agent coverage + per-day × agent buckets attributed to each session’s last activity UTC day). Synced session pages still show Tokens from raw frontmatter token_totals. Steady-state sync only updates new or fingerprint-changed sessions — it will not backfill older unchanged sessions.
sync / migrate also refresh a slim public site/session-tokens.js (aggregates only — no per-session ledger). Open an existing Analytics page after sync and the Tokens card updates from that sidecar without a full HTML rebuild. Run build once after migrate so Analytics HTML exists and other site pages stay current.
After upgrade: run once:
llmwiki migrate session-tokens --vault /path/to/vault --dry-run
llmwiki migrate session-tokens --vault /path/to/vault
llmwiki build --vault /path/to/vault
Codex CLI Tokens (#324): after this change, Codex sessions with native token_count usage contribute to Analytics Tokens. If you already ran migrate session-tokens before Codex capture shipped, re-run it (or sync fingerprint-changed sessions) while ~/.codex/sessions remains so historical Codex usage fills in. For a fast Codex-only pass (skips the multi-thousand Claude/Cursor origin walk), use:
llmwiki migrate session-tokens --vault /path/to/vault --adapter codex_cli --skip-raw
llmwiki build --vault /path/to/vault
Occupancy / rate-limits alone are never Tokens — see Codex CLI adapter — Tokens capture.
Cursor Agent chats only contribute measured totals when turn usage is available. store.db does not store per-turn input/output/cache fields (context-window occupancy there is never Tokens).
IDE Agent: install the managed stop hook (idempotent; keeps your existing hooks). The installer writes a POSIX /bin/sh handler (~/.cursor/llmwiki-cursor-token-stop.sh, ~3 ms) and points hooks.json at it — not a Python process (interpreter startup is tens of ms):
python3 -m llmwiki.cursor_token_events --install-hook
Each completed Agent turn then appends the full Cursor stop stdin JSON as one line to ~/.cursor/llmwiki-cursor-token-events.jsonl (override with LLMWIKI_CURSOR_TOKEN_EVENTS). That keeps the awaited hook cheap; treat the JSONL as local telemetry (not under site/). The Python ingest path (python3 -m llmwiki.cursor_token_events / --ingest-stream-json) writes a minimized usage row instead; sync accepts both shapes. Sync / migrate session-tokens join by conversation_id (= chat folder / agentId). Historical chats from before the hook cannot be backfilled from store.db.
IDE Composer ledger (no hooks, no API) (#396): on sync and migrate session-tokens, llmwiki scans global state.vscdb read-only for bubbleId:<composerId>:<bubbleId> rows with non-zero tokenCount.{inputTokens,outputTokens}, sums per composerId (same id as cursor_ide sessionId), and caches under usage/cursor-usage-ledger-cache.json. Input/output only — no cache read/write in the ledger schema. Agent CLI chat folder UUIDs are not in this DB; CLI tokens still need hooks, stream-json, or #356 API. Precedence: hook JSONL → local ledger → cursor_usage_api. Disable with "cursor_usage_ledger": false in sessions config. Fail-soft when the DB is missing or the schema drifts.
Agent CLI (cursor-agent -p --output-format stream-json): final result.usage uses camelCase (inputTokens, …) — ingest into the same JSONL:
cursor-agent -p --output-format stream-json "…" | tee /tmp/out.jsonl
python3 -m llmwiki.cursor_token_events --ingest-stream-json /tmp/out.jsonl
Or pipe stream-json NDJSON on stdin to python3 -m llmwiki.cursor_token_events. Then llmwiki migrate session-tokens / sync / build. Convert no longer writes empty token_totals. See state-persistence.md and migrate session-tokens.
ACP / Agent Orchestrator (cursor-agent --force acp) (#356): hooks and ACP streams carry no usage. Opt in by setting cursor_usage_api to dashboard in config.json (merged over examples/sessions_config.json). llmwiki reads your existing Cursor CLI or IDE session token locally (same machine, read-only) — it is never logged, printed, or written into the vault or site. Team plans can use cursor_usage_api: admin with CURSOR_ADMIN_API_KEY instead. The first poll backfills history back to your cursor_cli lookback (adapters.cursor_cli.since, else filters.since; all history Cursor retains when neither is set), so ACP sessions older than the day you enabled the option are covered too. If you enabled it on an earlier build, which fetched only the last 3 days, the next poll re-fetches that history once — no manual step. After enabling:
llmwiki sync --vault /path/to/vault
llmwiki migrate session-tokens --vault /path/to/vault
llmwiki build --vault /path/to/vault
Sync polls the API at most once per hour; migrate forces one fetch. Every measurable API conversationId upserts as Cursor CLI in Analytics Tokens (ACP/--force acp is the same agent). Chats that never land in raw/ (often headless AO workers) still count as metrics-only stubs. If you already use the IDE stop hook JSONL for a conversation, that source still wins — API rows are not double-counted.
Unreleased — dismissal ledger + near-match prior reasons (#146)
Behaviour flip for new discards/merges, plus an optional offline migration for vaults that still only have per-stub reason files.
New behaviour:
candidates discardandmergerecord the decision inwiki/archive/candidates/dismissals.jsonand no longer write a new sibling*.reason.txt.candidates listandsite/candidates.htmlmark pending near-matches of previously dismissed names and show the recorded reason (or(discarded without explanation)when the reason was empty). Exact settled dismissals stay excluded from harvest as before; merges are not treated as dismissals for the mark.- Topic exclusion and
migrate discarded-topic-linksread the ledger (merge intents included).
When to migrate: if the vault already has archived candidates from before this release (especially with legacy *.reason.txt siblings) and dismissals.json is missing or out of date, rebuild once:
llmwiki migrate dismissal-ledger --vault /path/to/vault --dry-run
llmwiki migrate dismissal-ledger --vault /path/to/vault
Ordinary ledger reads also auto-rebuild when dismissals.json is missing and wiki/archive/candidates/ exists (for example the first candidates list or discard after upgrade); a vault with no archive is read as an empty ledger and nothing is written, so an explicit migrate is mainly for --dry-run preview or forcing a rebuild when a ledger already exists. Legacy *.reason.txt files are imported into the ledger and may remain on disk — they are not deleted automatically. Rebuild afterwards so the candidates page picks up near-match marks: llmwiki build --vault <vault>.
Unreleased — one schedule per vault, checked by doctor (#359)
No data migration, but installed schedules change shape.
- Legacy schedule adopted on the next install. A schedule installed by an older release uses the single name
llmwiki-maintain(com.llmwiki.maintainon macOS). It keeps running after the upgrade. The nextllmwiki install-automation --vault <vault>(or the doctor repair) for the vault that schedule serves installs the vault's ownllmwiki-maintain-<slug>-<hash>schedule, then switches the legacy one off and deletes its files. A legacy schedule serving another vault is left alone; install that vault once too. - Schedules are pinned to their vault. Every new schedule runs
llmwiki … --vault <vault>. Changingvault.default_pathinconfig.jsonno longer moves the scheduled job to the new default. To schedule the new vault, runllmwiki install-automation --vault <new vault>; remove the old one with the stepsllmwiki doctorprints if you no longer want it. - Renamed or moved vault. The schedule names the old path, so
llmwiki doctor --vault <new path>reports the old schedule as a leftover (automation.orphan_unit) and the vault as having no schedule (automation.unit_missing). Accept the doctor repair to install the vault's schedule at its new path, then run the removal commands doctor printed for the leftover. - Run
llmwiki doctoronce after upgrading. It now checks that the vault's schedule exists, serves this vault, runs from a checkout that still exists, is switched on, and has completed a recent successful run, and lists leftover schedules. Schedule repairs are dangerous-tier: they run only after you confirm on a terminal, never with--yesalone.
Unreleased — automation never fails silently (#374)
No data migration. Home gains one red problems banner at the top that lists every current problem — a failed or partly failed Sync / Synth / Build, a run that failed as a whole, a missed scheduled run, and the lint-error note, which moves there from under the Knowledge table.
- Re-run
llmwiki install-automationonce per vault (or accept the doctor repair). The new wrapper stamps each scheduled run so Home can tell when one is missed, and finds the backend's programs the way a terminal does (login-profilePATHplus the program folders recorded at install). Until you do, every run adds aSchedule — setup outdatedentry and doctor reportsautomation.setup_outdated. - Restart long-running llmwiki processes (MCP servers your agents started, queue workers such as a per-minute
llmwiki queue run,watch) after upgrading. A process still running the older code rewritesllmwiki-state.jsonwithout the newoutcomessection, so the banner's entries vanish on its next write. From this release on, the state store keeps top-level sections it does not recognize, so a future upgrade no longer has this gap. - The banner arrives with the next build. The page script is written by
build, so an existing site shows the banner after its next build — the next scheduled Maintain run does one, or runllmwiki build --vault <vault>. - Error text. An unavailable synth backend now prints
error: backend <name> is not available: <reason and fix>(for example a pinnedsynthesis.claude.paththat no longer exists). Scripts matching the old… is not available. Start the server …sentence should match thebackend <name> is not availableprefix instead.
Unreleased — pin Claude path at install-automation (#275)
No data migration. If you already schedule Maintain with synthesis.backend: claude and rely on claude being on $PATH (for example under <home>/.local/bin), re-run llmwiki install-automation (or llmwiki install-automation --yes --job maintain --synth-backend claude) once after upgrading. The installer writes absolute synthesis.claude.path when that key (and flat claude_path) are unset, so systemd user-timer catch-up with a minimal PATH still finds the CLI. An explicit path you already set is left alone. The pin keeps the launcher symlink (for example <home>/.local/bin/claude). If an earlier build of this release already pinned a versioned binary such as <home>/.local/share/claude/versions/<X.Y.Z>, synth stops once Claude Code's self-update deletes that version (error: backend claude-cli is not available, llmwiki doctor reports synth.backend_unavailable): set synthesis.claude.path to the launcher or remove the key and re-run install-automation (#374).
Unreleased — whole-document storage (#311)
Behaviour flip for imports after this release, plus an optional offline migration for vaults that still hold length-driven pieces.
New behaviour (no migrate required):
llmwiki add/ MCPwiki_addwrite one complete Markdown file underraw/docs/(including long documents). Content hash / dedup stay whole-document. A converted document over 512 KiB of Markdown is rejected atadd(nothing written);synthrefuses a legacy raw doc already over that limit (no backend call, no page, it stays pending) — split it into smaller documents.llmwiki synthsplits a long document in memory to the active backend's usable body budget (synthesis.<backend>.usable_body_chars/context_window_tokens; see configuration.md — Claude's default is now far larger than the old ~7k (≈296k characters lean at 200k tokens), Cursor (composer-2.5and any other id) and an unknown Claude model id assume a 200,000-token window (≈185k characters for Cursor), Ollama is auto-sized from the model and otherwise assumes 8,192 tokens; the derived budget also reserves the backend's per-call agent overhead and working margin, and the 1,000-character floor applies only when you set a tiny value yourself), summarises each piece, and stitches them into onewiki/sources/page. A failure mid-document fails the whole document (no complete-looking partial page). There is no silent truncation-as-coverage path. Splits prefer heading, then paragraph, then line boundaries; a code fence cut by a split is closed and re-opened on every piece, and a heading is never sent as a chunk of its own.- Session transcripts are unchanged, including their 8,000-character send cap.
When to migrate: if an older release left raw/docs/<project>/<slug>-01.md … -NN.md and/or several wiki/sources/…--part-N pages for one logical document, Ctrl+K Wiki (and the wiki search corpus) can still list one row per part even after the #305 site Documents unification. Heal that offline — no mandatory mass re-synth:
llmwiki migrate whole-document-storage --vault /path/to/vault --dry-run
llmwiki migrate whole-document-storage --vault /path/to/vault
- What it changes: each clear multi-piece group becomes one raw file (
raw/docs/<project>/<slug>.md) and one canonical wiki source page (same deterministic stitch + tag union synth uses). Old-NNraw files and part wiki pages move under.llmwiki-whole-doc-recovery/<UTC>/(aMANIFEST.jsonlists every move). Part names become## Aliaseson the canonical page;[[wikilinks]]/sources:entries and synth state follow. Index / pending refresh run when anything changed. - Block on ambiguous: preview always lists clear and ambiguous groups. Apply exits non-zero and writes nothing (including clear groups) while any ambiguous group remains (gap in parts, conflicting or mixed empty/non-empty
content_sha256, a whole file that is not the same document or cannot be read, an unsafe frontmatterproject/date, partly summarised pieces, inconsistent wiki claims, and similar). Resolve or remove the ambiguous set, then re-run. Parts that all lackcontent_sha256(pre-hash imports) with clear(part i/N)titles and a contiguous-NNrun are clear — the migrate fills the hash from the joined body when writing the whole file. - Never: an LLM call, a mass re-synthesis from raw, or overwriting a whole file already on disk (different hash or unreadable).
- Optional re-synth queue: after a successful apply the merged documents are listed. On a terminal you are asked once (all-or-nothing) whether to mark them not synthesized so a later
llmwiki synthre-runs them; the default — Enter, EOF, or a non-terminal run — keeps the stitched summaries. Scripts:--mark-unsynthmarks them without asking,--keep-stitchedkeeps without asking. Migrate itself still makes no LLM call. - Idempotent: a clean second run is a no-op; an interrupted apply resumes. Rebuild afterwards:
llmwiki build --vault <vault>.
Unreleased — document synthesis uses its own prompt (#308)
Documents under raw/docs/ synthesize with document_page.md (vault override wiki/prompts/document_page.md); a custom source_page.md applies to sessions only. Existing document source pages change only after llmwiki synth --force.
Unreleased — document source pages claim their raw file (#307)
Optional offline migration. Synth now writes source_file: raw/docs/<path> on every page it synthesises from raw/docs/ and tags it raw-doc instead of session-transcript. Document pages an older release wrote still have a blank source_file (so llmwiki trace, provenance_integrity and remove's frontmatter scan cannot follow them) and still carry session-transcript (re-synth keeps existing tags as curation). Heal them without a backend call:
llmwiki migrate doc-source-provenance --vault /path/to/vault --dry-run
llmwiki migrate doc-source-provenance --vault /path/to/vault
- What it changes: for each raw doc, the page synth derives for it (including
--part-NNpages) gets the claim synth would write today when itssource_fileis blank. Every page identified as a document — by that match, by araw/docs/claim, or by araw-doc/wiki-addtag — losessession-transcript, and gainsraw-docwhen neither document tag is left. Stub pages are included. It then refreshes the synth backlog and appends amigrate | doc source provenanceentry towiki/log.md. - Never touched: pages whose
source_filenamesraw/sessions/, andraw/itself. - Left for you: a blank-claim page that two raw docs derive to is reported as ambiguous and left unchanged; a doc-tagged page no raw doc derives to is reported as unmatched, keeps its blank claim, and still loses
session-transcript. - Order: run this before
migrate source-page-paths, which only moves pages that already claim a raw file. A second run changes nothing. Rebuild afterwards:llmwiki build --vault <vault>.
2.4.0 — discard rewrites links to the discarded name (#282)
Optional one-time cleanup. candidates discard now turns every [[link]] to the discarded name into plain text (or, with --redirect PAGE, into [[PAGE|text]] plus a ## Aliases entry on that page), and the synth topic vocabulary no longer offers discarded names. Candidates you discarded before this release still have links pointing into wiki/archive/, which lint reports under link_integrity. Clean them up offline — no LLM call, raw/ never written, safe to re-run:
llmwiki migrate discarded-topic-links --vault /path/to/vault --dry-run
llmwiki migrate discarded-topic-links --vault /path/to/vault
# point some names at an existing page instead of unlinking them:
llmwiki migrate discarded-topic-links --vault /path/to/vault --redirect "Old Name=ExistingPage"
The same run moves candidate stubs that a / in their name had filed into a subfolder (candidates/entities/A/B thing.md) to their flat path (candidates/entities/A-B thing.md); an existing file at the flat path is never overwritten and is reported as a conflict. Rebuild afterwards: llmwiki build --vault <vault>. discard() callers in Python now receive a DiscardResult — use .path for the archived file.
Expect suggestions on the first run if you ever used candidates merge. A merged candidate's links belong on the page it was merged into, and a survivor page only answers to the merged-away name through the ## Aliases entry that merges started recording in #139. For an older merge — or one whose survivor you later renamed or re-filed — the archived reason.txt is the last record of where those links point. The migration therefore leaves such a name linked and prints what it thinks the page is, exiting 1:
merged, left linked: 1
- Old Name — merged into foo (587 links)
--redirect "Old Name=code-foo"
Check each suggested page, then re-run with those --redirect lines (--redirect "Old Name=code-foo"), which points the links at the survivor and records the alias so the next run reports nothing. If a name really was noise rather than a merge, --force unlinks it like any dismissal. The rest of the run applies either way, so you can take the redirects in a second pass.
2.4.0 — add / wiki_add no longer synthesize by default (#273)
Behaviour flip, no data migration. Scripts and agents that expected synth-on-add must opt in:
- Default:
llmwiki addand MCPwiki_addwrite raw docs and rebuild the site; they do not createwiki/sources/pages. - Opt in: pass
--synthesize(CLI) orsynthesize: true(MCP) on the same invocation, or runllmwiki synthafterward. --no-synthesize: warn+no-op for one release (synthesis is already off); remove it when convenient.--no-build/no_build: still skip the site rebuild.- Stdin / MCP text:
llmwiki add -and MCPcontentrecordsource: "piped"(no tempfile provenance).
2.4.0 — synth clean stop on Ctrl+C or backend usage limit (#181)
Behaviour flip, no data migration. Scripts and schedulers that read exit codes should check these:
- New exit code
75:synthandallexit75when the synthesis backend (Claude CLI, Cursor Agent CLI or Ollama) reports an exhausted usage quota in its error message. The run stops starting new sources, finishes the pages in flight, harvests what landed, and leaves the rest pending (Deferred:inwiki/log.md) instead of logging one error per remaining source. Treat75as "retry after the reset time", not as a failure. A plain rate-limit429("Too Many Requests") is still a per-source error. allno longer returns0after Ctrl+C: an interrupted synth step now makesallexit130(later stages still run for the pages that landed). A second Ctrl+C while in-flight pages finish kills the Claude / Cursor CLI processes and ends the run at once; with Ollama it waits for in-flight requests up to the Ollama timeout.- Lint failure no longer masks earlier codes:
all --lint-fail …used to return2even when an earlier step had failed; now the code of the earliest failing step wins — lint's2applies only when no earlier step failed. - Reinstall automation: wrappers installed by
install-automationbefore this release always loggedEXIT:0. Runllmwiki install-automationagain so the log'sEXIT:line and the scheduler both see the real exit code.
2.4.0 — source pages filed under a stale name (#265)
Optional offline migration, recommended when synth keeps skipping sources. After upgrade:
- Symptom: every
synthrun reportsskipped N source(s) already claimed by a real page under another name(older releases printed onereal source page already claims this sourceline per source), andsynth --estimate/ Home keep counting those sources as pending. The pages were filed under a name an earlier release derived — a generic session description shared by many sessions, or the whole raw filename after the date — while synth now derives<date>-<slug>for them. - Number-shaped slugs: a raw
slug:that looks like a number (0123,68657849,12e4) now keeps its written text in the page name instead of falling back to the raw filename, which produced a doubled date (<date>-<date>T<hh-mm>-<project>-<slug>). Existing pages under that doubled name are moved by the same migration. - Fix: run
llmwiki migrate source-page-paths --vault <vault> --dry-run, check the planned moves, collisions and ambiguous links, then run it without--dry-run. It moves each real page to its derived path (a doc's--part-NNpages move together), rewrites[[old-stem]]links andsources:entries acrosswiki/(wiki/archive/and the log are left alone), and records synth state so the nextsynthtreats the source as done. Zero LLM,raw/never written; a second run changes nothing. - Left for you: a real page already at the derived path is reported as a collision and both pages stay put; a bare
[[old-stem]]that more than one page answers to follows the one candidate that links back to the referring page; with no such candidate, or several, it is reported as ambiguous and not rewritten (the report says how many of those will break). Rebuild afterwards:llmwiki build --vault <vault>.
llmwiki migrate source-page-paths --vault /path/to/vault --dry-run
llmwiki migrate source-page-paths --vault /path/to/vault
2.4.0 — Findability by page title (#259)
No required migration. After upgrade:
- Title is the findability key:
llmwiki search, MCPwiki_search, and thepage_findabilitylint rule judge findability by each page's frontmatter title, not by slug/filename or bare link text. Slug/filename stays filesystem and[[wikilink]]resolution metainfo (link_integritystill covers broken links). - R2 removed:
page_findabilityno longer searches for raw wikilink anchor strings (e.g. hub pages that list many[[session-slug]]sources no longer fail findability solely because the slug string is not a search hit). Title-not-found / ranked-past-cap errors are unchanged. - Prefer
[[slug|Title]]: visible link text should show the page title while the slug keeps resolution stable. Bare[[slug]]links that resolve correctly are not findability failures. - Optional cosmetic migrate: when you want display text to match titles across existing wiki pages, run offline
llmwiki migrate wikilink-titles --vault <vault> [--dry-run]— reads titles already on disk underwiki/, rewrites resolving bare[[slug]]to[[slug|Title]], zero LLM,raw/never written. Not required for lint green. Fenced/example[[slug]]tokens are rewritten the same as prose — skim--dry-runchanged pages before apply. Rebuild after apply if you want HTML to show the new display text:llmwiki build --vault <vault>. - Re-run after #262: if an earlier
wikilink-titlespass left case/punctuation variants bare (e.g.[[LLM-Wiki]]while the page isllm-wiki), run the migrate again — those uniquely fold to a page under sharednorm_page_key(same fold aslink_integrity/ harvest) and rewrite to[[canonical-slug|Title]]. True aliases and ambiguous collisions stay skipped.
llmwiki migrate wikilink-titles --vault /path/to/vault --dry-run
llmwiki migrate wikilink-titles --vault /path/to/vault
2.4.0 — private vaults keep real home paths (#253)
Behaviour flip, no required migration. sync (and llmwiki add source: paths) no longer rewrite the home-path username to USER by default: new key redaction.redact_username defaults to false. API key, token, and email redaction is unchanged and still always runs.
- Mixed vault after upgrade: files synced before the upgrade keep
/Users/USER/…/-Users-USER-…; new files carry real paths. The site restores cwd either way. - Restore real paths in old files:
llmwiki migrate raw-unredaction --vault PATH --dry-run, then without--dry-run, thenllmwiki build --vault PATH. It touches only home-path and dash-encoded positions, never a bareUSERword, and is idempotent. - Warning — repositories that commit
raw/: a vault synced by the composite Action (action.yml) or the reusable workflow (.github/workflows/llmwiki-action.yml) runsllmwiki syncagainst the Actionvaultinput (default., the caller's checkout), so real home paths land in committed files. Such repositories must set"redact_username": trueunderredactioninconfig.json. This matters most on self-hosted runners, whose home directory belongs to a real account. When the workspace is the llmwiki source tree, pass a subdirectory (vault: action-vault) — the checkout root is refused as a vault. - You share
raw/or publish the site: set"redact_username": trueunderredactioninconfig.jsonbefore the next sync, and runllmwiki migrate raw-redaction --vault PATHfor files synced after the upgrade.
2.4.0 — Session description: assigned names + scored fallback (#249)
No migration. After upgrade, optional refresh of existing raw sessions:
- Assigned names win: when an adapter exposes a session title, that becomes
description:(redacted). Claude Code:customTitlethenaiTitle. Cursor CLI: store metaname, except the placeholderNew Agent(treated as absent). Other adapters: none yet — ChatGPT already sets a conversation title on its own convert path. - Scored fallback: without an assigned name, convert ranks real user prompts (type bands → position → length 0..120) and picks the top. Punctuation-only turns are out. Cursor XML chrome is normalized off the description path so scores are not dominated by
<user_info>wrappers. - Refresh:
llmwiki sync --forcethenllmwiki buildrewritesraw/sessions/and the site. No wiki synth required —description:is convert-time frontmatter only.
| Adapter | Assigned-name source |
|---|---|
claude_code |
customTitle + aiTitle |
cursor_cli |
store meta name (not New Agent) |
| others | none yet (ChatGPT uses conversation title on its own path) |
2.4.0 — Claude control tags + session TOC (#229)
No migration. After upgrade:
- Re-convert Claude sessions if tags leaked into
raw/:llmwiki sync --forcethenllmwiki build. Convert now strips Claude Code local-command / slash-command envelopes (local-command-caveat,command-name, …) and background-task[SYSTEM NOTIFICATION …]/<task-notification>blocks so they never becomedescription:or Conversation prose. Non-empty<command-args>are kept on the slash label (/implement-feature https://…); injected command/skill markdown dumps are skipped fordescription:; user-prompt newlines become markdown hard breaks. Already-writtenraw/sessions/*.mdkeep the old text until force-synced. (Under #249,description:may still select a scored slash turn when it outranks prose.) - Session TOC: rebuild alone is enough for layout — the “On this page” nav is sticky in a Raw-style left column below the hero (not fixed over the title band), appears when the article has ≥2 headings, and uses the same
max-width: 860pxcollapse as Raw.
2.3.0 — Home Pipeline state stamps + Automation panel shrink (#234)
No migration. After upgrade + rebuild:
- Pipeline state on Home: Eligible sources + Knowledge tables stay clean; Timeline holds Last sync / Last synth / Last build / Last lint. A lint-error note appears under the Candidates table when the last lint recorded an error.
- Automation is settings-only (shorter): no stage timestamps, no lint-fail reminder, no installer Updated line; short Synth backend line (spend hint); Agent hooks and Watch on separate lines. Maintain wording: site refreshes once after summarization.
- Standalone
llmwiki lintupdatesllmwiki-state.jsonand copiessite/llmwiki-state.js— it does not rewrite HTML.--lint-failonalldoes not undo the site built earlier in that run. --fail-faststill stops the full pipeline at the first failure; without it, later stages (including build) continue after an earlier failure.
2.3.0 — Cursor Agent CLI synthesis backend (#230)
synthesis.backend accepts "cursor_cli": shells out to Cursor Agent CLI (agent / cursor-agent on $PATH) the same way claude uses claude -p. Defaults: model composer-2.5, timeout 180s. Settings live under nested synthesis.cursor_cli (and nested synthesis.claude / synthesis.ollama); flat claude_* keys still work as fallbacks.
- One-run override:
llmwiki synth --backend cursor_cli(also honoured by--check/--estimate) — does not writeconfig.json. - Not session ingest: this is the synthesis generator. The contrib adapters
cursor_cli(Agent CLI chats) andcursor_ide(IDE Composer) only convert transcripts intoraw/. - Cost estimates:
--estimateprices Cursor models from the packagedmodel_pricing.csv(Cursor-published Composer / Grok rates +agent --modelaliases). No live Agent CLI price fetch. Stand-in rows (if any) are labeled insource/notes. - Overview:
build --synthesizefollows the active backend;dummy/ unavailable skips the overview LLM. - install-automation: interactive backend prompt and
--synth-backendacceptcursor_cli.
2.2.0 — install from PyPI as llm-wiki-plus (#210)
The published distribution is llm-wiki-plus (llmwiki and llm-wiki are unavailable on PyPI). The import and CLI stay llmwiki.
pip install -U llm-wiki-plus
llmwiki --version # → 2.2.0
Optional graph extra: pip install 'llm-wiki-plus[graph]'. Re-run llmwiki install-agent-kit --dest PATH after upgrade so retired slash commands (/wiki-export-marp, /wiki-synthesize) are pruned from an older kit install (#214). Prefer /wiki-synth (add sources-only when you want the old synthesize path).
2.1.0 — CLI help as a lifecycle map (#112)
llmwiki --help is grouped into six lifecycle sections. Command renames that affect scripts and muscle memory:
| Old name | Replacement |
|---|---|
synthesize |
synth (old default was sources-only; today's synth does sources + harvest unless you pass --sources-only) |
consolidate-topics |
gone — synth prepares known names at the start of each sources pass |
migrate-state |
migrate state |
migrate-raw-redaction |
migrate raw-redaction |
migrate-tools-used |
migrate tools-used |
migrate-page-kinds |
migrate page-kinds |
migrate-topic-kinds |
migrate topic-kinds |
migrate-broken-provenance |
migrate broken-provenance |
List migrations with llmwiki migrate or llmwiki migrate --list. Nothing runs until you pick a name. Prefer --dry-run first. The /wiki-synthesize slash alias is retired — /wiki-synth is the command, and synth --sources-only is the flag for the sources-only pass.
2.1.0 — durable sync lookback (#192)
Optional shared filters.since and per-adapter adapters.<name>.since (YYYY-MM-DD, or "all" to skip the date gate for one source). Unset still means unlimited history.
- Set a lookback before enabling a long-retention store so the first bare sync does not convert years of history. CLI
--sincestill overrides for one run. llmwiki configure-sourcesasks shared start date first (Enter = today−30, or keep a stored date), then per source shows Sessions · Earliest · In last 30 days before Enable / path / start date. Enable means the source is on the next baresync(Cursor IDE included). Skipped interviews invent no dates.- The next successful sync with a durable lookback prunes that coding-agent adapter’s
sync.filesstamps older than the window (CLI--sincedoes not GC; notes intake is not GC’d). Lookback-only skips are never remembered as done, so widening the date later can pick them up. GC does not deleteraw/or queue/synth/quarantine/ops. - Cursor IDE registry name is
cursor_ide(wascursor) so it is distinct fromcursor_cli.--adapter cursorand a legacyadapters.cursorconfig block still work. Preferadapters.cursor_idein new configs. Existingsync.fileskeys prefixedcursor::are rewritten tocursor_ide::on the next state load so Composer threads are not re-converted. llmwiki adaptersenabled column is yes/no (will the next bare sync include this source). The oldactivecolumn andauto/explicit/offlabels are gone. Keys and inheritance: configuration-reference.md — Sync lookback.
2.1.0 — MCP tool consolidation (#196)
The stdio MCP server registers six tools: wiki_search, wiki_read_page, wiki_health, wiki_sync, wiki_export, wiki_add. There are no alias stubs for retired names.
| Retired | Replacement |
|---|---|
wiki_query |
wiki_search with question or mode=extract |
wiki_list_sources |
wiki_search with list_sources=true |
wiki_confidence / wiki_lifecycle / wiki_category_browse |
wiki_search with mode=filter and the matching filter_by |
wiki_lint |
wiki_health (same lint JSON keys; adds totals) |
wiki_dashboard |
wiki_health (totals field) |
Full parameter tables: mcp.md. Historical telemetry rows keep the logged tool name; llmwiki usage and Analytics fold retired names into the canonical six-tool surface.
2.0.0 — static site, pipeline, and MCP (from v1.5.0)
Read this first
- Re-run
llmwiki install-automationif you schedulellmwiki all— bareallnow includessyncandsynth. With a real synthesis backend, add--no-synth(or--no-sync --no-synth) to keep the old behaviour (#156). - Run
llmwiki configure-sourcesafter upgrade if you use Cursor Agent CLI, OpenClaw, Codex, or other non-Claude stores (#182). - Stop using
llmwiki serve— open<vault>/site/index.html. Candidate decisions on/candidates.htmlexecute viallmwiki candidates apply --vault <vault> --actions -(#109). - Update MCP clients — replace
wiki_entity_searchwithwiki_search; parsewiki_lintasllmwiki lint --json(#102, #150). - Run migrations when applicable:
-
llmwiki migrate page-kinds --vault <vault>if you havewiki/questions/orwiki/comparisons/-llmwiki migrate topic-kinds --vault <vault>for #147 catch-up on older source pages (#174) -llmwiki migrate broken-provenance --vault <vault>after Cursor CLI re-sync left brokensource_filehops (#180) - Re-sync Cursor Agent CLI (
llmwiki sync --forceor targeted re-convert) sois_headless,sessionId, and timestamps are correct (#180). - Rebuild the site —
llmwiki build --vault <vault>refreshes vendored assets, topic pages, pipeline widgets, and provenance links.
Breaking changes
llmwiki serve/POST /api/candidates//wiki-servegone — static files + CLI review (#109).llmwiki alldefault pipeline issync→synth→build→graph→lint(#156).- Lint default on
allis--lint-fail never(report only) (#156). - MCP
wiki_lintJSON shape matches CLI (BREAKING); filterissuesbyrule; old keysorphans/broken_linksare gone (#150). wiki_entity_searchremoved —wiki_search(term, kind=…, format=…)(#102).llmwiki consolidate-topicsis gone (#147 / #112) — known-names prepare is part ofsynth.synth --allow-unclassifiedremoved (#102).type: question/type: comparisoninvalid —migrate page-kinds(#109).entity_consistencylint rule removed; unknown--rulesnames fail (#102).
Session sources and adapters
- Bare
llmwiki syncloads every enabled ingest-ready adapter whose store exists;enabled: falseis honoured (#182). - Obsidian and ChatGPT export stay opt-in (
adapters.*.enabled: true). filters.exclude_headless(default on) skips automated launches for every coding-agent adapter; re-sync to classify older Cursor CLI rows (#180).filters.exclude_empty(default on, #188) skips sessions with zero user messages and zero tool calls at convert time, and drops them from the synthesis backlog /--estimatewhen they are already inraw/. Existing vaults keep pages already synthesized from empty transcripts — delete those underwiki/sources/(leaveraw/and synth state alone so they are not recreated), then repair anywiki/candidates/whosesources:cited them. Setexclude_empty: falseto restore today's archive behaviour.- Cursor IDE Composer ingest works via bare
llmwiki syncafterconfigure-sourcesEnable (orllmwiki sync --adapter cursor_ide) (#2 / #192) — parses globalstate.vscdb. Setfilters.since/adapters.cursor_ide.since(or pass--since) before the first large run. Alias--adapter cursor/ legacyadapters.cursorstill resolve. Cursor Agent CLI remainscursor_cli.
Synthesis and candidates
- Prefer
llmwiki synth—synthesizeis removed (#112); use--sources-onlywhen you want the old sources-only default (#90). - Next
synthrewrites source pages lacking parseable topic bullets once (#147); optionalmigrate topic-kindsfor cheap catch-up (#174). Vocabulary now carries known kind into each source pass (#257); pages that only lack kinds still usemigrate topic-kinds, not a full re-synth. - Promote needs no LLM — empty Key Facts copy from source
fact:bullets;rewrite-key-factsstill needs a backend (#147, #103). wiki/archive/is cold storage — discarded candidates stay resolved in harvest; first lint after upgrade may report more broken links (#140).synth --estimateAlready synthesized follows synth state, not pages-on-disk alone (#163).- Ctrl+C during
synthexits 130 after recording pages that reached disk (#145).
Site and review
- Open
site/index.html(orfile://) — highlight.js and vis-network are vendored (#109, #127). llmwiki build --local-root PATHfor portable published paths (#109).candidates applyrebuildssite/unless--no-rebuild(#109).llmwiki export/llmwiki reindexCLI removed — usebuild; catalog reconciles onsync/synth/ candidate actions (#82).
Lint and MCP
<vault>/llmwiki.json—lint.disabled_rulesto opt out of named checks (#150).llmwiki lint --min-refs Nandllmwiki all --min-refs Nshare harvest threshold (default 3) (#150).llmwiki lint --fail-on-warningsfor warning-severity gate (#150).llmwiki lint --include-llmremoved — drop the flag from scripts (#72).provenance_integritymay report new errors on brokensources:/source_file:chains (#122).
Automation
install-automationplain-language wizard, cron--schedule,--job {ingest,maintain}(#156).--with-sync/--with-synthstill parse but are inert — use--no-sync/--no-synthto opt out (#156).--profile {A,B,C}deprecated —A→ingest,B/C→maintain;--hour/--minutesuperseded by--schedule.llmwiki install-agent-kit --dest PATHreplaces manual.claude/commandscopy and.claude-plugin/(#109).
No action needed
/vs/removed — never wired into normal builds (#138).- Honest Home pipeline counts — eligible sources and On disk column (#81).
- Estimate Candidates labelled pre-run state, not a harvest forecast (#113).
entity_typeon existing pages — inert metadata; optional re-stampwiki/projects/totype: project(#102).
v1.5.0 — Analytics layout + CallMcpTool migration
After upgrading the engine, rebuild the vault site so Analytics picks up the new section order and heatmaps:
llmwiki build --vault /path/to/vault
# or, when vault.default_path is already configured:
llmwiki build
build also one-shot backfills synth.pipeline in llmwiki-state.json / llmwiki-state.js when that key is missing (state last written by v1.4.0). That fills the Home State widget without a separate synth --estimate. The refresh is local-only (no API / no tokens) and runs only on a shape mismatch — later builds skip it once the snapshot exists. Sync / add / estimate still refresh the snapshot when content changes.
Optional: expand CallMcpTool entries in already-synced raw/sessions/*.md when the originating agent session file still exists:
llmwiki migrate tools-used --vault /path/to/vault --dry-run
llmwiki migrate tools-used --vault /path/to/vault
llmwiki build --vault /path/to/vault
When the origin store is gone (TTL / deleted sessions), rows are skipped safely — the migrator never invents MCP tool names. Prefer this over sync --force for the same TTL reasons as other raw rewrites: agent transcripts are usually retained only ~30 days, so force re-convert often has nothing left to read.
See reference/state-persistence.md for how usage logs, rollup, daily series, and state file relate.
v1.5.0 — index cwd restore + encoded-path redaction (#56)
For AI agents maintaining a user's vault: after the user upgrades llm-wiki (pull / pip install -U / brew), fix their vault — not the llm-wiki git clone. The engine change alone does not rewrite site/ or raw/.
Required: rebuild the site
llmwiki build --vault /path/to/their/vault
# or, if vault.default_path is already set in that checkout's config.json:
llmwiki build
That regenerates site/projects/index.html and site/sessions/index.html with restored local cwds (and a Cwd column on the sessions table).
If you skip the rebuild (engine updated, old site/ left as-is):
| Symptom | Why |
|---|---|
projects/index.html still mixes /Users/USER/… (or /home/USER/…) with real paths |
Stale HTML from before restore/autodetect fixes |
Session detail shows a usable cd … && claude --resume …, but the sessions index does not |
Index never restored paths until #56; old build has no Cwd column |
Descriptions on the sessions table still contain …/USER/… |
Same — restore runs at build time |
Grep checks from #56 stay non-zero (grep -c '/Users/USER/' site/sessions/index.html) |
Expected until rebuild |
Nothing in raw/ or wiki/ is harmed by skipping rebuild; only the browsable site stays wrong / inconsistent with session heroes.
Optional: deterministic raw/ redaction rewrite (no LLM)
56 also teaches convert to rewrite dash-encoded agent-store segments
(~/.claude/projects/-Users-<name>-… → -Users-USER-…). New syncs do that automatically.
Existing raw/sessions/*.md are immutable during normal sync. For a vault that stays private and local, leaving old raw/ alone is fine — site restore already shows usable local cwds after rebuild.
When the user intends to publish or share raw/ (or otherwise wants the USER placeholder complete in every path shape already on disk), run the deterministic migrator — it rewrites path strings in place, does not call the LLM, does not enqueue synthesize, and does not touch wiki/:
# preview
llmwiki migrate raw-redaction --vault /path/to/their/vault --dry-run
# or: python3 scripts/migrate_raw_encoded_username.py --vault … --dry-run
llmwiki migrate raw-redaction --vault /path/to/their/vault
llmwiki build --vault /path/to/their/vault
Do not use llmwiki sync --force / re-convert from ~/.claude/projects/ or Cursor session folders for this:
- Agent stores usually retain transcripts only ~30 days (Claude Code retention; Cursor similar). Older sessions in
raw/often have no source file left to re-convert from — force-sync silently skips or fails those rows while still looking like “migration work”. - Force-sync is the wrong tool anyway: agents may follow it with
synth/ queue digest and burn LLM tokens rewriting wiki pages that did not need to change. The path-string rewrite above is enough.
If you skip the raw migrator (normal for private vaults):
- Day-to-day browsing and resume: unaffected after rebuild.
- Old
raw/rows that already contain-Users-<real-username>-…next to a redacted/Users/USER/…prefix keep that incomplete masking untilmigrate raw-redaction(or a future sync of still-present sources). That is a redaction-contract gap for publish/share workflows, not data escaping a private vault.
Config note
If root config.json copied the examples placeholder "redaction": { "real_username": "" }, #56 re-autodetects after overlay so restore works again. No manual config edit required unless the user wants username redaction, which needs redaction.redact_username: true (#253).
Downgrading is guarded (#29)
Pointing an older checkout at a vault a newer engine wrote used to silently reconvert everything under the old slug scheme, duplicating raw/. As of #29, sync refuses to run when the vault's llmwiki-state.json was written by a newer meta.schema_version, or is present but unreadable:
error: <vault>/llmwiki-state.json: state file was written by a newer llmwiki
(schema_version=2 > 1). Upgrade llmwiki, or pass --force-resync to reconvert
from scratch ...
The fix is to upgrade the engine to match the vault. Only pass sync --force-resync if you genuinely want a full reconvert from scratch (it implies --force and may duplicate an already-populated raw/). This guard protects the newer→older direction; the older engine that lacks it still can't see the unified file, so keep engines at or ahead of the version that last wrote the vault.
Moving an in-clone wiki into a vault (pre-v1.5.0 checkouts only)
29 shipped in v1.5.0, so a fresh install is vault-first and nothing here applies to it. If you ran a pre-release checkout that kept raw/ and wiki/ inside the git clone and you are now setting vault.default_path, move the content by hand — there is no migration command, and two trees holding the same wiki drift silently:
llmwiki init --vault /path/to/vault # scaffold + seed the vault
cp -r raw/ wiki/ /path/to/vault/ # move your content across
llmwiki sync --vault /path/to/vault --no-auto-build # reconcile index after copy
llmwiki lint --vault /path/to/vault --rules index_sync
Two things to do explicitly, because neither is obvious:
- Delete the demo entries from the copied
index.md. The clone'swiki/index.mdcatalogs the repo's demo pages (entities/Anthropic.md,concepts/CachePricing.md,projects/demo-*.md). Copied into a vault that has none of them, every one becomes a dead index link.llmwiki sync --no-auto-buildreconciles the catalog for you — that is the reason to run it right after the copy. - Remove the leftover ignored pages from the clone.
raw/andwiki/are gitignored, so anything left behind is invisible togit statusbut still real on disk. A command run without a vault (or from a script with a different config) writes there, and you end up with pages that exist in only one of the two trees.
v1.4.0 — unified queue + vault state (hard cutover)
Requires Python ≥ 3.12.
One-time migration required if your vault still has legacy dotfiles:
python3 scripts/migrate_state_v1_4_0.py --state-file /path/to/vault/llmwiki-state.json
# or:
llmwiki migrate state --state-file /path/to/vault/llmwiki-state.json
# optional cleanup after verifying:
# rm -rf /path/to/vault/.llmwiki-state.json ...
What changed
| Before | After |
|---|---|
.llmwiki-state.json, .llmwiki-synth-state.json, .llmwiki-queue.json, .llmwiki-pending-prompts/ |
<vault>/llmwiki-state.json (+ llmwiki-state.js sidecar) |
LLMWIKI_ROOT env var |
vault.default_path in config.json |
| SessionStart auto-sync hook | Manual llmwiki queue run |
synthesis.backend: agent_delegate |
Removed — use dummy, ollama, or claude |
external wiki_tasks queue ownership |
llmwiki queue enqueue into vault state |
| Python 3.9–3.11 | Python ≥ 3.12 |
llmwiki add synthesized whole backlog |
add synthesizes only the docs it just wrote |
New commands
llmwiki queue status
llmwiki queue enqueue --task-type add_doc --source https://example.com
llmwiki queue run --limit 20
Rebuild the site after upgrading so the Home page loads llmwiki-state.js from site/ (build copies the vault sidecar into the site tree).
State path isolation (v1.4.0+)
The active state file is process-scoped: llmwiki CLI entry points call configure_state_file once from --vault / --state-file / config.json vault.default_path. Library code and tests must pass an explicit state_file= override or rely on that configured path — there are no import-time vault bindings.
If llmwiki-state.json looks truncated (e.g. only a handful of synth.files keys after a test run), re-run the migration against your vault:
PYTHONPATH=/path/to/llm-wiki python3 scripts/migrate_state_v1_4_0.py \
--state-file /path/to/vault/llmwiki-state.json
Legacy dotfiles (.llmwiki-state.json, .llmwiki-synth-state.json, …) are merged in; verify sync.files / synth.files counts before deleting them.
Re-run migrate state to repair dead synth_request items (#23)
Vaults migrated with the first v1.4.0 migrator carry queue items with task_type: "synth_request". The queue runner has no handler for that type, so llmwiki queue run marks every one of them status: error. Re-run the migration — it purges them, and enqueues a single synthesize task if (and only if) real backlog remains:
llmwiki migrate state --state-file /path/to/vault/llmwiki-state.json
llmwiki queue run --vault /path/to/vault
The migration resolves each legacy .llmwiki-pending-prompts/<uuid>.md against the pending sentinel pages left in wiki/sources/, so it is safe to rm -rf .llmwiki-pending-prompts/ afterwards — the prompts themselves are never needed again.
Check synthesis.backend before syncing (#23)
agent, agent-delegate, and agent_delegate were removed in v1.4.0. resolve_backend() reads them as a typo and silently falls back to dummy, which writes stub pages (Auto-synthesized from session) into wiki/sources/. migrate state prints a WARNING: when your config.json still names one — set synthesis.backend to claude, ollama, or dummy, then re-synthesize:
llmwiki synth --vault /path/to/vault
Stub pages left behind by the dummy backend count as unsynthesized backlog (#24): llmwiki queue status reports them under unsynth_total, llmwiki lint flags them with the stub_source_pages rule, and llmwiki synth refills them with a real backend.
v1.3.83+ — unified queue preview (superseded by v1.4.0)
Same migration as v1.4.0; use scripts/migrate_state_v1_4_0.py.
v1.3.0 — consolidated 1.2.x patch roll-up
Released: 2026-04-26.
Summary
Drop-in upgrade from any 1.2.x. v1.3.0 consolidates 38 in-tree patch versions (1.2.1 → 1.2.38) under one minor release tag — no breaking API changes, no schema migrations, no config changes.
pip install -U llm-wiki-plus # → 1.3.0
llmwiki --version # → 1.3.0
What's in it
The full per-fix detail is preserved under the [1.2.x] entries in CHANGELOG.md. Two themes:
-
Opus 4.7 deep code-review backlog (#403, ~26 issues) — every correctness, perf, and observability finding got a one-issue-one-PR fix. Headliners:
is_subagentstrict path check (#406),derive_session_slugUUID-prefix collision (#424), tilde-fence counting in_close_open_fence(#419),wiki_queryranking length normalisation (#418),wiki_searchcap (#413), per-vault synth state (#420),--forcesync persisting_meta/_counters(#426), subprocessclaude_pathresolved viashutil.which(#421). -
Performance + features —
DuplicateDetectionlint rule rewritten with bucket+fingerprint+SequenceMatcher (1s vs minutes on 500 pages, #412), perf-budget test suite (-m slow, #429),md_to_plain_textcache (#417), auto-seeded project stubs pre-populated from session metadata (#425), 2 new lint rules (frontmatter_count_consistency,tools_consistency, #378),wiki-allslash command,_context.mdfolder convention (#60).
Breaking — none
Same CLI surface, same config schema, same on-disk state format. The only thing that changed is that the next plain sync after a forced re-sync will now correctly identify already-processed files as unchanged (was: re-processed every time, #426).
Schema migrations — none
State files written by 1.2.x are read verbatim by 1.3.0.
v1.2.0 — first stable on the 1.x line
Released: 2026-04-25.
Install changes
- PyPI distribution name is
llm-wiki-plus—llmwikibelongs to another author, and PyPI's name-similarity rule also rejectsllm-wikias too close to it, so the distribution carries a-plussuffix. The Python module + CLI command stayllmwiki, only thepip installline changes: ```bash pip install llm-wiki-plus # was: pip install llmwiki llmwiki --version # → 1.2.0 (CLI name unchanged) python3 -c "import llmwiki" # still works (import name unchanged)
Releases before the rename documented this distribution as `llm-notebook`; that name was never published for this fork and no longer appears in install instructions (#210).
### Removed CLI subcommands
The CLI was slimmed in #362. If you scripted any of these, replace as noted:
- `llmwiki schedule` — removed. Schedule `llmwiki sync` directly via your OS's job runner (launchd / systemd / Task Scheduler).
- `llmwiki install-skills` — removed. Manually copy `.claude/commands/wiki-*.md` into `~/.claude/commands/` for global availability.
- `llmwiki check-links` — removed. Use the GitHub Actions link-check workflow instead.
- `llmwiki watch`, `llmwiki manifest`, `llmwiki link-obsidian`, `llmwiki export-obsidian`, `llmwiki export-marp`, `llmwiki export-qmd`, `llmwiki eval` — also removed. (`llmwiki eval` was never a live CLI — structural scoring never shipped; use `llmwiki lint` for wiki quality.)
### Removed adapters
`jira_adapter`, `meeting`, `pdf` were removed in #363. If you depended on any of them, pin v1.1.0-rc8 until you migrate.
### Demo data correctness
`user_messages` / `tool_calls` counts on the 8 demo session files were 2–10× higher than the body actually contained. The values are now recomputed from body content. Two new lint rules (`#16 frontmatter_count_consistency`, `#17 tools_consistency`) prevent regression.
### `sync --force` no longer drops colliding sessions
If you ran `sync --force` against a corpus where two sources had the same canonical filename (rare but real on large corpora), one of them was silently overwritten. Fix: per-run filename tracking now disambiguates regardless of `--force`. Affected ~200 of 495 sessions on a real corpus we tested.
### New: `llmwiki all`
One-shot pipeline runner for CI:
```bash
llmwiki all # build → graph → lint
llmwiki all --strict # exit 2 on any lint warning
Schema migrations
None. JSON sibling files now correctly emit int and bool types for user_messages / tool_calls / is_subagent (were strings); any downstream that string-compared is_subagent == "false" now needs is_subagent is False.
v1.1.0-rc5
Released: 2026-04-21.
New behaviour
-
Session transcripts strip project-local file refs. Anchors pointing at
tasks.md,user_profile.md,settings.gradle.kts,.kiro/…,/Users/…, etc. are unwrapped into inline<span class="session-ref dead-link">— the filename stays visible but the anchor doesn't 404. No action required. -
README.mdandCONTRIBUTING.mdnow compile as site pages.site/README.htmlandsite/CONTRIBUTING.htmlship alongsidechangelog.html. Link rewriter routes to the compiled page instead of GitHub for these two files. -
/wiki-synthesizeslash command — wrapsllmwiki synth --sources-only(prefer/wiki-synth). Copy viallmwiki install-agent-kit --dest PATH. (llmwiki install-skillswas removed in v1.2.0.) (retired in #214 — use/wiki-synth) -
Dual-mode docs landing pages.
docs/modes/api/anddocs/modes/agent/exist as skeletons; the actual API / Agent backends ship with #315 / #316.
Schema migrations
None. Fully backwards-compatible with rc4 state files.
Breaking
None.
v1.1.0-rc4
Released: 2026-04-20.
New behaviour
- Obsidian is opt-in now. Past versions fired the Obsidian adapter on every
syncby default. If your workflow relied on that, add this tosessions_config.json:
```json { "obsidian": { "enabled": true } }
Context: [#326](https://github.com/AlexanderMakarov/llm-wiki/issues/326). Runs as of rc3; surfaced in `llmwiki adapters` column `will_fire`.
- **Graph clicks respect compiled-site existence.** Nodes whose corresponding page wasn't rendered to HTML show a tooltip instead of opening a 404. No action needed — if you see the tooltip on entity / concept / nav pages that's the new design.
- **Backlinks now propagate.** Run `llmwiki backlinks` once to inject managed `## Referenced by` sections into every linked-to page. Idempotent, dry-runnable, prune-able:
```bash
llmwiki backlinks --dry-run --verbose # preview
llmwiki backlinks # commit writes
llmwiki backlinks --prune # strip every block
Schema migrations
-
.llmwiki-state.jsonkeys rewrite from absolute paths to<adapter>::<home-relative-path>on first load under rc3+. Migration is automatic and idempotent. If you moved your repo to a new machine, old state will be preserved verbatim — re-sync to reindex. -
.llmwiki-quarantine.jsonis a new local file (gitignored). First appears when a convert error happens. Inspect withllmwiki quarantine list. -
Frontmatter
tags:/topics:convention is lint-enforced (rule #14tags_topics_convention) — projects usetopics:, everything else usestags:. Runllmwiki tag conventionto see violations.llmwiki tag rename <old> <new>rewrites across every page.
Breaking — none
No breaking CLI or config changes. Every test pre-upgrade keeps passing post-upgrade.
v1.1.0-rc3
See the release notes for the full rc3 gap-sweep bundle. No migration required.
v1.0.0 → v1.1.0-rc1
Config: synthesis.backend now accepts "ollama" in addition to the default "dummy". See docs/reference/prompt-caching.md for the ollama setup.
wiki/candidates/ directory is new — created automatically by ingest when it sees a brand-new entity/concept. Triage with /wiki-candidates (renamed from /wiki-review in rc3).
Older versions
Pre-v1.0 milestones shipped under internal sprint tags. Upgrade from v0.9.x to v1.0.0 in one step — no intermediate migration required. If you're on a pre-0.9 build, start fresh: llmwiki init in a new tree and re-run sync.