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