<!-- source: https://docs.dreamlake.ai/notes/api/collaboration @ 0.1.192 b2f973b1 -->
# Memos collaboration and replay

**Implementation target — unreleased.** These pages specify the redesigned API. Examples are interface contracts, not claims that installed clients, tool registration or the deployed service already implement them. Verify current support before executing proposed calls against important resources.

[API index](/notes/api/) · [Reading](/notes/api/reading/) · [Editing](/notes/api/editing/) · [CLI streams](/notes/api/cli/) · [Moving](/notes/api/moving/)

Content watches report source progress; presence reports temporary awareness. Neither a roster entry nor an activity highlight proves durable mutation acceptance. Mutation receipts remain the authority for accepted writes.

## Implemented selection snapshot

The deployed-contract reference for roster and source-bound selection reads is
[agent presence](/notes/agent-presence/#source-bound-human-selections). Matching
clients expose `memos presence --selections`, TypeScript
`presence({selections: true})`, and Python `presence(selections=True)`. The built-in
agent requests these snapshots automatically when its presence tool runs.
This additive snapshot does not implement the durable watch/replay target below.

## Inspect presence

`presence()` reads the roster without joining or extending the caller's lease. Return participants with server-observed identity, expiry and valid location, plus an observation time. Expired participants are not inferred to be active.

**CLI**

```bash
dl memos presence "$NOTE_ID" --json
```

**TypeScript**

```typescript
const roster = await dl.notes(noteId).presence()
```

**Python**

```python
roster = dl.notes(note_id).presence()
```

**Tool call**

```javascript
notes_presence({ note: noteId })
```

Roster inspection needs no body baseline. If a location refers to another source revision, label that relationship rather than drawing its range against arbitrary current text. Client configuration supplies authentication and attribution; model-supplied names grant no authority.

## Visit a Memo or passage

`visit()` announces the caller once. `intent` is an optional short purpose, not observed progress. Optional `address` or `cursor` locates the visit; accept at most one. A location needs its original source baseline. A general visit without location needs no body baseline.

**CLI**

```bash
dl memos visit "$NOTE_ID" --intent "Reviewing this paragraph" \
  --address s1.p2 --base-revision "$REVISION"
```

**TypeScript**

```typescript
await dl.notes(noteId).visit({
  intent: "Reviewing this paragraph", address: "s1.p2", at: snapshot,
})
```

**Python**

```python
dl.notes(note_id).visit(
    intent="Reviewing this paragraph", address="s1.p2", at=snapshot,
)
```

**Tool call**

```javascript
notes_visit({
  note: noteId, intent: "Reviewing this paragraph",
  address: "s1.p2", baseRevision: revision,
})
```

Location flags extend today's CLI visit contract. Resolve an observed mapped address against its read revision. Addresses directly identify mapped elements; their spans may include descendant blocks. A visit changes awareness, never source.

An exact cursor is a zero-based Unicode code-point offset in original source, not a JavaScript UTF-16 index:

**CLI**

```bash
dl memos visit "$NOTE_ID" --cursor 125 --base-revision "$REVISION"
```

**TypeScript**

```typescript
await dl.notes(noteId).visit({ cursor: 125, at: snapshot })
```

**Python**

```python
dl.notes(note_id).visit(cursor=125, at=snapshot)
```

**Tool call**

```javascript
notes_visit({ note: noteId, cursor: 125, baseRevision: revision })
```

Reject invalid, unavailable or stale locations instead of highlighting unrelated content. Return the accepted location and lease expiry as awareness acknowledgment, not a content-write receipt. A one-shot visit is not a process that stays running.

## Follow successful reads and edits

Attributed CLI and SDK reads/edits update awareness by default. Focused reads publish the passage actually read; whole-document reads publish general reading activity without inventing a cursor. Accepted edits publish a valid edited location in the acknowledged source. Derive or map that range against the receipt's revision.

Rejected or uncertain edits must not publish successful-edit activity. An explicit visit moves awareness manually; the next successful read/edit may move it again. Background integrations need an opt-out; its public option spelling remains to finalize.

Awareness is best effort. If presence or contributing-session association fails after a write was accepted, keep the receipt and report the ancillary failure. Never replay an accepted write to repair a highlight. Ephemeral presence, fading highlights and persistent contributing-session records are different evidence.

## Watch source progress

A fresh `watch()` emits an initial mapped snapshot, then content changes and awareness. SDKs expose typed streams. CLI emits human-readable events or NDJSON under `--json`; diagnostics go to stderr.

**CLI**

```bash
dl memos watch "$NOTE_ID" --timeout 15m --json
```

**TypeScript**

```typescript
const watcher = dl.notes(noteId).watch({ timeoutMs: 900_000 })
for await (const event of watcher) {
  consume(event)
}
```

**Python**

```python
watcher = dl.notes(note_id).watch(timeout=900)  # seconds
for event in watcher:
    consume(event)
```

**Tool call**

```javascript
notes_watch({ note: noteId, timeoutMs: 900000 })
```

Default duration is **15 minutes total**, not an inactivity timeout. TS/tools use milliseconds, Python's proposed `timeout` uses seconds, and CLI accepts a duration. Connection retries must not silently extend the total indefinitely. Explicit overrides need documented bounds.

On timeout/cancellation, stop accepting work, finish the documented output boundary, attempt presence cleanup, and report the last delivered continuation. If cleanup fails, rely on lease expiry; do not claim confirmed immediate removal. Clean timeout is successful completion, distinct from a service error. SDK iteration must expose the end reason.

Tool hosts may impose shorter execution deadlines. Return a bounded batch with continuation before that deadline. Do not promise a synchronous tool can block for all 15 minutes. Tool results wrap the same event schema used by SDKs and NDJSON.

### Reporting cadence

| Event family | Target behavior |
| --- | --- |
| Initial snapshot | Promptly after a consistent source read |
| Content | After 2 seconds quiet; schedule within 5 seconds during continuous editing |
| Presence/cursor | At most once per second; latest state wins |
| Connection failure/end | Promptly |
| Unchanged heartbeat | Silent |

Maximum wait bounds normal scheduling, not delivery through a slow network, blocked consumer or unavailable service. These are watch-output timers: they must not delay writes or rewrite accepted RTC history.

**CLI**

```bash
dl memos watch "$NOTE_ID" --timeout 15m --debounce 2s --max-wait 5s
```

**TypeScript**

```typescript
const watcher = dl.notes(noteId).watch({
  timeoutMs: 900_000, debounceMs: 2000, maxWaitMs: 5000,
})
```

**Python**

```python
watcher = dl.notes(note_id).watch(
    timeout=900, debounce_ms=2000, max_wait_ms=5000,
)
```

**Tool call**

```javascript
notes_watch({
  note: noteId, timeoutMs: 900000, debounceMs: 2000, maxWaitMs: 5000,
})
```

Each content event describes the net change from the **last emitted source** to a later source. Keep base/result revisions, resulting content hash and patch format together. Never apply the patch to another base. A watch update never advances an existing edit's original baseline.

Bound event bytes, pending event count and queued work. Under backpressure, combine content changes against the last delivered base and reduce awareness to latest state. If a patch or queue exceeds budget, explicitly require resynchronization rather than truncating source or accumulating unbounded work. Exact byte/event limits remain to choose.

### Proposed event schema

Common fields identify the Memo, observation time and resumable content position when available. An awareness-only event does not create a durable content position. Expose a token only when supported by the server retention contract.

```typescript
type WatchEvent = WatchEnvelope & (
  | { type: "snapshot"; snapshot: NoteRead }
  | { type: "change"; baseRevision: string; revision: string;
      hash: string; patch: string; format: "diff" }
  | { type: "presence"; participants: Participant[] }
  | { type: "activity"; actor: Actor; action: "read" | "edit" | "visit";
      location?: Location }
  | { type: "connection"; state: "reconnecting" | "connected" }
  | { type: "resync-required";
      reason: "retention-gap" | "history-changed" | "budget";
      lastDeliveredRevision?: string }
  | { type: "end"; reason: "timeout" | "cancelled";
      continuation?: string }
)
interface WatchEnvelope {
  note: string
  observedAt: string
  continuation?: string
}
```

Shared `NoteRead`, `Participant`, `Actor` and `Location` types and the error variant need finalized exported schemas. A service failure is not a clean timeout. A reconnect notice does not prove that missed content was recovered.

## Durable net content catch-up

Durable catch-up is required. Replay content progress, not every keystroke, transport frame or awareness update. Resume from the last delivered content position and return a net diff to later retained source. An edit made then undone between those states may disappear from the net diff; this is not an audit of all intermediate edits.

**CLI**

```bash
dl memos watch "$NOTE_ID" --after "$CONTINUATION" --timeout 15m --json
```

**TypeScript**

```typescript
const watcher = dl.notes(noteId).watch({
  after: continuation, timeoutMs: 900_000,
})
```

**Python**

```python
watcher = dl.notes(note_id).watch(after=continuation, timeout=900)
```

**Tool call**

```javascript
notes_watch({
  note: noteId, after: continuation, timeoutMs: 900000,
})
```

Continuation is separate from the edit baseline and metadata version. Bind it to Memo identity, source history/generation and stream contract. Recheck current authorization; a token is not permission. Retained state must survive the failures and restarts actually promised. An in-memory watcher variable is not durable replay.

Awareness reconnects from current roster/state. If a baseline expired, history was rebuilt or continuation cannot be recovered, return an explicit gap/history-change result. A fresh snapshot recovers current state but is not replay of the missing interval. Preserve local drafts and original edit baselines.

Retention window, token expiry, restart durability boundary, acknowledgment rules and storage budgets remain explicit implementation decisions. Do not claim exactly-once consumption without an acknowledgment protocol. The target is resumable content catch-up, not an unlimited immutable event archive.

## Current support and changes required

The inspected CLI already supports roster inspection, one-shot visit and SSE-driven `read --linger`. It maintains presence, validates source, emits diffs and cleans up leases. Its event shapes and debounce/throttle behavior differ from this target. It currently has **no durable SSE replay**.

Implement the total timeout, maximum-wait scheduling, normalized events, location-aware visits and interface adapters. Durable catch-up requires a backend retention/reconciliation contract; a response field named continuation does not supply it. Content hash, RTC revision and event continuation are not interchangeable.

Continue with [editing and receipts](/notes/api/editing/), [source reads](/notes/api/reading/) or [CLI streams](/notes/api/cli/).

## Durable contributors

Contributing sessions use the same optional identity as presence but survive its
expiry. See the [implemented attribution contract](/notes/agent-presence/#persistent-contributing-sessions)
for supported headers, privacy, failure behavior and coverage. A contribution is a
server-observed `created` or `edited` record; an explicit link has null evidence.
The built-in agent registers this call as `dreamlake_notes_contributors`.

**CLI**

```bash
dl memos contributors "$NOTE_ID" --json
```

**Tool call**

```javascript
notes_contributors({ note: noteId })
```

This read does not join presence, fetch a transcript or grant session access.
Paginate with `nextCursor`; an empty visible page with `hasMore: true` can precede
another accessible session.
