Editing with patches
A patch describes changes to the source you read. Save that source and its revision, submit the patch against that original revision, then verify the acknowledgment. MERGE is the default; EXACT is an option for one request.
Reviewed prose and prompt revisions
Requires CLI 0.114.0 or later and a named-version writer that preserves the requested opaque revision. A mismatched version receipt is refused before content editing; matching text alone does not establish exact revision identity.
memos revise combines a reviewed source snapshot, concrete presence intent,
pending redlines and verified immutable before/after checkpoints. Existing
low-level edits remain available for targeted operations and recovery.
With the matching backend automatic-ancestry update, the before checkpoint inherits the newest saved causal ancestor in the same RTC room and generation, including a previous after checkpoint of the same unchanged baseline. The after checkpoint names that before checkpoint as its parent. When ancestry cannot be established, the before checkpoint remains a root; content hashes alone do not establish lineage. Existing saved versions are unchanged.
Numeric dotted tags may contain any number of parts, with an optional v
prefix: v0.5, 1.2.03.04.005, or v1.2.03.04.005. Segments and leading
zeros are preserved. The updated history UI displays that tag as the version
label; the immutable version ID and server save number remain independent.
The default stores pending native suggestions, preserving the author's wording.
Use --direct when the current instruction authorizes direct replacement, such
as updating an agent-owned working prompt. A request to review an essay does
not by itself authorize replacement. Existing pending suggestions and changes
to code/frontmatter that cannot be represented as suggestions are refused;
retain the proposal and use a targeted supported edit rather than accepting
unrelated suggestions.
Resource directives are preserved byte-for-byte, including attributes,
fragments and repeated references. Do not flatten them into links or IDs.
Use --allow-reference-changes only for an intentional reference change;
this check is conservative, including code examples. Use each resource's
supported authoring syntax: native artifact/experiment/project/folder directives,
canonical :memo[full-id] references for new Memos, and preserved saved legacy references.
The guarded revision preserves canonical Memo atoms as well as saved legacy atoms;
changing a title in surrounding prose does not authorize replacing their IDs or syntax.
The command requires a stable DREAMLAKE_AGENT_ID, validates intent before
requests, and publishes it with the existing presence API. Identity, presence
intent, version summary and native session identity remain distinct. Both
checkpoint summaries describe the change; saved IDs, revision, full text and
hash are read back and verified. Before editing it checks the live revision
against the reviewed baseline, then submits one exact patch with a recorded
command ID. A concurrent change stops the operation.
--receipt must name a new local file. It holds source and write evidence under
mode 600, is updated at each stage, and is never automatically replayed. After
a failure, inspect its stage: before-saving or after-saving means reconcile
memos hist and read candidate immutable IDs before another version save;
write-submitting means inspect memos command-status with its recorded ID;
write-acknowledged means the content succeeded and only verification/checkpoint
work remains. Saved version IDs are recorded before readback. Never rerun a
successful content write to recover a version or session link. A new receipt
is for a deliberately reviewed new operation, not a retry. If another edit
follows the acknowledgment, recover the retained revision separately instead
of tagging someone else's draft. --dry-run creates no receipt, presence,
version or content write. Receipts contain private source: retain them locally.
Try a complete edit
This creates a new private test Memo and uses a structured snapshot to retain
its source and original revision. It requires login, write access, and jq. The initial source is exactly Hello world.
without a trailing newline. Keep the baseline unchanged while preparing the patch.
Explicit structured integration
Use this alternative only when a structured integration has been requested.
It requires login, write access, and jq.
The initial source is exactly Hello world. without a trailing newline.
A successful receipt contains note, mode, baseRevision, hash, and
revision. baseRevision is the snapshot you submitted; revision is the
acknowledged result. The quoted here-document passes patch text literally,
including $, backticks, backslashes, and Unicode.
MERGE and EXACT
| Mode | Command | If someone edits after your read |
|---|---|---|
| MERGE (default) | patch --base-revision "$BASE" | Applies to the original collaborative character identities |
| EXACT | patch --base-revision "$BASE" --exact | Rejects atomically if the original revision is no longer current |
For example, if a person prepends Human: after you read Hello world., the
patch above can merge to Human: Hello team.. The prefix has its own character
identities. EXACT instead rejects the intervening revision with exit 3 and
zero patch writes. MERGE preserves unrelated concurrent edits; it does not
promise that overlapping edits express either author's intended final sentence.
Overlapping concurrent changes
The DreamLake server checks overlap in MERGE mode since 06fbbe65, deployed to
production on 2026-10-27. No CLI update is needed. Earlier servers could keep two
replacements of the same word side by side (for example
browser-overlapCLI-overlap) with exit 0.
MERGE refuses the whole patch with exit 3 (HTTP 412 stale,
message merge refused: …) and writes nothing when a change made after your
read overlaps any hunk. The check compares collaborative character identities,
not text, so an identical word elsewhere in the memo never matches. A hunk
overlaps when, since your read:
- a character it replaces or deletes was changed, deleted or replaced, even by an identical replacement;
- new text appeared inside its span or directly at either edge, with no original character in between;
- the character directly before or after the span was deleted; or
- for a pure insertion, new text was inserted at the same position, or a neighbouring character was deleted.
Adjacent edits are treated as overlapping on purpose: replacing shared in
shared baseline still merges with a concurrent edit to baseline, because the
original space between them is unchanged, but not with text typed directly
against shared. Two concurrent appends at the end of a memo also conflict.
Disjoint hunks continue to merge, and EXACT is unchanged.
The server checks and commits against the same revision, so a change that lands
in between is never written over: the server re-checks the same original intent
at most three times, then refuses with merge refused: the note kept changing.
On a refusal, keep your original baseline and draft, read the memo, review the
concurrent change and reconcile. Never use --force or substitute a newer
baseline for the old patch.
Both modes validate against the retained original snapshot. Missing snapshots, invalid ranges, and mismatched old text are errors. There is no fuzzy matching against the latest source and no automatic baseline refresh.
--if-match "$BASE" is a compatibility alias for EXACT and can supply the
baseline by itself. If supplied with --base-revision, the values must agree.
EXACT never locks the memo or changes later requests. V2 patches reject --force.
Patch formats
Choose a format for each upload independently of the format used for reads.
Inline character edits
The current format name is inline-dff (the default). Each hunk has a range
header and one physical ~ record:
Plain text is unchanged; [-…-] deletes; {+…+} inserts. The old projection
must exactly match the specified source range. Offsets are zero-based,
end-exclusive Unicode code points, not UTF-8 bytes or JavaScript UTF-16
indices. All hunks address the same original source and must be ordered and
disjoint. A zero-length range inserts at that boundary.
Inside a record, encode newlines as \n, carriage returns as \r, tabs as \t,
and backslashes as \\. Escape literal delimiter characters with a backslash.
Unknown escapes, nested markers, overlaps, and malformed hunks are rejected.
Patch framing uses LF and is not appended to the memo.
Unified line diff
For editing in a local editor, save exact source, edit a copy, then generate a
diff. Start with an accessible MEMO_ID; keep both the baseline and draft.
Only a single-file unified patch is accepted. Preserve context, line counts,
CRLF, and \ No newline at end of file markers. File labels do not select the
memo. If the files match, stop without sending a patch. Empty patch input is rejected.
Preview and input
--dry-run prints the proposed request without submitting it. It does not
ask the server to validate the patch or prove that a later write will succeed.
Input is --diff string, --file path, or --file - for stdin (a here-document
or a pipe). Choose one. Stdin is read only with --file -: a pipe is never
consumed implicitly, and --diff/--file path ignore whatever stdin is, so the
result does not depend on how the command was launched. With a terminal on
--file -, a hint to end input goes to stderr. Patches are limited to
8,000,000 UTF-8 bytes.
Every write refuses text that adds a generated reading-view header
(<!-- notes-reading-view revision=…). memos patch sends without reading
the memo, so for it the check is best-effort on the patch's insertion payloads
(adjacent hunks included); the server is the authoritative enforcement point.
Handle a failure
| Exit | Meaning | Next action |
|---|---|---|
1 | Invalid options, authentication, transport, missing baseline, or a proven unsubmitted patch | Read the diagnostic; retain your files |
3 | Stale EXACT/read precondition, invalid original identities, or a MERGE overlap refusal | Inspect current state and review the edit |
4 | RTC acknowledgment unavailable; outcome may be ambiguous | Read resulting state before deciding whether to resubmit |
5 | Patch rejected against its original snapshot | Correct the patch using that source |
A current API503 with error: "rtc_unavailable" and exactly
mutation: {apiVersion: 1, started: false, phase: "baseline_read"} proves that
the requested native edit did not start. The CLI reports patch not submitted,
exits1, and leaves the original baseline and draft intact. This does not prove
that other collaborators made no changes. An absent, malformed or unsupported
marker proves nothing: submission remains unknown and exit4 still applies. The
CLI never guesses from the error sentence or downgrades APIs to recover a write.
The CLI does not automatically retry an HTTP patch. Separate requests do not share an idempotency receipt. If an acknowledgment is lost, keep the original baseline and draft, inspect the memo, and reconcile. Never attach a newer revision to an old patch merely to make it pass. A later successful read does not by itself prove whether an earlier ambiguous request committed.
Retry-safe writes with --command-id
append, patch, write, replace, insert and delete accept
--command-id ID: a caller-stable identity of 8–128 characters from
A-Z a-z 0-9 . _ : -, checked before any request. The server binds the id to a
fingerprint of the original intent (memo, baseline revision, mode, format and
patch). Retrying the same id with the same intent returns the stored receipt
with replayed: true and commits nothing. The same id with different intent is
refused with 409 command_intent_mismatch; an unfinished or unresolved command
answers 409 command_in_progress or 409 command_outcome_unknown. This is the
Memos API contract's public command identity: the answer to safely replaying an
append whose response was lost. It is opt-in in this release; the server side
ships separately, and until it does a receipt without the echo exits 4.
Every v2 write receipt carries outcome (accepted, or no-write when the
compiled edit set was empty), commandId (null without the flag) and
replayed. With --command-id, a receipt that does not echo the id exits 4:
the server predates command identity, the write may have been applied, and a
retry would not be deduplicated. A lost acknowledgment with --command-id also
exits 4, and the diagnostic names the id: retry with the same id, or read
memos command-status MEMO_ID COMMAND_ID, which reports pending, accepted,
no-write or unknown with the stored receipt or error, or
404 command_not_found. Without the flag nothing new is sent, so older servers
keep working. --command-id requires the v2 write: it cannot combine with
--legacy, --force, --section, or the legacy --if-match of replace,
insert and delete.
Next: Live collaboration. For existing section/text mutation scripts, see Legacy commands.
Native stdin and error diagnostics
Use --file edit.dff for a saved patch. Native CLI 0.33.0 can incorrectly read
--file - < edit.dff as empty input and receive a successful no-op receipt; this
is an input-transport defect, not a merge conflict. The fix is unreleased. Until
upgrading to a release containing it, pass the file path directly and inspect
--dry-run --json to verify payload.patch before submission.
The corrected native reader preserves redirected-file and pipe bytes, rejects
empty patch input before sending, and retains UTF-8 and 8 MB limits. Server error
details are printed alongside their error code. A 422 may indicate an alignment
limit as well as an invalid patch; it does not by itself prove a baseline mismatch.
Keep the baseline and draft on any failure. Default merge and opt-in exact mode
are unchanged. Verify the intended edits in the acknowledged --at snapshot.
Literal text without inline-DFF escaping
To avoid hand-writing \[, \- and other inline-DFF escapes, prepare an edited
copy of the exact canonical baseline and generate a unified diff. Keep Unicode,
$, <, & and backslashes literal in those files. Do not copy generated
address hints into either file. Preserve the baseline's original revision and
line endings. This uses the existing source patch API, not a new semantic edit API.
The patcher checks the old source against the retained baseline. Keep any Markdown escapes needed in the actual saved source; the diff transport does not require extra escaping of its line contents. Existing merge/exact semantics apply.
Propose instead of write
To let the memo's owner accept or reject each change rather than applying it
directly, render the edit as suggested edits with
memos suggest-diff --in-place
and write that body instead.
Append against the original snapshot (CLI 0.59.0+)
Original-revision append requires CLI 0.59.0 or later and the compatible Memos v2 API. CLI 0.58.0 and earlier use the retained ETag/body replacement append. The new append preserves collaborative source identities instead of replacing the complete Memo body. No legacy route is retired.
Without --base-revision, append reads one complete, hash-verified source
snapshot and submits an EOF insertion against that original revision. With an
original saved revision, it reads that retained snapshot using at; it never
swaps a rejected baseline for the latest token. Merge is the default and retains
unrelated concurrent edits. Use --exact when the original revision must still
be current. Overlapping identity changes or unavailable original snapshots can
reject; preserve the original baseline and addition for review.
--text, --file, --file -, and piped stdin retain literal text, Unicode and
line endings. Append is verbatim: exactly the addition is inserted at the
original document end, with no separator added, even when the original lacks
a final LF (printf '\nHello\n' supplies the separating newline deliberately).
An empty addition performs no write and JSON reports noChange: true with the
observed snapshot revision; it does not claim a new acknowledgment. The EOF offset counts Unicode code points, and patch syntax
characters and source controls are escaped before transport.
Human --dry-run keeps the composed original source plus addition on stdout,
with the PATCH/base revision/mode on stderr. This preview is based on the
original source, not the future merged document. JSON dry-run describes the
actual PATCH payload. Successful writes print Memos v2 note, hash, revision,
mode, and baseRevision; use that acknowledged revision for pinned readback.
A failed or malformed acknowledgment can leave the outcome unknown. No retry
is automatic: inspect the Memo before resubmitting, keeping the original draft.
Explicit --legacy retains the prior ETag-guarded body replacement append.
Existing --force retains its prior unguarded legacy behavior; it never selects
a forced v2 write. Neither compatibility choice can combine with
--base-revision or --exact. Avoid forced replacement for collaborative work.
Insert at an original-source position (CLI 0.60.0+)
Original-revision insertion requires CLI 0.60.0 or later and the compatible Memos v2 API, reusing the CLI 0.59.0 append snapshot/PATCH helpers. CLI 0.59.0 and earlier use retained ETag/body replacement insertion. No legacy command or route is retired.
Insertion reads one hash-verified original snapshot, resolves the
requested position in that source, and submits one escaped literal insertion.
A supplied --base-revision pins the retained snapshot; rejected original tokens
are never replaced with the latest revision. Default merge preserves unrelated
concurrent edits; --exact requires that original revision to remain current.
Overlapping identity changes may reject and require review of the original draft.
Choose exactly one location:
--ind Naddresses a Unicode code-point boundary from0through source length, including both ends. Text is inserted literally, with no added newline.--line Ninserts before a 1-based source line, or at EOF for one past the final line. The line algorithm preserves the source newline style and terminates the addition unless it already ends in LF. At EOF after a source with no final LF/CR, it also inserts the source-style newline before the addition. A final LF already creates an empty last line; that line and one past it both resolve to EOF.--selector CSSmust match exactly one original-source HTML element.--positiondefaults toappend;before/afteruse the outer boundaries, whileprepend/appenduse the inner boundaries. Text is literal markup and gets no added newline. Void elements reject inner insertion; use before/after instead.
Human --dry-run prints the composed original source exactly, without a trailing
newline added for display. JSON previews the actual PATCH and composed text;
this is not a prediction of the future merged source. Empty literal insertion
sends no write and reports noChange: true for the observed snapshot. Empty
line-oriented insertion still follows the newline rules and can create a line.
Success returns the acknowledged v2 revision. Pin readback with --at; failed,
malformed, redirected or lost acknowledgments are never automatically replayed.
Keep the original baseline and text and reconcile the Memo before resubmitting.
Explicit --legacy, existing --force, or existing --if-match <etag> select the
retained replacement path. Preserve a content ETag for that path, never an RTC
revision. These compatibility flags cannot combine with --base-revision or
--exact. Section mutation keeps its existing contract. Replacement and deletion
use the original-revision contracts below in CLI 0.60.0 or later.
Contract spellings (CLI 0.98.0)
The memo may be given positionally: dl memos insert "$MEMO_ID" --after s1.p2 --file addition.md --base-revision "$BASE" --json inserts the file's exact UTF-8
text, verbatim, at the end of that mapped element's full original span (--before
inserts at its start; --cursor N at an original code-point position). Addresses
come from a mapped read of the same revision. --text, --file PATH and
--file - are mutually exclusive.
Replace and delete original-source spans (CLI 0.60.0+)
Original-revision replacement and deletion require CLI 0.60.0 or later and the compatible Memos v2 API. CLI 0.59.0 and earlier use retained ETag/body replacement for these editors. The original-revision editors submit precise code-point spans through the v2 snapshot/PATCH API. Multiple matches become separate hunks in one PATCH against one original revision, leaving the source between targets untouched.
Literal queries require one match by default; --count N requires exactly N
matches, and --all selects every match. Query/regex, inclusive 1-based line
ranges, and end-exclusive Unicode code-point ranges preserve their existing
rules. Plain-source regex replacement expands JavaScript replacement tokens
against each original match, including numbered/named captures, $&, and $$.
Line replacement preserves source newline style. No match, ambiguous cardinality,
invalid targeting or range errors remain nonmutating refusals (normally exit 6).
With --selector, exactly one source element is selected and matching stays
within its individual decoded text pieces. Matches cannot bridge intervening
markup. Each decoded match maps back to its original raw entity/source span;
replacement --text escapes ampersands and angle brackets for markup. As in the
retained selector implementation, replacement text is literal after that
escaping: selector regex replacement does not expand $1 or named backreferences.
--html instead replaces the selected element's inner source with literal markup
and cannot combine with a query/regex or --text.
Default merge uses the original snapshot identities. A supplied --base-revision
pins the retained original source; --exact requires it to remain current. A
rejected baseline is never silently swapped for the latest one. Unrelated
concurrent edits outside the targeted spans can be preserved, including edits
between disjoint matches in the same paragraph. Overlapping edits can reject;
keep the original baseline and draft for review.
Human dry-run prints the composed original source exactly; JSON carries that
text and the actual multi-hunk PATCH. Equal old/new spans are omitted to preserve
unchanged identities; an entirely unchanged plan sends no write and reports
noChange: true for the observed snapshot. Successful writes return the v2
acknowledged revision for read --at. Lost/malformed acknowledgments are never
replayed automatically; reconcile before resubmitting.
Explicit --legacy, existing --force, or existing --if-match <etag> retain
legacy replacement and failure semantics. They cannot combine with
--base-revision or --exact. These changes do not migrate section editors or
retire legacy endpoints.
The original-revision migrations of section write, add-section, and
rm-section remain unshipped. Their existing ETag-based interfaces remain
available. Runbook attachment is separate proposed work and is not included
in CLI 0.61.0; no legacy Memo route or compatibility option is retired.
Contract spellings (CLI 0.98.0)
memos remove is an alias of memos delete (selected source, never the Memo).
With a span selector the memo may be given positionally and no query is needed:
--lines a:b takes exactly two integers (1-based, inclusive; the span includes
its line terminators). --address ID selects the full original span of a mapped
element at the snapshot revision, nested content included. --file supplies the
exact replacement text; empty replacement text deletes the span.
Write a target body against its original source (CLI 0.61.0+)
Original-revision whole-body write requires CLI 0.61.0 or later and the
compatible Memos v2 API. CLI 0.60.0 and earlier keep whole-body write on the
retained ETag interface. Modern write derives bounded, exact code-point changes between an original source snapshot and your target
body, retaining unchanged source islands even inside one paragraph. It emits
ordered disjoint hunks in one v2 PATCH, rather than replacing the complete body.
A target prepared from an older source must retain that source's original
--base-revision. Without one, write reads one current hash-verified snapshot
and protects the subsequent request window; that cannot prove which source an
older local file came from. A supplied baseline pins the retained source with
at; rejected tokens are never silently exchanged for the latest revision.
Default merge preserves unrelated concurrent changes outside the planned spans;
--exact requires the original revision to remain current. Concurrent edits
that overlap those spans can reject and need review of the original draft.
--text, --file, --file -, and piped stdin preserve literal Unicode and line
endings. Modern file/stdin bytes must be valid UTF-8; malformed input rejects before
transport, preserving the existing legacy decoding separately. File and text
flags remain mutually exclusive. An empty target is an
intentional deletion of the original source, not a missing-patch no-op. An
unchanged target in merge mode sends no write and reports noChange: true for
the observed snapshot. With --exact, an unchanged target sends an empty PATCH
so the server still validates the original revision; a stale exact request
rejects even when no source characters would change. Human dry-run keeps the target body on stdout (adding a final display
LF only when absent); JSON includes the target text and actual PATCH. Neither
preview predicts the future merged source. Text that resembles a unified diff
still warns on stderr and is treated as a literal target body.
Alignment is exact and bounded: source and target are limited to 1,000,000 code
points each; generated patches to 8,000,000 UTF-8 bytes and 10,000 edits; alignment
work to 4,000,000 cells and retained trace storage to 250,000 units. Sparse changes
and supported dense changes preserve unchanged identities. Exceeding a limit
fails before submission (exit 5); it never falls back to a coarse rewrite.
Invalid unpaired Unicode surrogates also reject. Lost/malformed acknowledgments
are never replayed automatically; keep the original baseline and target and
reconcile the Memo before resubmitting. Verify the acknowledged revision with
read --at after a successful write.
Explicit --legacy, existing --force, or existing --if-match <etag> retain
the prior whole-body replacement path. --section explicitly selects its
retained section-write API; section migration remains unshipped. These choices
cannot combine with --base-revision or --exact. add-section and rm-section
keep their existing contracts; no legacy route or compatibility option is retired.
Insert a created Memo
dl memos create --json returns id and directive separately from the
name/slug. Copy directive into new Memo or Chat content. With the JavaScript
API, use const created = await dl.memos.create({ namespace: "team", name: "Review" })
and insert created.directive. It is :memo[<full-24-hex-id>], never the title,
slug or URL. Display labels can change without changing the reference.
If creation did not confirm an ID, inspect Memos before creating again. Never
fall back to :note, even when saved content or historical tool names use it.
Existing legacy source remains readable and is not rewritten by this operation.