Canon file-first: disk beats chat
Canon file-first: the disk beats chat principle — the foundation for durable AI novel writing on NovelKit/Hermes.
Canon file-first means every truth decision (characters, timeline, world rule, cultivation state) is stored on disk in the novel workspace — not in the model's chat "memory". NovelKit asserts: disk beats chat, canon beats index (RUNBOOK P5).
Why file-first for long fiction?
A chat thread can't be audited, can't be diffed, can't be resumed safely. A file has an owner (agent contract), provenance after sync, and doctor checks coherence. A Publisher can evaluate it before buying the catalog.
The main canon files
- PROJECT_DNA.md
- database/characters, worldbuilding, plot_threads, timeline
- outlines/, chapters/, reviews/
- memory/Memory.md (after an approved sync)
Story bible: Story bible AI.
RAG and vector do not overturn canon
The novelkit-context plugin retrieves to inject context — but when there is a conflict, the file wins. Memory layer: 5 layers. The system: AI novel writing.
Conflict resolution: who wins when there's a conflict
Authority order: (1) the story's PROJECT_DNA + database canon, (2) genre consistency rules, (3) retrieved memory/index, (4) model suggestion. The agent reports CANON_CONFLICT instead of choosing arbitrarily. The human owner resolves it and writes it to the file.
Versioning and diff
Chapter and review files have provenance after sync. The Publisher audits the diff between review versions — transparent about edits before publishing.
Quoting the RUNBOOK
Disk beats chat, canon beats index. The canon file is the source of truth; retrieval/index/memory are derived state and never overturn canon (P5). This is the foundational principle behind every NovelKit technical blog post.
Canon file-first: disk beats chat, canon beats index
The canon file-first principle (NovelKit P5) makes the file on disk the absolute source of truth — not chat history, not a RAG snippet, not a vector match that scores high but is canon-wrong. RUNBOOK: Disk beats chat, canon beats index. Retrieval/index/memory are derived state; the agent reports CANON_CONFLICT instead of silently merging a contradiction.
A novel workspace contains PROJECT_DNA, database/* (character, world, timeline, plot_threads), outlines/, chapters/, reviews/, memory/Memory.md. Every canon mutation goes through a sync commit after a PASS ≥85 — the write stage alone is not enough.
Authority order when there's a conflict
- The story's PROJECT_DNA + database canon
- Genre consistency rules (Meta Genre, Xianxia, romance…)
- Retrieved memory/index (layers B–E novelkit_memory + novelkit-context)
- Model suggestion — lowest, does not override 1–3
Conflict resolution workflow
The agent detects a conflict → flags it in the review → HARD-FAIL or a blocked task → the human owner fixes the canon file → doctor → resume the pipeline. No silently "picking the version the model prefers".
Versioning, provenance and Publisher audit
Chapter and review files have provenance after sync: who wrote, who reviewed, score, commit id. The Publisher diffs reviews across SOFT-FAIL rounds — transparent about edits before publishing to a platform. The novelkit-context plugin reindexes after sync — the index is always a derivative of the latest canon.
Workspace layout and file owners
A canon file-first workspace: PROJECT_DNA.md, database/characters, database/world, database/plot_threads, master timeline, Cultivation Clock (xianxia), outlines/master, chapters/draft, reviews/chapter_*, memory/Memory.md. Each kind of state has a file owner — the agent mutates the correct path after sync, no silent overwrites. RUNBOOK: Disk beats chat, canon beats index.
Conflict resolution for the studio
The agent detects a conflict → flags the review HARD-FAIL or CANON_CONFLICT → the human owner fixes the canon file → doctor health-check → resume the pipeline with plan_next. No choosing "the version the model prefers" — that loses provenance and pollutes the 5-layer memory. Authority order: (1) DNA + database, (2) genre rules, (3) retrieved B–E, (4) model suggestion lowest.
| Canon directory | Owner agent | Mutate when |
|---|---|---|
| PROJECT_DNA.md | novelkit_dna / human | Bootstrap, amend with review |
| database/* | Architect / Weaver | Sync after PASS ≥85 |
| chapters/ | Prose Writer | Write stage; sync commit final |
| reviews/ | Quality Auditor | novelkit_gate every chapter |
Lãng Khách dispatches via delegate_tool in hub-and-spoke — every mutation has an audit trail. Publisher B2B pilot: requires a canon diff between chapter versions + review scores — no buying a black-box generation.
Read more: story bible, Project DNA, memory layer, pipeline, quality gate.
Canon file-first FAQ
- Can chat history be canon?
- No — RUNBOOK: disk beats chat; PROJECT_DNA + database/* are the authority.
- High vector similarity but wrong?
- Canon beats index (P5) — the agent raises CANON_CONFLICT, does not pick the snippet.
- Has the write stage already mutated memory?
- No — only a novelkit_sync commit after PASS ≥85 upserts layers B–E.
The Publisher diffs reviews across SOFT-FAIL rounds — transparent about edits before publishing to a platform. Lãng Khách enforces file owners; the human fixes canon → doctor → resume the pipeline with plan_next.
Canon file-first is NovelKit's foundation: PROJECT_DNA, database, outlines, chapters, reviews, memory — disk beats chat, canon beats index (P5). The sync gate PASS ≥85 before mutating memory.
Canon file-first protects Publishers from a wrong RAG snippet and from chat history becoming the source of truth.
Conflict resolution: the human fixes the canon file → doctor → resume — no silent merge following the model suggestion.
novelkit_sync commit is the single point that mutates canon and memory layers B–E.
Provenance and diff after each sync
File-first is not just "save to disk" — each synced chapter carries provenance: the writing agent, the reviewing agent, score, timestamp. The Publisher diffs chapter N vs N-1 to audit canon changes. When doctor reports canon_index_incoherent, the pipeline pauses until it reconciles — no generating further on top of an error.
Compared with a Lorebook / custom instructions
A chat Lorebook has limited entries and no DAG. NovelKit canon has an owner agent, a dependency graph, and a gate: an outline must point to a character ID that already exists in the database. Missing file → task blocked, no "making it up".
Publisher canon evaluation checklist
- PROJECT_DNA has genre, tone, hook complete
- database/characters has want/need/lie
- plot_threads have status open/resolved
- timeline matches published chapters
- reviews/ have a score ≥85 for production chapters
Cluster: story bible, Project DNA, memory, pipeline.
P5 in the RUNBOOK: canon beats index
A stale RAG chunk may not override the character file. Vector search returns an old passage — the agent must reconcile it with database/characters before writing. Doctor flags rag_index_stale and canon_index_incoherent as blocking.
Git-friendly workflow (studio)
A novel workspace can be version-controlled — diff a chapter, blame a review. The Publisher's technical team audits it like a code review. There is no equivalent in a chat thread.