Teller Framework - AI Story Bible
A directory of markdown files that lets any AI with file access write consistent, canon-accurate fiction across sessions, projects and models. No memory, no plugins, no special setup.
Role
Design & Development
Stack
Markdown, YAML, Claude Code
Type
Writing automation
Status
Actively used
1. Overview
The structure of the files tells the AI what to load. Teller is a story bible built from plain markdown. Each concept lives in its own file, called a node, and declares which other files must be loaded with it. Any AI that can read files can then work on a long story with precision, without relying on memory.
It is the evolution of my Teller UX/UI case study: the same problem, context-aware AI for fiction writers, solved this time as an engine instead of an interface. I built it for my own long-form universe, which today spans two books and more than 115 tracked chapters.
⚠️ The Problem
A long story outgrows any context window, and chat memory drifts. Characters change their voice between sessions, a rule of the world is quietly contradicted, and every new session starts by pasting the same background again.
- Loading everything is noisy and expensive, and more context also means more chances to contradict it
- Loading too little breaks continuity across chapters
- Relying on the model to remember fails across sessions and across models
2. Why Not the Alternatives
| Approach | What goes wrong |
|---|---|
| Paste the whole bible | Noise, cost and contradictions grow with the story. |
| Rely on chat memory | Drift between sessions and models; nothing is auditable. |
| Plugins or a vector store | Extra infrastructure, fuzzy retrieval and files nobody can read or diff. |
| Teller: files that declare their dependencies | Exact, portable, human-readable and versioned in git. |
✓ The Idea
A node knows its own dependencies. When the AI opens a character, that node already declares which system, world and voice files come along, so nothing important is forgotten and nothing else is loaded.
3. Core Concepts
| Concept | What it is |
|---|---|
| Node | One concept per markdown file, with YAML frontmatter: id, type, project, module, tags, relations, load-with and updated. |
| Module | A category folder inside a project: characters, world, system, plot, relations, voice, themes, bestiary and chapters. |
| Bundle | A task preset that says which nodes an AI task loads: write, plan, edit, continuity check, update nodes, develop and dashboard. |
| load-with | The frontmatter field where a node declares its own dependencies. The key to precision. |
| state.md | Per-project file that tracks the current position, the last chapter written and the plan for the next one. |
| Chapters index | One row per chapter with its number, title, point of view, key characters and a one-line summary. |
4. Architecture
Three layers keep the framework separate from the story it serves.
Agent instructions: A short root file that acts as a router, the agent specification, and five slash commands. It is the only thing the AI reads automatically.
Framework: Bundles, node templates and the path conventions. It contains no story data.
Project data: One folder per project with its state, index and module folders. Planning notes and spin-off pitches live outside the projects, so they are never loaded while writing.
5. Keeping the Context Small
The whole design is a set of rules about what not to load.
Session start: Only each project's state file is read, never the full bible.
Writing default: A chapter is written with the state file and the voice guide, and nothing else loads automatically.
Demand-driven nodes: A node loads only if the writer names it, the scene requires it and the agent asks, or the writer asks mid-scene.
Depth capped: Dependencies are followed one level deep. Excess context is treated as noise.
Per-task bundles: Planning at chapter level loads arcs, state and conflicts only, and editing loads only the relevant book's voice section.
6. The Session Lifecycle
A session opens in Claude Code at the repository root. The agent reads the project states and greets the writer, unprompted, with a table of projects, the available actions and the next step. The writer then writes, plans, edits or runs a continuity check, and every finished chapter ends with a prompt to close the session.
Closing a session
The close command runs nine steps and asks for confirmation before every write: it stops if there are unresolved continuity flags, proposes the new state and the new chapter-index row, updates the story structure only if arcs moved, offers a canon update, detects the end of a book, and finally proposes a commit message before committing and pushing. Nothing is applied without approval.
7. Features in Depth
What follows is how each feature feels in a real session. The conversations replay as you scroll, and they are illustrative: the commands, prompts and output formats are the real ones, while the story content is placeholder and not taken from my manuscripts.
Continuity checking: flags, never rewrites
The bundle loads the arcs, the relationships, the rules of the world and the characters present in the scene, then compares the chapter against them. It only raises flags, and the session cannot close while one is unresolved.
Canon updates as a reviewed diff
Closing a session walks through gated steps, and each write needs a yes. The canon is updated as a list of proposed changes that the writer approves or rejects one by one.
Editing without side effects
Editing an old chapter is deliberately isolated. It never touches the project state and never suggests closing the session, so a late fix cannot corrupt the active progress.
Planning at the right granularity
There are no separate commands for planning levels. The bundle reads the phrasing and decides whether it is looking at a chapter, a batch, an arc, a book or a single event.
Multiple books, one universe
A new book versions only the voice, the themes and the plot. The world, the system and the characters stay shared, and existing content is wrapped, never overwritten. A spin-off goes further and declares its parent, so shared characters and world load only when a scene requires them.
Voice as data
Voice lives in files: a versioned style guide per book and a voice node per point-of-view character, plus a list of patterns to eliminate. Writing loads almost nothing by default and pulls a node in only when the scene needs it.
8. Decision Records
Plain files instead of a database or plugin
Files are portable, diffable in git (every session ends in a commit) and readable by both people and any AI. The trade-off is that there is no query engine, so integrity depends on conventions and on the agent following them.
Dependencies declared by the node, not the caller
Bundles stay short and dependencies are not forgotten, because the file that needs a dependency is the one that names it. Retrieval is exact rather than semantic, and capped at one level.
Human in the loop
Agents read freely, propose changes as structured diffs and never apply them without approval. There are no parallel writes and no shared memory between agents.
Model-agnostic in principle, Claude Code in practice
Any AI with file access can navigate the structure, while the shipped orchestration (the auto-read instructions and the slash commands) targets Claude Code.
9. How It Evolved
Most of the design came from friction, and the commit history shows it: the always-loaded instruction file was slimmed down to a minimal router, node loading moved from preloading to on-demand, multi-project support arrived as a refactor with the parent-project pattern, and a structural map of book, arc and chapter was added when the index and the arcs drifted apart. Seventy-five commits in about seven weeks, part of them produced through parallel Claude Code worktrees.
170+
files tracked
2
projects
10
bundle files
5
slash commands
115+
chapters tracked
Key Takeaways
- Structure beats memory: Making the dependencies explicit worked better than hoping the model would remember them.
- What not to load is the real design: Every rule that keeps context small also removed a source of contradictions.
- Confirmation gates build trust: Because nothing is applied without approval, the canon can be trusted after months of sessions.
- Conventions need care: Without a query engine, documentation can drift from behaviour, as my own notes show, so keeping the docs in sync is part of the work.
Next steps: Measure the effect on consistency more rigorously, for example by counting the canon flags caught per chapter, and reconcile the remaining documentation drift.