The ContextStitch Architecture

1. The Context Window Problem

A context window is both an LLM's working memory and its hard boundary. Modern models support large windows, but no window can hold the full history of a project that grows over days or weeks. The standard workarounds each have failure modes.

Full-context injection — loading the entire codebase into every session — is expensive and still fails to capture implicit decisions that exist only in prior conversation history. A function name chosen deliberately, a pattern explicitly rejected, an architectural constraint discussed but never committed — none of these survive a cold start.

Retrieval-augmented approaches — vector search over codebase and history — solve the retrieval problem but not the synthesis problem. The LLM receives relevant fragments, not a coherent picture of project state. It may retrieve a function that uses an invariant without retrieving the invariant itself.

Stateless operation produces drift: locally correct code that is globally inconsistent with decisions made in earlier sessions. The drift accumulates silently until a debugging session forces a reconciliation that could have been prevented.

2. Core Principles

ContextStitch is built on eight model-agnostic principles derived from the Fablyos verified bookkeeping architecture, which was developed to maintain narrative consistency across long-form interactive fiction sessions — a structurally analogous problem.

3. Architecture

ContextStitch introduces three structured artifacts that persist across sessions and are injected as a prompt prefix at session start.

3.1 The State Ledger

The state ledger lives at .contextstitch/state.yml in the project repository. It captures the information most likely to cause drift when lost: active interfaces and their contracts, established invariants, open decisions, naming conventions, and file responsibilities. It is capped at 150 entries (30 pinned) — small enough to include in every session without meaningful overhead.

The ledger distinguishes settled decisions from open questions. Settled entries carry a "do not re-derive" flag. Open entries are explicitly available for LLM reasoning. This distinction prevents the most common form of drift: re-solving a problem that was already solved, sometimes reaching a different conclusion.

Supersession is handled at write time. When a new entry contradicts an existing one — same subject, opposing state — the old entry is retired and the replacement is recorded. Detection is conservative: it requires matching subject and an opposing predicate, a negation flip, or a changed value on a standing quantity. Each replacement can be rewound.

3.2 The Session Handoff

At the end of each session, ContextStitch generates a handoff document: what changed, what was decided and should be promoted to the ledger, and what remains open. This document runs 300–800 tokens and is the bridge between sessions. Generation is automated — the LLM produces it as the last step of each session using a fixed prompt template — or produced manually. The structure is intentionally simple. No complex schema, no graph traversal, no embedding pipeline.

Ledger entries carry source pointers — which session wrote them, how many sessions ago — allowing a continuity checker to flag potentially stale lines. In long projects, entries older than a configurable threshold are tagged as possibly outdated.

3.3 The Re-entry Contract

The re-entry contract is a prompt template injected at session start. It frames the LLM's role, injects the state ledger and session handoff, and establishes behavioral constraints: respect invariants, flag conflicts before proceeding, treat open decisions as open. The same template produces consistent behavior across Claude, OpenAI-compatible APIs, and local models via Ollama.

Total prefix overhead — ledger plus handoff plus contract — is typically 2,500–4,500 tokens. The elimination of re-derivation loops and drift-induced bugs more than offsets this cost on any project spanning more than two sessions.

4. Project and Topic Hierarchy

Real coding work is not flat. A developer maintains multiple projects simultaneously, and within a project, work is organized into topics — a feature branch, a subsystem, a refactor pass. ContextStitch's storage model reflects this hierarchy directly.

At the top level, a project is a named codebase with its own state ledger, session history, and conventions. Within a project, topics are persistent subcontexts: a topic has its own ledger slice (the entries most relevant to that area of the codebase), its own open decisions, and its own handoff history. When a session begins, the user selects the active project and topic; the re-entry contract is composed from the shared project ledger plus the topic slice.

This structure maps directly to the Fablyos story model — where stories (projects) contain arcs (topics) each with their own beat history — and to the database schema used for session persistence in that system.

5. Derivation from Narrative AI

The ContextStitch architecture is derived from the Fablyos Verified Bookkeeping system, developed to maintain narrative consistency in long-form interactive fiction across context windows that cannot hold the full story history. Fablyos uses a beat verification loop — the writer proposes, a verifier checks for a verbatim quote from the actual story text, and only verified beats enter the ledger — along with a layered facts ledger with supersession and slip-learned line selection.

The translation to coding projects maps narrative categories to code categories: characters become interfaces, world facts become invariants, scene state becomes session handoff, story rules become conventions. The underlying mechanism — propose, verify, persist, inject — is identical. The key adaptation is replacing quote-based evidence (narrative) with artifact-based evidence (code): a function signature, a passing test, a committed file.

Fablyos's slip-learned selection — entries that have previously caught inconsistencies receive higher selection weight, clamped to a 0.6–1.8 multiplier range with a prior of 30 observations — is preserved in ContextStitch's ledger selection algorithm. The system learns which entry types and which specific entries are most predictive of drift in a given codebase.

6. When ContextStitch Applies

ContextStitch is not a universal improvement. The overhead is unjustified for single-session tasks, one-off scripts, and exploratory work where no invariants have been established. The break-even is approximately two sessions on a project with any structural decisions — at that point, the first re-derivation loop or drift-induced bug costs more than the cumulative ledger overhead.

ContextStitch is highest value for projects spanning multiple days, codebases with established architectural constraints, teams where multiple developers use LLM assistance on the same project (a shared ledger eliminates human-LLM convention drift), and any project where an LLM has previously made a decision it must respect in future sessions.

7. Evaluation Status

The core architecture is validated in production in the Fablyos narrative system, where the beat verification loop and layered ledger have been field-tested across many multi-session story runs. Each verification gate in the narrative system was added in response to a specific observed failure — the architecture is empirically derived, not theoretically constructed.

Application to coding projects is in early development. The planned evaluation methodology — an offline replay harness running the same multi-session coding task with and without the harness, measuring re-derivation events and drift-induced bugs per 1,000 lines — does not yet have results. The architectural principles transfer; the coding-specific empirical validation is the open work.

References