Storage Model

Version history uses a keyframe + diff model for storage efficiency.

Directory structure


.versions/
├── context_history.yaml          # Vault-level checkpoint history
└── nodes/
    └── architecture/
        ├── history.yaml          # Version history for this document
        ├── v1.md                 # Keyframe (full snapshot)
        ├── v2.diff               # Diff from v1 → v2
        ├── v3.diff               # Diff from v2 → v3
        └── v4.md                 # Keyframe (full snapshot, every N versions)

history.yaml

Each document’s version history:


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

Reconstruction

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


ctx reconstruct nodes/architecture 3

Keyframe files are self-contained and safe to read without the diff chain.