Reading and locating Memo source
Implementation target — unreleased. This page specifies proposed unified read methods, CLI flags and model-facing tools. It is design documentation, not proof that the installed CLI/SDK or deployed server implements the examples. See the API overview for package/status context and CLI I/O for presentation and stream rules.
IDs are primary: $NOTE_ID, noteId and note_id denote the same stable Memo.
The configured SDK is dl; dl.notes(noteId) constructs a local stateful handle.
ID lookup requires no caller-supplied namespace; the server checks its current
owner/access. Explicit --namespace / --ns asserts source context. Slugs need
explicit or configured namespace context; deep project folders are separate
fields, never parsed as namespace prefixes. See moves.
Read result contract
read() in an SDK returns exact source with structured provenance. Agent tools
and normal CLI text output default to source-mapped presentation. These are two
representations of the same source contract, not competing edit baselines.
- Stable Memo ID and the original opaque RTC revision identify the source.
contentis exact canonical source or an explicitly scoped source slice; mapping decoration is never part of that string.- The full-source hash identifies the complete source; scoped results also need their own slice hash/range when verification requires it. A full-source digest cannot be checked by hashing an arbitrary partial slice.
- Scope identifies whole Memo, section, element or source lines;
completeexplicitly says whether the complete Memo source is included. - Mappings identify observed elements and their absolute source ranges. Offset units are Unicode code points with end-exclusive endpoints; source line pairs are 1-based and inclusive.
- Large mapped reads include bounded continuation and the pinned original revision. Reuse that revision for every page; never silently concatenate source from different revisions. Page field spelling/limits remain to settle.
The schema must keep exact source separate from human/agent address hints. A map may be projected as annotated Markdown or literal-source HTML-like wrappers; this is not necessarily browser-renderable HTML. Do not DOM-parse arbitrary literal Markdown to recover its source. Generated addresses are local to the observed revision; they are not permanent document IDs.
Read complete source
Each tab reads a complete current source snapshot with its identity, hash and
revision. CLI/tool examples explicitly choose source to match SDK read().
Normal CLI/tool omission of that view instead selects mapped presentation.
dl memos read "$NOTE_ID" --view source --jsonconst note = dl.notes(noteId)
const snapshot = await note.read()note = dl.notes(note_id)
snapshot = note.read()const snapshot = await notes_read({ note: noteId, view: "source" })A complete snapshot is suitable for whole-body write planning. A title, search snippet, rendered preview, partial page or outline is not. SDK object state may cache client context, but the snapshot passed to a prepared write stays explicit; reading latest later must not advance that original edit's baseline.
Read a retained RTC revision
Every tab requests the exact retained revision, not whatever source is current.
The revision must come from a prior source read or accepted mutation receipt.
dl memos read "$NOTE_ID" --at "$REVISION" --view source --jsonconst snapshot = await dl.notes(noteId).read({ at: revision })snapshot = dl.notes(note_id).read(at=revision)const snapshot = await notes_read({ note: noteId, at: revision, view: "source" })at retrieves historical retained source; it does not assert the revision is
still current. A conditional current read is a separate precondition. Unknown,
expired or invalidated history must fail explicitly instead of falling back to
latest. Current permission checks still apply to historical content. Saved named
versions are a distinct immutable version API; their IDs are not RTC revisions.
Read mapped source
Each tab requests the same current source with mapping addresses/ranges. This
is the target default for CLI and agent tools; SDKs request the mapped view.
The exact explicit CLI mapped-view spelling remains to finalize; these examples
exercise the agreed default rather than inventing a shipped --view mapped flag.
dl memos read "$NOTE_ID"const mapped = await dl.notes(noteId).read({ view: "mapped" })mapped = dl.notes(note_id).read(view="mapped")const mapped = await notes_read({ note: noteId })Mapped reads exist to help an agent navigate and edit the right source with less context. They are first-class, not an inferior substitute for raw source. A flat address points directly at an element: a caller need not traverse nested objects. The addressed element can nevertheless span nested list/section descendants. The map must disclose that full source span before an agent replaces it.
Current --view markdown adds address hints; --view html exposes mapped markup.
How both encodings map onto the target logical mapped view remains open.
Read back actual returned IDs after renderer changes instead of manufacturing
an address from old heading numbers or visual text.
Read one section
Assume a prior mapped read or outline returned section address s1. Every tab
reads that section's exact source plus mapping at the same retained revision.
dl memos read "$NOTE_ID" --at "$REVISION" --section s1const section = await dl.notes(noteId).read({ view: "mapped", section: "s1", at: revision })section = dl.notes(note_id).read(view="mapped", section="s1", at=revision)const section = await notes_read({ note: noteId, section: "s1", at: revision })A section contains its heading and subsections until the next equal/higher-level heading under the current mapping contract. Source selection is not a promise of inner-text editing. Unknown addresses fail; duplicate headings must use observed unique addresses. A section result is explicitly partial even if its source is large. It can support a targeted edit when it retains the exact original source range/revision, but cannot replace the whole Memo.
Read source lines
Every tab reads original source lines 40–80 inclusive at the same revision. The Memo must contain that valid range. Invalid or reversed bounds must produce an actionable selection error instead of silently reading unrelated content.
dl memos read "$NOTE_ID" --at "$REVISION" --lines 40:80const part = await dl.notes(noteId).read({ view: "mapped", lines: [40, 80], at: revision })part = dl.notes(note_id).read(view="mapped", lines=(40, 80), at=revision)const part = await notes_read({ note: noteId, lines: [40, 80], at: revision })A pair contains exactly two integers. Return total source-line count, absolute range and explicit partial/completeness information. Preserve original line terminators and terminal-newline state; line numbers refer to canonical source, not visual wrapped lines, rendered Markdown or generated address-hint comments. One line can contain multiple HTML elements: line selection does not make them separate editing units. Use a precise observed address for a narrower span.
The target replaces separate start/end CLI flags with --lines START:END and
removes the need to select legacy reads for line ranges. That requires CLI and
server implementation; it is not a statement about today's parser. Whether
out-of-bounds endpoints clamp or reject must be standardized; the examples use
an entirely valid range and do not depend on either behavior.
Read an observed element
Selector spelling proposed: a read address field corresponds to the current
CLI's --tag concept. Every tab selects the same observed paragraph s1.p2 at
the retained revision. Keep the existing CLI spelling in the example until a
public flag rename is separately agreed.
dl memos read "$NOTE_ID" --at "$REVISION" --tag s1.p2const element = await dl.notes(noteId).read({ view: "mapped", address: "s1.p2", at: revision })element = dl.notes(note_id).read(view="mapped", address="s1.p2", at=revision)const element = await notes_read({ note: noteId, address: "s1.p2", at: revision })Selection needs a defined combination rule: prefer exactly one of section,
address or lines rather than surprising intersections. An explicit original
revision can accompany any selector. Returning one item/paragraph must state
whether its source includes nested content; never infer an inner edit range
from a tag name alone. See editing.
Export exact source
Each tab emits only complete source bytes as UTF-8, without mapping hints,
metadata headers or an added terminal LF. Tool output remains structured: the
integration extracts the exact content string rather than parsing prose.
dl memos read "$NOTE_ID" --view source > note.mdconst snapshot = await dl.notes(noteId).read({ view: "source" })
const bytes = new TextEncoder().encode(snapshot.content)
// Pass bytes unchanged to the destination file/download API.import sys
snapshot = dl.notes(note_id).read(view="source")
sys.stdout.buffer.write(snapshot.content.encode("utf-8"))const snapshot = await notes_read({ note: noteId, view: "source" })
const bytes = new TextEncoder().encode(snapshot.content)
// Save bytes unchanged; do not serialize the entire result as Note content.Raw source is useful for export, external editing/diff generation and byte-exact
verification. Mapped targeted editing should not need a second raw whole-source
fetch. --view source --json instead returns a structured snapshot: it is not
source-only output. A partial raw export is possible with an explicit selector,
but only a structured result carries its completeness/provenance to another
program automatically. See CLI I/O.
Outline
Method proposed: each tab returns headings and observed addresses tied to one retained revision. The outline can locate a section for a focused read; it is not complete writable source.
dl memos toc --note "$NOTE_ID" --at "$REVISION" --jsonconst outline = await dl.notes(noteId).outline({ at: revision })outline = dl.notes(note_id).outline(at=revision)const outline = await notes_outline({ note: noteId, at: revision })Heading levels may express nested sections, but each address resolves directly.
Include revision and range metadata; never return a decorative heading number
as a permanent identifier. Pinning/scope options on outline and the CLI toc
spelling above are target requirements to verify before implementation. Current
read --toc mapping and a parsed source outline need equivalent source provenance,
not merely similar-looking text.
Find source text within a Memo
Target method proposed: search the same Memo source for literal Draft,
case-sensitively, at the original revision. Every tab performs that exact search.
dl memos find Draft --note "$NOTE_ID" --at "$REVISION" --case-sensitive --jsonconst matches = await dl.notes(noteId).find({ text: "Draft", caseSensitive: true, at: revision })matches = dl.notes(note_id).find(text="Draft", case_sensitive=True, at=revision)const matches = await notes_find({ note: noteId, text: "Draft", caseSensitive: true, at: revision })Return exact matched source, absolute code-point ranges, original revision and bounded context; surface truncation/continuation explicitly. Return every requested match within the declared limits, or explain the limit. Never manufacture a unique target when text repeats. Literal versus regex mode, default sensitivity, occurrence selection and match/page caps remain naming/schema decisions; this example chooses literal and sensitivity explicitly. Cross-Note search/grep is a separate discovery family. A find result is not a complete source baseline for a whole-body write. Current search hits can carry legacy validators; the target must use original RTC provenance rather than accepting those ETags as revisions.
Diff from an explicit original revision
Proposal still to ratify: let all interfaces accept an RTC revision as
since; SDKs may also accept the snapshot that carries it. This deliberately
changes today's CLI hash/time-based --since contract. The example requests
a source diff from the same revision to the current observed result, without
editing anything or moving a prepared draft's original baseline.
dl memos diff "$NOTE_ID" --since "$REVISION" --format diff --jsonconst changes = await dl.notes(noteId).diff({ since: revision, format: "diff" })changes = dl.notes(note_id).diff(since=revision, format="diff")const changes = await notes_diff({ note: noteId, since: revision, format: "diff" })Return stable Memo identity, base/result revisions, base/result hashes, patch and format. A caller applies a patch only to source matching its base and verifies the result hash. An empty patch can accompany a newer RTC revision when content is identical; source equality does not imply identical collaborative history. Expired bases fail clearly instead of silently substituting latest. A fresh read can restore current state but is not replay of missing intermediate changes.
A source hash identifies content, an RTC revision identifies retained collaborative state, a saved-version ID identifies an immutable saved version, and a watch continuation identifies stream progress. They must not share an untyped field that guesses which meaning the caller intended. The exact diff selector migration and support for time/hash inspection remain open; do not use this proposal as current CLI guidance. Watch's durable net-content catch-up is specified separately in collaboration.
Current support and migration boundaries
Inspected package evidence is CLI/TypeScript 0.94.0 and Python 0.32.1. Current
CLI default source output, mapped --view markdown / --view html, addressed
selectors and legacy line-read options differ from this target. Current TS
source validates full RTC snapshots and readView returns one addressed page;
CLI mapped Markdown traverses those pages automatically. Python read_snapshot
exists, but the proposed callable dl.notes(id)/uniform read and mapping methods
are not established by that release. Current Python read() returns an editable
draft rather than the exact target snapshot shape here.
Do not remove useful mapped/partial behavior when retiring legacy reads. Converge
onto one original-revision source contract, retaining clear scope and source
mapping. Default switches and flag/signature changes require a migration and
released-client verification; a docs merge does not make them available. Proposed
notes_* tool names are model-facing design labels, not claims about currently
registered built-in plugins or an advertised MCP server.