DreamLake

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.
  • content is 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; complete explicitly 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.

bash
dl memos read "$NOTE_ID" --view source --json

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.

bash
dl memos read "$NOTE_ID" --at "$REVISION" --view source --json

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.

bash
dl memos read "$NOTE_ID"

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.

bash
dl memos read "$NOTE_ID" --at "$REVISION" --section s1

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.

bash
dl memos read "$NOTE_ID" --at "$REVISION" --lines 40:80

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.

bash
dl memos read "$NOTE_ID" --at "$REVISION" --tag s1.p2

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.

bash
dl memos read "$NOTE_ID" --view source > note.md

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.

bash
dl memos toc --note "$NOTE_ID" --at "$REVISION" --json

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.

bash
dl memos find Draft --note "$NOTE_ID" --at "$REVISION" --case-sensitive --json

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.

bash
dl memos diff "$NOTE_ID" --since "$REVISION" --format diff --json

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.