Checkpoints

A Checkpoint is a named marker in the workspace's document change log — a bookmark that says “this is where document history stood at that moment.” If you know git, it is deliberately like a git tag: a lightweight label on a cursor, not a copy of your documents and not a snapshot of every workspace resource. Create one before a risky document cleanup or rewrite so a restore client can project the work needed to return tracked documents to that point.

Requirements

Checkpoints share Note History's gate: cloud sync must be enabled and unlocked. Creating or deleting a checkpoint, or restoring documents to one, additionally requires an active subscription; listing and viewing checkpoints does not.

Opening Checkpoints

• Command Palette — search "Checkpoints" (Mod+K). Always listed (it is workspace-level, not tied to the active frame); disabled with a hint when sync isn't ready.

• Keyboard shortcut — unbound by default; assign one in Settings → Shortcuts → History.

• Toolbar icon — a tag icon in the app's global top toolbar. Hidden entirely (not just disabled) when the readiness gate is off, so it never shows up as a dead button.

Layout

Checkpoints opens as a full-viewport surface with a vertical timeline on the left (dot-and-line, newest first) and a detail pane on the right.

The very top entry is always the current state — a pseudo-entry, not an actual checkpoint, representing "everything as it is right now." Selecting it shows a plain confirmation that you're looking at the live workspace rather than a saved point.

Creating a checkpoint

Use + Create checkpoint at the top of the timeline, type a label, and confirm (leave it blank to fall back to a generic default label). The label is end-to-end encrypted the same way note content is — the server only ever stores an encrypted envelope.

Reviewing a checkpoint

Selecting a checkpoint shows:

• Changed files — every path that changed between this checkpoint and the previous one (or the beginning of the workspace's history, for the oldest checkpoint), each tagged Created, Changed, or Deleted with a change count.

• A before/after diff peek — click a changed file to lazily load and expand a diff between its state at this checkpoint and its current state, without leaving the list.

Deleting a checkpoint

The trash icon in the detail header removes the marker (with a confirmation step). This only removes the bookmark itself — like git tag -d — the underlying save history and content it pointed at are untouched and stay reachable through Note History or any other checkpoint.

Restoring workspace documents

Restore to this point, in the footer, brings the supported document paths back to how they looked at the selected checkpoint. It is client-driven; the server has no one-call checkpoint-restore endpoint:

1. A preview lists every file the restore would touch, tagged Restore or Delete, with a plain-language summary and file count. If nothing would change, it says so instead of offering to restore.

2. Confirming re-checks for changes made by another device since the preview was fetched. If something moved, the preview refreshes and shows you the updated plan before asking again — a restore never silently applies a stale plan.

3. Before touching anything, the app automatically creates a safety checkpoint of the current state, so the point you're restoring from is never lost either.

4. Documents are then restored one by one with a progress indicator. If a step fails partway through (for example, a network drop), the client stops and reports progress; a retry obtains fresh state before continuing.

Because a safety checkpoint is created first, a completed restore can be reversed for the document paths covered by the manifest: restore those documents again to the safety checkpoint made immediately beforehand. Assets and unsupported document-shaped resources remain outside that promise. If the first restore stopped partway, recovery also needs a freshly reconciled plan; checkpoint rollback is not atomic.

What restore covers

Checkpoint projections use the document change log. The app's restore UI can safely route notes (Inbox/Archives and other Note Tray directories), messages, and pin content — the same content Note History versions. If an actionable manifest entry is a path the UI cannot safely route (settings, workspace configuration, a root file, trash, or another unknown namespace), the entire restore is blocked before any step and the paths are listed.

Assets are a separate encrypted resource family and are never part of a checkpoint, summary, restore manifest, version history, or document change cursor. Restoring documents also does not rewrite ../assets/... references.

Local agent undo boundary

The Local Agent Authoring flow uses the MCP integration tool begin_authoring_session(label) to create a document checkpoint before a local coding agent starts writing. Its companion get_checkpoint_restore_manifest(checkpointId) returns the actionable work order and expectedHeadCursor; it does not execute a rollback.

A local rollback client must page explicit what_changed(afterCursor: 0) calls until hasMore is false, passing each page's changeCursor into the next call, then compare that final fresh cursor with expectedHeadCursor. Only then does it apply normal version-guarded restore and delete operations. A move-back is represented by an old-path restore and new-path delete sharing one stable fileId. The process is not atomic: stop on the first conflict and report possible partial progress. Treat HISTORY_COMPACTED as an explicit failure, not an empty result.

The official authoring policy treats settings, frameset state, and pins as read-only even though they are document-shaped storage. An agent must not use a checkpoint manifest to bypass that policy.

Current limitations

• Checkpoints are manual-only in this release — there is no scheduled/automatic checkpoint yet.

• There is no workspace clone from a checkpoint, or browser for the history of a note that has since been deleted — restoring through a delete works (deleted content is retained and restorable), but there is no dedicated UI to browse deleted notes yet.

• The sync server runs a nightly retention pass over version history: every version younger than 24 hours is kept, then older history is thinned to hourly, daily, and weekly representatives. Current versions and every checkpoint-pinned version are always kept. Version rows selected for pruning hand off their now-unreferenced encrypted R2 blobs to a queue; the reclaimer waits another 24 hours before deletion and rechecks references at dequeue time. This does not prune checkpoints.

• Change-log compaction stays disabled while checkpoints exist. Retention never deletes changes rows or advances compaction_floor, so HISTORY_COMPACTED behavior and complete checkpoint projections are unaffected; document history growth remains an explicit tradeoff.

Closing

Press Escape, or use the × button in the header.