Journey: Context Time Machine

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 is a git-anchored, Ed25519-signed capture of the whole context layer at one moment: the distilled IR the model saw, the decisions and knowledge in play, the savings-ledger slice and the live session. Rewind to any commit, see exactly what the model saw and why it acted, then reproduce, resume or share that exact state. Same trust model as the savings receipt — now on a time axis.

What a snapshot captures

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	The 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

Every snapshot is content-addressed (BLAKE3) and signed with your machine’s persistent key — the same key that signs the savings ledger. Editing any byte of the body changes the id and breaks the signature.

1. Capture — anchor the moment

lean-ctx snapshot create        # capture the current context state, git-anchored + signed

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

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.

2. 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:

lean-ctx snapshot list          # the timeline, newest first
lean-ctx snapshot list --json   # machine-readable, for scripts and the dashboard
lean-ctx snapshot show 9f2c4b   # the full distilled state behind one snapshot

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, inspect the IR, decisions and ledger slice for any point, and read off the token-ROI for that state. Replay answers what did the model see, and why did it decide that? — long after the chat is gone.

3. Verify — trust by construction

Any snapshot, local or received, checks out offline with no network and no LeanCTX history:

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. This is the same append-only, signed model as the savings ledger, applied to temporal state.

4. 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.

5. Share & publish — hand someone the 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   # signed, shareable
# … on a teammate's machine …
lean-ctx snapshot import ./review.ctxsnapshot.json                 # verifies, then adds to their 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.

When to reach for which verb

• 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 to put the tree and session back exactly.
• Resume yesterday’s work — snapshot restore to reload the session without touching git.
• Send a teammate the exact state — snapshot publish, they snapshot import and verify.

The Time Machine is built on the same primitives as the rest of LeanCTX — git, the IR, the session, the signed ledger — so replay, restore and share inherit the same determinism and the same offline-verifiable trust. The full data model lives in the Context Time Machine concept doc.