<!-- source: https://docs.dreamlake.ai/notes/history @ 0.1.192 b2f973b1 -->
# 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.

```bash
# Keep the same explicit namespace on every command.
dl note tag "$NOTE_ID" reviewed --namespace "$NOTE_NAMESPACE" --summary "Reviewed draft"
dl note hist "$NOTE_ID" --namespace "$NOTE_NAMESPACE" --json
dl note read "$NOTE_ID" --namespace "$NOTE_NAMESPACE" --version "$VERSION_ID" --json
```

`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](/notes/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:

```bash
# These variables must already identify the intended account, Note and baseline.
dl note read "$NOTE_ID" --namespace "$NOTE_NAMESPACE" \
  --view source --at "$OLD_REVISION"
```

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.

```python
import datetime as dt
import hashlib
import json
import os
from pathlib import Path
import re
import subprocess
import urllib.error
import urllib.parse
import urllib.request

required = ("DREAMLAKE_REMOTE", "DREAMLAKE_API_KEY", "NOTE_NAMESPACE",
            "NOTE_ID", "OLD_REVISION", "DREAMLAKE_AGENT_ID", "DREAMLAKE_AGENT_NAME")
for key in required:
    if not os.environ.get(key):
        raise SystemExit(f"Set {key} before running recovery")
remote = os.environ["DREAMLAKE_REMOTE"].rstrip("/")
if urllib.parse.urlsplit(remote).scheme != "https":
    raise SystemExit("Use the intended HTTPS API")
ns, note, revision = (os.environ[k] for k in ("NOTE_NAMESPACE", "NOTE_ID", "OLD_REVISION"))
if not re.fullmatch(r"[a-f0-9]{24}", note):
    raise SystemExit("Use the resolved stable Note ID")
os.umask(0o077)
evidence = Path("recovery-evidence")
evidence.mkdir(mode=0o700)  # Existing evidence stops a second submission.
def keep(name, value):
    with (evidence / name).open("x", encoding="utf-8") as output:
        json.dump(value, output, ensure_ascii=False, indent=2)
def read_source(name, *extra):
    raw = subprocess.check_output([
        "dl", "note", "read", note, "--namespace", ns,
        "--view", "source", "--json", *extra], text=True)
    value = json.loads(raw)
    keep(name, value)
    assert value["note"] == note and isinstance(value["content"], str)
    digest = hashlib.sha256(value["content"].encode("utf-8")).hexdigest()
    assert value["hash"] == "sha256:" + digest
    return value
old = read_source("retained.json", "--at", revision)
assert old["revision"] == revision
before = read_source("live-before.json")
payload = {"revision": revision, "hash": old["hash"][7:], "parentId": None,
           "tag": "Recovered retained draft", "summary": "Reviewed historical source"}
# This recovery intentionally saves an independent root; use a reviewed
# parentId for a branch, or omit parentId for automatic causal ancestry.
keep("request.json", {"remote": remote, "namespace": ns, "note": note,
                     "startedAt": dt.datetime.now(dt.timezone.utc).isoformat(),
                     "payload": payload})
base = remote + "/namespaces/" + urllib.parse.quote(ns, safe="") + "/notes/" + note
class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None
opener = urllib.request.build_opener(NoRedirect)
def api(path, body=None):
    request = urllib.request.Request(base + path,
        data=None if body is None else json.dumps(body).encode("utf-8"),
        headers={"Authorization": "Bearer " + os.environ["DREAMLAKE_API_KEY"],
                 "Content-Type": "application/json"},
        method="GET" if body is None else "POST")
    with opener.open(request, timeout=30) as response:
        return response.status, json.load(response)
try:
    status, saved = api("/versions", payload)
except urllib.error.HTTPError as error:
    keep("post-error.json", {"status": error.code,
                            "body": error.read().decode("utf-8", errors="replace")})
    raise SystemExit("Stopped: inspect post-error.json and the outcome rules below")
except (urllib.error.URLError, TimeoutError, OSError, ValueError):
    raise SystemExit("Outcome unknown: reconcile history before another POST")
keep("post-response.json", {"status": status, "version": saved})
assert status == 201
version_id = saved["id"]
assert re.fullmatch(r"v_[0-9]{13}_[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}", version_id)
def verify_metadata(value):
    assert value["id"] == version_id
    assert value["revision"] == revision and value["hash"] == payload["hash"]
    assert value["tag"] == payload["tag"] and value["summary"] == payload["summary"]
    assert value.get("parentId") == payload.get("parentId")
    observed = dt.datetime.fromisoformat(value["sourceObservedAt"].replace("Z", "+00:00"))
    assert observed.tzinfo is not None
verify_metadata(saved)
verified = json.loads(subprocess.check_output([
    "dl", "note", "read", note, "--namespace", ns,
    "--version", version_id, "--json"], text=True))
keep("verified-version.json", verified)
verify_metadata(verified)
assert verified["sourceObservedAt"] == saved["sourceObservedAt"]
assert verified["text"] == old["content"]
assert hashlib.sha256(verified["text"].encode("utf-8")).hexdigest() == payload["hash"]
after = read_source("live-after.json")
assert before["content"] == after["content"], "Live text changed; inspect concurrent edits"
print("Verified historical version:", version_id)
```

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`:

```bash
dl note hist "$NOTE_ID" --namespace "$NOTE_NAMESPACE" --json
# Repeat for each non-null nextCursor until the attempt's time range is covered.
dl note hist "$NOTE_ID" --namespace "$NOTE_NAMESPACE" --before "$NEXT_CURSOR" --json
# Read each plausible candidate by immutable ID.
dl note read "$NOTE_ID" --namespace "$NOTE_NAMESPACE" --version "$CANDIDATE_ID" --json
```

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, or `404 parent_not_found`: correct the
  target, access or request before proceeding. History still requires editor access.
- The historical route's structured `503 history_unavailable` or
  `503 invalid_baseline` is 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 /versions` accepts `{hash, revision?, tag?, summary?, parentId?}`. `hash` is 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 when
  `revision` is omitted, and returns `409 note_changed` on mismatch.
  Tags are at most 80 characters and summaries at most 2,000 characters.
  Numeric dotted tags support any number of parts, with an optional `v` prefix,
  such as `1.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 successful `201` returns `id`, `tag`, `summary`, `hash`, `createdAt`,
  `createdBy`, `author`, `number`, and `parentId`. The optional nullable
  `parentId` must identify a version in this memo; a missing/foreign parent
  returns `404 parent_not_found`. On the matching automatic-ancestry backend release,
  omitting `parentId` selects the newest saved causal ancestor proven by the RTC
  clock in the same room and generation. Explicit `parentId: null` creates an
  independent root; an explicit ID preserves that branch choice. No proven
  ancestor (including legacy snapshots without clocks) leaves the save unlinked.
  The optional `parentMode: "auto"` remains supported; do not combine it with
  `parentId`. Saved history is never rewritten. RTC-backed
  versions also include `revision`, `clock`, `editCount`, and `historyComplete`.
  The count measures retained content-edit messages, not keystrokes.
- `GET /versions` returns `{versions, nextCursor}` with up to 50 metadata
  entries, newest first. Send `?before=<nextCursor>` for older entries.
- `GET /versions/:versionId` returns the metadata plus `text`.
- `GET /versions/:versionId/history` returns 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:

```python
memo = dl.memos(memo_id)
page = memo.versions.list()
version = memo.versions.read(version_id=page.versions[0].id)
```

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.
