History and saved versions
Time travel
Click the Time travel history icon beside the title to open a near-full-screen, resizable viewer. Use Play/Pause, previous/next step, or the ticked slider to browse retained versions. Each tick selects one recorded edit; the slider snaps to those ticks.
The viewer is view only. It captures the checkpoint and retained edits when opened, renders them separately, and does not replace the live editor or publish changes. Close and reopen it to include newer edits. There is no restore action.
When you step or play through versions, added rendered text briefly glows green. Removed text appears in red with a strikethrough, fades, then disappears. Colors compare the view you left with the view you entered: stepping backward reverses which text appears and disappears. A jump compares the two selected views rather than replaying every intermediate edit. Formatting-only changes update normally.
Pausing playback freezes an active highlight; resuming continues it. Stepping or scrubbing cancels the old transition so ghosts never pile up. Faster playback uses shorter fades. Reduced-motion preferences use static highlights that clear without fading. Very large comparisons display the version without highlights to keep navigation responsive. Deleted ghosts are presentation-only, excluded from accessibility output, selection, and the code-copy action. They never alter saved text or the live editor. Scroll position stays under your control.
History starts at the retained checkpoint: compaction can remove older versions. This is not a complete archive, and playback is not a recovery tool for an unsent local draft. Download a held draft through the sync dropdown instead.
Saved versions
The version tag in the toolbar opens a compact revision graph. The right sidebar
uses one toolbar toggle for Comments, Table of contents, and History.
Choose History (the GitGraph icon) to see the graph there. Contents is the
default; the memo remembers your chosen sidebar. Working Draft sits directly above its base version, with an edit
count and a GitCommitVertical save icon on that row. A small solid dot marks the draft endpoint; saved-version waypoints are hollow. Choose the icon, enter an optional title/tag
and summary, then save. Memos continues to autosave while you work; metadata
does not appear in the memo body. New milestones receive stable numbers such
as v3, independent of their titles. Numbers can have gaps after failed saves.
Saved versions show their parent connections, including forks from a shared base. The save form defaults to your draft's base; choose another Base version to record a different ancestry. This records the relationship without replacing or merging the live draft. The working draft follows the newest saved version when history refreshes, including versions saved by another collaborator, so it stays at the top and its edit count uses the latest checkpoint. This changes only the history display and default save parent, not the memo text or saved ancestry. Older versions without recorded parents remain unconnected.
The current edit marker shows its one-based index and total within that version interval (for example, Edit 439 of 443), including when selected from a grouped tick. Historical previews use the title-row status slot: e439, preview for a saved version, or e430–439 for a selected range. Version tags use a lowercase v and are hidden while an intermediate edit or range is displayed. Hovering the preview label turns it red with a strikethrough; clicking it returns to the working draft. The chevron opens history. The full preview label remains in the tooltip. The history dropdown fits its content, capped at the remaining viewport height with a 16px bottom gap; longer timelines scroll inside it. The sidebar and dropdown share the editor selection, including resets and selected ranges. The magnifier appears above the selected marker and displays its own red edit-index line on hover. Only an explicitly selected edit or range creates a persistent marker. The lens follows the pointer immediately; document and range previews settle after a short pause, reusing a bounded cache of recent historical text.
Each small dot represents one retained intermediate edit; all retained edits are shown. Hover or keyboard-focus a dot to preview its exact text directly in the main body. The historical preview is read-only and isolated from live sync; editor controls and saving are disabled while it is displayed. Leaving the dot restores the prior selection, while clicking the dot keeps that edit selected. There is no separate edit list. The magnifier's right edge stays fixed against the timeline panel as the pointer moves horizontally. A larger magnified region spreads nearby dots apart for selection. Scrolling previews nearby snapshots; clicking version text or activating it with the keyboard selects that revision. Leaving a transient preview restores the last selection. Back to draft returns to the still-mounted live editor. The sidebar's Contents view follows Dockit's On this page format: compact heading links, monospace subheadings, an accent-colored active heading, and a curved progress rail. Section chevrons collapse or expand their child headings; clicking heading text jumps directly to that section. The separate minimap column is omitted.
Each saved version retains the exact server-confirmed text, author and date, plus the available collaboration checkpoint and journal. It remains readable after live history is compacted or a room is recreated. Compacted edits that were already missing at save time cannot be recovered; partial counts say retained edits. In a saved-version preview, Compare / link opens side-by-side comparison and Copy version link. Saving never replaces the current memo. Tags may repeat; the version ID is unique and immutable. Summaries are written by the person saving the version; automatic AI drafting is not included.
Saved history requires edit access, including accepted write-share access. A public memo or read-only share does not expose earlier text that may have been removed. Version links do not grant access. If the memo changes or is still syncing while you save, review the current text and retry; no version is created from a mismatched browser/server state.
Saving safely across a connection failure
A failed or lost save response does not prove that a version was not saved. Refresh History and inspect its ID, author, time and content before saving again. An acknowledged edit to the live draft is separate from saving a named version; do not resend that edit to recover a failed version save.
Catalog readers and the default catalog writer are included in the verified API release. Strict runtime verification and read-only version metadata/header checks are separate from accepting a real version save; no production save was performed for this release verification. Existing saves without an idempotency header and existing version links retain their current workflow.
The serving implementation routes new saves through the publication catalog by default, without changing the save endpoint, request fields, CLI commands or existing version IDs and history. It rechecks current edit authority and the Memo's ownership binding before publication. Runtime verification is not a live-save receipt and does not activate durable attachment purge or ownership transfer.
Do not use a version-save POST to test readiness. An older API may ignore
Idempotency-Key and create an ordinary version. Only a verified catalog-reader
release with its writer still disabled returns
503 version_publication_unavailable without saving for a keyed request. Do not
adopt the header for saving or retries until the matching writer release is
separately verified; a successful POST alone proves neither support nor
idempotency.
On the verified catalog-writer release, API clients may supply a unique
Idempotency-Key (16–128 letters, digits, underscores or hyphens) on
POST /namespaces/:slug/notes/:noteId/versions. Keep that key with the original
hash, tag, summary, parent and optional retained revision. Retry against the same
server and Memo while signed in as the same account; keys are scoped to that
Memo and actor. Another editor must inspect history and must not reuse your key
expecting deduplication. An identical retry
reconciles the original save rather than saving the current draft again; changed
input with the same key is rejected. Only currently authorized editors can
reconcile the save. If the original upload was incomplete and its publication is
aborted, inspect history and deliberately start a new save with a new key. The
server never substitutes newer text for an unavailable original snapshot.
503 version_save_unconfirmed also covers transport or database failures while
reconciling a keyed save. On the verified catalog-writer release, retry only the identical original request with the same key, server, Memo and
account; do not generate a new key or resend the body edit to clear the error.
A published or fully staged matching operation returns its original version.
409 RECOVERY_IN_PROGRESS means another executor is still active;
409 IDEMPOTENCY_CONFLICT means the key was reused with different input.
409 PUBLICATION_ABORTED requires inspecting history before an intentional new
save with a new key. A storage mismatch or network failure does not prove that
nothing was saved. Without an original idempotency key, inspect history before
considering another save; the CLI commands below do not add a key automatically.
This does not enable cross-namespace transfers or change who can read history.
Use the CLI for saved versions
CLI 0.44.1+ supports current-draft checkpoints, version lists, and saved
text reads. Check the installed dl note tag --help, note hist --help,
and note read --help first. note and notes are aliases; the older
notes version group was removed in 0.44.2.
hist lists saved checkpoints, not every autosaved edit. JSON is appropriate
here for parsing IDs, hashes and cursors. Save and read by immutable version ID;
tags can repeat. The CLI does not yet promote a retained revision to a saved
version or read its checkpoint/journal. Use the authenticated API below for
that specific gap, rather than inventing a tag --revision option.
Recover a retained snapshot
Use this workflow when an earlier full draft still has a retained revision but was never saved as a named version. It creates a version on the same Memo; it does not restore the old text into the live draft. An empty version list does not prove old content is gone. Identify the exact memo ID and namespace, locate a known retained revision from earlier read receipts or recovery evidence, and review its full source before saving. Do not guess revisions from content hashes. Without a retained baseline, this endpoint cannot recover compacted edits, deleted Memos, a different Memo's history, or text available only in a screenshot. Preserve any independent backup and report that limitation.
First establish a stable agent identity as described in agent presence,
and reuse it for every live CLI read. Confirm that the selected API deployment
supports historical POST /versions (the October 8, 2026 retained-revision
extension). Older servers can silently discard an unknown revision property.
Even HTTP 201 and matching text are insufficient: the saved revision and
sourceObservedAt must also pass readback verification.
Use the same authenticated remote and token for both CLI and REST. In the
following example, provision DREAMLAKE_API_KEY through your normal secret
mechanism; do not paste it into memos, shell history, or receipts. Explicitly set
DREAMLAKE_REMOTE to the intended HTTPS API, NOTE_NAMESPACE, the stable
NOTE_ID, and OLD_REVISION. Preserve DREAMLAKE_AGENT_ID and
DREAMLAKE_AGENT_NAME from identity setup. Review the pinned source first:
The executable example below uses Python's standard library for the missing
REST operation and the CLI for full source reads. Run it from a private working
directory after reviewing the old draft. It creates recovery-evidence with
owner-only permissions and refuses to overwrite an earlier attempt. It sends
one POST, retains the request and response, and verifies by the returned ID.
Do not remove that directory to work around an uncertain outcome.
Hash the JSON-decoded complete content as UTF-8, preserving Unicode,
trailing newlines, and the empty string. Do not hash a section, annotated
Markdown, HTML, terminal metadata, or text modified by trimming or jq -r.
The source read uses sha256:<digest>; the API requires the raw lowercase
64-character digest. The opaque revision identifies the RTC baseline, not just
its text: two different revisions can have the same hash. sourceObservedAt
is the baseline's observation time, not necessarily the original edit time;
createdAt is when this version was saved. Full source reads need not contain
sourceObservedAt.
If a receipt/readback is missing, malformed, or has the wrong ID, revision,
hash, source time, or text, stop and keep the evidence. Do not declare recovery
complete, remove revision, fall back to saving the live draft, or issue another
POST to test support. If the live text changed during verification, inspect
concurrent edits without overwriting them. Saving a historical version itself
does not write the live body.
Reconcile an uncertain save
A save without an idempotency key creates a distinct version; tags are not idempotency keys. On the verified catalog-writer release, an exact same-key retry may instead reconcile the original version as described above. A timeout, lost connection, unreadable response, generic 5xx, or failure after submission may leave a saved version behind. Do not blindly repeat the POST, including after a failed verification read.
Inspect saved metadata on the same remote, namespace and Memo, starting
with the first page and continuing through nextCursor using --before:
Each page has at most 50 entries. Compare candidates with the retained request:
revision and hash, tag, summary, explicit parent (or null), and submission
time range. Then verify the candidate ID, sourceObservedAt, and full text
against the saved evidence as above. A matching hash with a different revision
is not a match. If a matching version exists, reuse its ID; if several match,
record their IDs and report that the individual request's attribution is
uncertain. Do not create a duplicate to obtain a clearer receipt or delete
versions automatically. Finding no match on a partial page, or immediately
after a timeout, does not prove that the original save failed. Continue read-only
reconciliation; retry only after the outcome is resolved and a new save is an
intentional decision. This unkeyed workflow has no request deduplication guarantee.
For a structured rejection from the compatible server:
409 note_changed: no version was saved by that rejected request. Recheck the retained source/revision/hash; never replace its hash with the live hash.404 revision_not_found: the selected baseline is unavailable. Preserve independent evidence; this is not an empty saved-version list.400, authentication/access failures, or404 parent_not_found: correct the target, access or request before proceeding. History still requires editor access.- The historical route's structured
503 history_unavailableor503 invalid_baselineis a baseline-read failure before saving. Resolve that specific read problem first. A generic 503/5xx is still an unknown outcome; do not infer this pre-save guarantee from HTTP status alone.
This workflow does not archive every future edit, reconstruct already compacted history, or add a rollback UI. Restoring text into the working draft is a separate, explicitly requested edit with its own reviewed current baseline.
Version API
These authenticated endpoints are scoped to /namespaces/:slug/notes/:noteId:
Historical recovery: POST /versions also accepts an optional
revision copied from a retained full source read. With it, the server saves
that memo's immutable retained baseline instead of reading the live draft.
hash must match the retained source; a mismatch returns 409 note_changed,
and an unavailable revision returns 404 revision_not_found. This does not
replace the live body, change its collaboration session, or restore deleted
memos. Editor access is still required. A recovered version's createdAt
records when it was saved; sourceObservedAt records the baseline observation.
New historical saves preserve the exact validated request revision in their
receipt, list entry and immutable readback, including scoped memo-rtc:v1:
references. The retained native RTC envelope, clock and journal stay unchanged.
Older saved versions keep their original native rtc: provenance; they are not
rewritten or upgraded by a read or an idempotent retry. A matching text/hash alone
cannot establish equivalence with another revision. Wrong Memo, room scope or
native snapshot identity is refused even when the text is identical.
Omit revision to retain the existing current-draft consistency check. Do not
retry a failed stale-current save as a historical save without reviewing the
intended retained content. The CLI does not yet expose this extension.
POST /versionsaccepts{hash, revision?, tag?, summary?, parentId?}.hashis the lowercase SHA-256 of the UTF-8 body the user intends to save. The server compares it with the specified retained baseline, or a coherent current read whenrevisionis omitted, and returns409 note_changedon mismatch. Tags are at most 80 characters and summaries at most 2,000 characters. Numeric dotted tags support any number of parts, with an optionalvprefix, such as1.2.03.04.005. The updated history UI uses the dotted tag as its label and preserves leading zeros; immutable IDs and save numbers do not change. A successful201returnsid,tag,summary,hash,createdAt,createdBy,author,number, andparentId. The optional nullableparentIdmust identify a version in this memo; a missing/foreign parent returns404 parent_not_found. On the matching automatic-ancestry backend release, omittingparentIdselects the newest saved causal ancestor proven by the RTC clock in the same room and generation. ExplicitparentId: nullcreates an independent root; an explicit ID preserves that branch choice. No proven ancestor (including legacy snapshots without clocks) leaves the save unlinked. The optionalparentMode: "auto"remains supported; do not combine it withparentId. Saved history is never rewritten. RTC-backed versions also includerevision,clock,editCount, andhistoryComplete. The count measures retained content-edit messages, not keystrokes.GET /versionsreturns{versions, nextCursor}with up to 50 metadata entries, newest first. Send?before=<nextCursor>for older entries.GET /versions/:versionIdreturns the metadata plustext.GET /versions/:versionId/historyreturns the retained{snapshot, journal}for read-only replay, with the same editor access requirement. Legacy versions return{snapshot: null, journal: []}. This is not a content-write endpoint.
The content hash identifies text, not the identity-bearing RTC baseline used
for collaborative patches. Saving a version is a retained snapshot operation,
not a content write. Use note tag, note hist, and note read --version
for ordinary saved-version work. Retained-revision promotion and checkpoint/journal
reads currently require authenticated REST. The current Python facade supports
saved-version listing and reading:
Only read an entry when the page is nonempty; continue with
memo.versions.list(before=page.next_cursor) when a cursor is returned.
A saved version is not a current write baseline. These helpers do not create
versions, promote retained revisions, or provide a complete human edit audit.