<!-- source: https://cli.dreamlake.ai/notes/versions @ 0.134.0 99837ab -->

# Saved versions

`memos tag` saves durable checkpoints on an existing Memo. It does not
create another Memo or change the live body. All version operations require
edit access, including reading history that may contain previously removed text.

**Availability:** `memos tag`, `memos hist`, and `memos read --version` require
CLI **0.44.1 or later**. `note` and `notes` are aliases. Check
`dl memos hist --help` in your installed executable
before using them in automation. They require the server's native Memos
`/versions` endpoints; an older server's failure is not an empty version list.

## Create a checkpoint

```bash cli-help="memos tag"
# Save the current content on the existing Memo.
dl memos tag MEMO_ID end-of-day --namespace my-org --summary "Reviewed today's actions"
# Require the hash retained from a reviewed full read (not its opaque revision).
dl memos tag MEMO_ID reviewed --hash sha256:CONTENT_HASH --json
# Connect this checkpoint to an earlier version in the same Memo.
dl memos tag MEMO_ID next-checkpoint --parent VERSION_ID
# Keep every dotted segment and deliberately start independent history.
dl memos tag MEMO_ID 1.2.03.04.005 --root
# Read and validate without creating a version.
dl memos tag MEMO_ID preview --dry-run --json
```

Creation performs one complete Memos v2 source read, verifies its SHA-256 hash,
and submits that same hash to the server. Optional `--hash` accepts either the
`sha256:`-prefixed hash from `memos read --json` or the raw 64-character digest.
If the reviewed hash differs from the current read, nothing is submitted.
If the Memo changes between the read and save, the server returns
`409 note_changed`; the command exits **3** without retrying. Review the current
text before explicitly trying again. Do not substitute an opaque write revision
for the content hash.

The positional label is required (80 characters maximum); `--summary` is optional (2,000
characters maximum). Tags are labels, not unique IDs or idempotency keys:
repeating a successful create makes another version. Retain the returned `id`
for reading and ancestry. `--parent` must identify a saved version in the same
Memo; it records ancestry without restoring or altering the live Memo.

With the matching backend automatic-ancestry update, omitting `--parent`
selects a proven causal ancestor in the same RTC room and generation.
Use `--root` to deliberately save an independent root; do not combine it
with `--parent`. When ancestry cannot be proven, the backend leaves the
save unlinked. Existing saved history is unchanged.

Dotted numeric labels may have any number of parts, optionally prefixed
with `v`: `1.2.03.04.005`, for example. Segments and leading zeros are
preserved. The updated history UI displays this as the version label;
the server's internal save number and immutable ID remain independent.

A server or transport failure after submission may leave the outcome uncertain.
Paginate `memos hist` and read matching candidates with `memos read --version`
before deciding whether another create is necessary; see the retained-snapshot
workflow below. There is no automatic retry or
fallback that creates a separate Memo. RTC unavailability exits **4**; other
failures exit **1**. Version request errors preserve the server error code in
`--json` output. Connection/authentication and Memo resolution follow normal
Memos diagnostics.

## List saved versions

```bash cli-help="memos hist"
dl memos hist MEMO_ID --namespace my-org --json
# Continue with nextCursor returned by the previous page.
dl memos hist MEMO_ID --before VERSION_ID --json
```

One request returns up to 50 versions, newest first. JSON preserves
`{versions, nextCursor}`; `nextCursor: null` means the last page. Plain output
includes IDs, tags, timestamps, summaries and any next cursor. Listing returns
metadata, not bodies, and does not automatically fetch all pages.

## Read a saved version

```bash
dl memos read MEMO_ID --version VERSION_ID
dl memos read MEMO_ID --version VERSION_ID --namespace my-org --json
```

Read by the returned version ID (`v_<timestamp>_<uuid>`), not by tag. Plain
output prints metadata and the SHA-256 hash followed by the exact retained
text. JSON preserves server metadata and `text`, including an empty string.
The CLI validates the saved text's hash and never fetches or restores the live
body. The server also exposes version history snapshots/journals, but this
command group does not yet expose that endpoint.

All three commands accept a Memo ID, slug or title, `--namespace`, normal
connection flags, and `--json`. Prefer stable Memo and version IDs in automation.

`hist` lists saved checkpoints, not every live edit or RTC journal entry.
`read --version` accepts `--note` as an alternative to the positional Memo.
It cannot combine with `--at`, `--since`, `--format`, `--if-match`, `--legacy`,
partial/numbered reads, HTML/Markdown views or collaboration options such as
`--linger`. `--view source` and `--json` are supported. Omit `--version` to read
the live Memo normally. A saved version's JSON uses `text` and saved metadata,
not the live read's `content` and write-baseline envelope.

## Recover a retained snapshot

Use the [authoritative retained-snapshot recovery workflow](https://docs.dreamlake.ai/notes/history/#recover-a-retained-snapshot)
when an older full source is retained but missing from saved versions.
`memos tag` checkpoints the **current** live source; it cannot import an older
snapshot. The CLI has no historical-revision save option or checkpoint/journal
read command. Use the documented Memos REST endpoints only for those missing
capabilities; keep supported `tag`, `hist`, and `read --version` operations in
the CLI.

Before recovery, retain a complete live `--view source --json` read, its exact
source bytes, opaque revision, and content hash for the same stable Memo ID and
namespace. Retain the older full source separately with its provenance; a
partial read, rendered view, or copied memo is not a recovery baseline. The
content hash is SHA-256 over exact UTF-8 source bytes; REST hash fields require
the raw 64-character digest (remove the CLI envelope's `sha256:` prefix).
The opaque revision is a separate write-baseline token and is never a hash.

Check installed `--help` before choosing a command. On CLI versions before
0.44.1, update the executable or use the documented REST fallback; 0.44.2 removes
the older `notes version` group. Independently confirm the server supports
historical-revision saves. An unsupported route, validation failure, or
`409 note_changed` on an older server is not an empty history and does not
justify substituting the current hash or overwriting the live body.

If a create times out or its result is otherwise unknown, do not blindly retry.
Inspect every relevant `memos hist` page using `nextCursor` with `--before`, then
read each plausible candidate by ID with `memos read --version`. Compare its
exact retained text and hash, plus the operation's tag, summary, parent and
provenance where applicable. Labels and hashes are not idempotency keys. Reuse
a verified matching receipt; if the outcome remains ambiguous, preserve the
evidence and resolve it before another create.

After saving, verify the returned version by ID: its exact retained revision,
text, hash and `sourceObservedAt` must match the reviewed recovery evidence.
Older servers can ignore `revision`, so HTTP 201 or matching text/hash alone
does not establish that the requested historical baseline was saved. Read the
live source again in the same namespace and compare it with the live baseline;
investigate concurrent edits without restoring stale content. Follow the authoritative workflow for endpoint details and complete
recovery verification.

## Removed commands

CLI 0.44.2 removes the old `notes version` command group. Use `memos tag`,
`memos hist`, and `memos read --version` instead. The `notes` spelling of the
Memo command group remains supported.
