Core Concepts

Context Time Machine

Git-anchored, Ed25519-signed snapshots of the whole context layer. Rewind to any commit, see exactly what the model saw and why, then reproduce, resume or share that state — verifiable offline. The savings receipt, now on a time axis.

LeanCTX already decides what your agent reads, remembers what it learns, guards what it touches and proves what it saves. The Context Time Machine adds the fifth verb — replays. A snapshot captures a git-anchored, signed view of the context layer at one moment, so you can rewind to any commit, see exactly what the model saw and why it acted, then reproduce, resume or share that exact state.

It is built on the primitives you already trust — git, the distilled IR, the session and the signed savings ledger — so replay inherits the same determinism and the same offline-verifiable provenance. Nothing leaves your machine unless you explicitly publish a snapshot.

What a snapshot captures

A snapshot (CONTEXT_SNAPSHOT_V1) bundles distilled slices of the live context layer into one content-addressed, signed JSON artifact:

Slice	What it holds	Why it matters on replay
Git anchor	Commit SHA + dirty flag at capture time	Pins the snapshot to a point in your history
IR digest	The distilled view the model actually saw	Replays what entered the window, not raw files
Decisions & knowledge	Session decisions + project facts in play	Replays why it acted
Ledger / ROI slice	Token savings booked up to that point	Carries the receipt — savings with the Φ-score
Session state	Current task, touched files, findings	Lets you resume from exactly there
Signature	Ed25519 over a content-addressed `snapshot_id`	Tamper-evident, offline-verifiable provenance

The snapshot_id is a BLAKE3 hash of the body, so the id is the content; the snapshot is signed with your machine's persistent Ed25519 key — the same identity that signs the savings ledger and agent handoffs. Change a single byte and the id changes and the signature breaks.

The `snapshot` commands

Command	What it does	Leaves your machine?
`lean-ctx snapshot create`	Captures the current context state, git-anchored + signed, into the append-only timeline	No
`lean-ctx snapshot list`	The timeline, newest first (`--json` for scripts and the dashboard)	No
`lean-ctx snapshot show <id>`	The full distilled state behind one snapshot	No
`lean-ctx snapshot verify <id>`	Checks the content id + Ed25519 signature (works offline)	No
`lean-ctx snapshot restore <id>`	Merges the snapshot's session back into your live session (`--git` also checks out the anchored commit)	No
`lean-ctx snapshot publish <id>`	Writes a single signed, shareable file (`--out` to choose the path)	Only the file you choose to share
`lean-ctx snapshot import <file>`	Verifies a shared snapshot, then adds it to your timeline (idempotent)	No (runs on any machine)

Capture — anchor the moment

A snapshot is cheap and side-effect-free: it reads the live context layer and appends one signed JSON artifact to an append-only timeline. Take one before a risky refactor, at the end of a session, or on every commit via a hook.

$ lean-ctx snapshot create
Snapshot created
  id:     9f2c4b…e1a7
  commit: 3a8f12c (clean)
  slices: ir · decisions · knowledge · ledger · session
  signed: 7b1e90…c4d2 ✓

Replay — rewind to any state

The timeline is the spine. List it, then open any entry to see exactly what the model saw at that commit — the IR, the decisions and the ledger slice, with the token-ROI for that state.

$ lean-ctx snapshot list
TIMELINE                                    commit     saved      signed
9f2c4b…  Resume the timeline work           3a8f12c    +812K tok   ✓
7d1a02…  Wire the share verb                2f9e004    +640K tok   ✓
1c44e9…  First pass on restore              9a17bb3    +301K tok   ✓

In the cockpit, the same data drives the Replay view: scrub the timeline and inspect any point. Replay answers what did the model see, and why did it decide that? — long after the chat is gone. See the Observatory for the dashboard surface.

Verify — trust by construction

Any snapshot, local or received, checks out offline with no network and no LeanCTX history. This is the same append-only, signed model as the savings ledger, applied to temporal state.

$ lean-ctx snapshot verify 9f2c4b
Snapshot 9f2c4b…e1a7 — VALID
  content id:  matches body (BLAKE3)
  signature:   7b1e90…c4d2 ✓
  git anchor:  3a8f12c

Tamper with anything — flip the dirty flag, rewrite a decision, swap the key — and verification fails loudly.

Restore & resume — pick up where it stood

Restoring merges the snapshot's session back into your live session, so the agent resumes with the task, decisions and touched files it had then. With --git, it also returns your working tree to the anchored commit.

$ lean-ctx snapshot restore 9f2c4b          # restore the session slice only
$ lean-ctx snapshot restore 9f2c4b --git    # also check out the anchored commit

--git refuses to run on a dirty tree — it never silently discards uncommitted work. Restore is how a "rewind" becomes a real continuation: replay to understand, then resume from that exact state.

A snapshot is portable. publish produces a single signed file; anyone can import it into their own timeline and verify the provenance — without your repo, your prompts or your code.

$ lean-ctx snapshot publish 9f2c4b --out ./review.ctxsnapshot.json
# … on a teammate's machine …
$ lean-ctx snapshot import ./review.ctxsnapshot.json
Imported 9f2c4b…e1a7 — signature VALID, added to timeline

Import is idempotent and refuses tampered files. This is how a reproduction case, a "here's what the agent saw when it broke" report, or a teaching example travels between machines — as evidence, not a screenshot. It complements context packages: a package ships the inputs, a snapshot ships the state at a point in time.

The trust model

A verified snapshot answers two independent questions at once:

Integrity — the body has not changed by a single byte since signing. The content-addressed snapshot_id (BLAKE3) and the Ed25519 signature both cover the canonical payload.
Origin — it was produced by the holder of a specific keypair. Pair that public key with your name once and every snapshot from it is attributable to you.

When to reach for it

Before a risky change. snapshot create — you can always rewind.
"Why did it do that?" snapshot show (or the Replay view) at the relevant commit.
Reproduce a result. snapshot restore --git puts the tree and session back exactly.
Resume yesterday's work. snapshot restore reloads the session without touching git.
Send a teammate the exact state. snapshot publish; they import and verify.