Storage Model

Version history uses a keyframe + change-log model for storage efficiency. Keyframes are full snapshots stored as separate vN.md files; every intermediate version is stored as a unified-diff change log for that version.

Directory structure

.versions/
├── context_history.yaml          # Vault-level checkpoint history
└── nodes/
    └── architecture/
        ├── history.yaml          # Version history + per-version diffs
        ├── v1.md                 # Keyframe (full snapshot)
        └── v4.md                 # Keyframe (full snapshot, every N versions)

In the inspected engine build, each intermediate version's unified-diff change log is stored inline in history.yaml as a diff: field on that version's entry — only keyframes are written as separate vN.md files. (Separate suggestion patches — .patch files — are drift suggestions, not version change logs.)

history.yaml

Each document's version history — including the per-version diff:

document_id: nodes/architecture
versions:
  - version: 1
    edited_by: "alice@example.com"
    edited_at: "2026-01-15T10:00:00Z"
    published_at: "2026-01-15T10:00:00Z"
    content_hash: "sha256:a1b2c3..."
    chain_hash: "sha256:d4e5f6..."
    keyframe: true
    note: "Initial version"
  - version: 2
    edited_by: "bob@example.com"
    edited_at: "2026-02-01T14:30:00Z"
    published_at: "2026-02-01T14:30:00Z"
    content_hash: "sha256:g7h8i9..."
    chain_hash: "sha256:j0k1l2..."
    keyframe: false
    diff: |                       # unified diff v1 → v2, stored inline
      Index: v2
      ===================================================================
      --- v1
      +++ v2
      @@ ...

Keyframes are written every keyframe_interval versions (default 10), so no read ever replays more than ~10 diffs from a keyframe.

Version numbering is graft-proof: numbering is fixed at the source (the engine's nextVersion), and the repair-version-chains path re-anchors any already-grafted document onto its live bytes without renumbering, so a node cannot be grafted onto another history. New nodes start at version 1 (ctx add creates v1).

Reconstruction

Any version can be reconstructed by applying change-log diffs forward from the nearest keyframe:

ctx reconstruct nodes/architecture 3

Reconstruction is lazy — it reads the nearest keyframe (≤ the target version) and applies only the diffs needed to reach the requested version, rather than replaying the whole chain. Keyframe files are self-contained and safe to read without the diff chain.

Performance

The published storage model is designed to scale linearly with vault size — the keyframe + per-version diff layout and lazy chain reads keep throughput proportional to document count rather than degrading as history grows. A reference benchmark cited for the current engine is roughly ~108 seconds for 10,000 documents.