<!-- source: https://docs.dreamlake.ai/notes/api/reading @ 0.1.192 b2f973b1 -->
# 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](/notes/api/) for package/status context and
[CLI I/O](/notes/api/cli/) 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](/notes/api/moving/).

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

**CLI**

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

**TypeScript**

```typescript
const note = dl.notes(noteId)
const snapshot = await note.read()
```

**Python**

```python
note = dl.notes(note_id)
snapshot = note.read()
```

**Tool call**

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

**CLI**

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

**TypeScript**

```typescript
const snapshot = await dl.notes(noteId).read({ at: revision })
```

**Python**

```python
snapshot = dl.notes(note_id).read(at=revision)
```

**Tool call**

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

**CLI**

```bash
dl memos read "$NOTE_ID"
```

**TypeScript**

```typescript
const mapped = await dl.notes(noteId).read({ view: "mapped" })
```

**Python**

```python
mapped = dl.notes(note_id).read(view="mapped")
```

**Tool call**

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

**CLI**

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

**TypeScript**

```typescript
const section = await dl.notes(noteId).read({ view: "mapped", section: "s1", at: revision })
```

**Python**

```python
section = dl.notes(note_id).read(view="mapped", section="s1", at=revision)
```

**Tool call**

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

**CLI**

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

**TypeScript**

```typescript
const part = await dl.notes(noteId).read({ view: "mapped", lines: [40, 80], at: revision })
```

**Python**

```python
part = dl.notes(note_id).read(view="mapped", lines=(40, 80), at=revision)
```

**Tool call**

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

**CLI**

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

**TypeScript**

```typescript
const element = await dl.notes(noteId).read({ view: "mapped", address: "s1.p2", at: revision })
```

**Python**

```python
element = dl.notes(note_id).read(view="mapped", address="s1.p2", at=revision)
```

**Tool call**

```javascript
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](/notes/api/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.

**CLI**

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

**TypeScript**

```typescript
const snapshot = await dl.notes(noteId).read({ view: "source" })
const bytes = new TextEncoder().encode(snapshot.content)
// Pass bytes unchanged to the destination file/download API.
```

**Python**

```python
import sys
snapshot = dl.notes(note_id).read(view="source")
sys.stdout.buffer.write(snapshot.content.encode("utf-8"))
```

**Tool call**

```javascript
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](/notes/api/cli/).

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

**CLI**

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

**TypeScript**

```typescript
const outline = await dl.notes(noteId).outline({ at: revision })
```

**Python**

```python
outline = dl.notes(note_id).outline(at=revision)
```

**Tool call**

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

**CLI**

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

**TypeScript**

```typescript
const matches = await dl.notes(noteId).find({ text: "Draft", caseSensitive: true, at: revision })
```

**Python**

```python
matches = dl.notes(note_id).find(text="Draft", case_sensitive=True, at=revision)
```

**Tool call**

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

**CLI**

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

**TypeScript**

```typescript
const changes = await dl.notes(noteId).diff({ since: revision, format: "diff" })
```

**Python**

```python
changes = dl.notes(note_id).diff(since=revision, format="diff")
```

**Tool call**

```javascript
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](/notes/api/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.
