Skip to main content
Every wiki page llmwiki generates records the source files - and their content hashes - that produced it. At compile time, those hashes are written to .llmwiki/state.json. On any subsequent command, llmwiki compares the recorded hashes against the current state of sources/ on disk. This comparison is source freshness tracking: a lightweight, on-demand signal that tells you whether each page still accurately reflects the sources it was built from, without requiring a full recompile to find out. When sources drift out of sync with the compiled wiki, llmwiki surfaces the issue clearly so you can repair it deliberately rather than discovering it through stale query results.

​
The two freshness states

​
Stale

A page is stale when at least one of its owning sources still exists on disk but its content has changed since the last compile. The recorded hash in .llmwiki/state.json no longer matches the file’s current content hash. The page exists and is readable, but it may no longer accurately represent the current state of the source material. A page with multiple contributing sources is also marked stale when a subset of those sources was deleted - the surviving sources are still present, but the page can no longer be fully regenerated without them.

​
Orphaned

A page is orphaned when every source that produced it has been deleted from sources/. The page exists on disk but has no living source to regenerate it from. Orphaned pages are flagged by llmwiki lint and are candidates for cleanup.
Query pages (saved answers written by llmwiki query --save) are never marked stale or orphaned - they are generated answers, not source projections. Their freshness status is always unverified.

​
How llmwiki detects freshness

Freshness is derived on demand. There is no background watcher or daemon involved. When you run a command that checks freshness - llmwiki lint, llmwiki status, or llmwiki refresh --stale - llmwiki:
  1. Reads .llmwiki/state.json, which records the per-source content hashes from the last compile along with each source’s ownership map (which concept slugs it produced).
  2. For each source in the state file, checks whether the file still exists on disk and hashes its current content if so.
  3. Compares the current hash against the recorded hash for each source.
  4. Applies the classification algorithm to each page:
    • If state is missing or corrupt → unverified
    • If all owning sources were deleted → orphaned
    • If any owning source was deleted, or any live owning source has a changed hash → stale
    • If all live owning sources match their recorded hashes → fresh
This hashing pass happens once per command and is shared by every consumer - lint, export, MCP tools, the viewer - so freshness is never computed redundantly in a single run.

​
Where staleness is surfaced

You don’t need to run a dedicated freshness check to know about stale pages. The signal propagates across all of llmwiki’s output surfaces. llmwiki lint lists every stale and orphaned page as named lint results, alongside broken links, missing citations, and other quality issues. Stale and orphaned pages contribute to the health score reported by llmwiki eval. llmwiki status (and the MCP wiki_status tool) returns a structured snapshot that includes stale and orphaned page counts, the full list of affected slugs, and a stateStatus field that reports whether .llmwiki/state.json is ok, missing, or corrupt. Local viewer (llmwiki view): an open page’s metadata rail displays a badge for its freshness status - STALE, ORPHANED, CONTRADICTED, or ARCHIVED. The Concepts screen (#/concepts) marks each row with a freshness dot and filters the list by freshness axis; Health & lint (#/health) shows the aggregate counts, and the header pill reports the whole-wiki verdict. If .llmwiki/state.json is missing or corrupt, a corrupt-state banner appears at the top of the viewer and the header reports freshness as unverified rather than fresh. MCP get_context_pack: the evidence pack includes a freshnessStatus field per page, so agents consuming the pack know which pages may be outdated before reasoning over them. JSON export (llmwiki export --target json): each page record in the export envelope includes freshness metadata, making it inspectable downstream or importable into tools like @atomicmemory/llmwiki. llmwiki next: when stale pages exist, llmwiki next recommends running llmwiki refresh --stale as your next action, so you’re guided toward repair naturally.

​
Repairing stale pages

​
llmwiki refresh --stale

llmwiki refresh --stale is the targeted repair command. It does three things:
  1. Recompiles the changed owning sources - only the sources that changed and own stale pages are sent back through the two-phase LLM pipeline. Sources that are new and have never been compiled are deliberately skipped.
  2. Cleans up orphaned pages - pages whose every source was deleted are removed from wiki/. This cleanup requires no LLM calls and no API key.
  3. Leaves unrelated pages untouched - pages whose sources haven’t changed are not reprocessed, even if other pages in the project are stale.
llmwiki refresh --stale does not pick up new source files that have never been compiled. If you’ve added new files to sources/ since the last compile, run llmwiki compile to ingest them. Use refresh --stale specifically for repairing pages whose sources changed or were deleted.

​
Preview with --dry-run

Before committing to a repair, preview exactly what refresh --stale would do:
--dry-run prints the repair plan - which sources will be recompiled, which orphaned pages will be cleaned up - without making any LLM calls or writing anything to disk. Use this to verify the scope of the repair before running it for real.

​
Cleanup-only refreshes

When all stale pages are orphaned (every affected source was deleted, no sources merely changed), the repair requires no LLM calls - it’s a filesystem cleanup only. You can run llmwiki refresh --stale in this case without any provider credentials configured.

​
Review policy and refresh

If your project has a review policy declared in .llmwiki/config.json, llmwiki refresh --stale honors it the same way llmwiki compile does. Pages that trip a hold condition (low confidence, contradicted, schema-violating, or provenance-violating) are queued as candidates in .llmwiki/candidates/ rather than written directly to wiki/. Configuration is fail-closed - a malformed config aborts the refresh rather than silently disabling the policy.

​
Corrupt state

If .llmwiki/state.json is missing or contains invalid JSON, llmwiki surfaces the problem explicitly. It does not silently create a .bak file or fall back to an empty state. Instead:
  • llmwiki lint and llmwiki status report stateStatus: "missing" or stateStatus: "corrupt" and list all pages as unverified.
  • The local viewer shows a corrupt-state banner.
  • llmwiki refresh --stale will report the corrupt state and cannot proceed.
To recover, rebuild the state file from scratch by running a full compile:
This regenerates .llmwiki/state.json from the current sources/ directory and produces fresh pages. After compile completes, freshness tracking resumes normally.

​
Repair workflow

1

Check what's stale

Run llmwiki lint to see which pages are stale or orphaned, along with any other quality issues in the wiki.
Look for results with rule names stale-page and orphaned-page. Each result names the affected slug and the source file responsible.
2

Preview the repair plan

Before making any changes, preview what refresh --stale will do. No LLM calls are made and nothing is written to disk.
Review the output to confirm the scope: which sources will be recompiled, which orphaned pages will be deleted.
3

Run the repair

Once you’re satisfied with the plan, run the repair for real:
Stale pages whose sources changed are recompiled. Orphaned pages are cleaned up. Unrelated pages are not touched.
4

Verify resolution

Run llmwiki lint again to confirm that no stale or orphaned pages remain:
If any stale pages are still present, check whether their source files exist and whether you may have new sources that need a full llmwiki compile.
The best way to avoid accumulating stale pages is to keep llmwiki watch running during active editing sessions. It monitors sources/ for changes and triggers an incremental recompile automatically whenever a file is saved - so pages stay fresh as you work rather than drifting until you notice.