‹ 2/2 ›
+ under a turn steps between the takes it has.
Engineering guide
An AI Dungeon-style storytelling engine. The chat loop is the boring part β - the interesting parts are the token-budget allocator, the world-state referee, and the - memory system that decides what the model is allowed to remember.
+ the interesting parts are the token-budget allocator, the world-state referee, the story tree + that lets a turn have more than one answer, and the memory system that decides what the model is + allowed to remember.Three things make it more than a chat wrapper:
+Four things make it more than a chat wrapper:
hp,
trust, day. The model proposes changes each turn; a Python engine
decides what actually sticks.backend/app/routers/adventures.py.
Snapshots happen before the model call, not after. state_before
-and world_state_before are stapled onto the action before the hooks and the
-delta run. Thatβs the entire mechanism behind undo and retry actually rewinding rather than just
-deleting text.
Every node records the state it leaves behind. state_after and
+world_state_after are stapled onto the action once its hooks and its delta have run,
+so a node carries the scoreboard and the RPG stats as they stood when that turn finished. Rewinding
+to before a turn is then a read of the node in front of it β the same move as switching to
+another branch. One mechanism, and it is why undo, retry and a branch switch all put the numbers
+back rather than only rewriting text.
Only settled actions get summarized. The newest action is always held -back one turn. Only the last action can be retried β so if a memory summarized the newest action -and the player then retried it, that memory would describe narration that no longer exists, and -because its cursor has already advanced it would never be regenerated. Holding one action back -costs a turn of latency and makes that state unreachable.
+A memory hangs off the node whose block it ends on. Not off the adventure, and
+not off a position in a list of actions β off a (branch_id, depth) coordinate.
+That makes βwhich memories described this turn?β an indexed lookup rather than a scan for rows whose
+covered range has fallen off the end of the story, and it is what makes memories inherit correctly
+across a fork: the ones above the fork point already sit on ancestors both lines read.
It is also the repair. When a turnβs text is replaced or removed β a retry, an undo, a deleted
+action β forget_node withdraws the memory hanging off that coordinate and
+rewinds both marks to just before the stretch it covered, so that ground is summarized again from
+what the story now says. An earlier version instead held the newest action back a turn so it could
+never be summarized before it stopped being retryable; that is no longer needed, because the repair
+exists whether or not the invalidation happens at the tip.
Cursors only advance on success. Every AI call here is best-effort. If summarization fails, the function returns and the cursor is unchanged, so the same block is @@ -883,10 +895,12 @@ ugly fast.
User
ββ Scenario (the template) ββ stat_schema, prompt, memory, author's note
β ββ StoryCard, Script
- ββ Adventure (the playthrough) ββ world_state, script_state, cursors
- ββ Action (one story entry) ββ text, context_snapshot, variants, state_before
+ ββ Adventure (the playthrough) ββ world_state, script_state, head_branch_id/head_depth
+ ββ Branch (one line of it) ββ parent_branch_id, fork_depth, lineage, name
+ ββ Action (one node) ββ branch_id, depth, parent_id, live,
+ β text, context_snapshot, state_after
ββ StoryCard (its own copy)
- ββ Memory (text, embedding, source_start/end, use_count)
+ ββ Memory (text, embedding, branch_id, depth, use_count)
ββ AdventureScriptThe one decision that shapes everything: template vs instance. A scenario @@ -897,75 +911,266 @@ flow for when you do want that, which diffs the two and shows what woul
Same reasoning as instantiating a class: shared definition, independent state.
-The subtlest thing in the codebase.
+The largest structural change the project has had, and the one with the most reasoning behind +it.
-There are two ways to identify an action:
+The story used to be a list, and a mutable one. Retry rewrote the last entry in place; undo and +delete removed entries from the middle. Everything derived from the story β the memories, the +running summary, the two marks saying how far each had got β was indexed by position in that +list, and a position means something different after anything in front of it is deleted.
+ +That single fact produced a family of bugs that all looked different:
Action.index β a stable number stored on the row. Gaps appear
- when actions are deleted.The memory cursors are positions. Memory.source_start and
-source_end are Action.index values.
The two spaces are identical until the first deletion, and diverge forever after. Mixing them - means summarization silently skips or duplicates blocks β no crash, no error, just a memory - describing the wrong turns.
+ The pattern +Each was fixed where it was found. The shape only becomes visible when you line them up: + they are all the same bug, and it is that the story is a list nobody may reorder.
Three things hold it together:
+position_of_index() is the explicit translation between the spaces, and every
- crossing goes through it.note_action_removed() is called before a delete: if the removed action
- sat before a cursor, the cursor decrements, so an unsummarized action canβt slide into the
- βalready coveredβ range and be skipped forever.trim(), because SQLiteβs and Postgresβ single-argument trim()
- only strips spaces while Pythonβs .strip() also drops newlines. An action of nothing
- but a newline would otherwise count as story text in one and not the other, and every cursor
- after it would be off by one.Make the story a tree and none of them are reachable. Every action is a node
+with a branch_id and a depth. A branch is one line
+through the tree: it holds the nodes played on it and borrows everything before its fork
+point from its ancestors. Nothing is ever copied, and β apart from an explicit delete β nothing is
+ever removed.
branches(id, adventure_id, parent_branch_id, fork_depth, lineage, name)
+actions(id, adventure_id, branch_id, depth, parent_id, live, text, β¦, state_after)
+memories(β¦, branch_id, depth)
+adventures(β¦, head_branch_id, head_depth)depth is a position along a path, not a global turn number:
+A4 and B4 are two alternatives, not two turns. Reading branch C, whose
+tip is at depth 7 and which left B at 5, which left A at 3:
SELECT * FROM actions
+WHERE (branch_id = 'C')
+ OR (branch_id = 'B' AND depth <= 5)
+ OR (branch_id = 'A' AND depth <= 3)
+ORDER BY depth DESC LIMIT 32β A0 A1 A2 A3 B4 B5 C6 C7.
Why branch_id + depth rather than parent pointers alone.
+Parent pointers are the obvious way to store a tree and the wrong way to read one: reading a story
+would be N round trips up a chain, which throws away the windowed history work (1.2)
+that made a turnβs read cost flat. Depth replaces the old index as the ordering key, so
+the reads keep the shape they already had.
The OR-clause above is not reconstructed per read. It is stored on the branch row as
+lineage β [(C, β), (B, 5), (A, 3)] β computed once when the fork happens,
+from the parentβs lineage plus one entry. One module knows how to turn it into a query, which is
+deliberate: one forgotten clause shows the wrong story and reports nothing.
Two properties of the shape do the real work:
+ +depth DESC reads entry 0βs nodes, then entry 1βs,
+ then entry 2βs β which lets a tail read use the newest few entries and stop.None of the above is what the screen shows. In the playerβs words:
+ +++ +Any turn can gain another take. On an AI turn that means regenerate; on your + own message it means type something else. Stepping between takes with
+βΉ 2/4 βΊis free + β the story below simply empties, because that take has no children yet. A branch is + created when you write below a take that is not the live one, never before.
That rule collapses two operations into one and deletes a distinction from the UI. The first +version of this screen had a chip that switched at the tip and only previewed +above it, with a second button to take that line β one control whose meaning depended on where the +reader was standing. The rule above replaced it with a pager that only ever steps, a fork button on +every turn, and no tip-versus-past distinction at all. The distinction survives in the +implementation, where it decides whether a write needs a branch: at the tip the attempts are still +leaves nobody has built on, so taking one is a switch and no branch is created.
+ +The load-bearing detail, and the one that isnβt obvious. The natural way to find βthe other +takes of this turnβ is by coordinate β same branch, same depth. It is wrong in both directions:
+ +B ββ C C1 C2 <- three takes, one parent (B)
+ β βββ D1' D2' <- two takes, parent C2
+ βββ D1 D2 D3 <- three takes, parent C1Standing on the C2 path at that depth must read 2/2, not 5. Coordinate
+grouping gets that one right by accident, because writing under a non-live take forks and the two
+sets land on different branches. It gets C wrong: once C has been forked onto a branch
+of its own it is alone at its coordinate and reads 1/1, having lost C1 and C2 from a
+pager that must still say 1/3.
So a node carries parent_id, read for nothing but this. The alternative β making a
+branchβs fork point a node rather than a depth, so a promoted take never moves β was
+rejected: the whole point of lineage is that a read is an OR-clause per branch instead
+of a walk up parent pointers, and re-pointing the fork at a node changes path resolution itself,
+dragging in the cursors, memory depths and both bundle formats. parent_id is one
+indexed lookup, never a walk, and nothing about how a path resolves changes.
The two marks β how far the memory bank has got, how far the summary has got β used to be
+counts. A count is a position in a list, and every rule about sliding them, rewinding them and
+translating between positions and Action.index existed to patch up the fact that the
+list moves.
A cursor is now an anchor: (branch_id, depth), the node up to and
+including which the work is done. Deleting an action doesnβt move it, because a depth is a
+coordinate along a path rather than a slot in a list. βWhat is not covered yetβ becomes a question
+about the story instead of about a list index, and it answers correctly whatever has been deleted
+in front of it. The branch half is what makes it survive forking: a depth alone is ambiguous once
+two branches both have a node 41.
position_of_index, note_action_removed,
+settled_story_actions and the cursor-rewind machinery were deleted,
+not left unused.
Generalise the rule and a lot falls out: anything derived hangs off the node that produced +it. A memory covering depths 37β42 hangs off that branchβs node 42 and is invisible to any path +that doesnβt run through it. Shared ancestors are therefore shared automatically, so a fork +needs nothing recreated β the memories above the fork point are already on the ancestors +both lines read.
+ +The memory sitting at the forked coordinate. The first cut moved it onto the new + branch and re-anchored the marks naming it. Both are wrong for the same reason: that memory + describes whichever attempt was live at that coordinate, which is the one staying on the parent.
+The right answer needs no code. The lineage caps the parent one depth short of the fork, so + the memory is simply out of range from the new branch β invisible to both the retrieval clause and + the anchor read. The new line summarizes that ground again, from the text it actually tells.
+Hand-written memories obey the same rule. One used to carry a NULL depth, described as βbelongs +to the adventure rather than to a pathβ β which sounds harmless and is not: a NULL is a coordinate +no fork can cap, so a note typed on one line followed the reader onto branches whose events it never +described. They are anchored at the head instead: the story you were reading when you wrote +it.
+ +Nothing is ever auto-pruned. That is the guarantee the whole design rests on, and it is also why +branch management couldnβt be a nice-to-have: without a way to delete a line, storage grows without +limit.
+ +The delete rule has two halves and the second is easy to miss. Refusing to delete the line being
+read is obvious. The other half is refusing any line it was forked from β
+parent_branch_id cascades, so deleting an ancestor takes the head with it and leaves
+head_branch_id pointing at a row that is gone. One membership test against the headβs
+own lineage covers both, because a lineage already names itself and every branch it borrows from.
+The server is the authority; the client computes the same set only so a button can say so before it
+is pressed.
There is no feature flag. A linear story is a tree with one branch, so the +intermediate states werenβt half-migrated β they were the same product with a superset schema +underneath, which made βexisting adventures are unaffectedβ a literal, testable pass condition at +every step. A flag would have bought two live code paths through the context builder, the memory +bank, undo and retry at once.
+ +The legacy columns (index, variants, variant_index, the
+two *_before snapshots) were kept unread for a release rather than dropped with the
+migration that stopped using them, so that redeploying the previous build is still a way out.
+Dropping columns is the one step that isnβt.
On Postgres a migration that rewrites every row of actions roughly doubles the
+ table, and only VACUUM FULL gives it back β 79 MB reclaimed in 5.5 s on one occasion.
+ But bloat scales with the heap, and context_snapshot is 94% of this
+ table and lives out of line, so a migration touching only small columns reuses the existing TOAST
+ pointer and costs a tenth of that.
Read the sizes from sum(octet_length(col)) per column, not from
+ n_live_tup β that one is a stale estimate in exactly the direction that makes bloat
+ look smaller.
Most implementations of undo delete the last message. Thatβs wrong here, because a turn mutates three things: the text, the scripting scoreboard, and the RPG stats.
-The mechanism: every action carries state_before and
-world_state_before β deep copies taken before the turnβs hooks ran. Undo restores from
-them. Retry rolls back to them, then regenerates.
The mechanism: every node carries state_after and
+world_state_after β deep copies of what the adventure looked like once that turn had
+played. Rewinding to before a turn is a read of the node in front of it, so undo, retry and a branch
+switch are the same restore. The cooldown clock comes along for free: it lives inside the world
+state, so each line of the story carries its own without anything having to know there is one.
Retry keeps every attempt. Instead of deleting and replacing, the row survives
-and each attempt is appended to Action.variants; variant_index names the
-live one. The UI shows βΉ 2/3 βΊ and you can page back to a discarded take. A variant
-stores only what differs between attempts β the narration, its reasoning trace, and the state it
-produced β never the assembled prompt, which is identical across attempts of the same turn and is
-by far the biggest thing in the snapshot.
Nothing a retry replaces is thrown away. The old attempt stays as another
+take of that turn β a sibling node at the same coordinate, live false β and the
+pager steps between them. Which is to say retry isnβt a special case: it is the tree, with the branch
+not yet created (2.2).
Three details that are easy to get wrong:
+Four details that are easy to get wrong:
delete_turn used to mean βevery take at this coordinateβ. Once a
+ take can be forked onto a branch of its own the group spans branches, and undo reached across and
+ deleted a take belonging to a line nobody asked about. Anything that reads a take group and then
+ writes has to say whether it means the turn or the coordinate.try/finally: if it ends without saving β provider error, empty reply, a script
- stop, or the browser hanging up β the previous variant is put back in charge.
- Otherwise the state on the server drifts from the text still on the userβs screen.stop, or the browser hanging up β the previous take is put back in charge. Otherwise
+ the state on the server drifts from the text still on the userβs screen.
Thereβs a companion denormalization for the same reason: variants is deferred, so
-variant_count exists as its own column to answer βhow many attempts?β without fetching
-them. One function is the only thing allowed to write variants, precisely so the two
-canβt drift and the pager canβt lie.
Thereβs a companion denormalization for the same reason: the pager has to know how many takes a
+turn has without fetching any of them, so variant_index and variant_count
+are cached on the row and refreshed by exactly one function, precisely so they canβt drift and the
+pager canβt lie. variant_count is 0 rather than 1 for a turn nobody retried, because
+the question it answers is βis there anything to page through?β
No Alembic. An append-only list of (version, SQL) pairs, with the current version
-stored in SQLiteβs PRAGMA user_version or a one-row table on Postgres. 37 versions so
+stored in SQLiteβs PRAGMA user_version or a one-row table on Postgres. 64 versions so
far.
Action has no UniqueConstraint('adventure_id', 'index'); index
- allocation is ad-hoc per writer, and a database constraint would make the turn-lock race
- impossible rather than merely fixed.index, variants,
+ variant_index, and the two *_before snapshots) are still on
+ actions, unread, kept for one release so redeploying the previous build remains a way
+ out. Dropping them is a migration that rewrites every row, so it owes a
+ VACUUM FULL actions; after it.
‹ 2/2 ›
+ under a turn steps between the takes it has.
Three things a plain "talk to a model" app doesn't do.
+Four things a plain "talk to a model" app doesn't do.
Any turn can hold more than one take. Stepping between them is free β the story below simply + empties, and the server is told nothing. Writing below a take that isn't the live one is what makes a + branch, and a branch stores no turns of its own: it records where it left its parent and borrows + everything above that. Twenty forks cost 1.007Γ the page load of the same story flat. Switch lines and + the world state, the script scoreboard and the cooldown clocks all come back to what that line left.
+
+ A scenario declares stats, flags, milestones and a named cast. Each turn the model appends the changes @@ -192,7 +203,7 @@ β onInput script modifier β assemble context: [narrator prompt] + [world state + stat guide] + [AI instructions] + [plot essentials] + [story summary] + [retrieved memories] - + [triggered story cards] + [story history, token-budgeted] + + [triggered story cards] + [history along this branch, token-budgeted] + [author's note] + [player action] β onModelContext script modifier β snapshot context (Insights) @@ -219,8 +230,8 @@