DreamLake

Agent presence and activity

Agreed lifecycle and identity

Presence is opt-in. Agents can read and edit using normal authentication and revision checks without any agent ID, join, heartbeat, or leave. A runner opts in by supplying a stable session ID. The client generates it (a UUID once per task), not the server. Names and IDs are self-reported, grant no permissions, and are not verified audit identity. Two clients under the same authenticated owner can reuse an ID; random UUIDs prevent accidental collisions, not deliberate impersonation.

Presence means active in this memo recently, for both humans and agents. It is not proof that an agent is continuously watching, reading, or typing. Reuse the existing RTC awareness channel and header badge; do not add a status row below the bindr row.

Keep three identities separate:

IdentityPurpose
Agent identity / display nameIdentifies the agent; its name is a supplied label, not verified model identity.
Task/session IDStable across all CLI calls in one task; distinct for concurrent sessions, even for the same agent.
Human ownerDerived from authentication, not an agent-supplied owner field; attribution does not imply the owner is present.

The runner creates the task/session ID once, retains it across tool invocations, and passes it to every Memos command. Do not generate an ID on every command or use a shared display name as the session key. Resume the same ID for the same task; use a new ID for a new or concurrent task. Socket reconnections have their own transport IDs and must not create a new logical participant.

The current DREAMLAKE_AGENT_ID / X-DreamLake-Agent-Id field carries this task/session ID, despite its name. It does not yet represent a separate, persistent agent-account ID. The roster key is scoped by memo, authenticated owner, and session ID; the display name is never the key.

EventIntended behavior
First attributed read/editImplicitly join and start the recent-presence timeout.
Later read/edit with the same session IDRefresh the existing badge, without adding another participant.
InactivityRemove the badge after expiry; no cleanup command is required.
Explicit leave/unjoinRemove that session from that memo immediately; do not erase its identity.
Interaction after leave or expiryImplicitly rejoin using the same session ID.
Optional explicit join or maintained sessionSupport clients that need sustained presence; ordinary CLI use does not require it.

Human clients can send leave on navigation away or memo closure. Abrupt tab close, crash, or network loss may prevent delivery, so expiry is still required. Agents have the same optional leave and expiry fallback. A session ID is identity, not a live lease: storing the ID does not keep a badge alive. Neither a TUI nor a continuous edit stream is required for recent presence.

Read activity uses the existing human selection and cursor display, with the agent label and participant color. It selects the returned source range; a full-body read selects the full source, and incremental changes do not claim a whole-source selection. New read/focus activity replaces the previous selection. Search does not add a separate seek event. Do not render a second agent-specific selection style or a tool-call log.

Insertion/replacement text uses a fading highlight only after acknowledgement. Deletion has no special marker in this iteration. Failed writes and dry runs never produce success highlights. Agent read selections expire after 8 seconds; completed edit highlights fade over 5 seconds. Neither heartbeat nor badge renewal extends those lifetimes. A completed edit may finish fading after its author leaves. Human cursors retain relative CRDT anchoring; CLI selections are exact-source-hash bound and disappear on source changes, rather than guessing a new position.

People and agents share participant-color rules, not action-specific colors. Use an agent icon and agent/owner labels to distinguish them; do not rely on color alone. Concurrent sessions must remain distinguishable even when names match.

The agent defaults are a 60-second recent-presence timeout and a 5-second completed-edit fade. Agent passage activity has an independent 8-second expiry. Human selections come from the browser connection’s current RTC awareness; they can change or clear on focus changes and do not inherit the agent activity TTL. These are DreamLake choices, not asserted Google Docs, iMessage, or Claude Tag timing constants.

Availability and optional controls

An attributed operation uses the lifecycle above and implicitly joins or renews the same 60-second presence entry. Anonymous agent identity is not inferred from ordinary API calls. A separate persistent agent-account identity is not yet part of the wire contract. Deployment and client release status must be checked independently of this source documentation.

CLI 0.27.0+ and Python SDK 0.21.0+ support attributed reads and edits. CLI 0.29.0+ adds visit and read --linger; CLI 0.31.0+ adds the read-only presence command and event-driven selections. These require matching server capabilities; a successful read does not prove presence or event support. The CLI uses the active login's API; running a locally installed binary does not select a local server. Use --remote <url> to test a specific API or --debug for the local development server.

To check a matching API, use an accessible test memo and the stable task identity below. Run a read, inspect notes presence, then start read --linger and stop it with Ctrl-C to verify automatic session cleanup. Verify patch support separately on a disposable memo with a merge patch, an exact readback, and a stale exact request that must fail without changing the source. Do not use an existing user document as a write-test fixture.

Read and linger in the foreground

CLI 0.29.0+ adds notes read --linger and notes visit. They use the deployed Memos v2, presence-roster and agent-activity endpoints. Python has no corresponding convenience method yet.

Set DREAMLAKE_AGENT_ID once to a unique, stable task-session identity (and optionally DREAMLAKE_AGENT_NAME) as described below. NOTE_ID must identify a memo you can access as a member or explicitly shared reader.

bash
# NOTE_ID and the stable task identity must already be set.
dl memos read "$NOTE_ID" --linger

Use the default text output for people and coding agents. It shows readable diffs, participants, and quoted selections. JSON is optional and intended only for a program that explicitly needs to parse structured events.

The command registers presence automatically, prints the complete source with its hash/revision and the other current participants, and stays in the foreground. A separate visit is optional. Interrupt with Ctrl-C or SIGTERM to stop and send leave. No background daemon is spawned. Presence expires after its server lease if the process is killed or cannot send leave. Use one linger process per note/task identity; multiple keepers using the same identity share one lease.

Edit delivery is debounced: wait until the observed source has been quiet for --debounce (default 2s), then deliver one unified diff from the last emitted content baseline through the end of the burst. Each newly observed edit restarts that quiet timer. Continuous editing keeps the diff pending; there is no forced maximum-wait flush. Stopping before the quiet period ends discards the pending notification, not any document edits.

All output batches are throttled by --throttle (default 2s): no two update batches are emitted closer together than that interval. Presence and activity can still be delivered while edits continue; they do not reset the edit quiet timer. Once a diff is ready it joins the next eligible output batch, so a recent presence batch can delay it until the throttle expires. The first source snapshot is immediate. No new batch is emitted merely because a timer elapsed.

Both flags require --linger and accept explicit ms, s or m units, including fractions, from 250ms through 5m. Bare numbers, zero, negatives and out-of-range values are rejected before presence registration. For example:

bash
# One second of edit quiet; no more than one output batch every two seconds.
dl memos read "$NOTE_ID" --linger --debounce 1s --throttle 2s
# Slower text output for a coding agent or a quieter session.
dl memos read "$NOTE_ID" --linger --debounce 2s --throttle 5s

CLI 0.42.0+: --intent "…" publishes a self-reported purpose with the session — one short, specific sentence in the agent's own voice, shown to collaborators in the agent's presence card. It is sent once at join; heartbeats preserve it, and leave or lease expiry removes it. The flag requires --linger (notes visit also accepts it for one-shot presence). The server trims the text and rejects empty values and more than 280 Unicode code points.

bash
dl memos read "$NOTE_ID" --linger \
  --intent "I'm reviewing this sequence to make the pacing clearer."

CLI 0.31.0+: linger subscribes to authenticated GET /namespaces/:slug/notes/:noteId/events (SSE). CLI 0.29.0–0.30.0 used polling. The event stream requires a matching server; there is no silent polling fallback.

The server observes the existing RTC connection events and coalesces them to at most one batch per 250ms. The CLI keeps only the latest selection per browser connection, emits at most one update per --throttle, and delivers the final selection after a drag stops. Continuous dragging does not restart a debounce timer. Content diffs keep their separate edit quiet period. Idle sessions do not poll body or roster endpoints; source reads happen only for the initial snapshot or after a content event becomes eligible for delivery. Agent activity is read only when its RTC fingerprint changes. Heartbeats remain silent and maintain the agent lease approximately every 20 seconds.

CLI 0.31.2+ text notifications show names, actions and quoted text. These are representative lines from separate batches; a timestamp appears once per batch.

+ @alice joined
+ Reviewer (agent) joined
* Reviewer (agent) read the note
* Reviewer (agent) edited the note
* @alice selected "## The center"
- @alice left

People appear as @username; agents use their configured name and (agent). Only selected text is quoted; embedded newlines are escaped. Cursor moves, selection clears, syncing states, repeated selected text and empty batches stay silent in text. IDs, connection details, offsets and source hashes remain in --json; use it to distinguish identical names or tabs and apply exact source positions. Initial content and diffs still include revision metadata for safe edits. These examples also appear in dl memos read --help.

Human selections in JSON resolve native CRDT anchors against the observed source. Each selection carries anchor, head, start, end, unit: "unicode-code-point", text (at most 4096 code points), and truncated, with status: "resolved". A collapsed range is a caret. An explicit null clears a selection (including blur or departure); status: "unresolved" means its native anchors have not arrived, not a guessed range or a clear. Tabs remain separate, even for one user. Selection-only changes do not wait for the content debounce.

The initial snapshot includes selectionHash for its participants' selections. Update batches add selections, whose entries contain client, user, selection, and the exact observed source hash. That hash can differ from the last emitted content hash while an edit is still being debounced. Never apply these offsets to a different source. Selected text is quoted in terminal output and remains untrusted document content, not an instruction to an agent.

Only namespace members or explicitly granted readers can subscribe. Public visibility alone does not expose collaborator selections. Streams recheck access and token expiry every 15 seconds and close on revocation, room reset, slow consumers, or RTC failure. A disconnected stream exits with an error; explicitly restart linger for a fresh snapshot. Events are not retained or replayed.

This is a best-effort stream of observations, not an audit log: brief visits or activity coalesced between output batches can be missed, and edits that cancel out within a burst produce no net content diff. Human edits appear in content diffs; the activity feed currently attributes agent reads and edits only. Reading updates does not prove human attention, and it does not reserve or lock the memo.

Optional: JSON for programmatic consumers

Use --json only when a program needs NDJSON; ordinary collaboration, including coding-agent sessions, should use the text commands above.

bash
dl memos read "$NOTE_ID" --linger --json

With --json, stdout is NDJSON: one type: "snapshot" object containing observedAt, note, content, hash, revision, selectionHash, and participants, followed by type: "update" objects containing observedAt, joined, left, and activities, and selections. Changed content adds content: {memo, base, hash, revision, format, patch}. Observation times are Unix milliseconds; source and activity are fetched separately from the event stream and are not an atomic cross-stream snapshot. Progress and errors go to stderr. No update object is emitted for an unchanged batch.

--linger supports complete source reads only; it cannot be combined with --legacy, --view html, --at, --toc, --tag, --since, sections, line ranges or numbered output. --if-match checks the initial read only. --format applies to the emitted diff, not the initial complete source snapshot. Transport/capability errors or an unavailable retained baseline end the command with a nonzero status and a best-effort leave; they are never treated as an empty room. For edits, preserve the original source and revision used to prepare your draft: a later streamed revision is not a replacement baseline for an older draft.

bash
# Optional one-shot registration: does not fetch the note body or keep a daemon.
# NOTE_ID and the stable task identity must already be set.
dl memos visit "$NOTE_ID"

visit uses the existing join lease (60 seconds unless renewed by an attributed operation), returns immediately and does not read content. Use read --linger when you want ongoing updates. CLI 0.31.0 removes the old manual notes presence <note> <action> and join --watch controls.

read --linger manages joining, heartbeats, and leaving automatically. Stop it with Ctrl-C when finished; one-shot reads and visit expire naturally. There is no manual lifecycle sequence to run alongside it. Never start an untracked helper that outlives the task.

Read who is present

In CLI 0.31.0+, presence reads the current roster without joining or refreshing your session. It does not require an agent ID. Text is the default:

bash
dl memos presence "$NOTE_ID"

Add --json only for a program consuming the roster. There are no direct notes join, notes heartbeat, or notes leave commands. Use visit, read --linger, and Ctrl-C for participation.

Low-level HTTP lease protocol

SDK integrations and linger use the HTTP protocol below internally. It is not a manual CLI workflow.

API: POST /namespaces/:slug/notes/:noteId/presence accepts {action, hash?, ranges?: [{start,end}], intent?}, bearer authentication, X-DreamLake-Agent-Id, and optional X-DreamLake-Agent-Name. Actions are join, heartbeat, read, edit, seek, clear, leave. Response is {state} or {state:null} after leave. Only authenticated members or explicitly shared readers may publish; edit also requires write permission. Public visibility alone does not grant presence access. Controls do not mutate document content or revision. Owner metadata comes from authenticated lookup.

intent is the agent's self-reported purpose — one short plain-text sentence in the agent's own voice, such as "I'm reviewing this sequence to make the pacing clearer." Omitting the field preserves the current purpose, {"summary": "…"} replaces it, and an explicit null clears it, on any action. Summaries are trimmed; empty strings and more than 280 Unicode code points are rejected with 400 invalid_presence. The server stamps updatedAt; clients cannot supply owner attribution or timestamps. Intent lives with the presence lease: leave or lease expiry removes it, and a later join never resurrects an expired purpose. clear keeps its existing meaning — it clears passage activity, not intent. Intent is a self-reported claim, not observed activity, progress, or a permission grant; the roster's authorized readers can see it.

Read who is present (HTTP API)

GET /namespaces/:slug/notes/:noteId/presence returns the current RTC awareness roster, including humans and agents. Use bearer authentication as a namespace member or explicitly shared reader. Public visibility alone is insufficient. Agent identity headers are not required, and the observer does not publish presence, renew an agent lease, or edit the memo.

Successful reads default to text/plain; charset=utf-8 (also available with ?format=text):

Observed at: 2026-09-26T08:00:00.000Z
- human: "Ge" (id: "ge"; client: "browser-session-123")
- agent: "Codex" (id: "agent:owner-id:agent-id"; client: "note-agent-session-456"); owner: "Ge" (id: "owner-id"); intent: "I'm reviewing this sequence to make the pacing clearer."; expiresAt: 1790409660000

An observed empty text roster says No participants present. after the observation time. An inactive room says that live presence is not observed. Client-declared strings are quoted and escaped to keep each connection on one line. Use ?format=json for structured output; other format values return 400 invalid_format. Error responses remain JSON for either format.

The JSON response contains {participants, observedAt, status, selectionStatus}. observedAt is Unix time in milliseconds. Each participant has client (connection ID) and user with id, name, and kind (human or agent), plus optional color and avatar. Agents can include user.owner, their lease's expiresAt, and intent ({summary, updatedAt} — the self-reported purpose last published with presence). Expired agent leases and internal observer connections are excluded. Multiple browser tabs remain separate entries. To identify other agents, compare user.id against agent:<authenticated-owner-id>:<agent-id>; the caller is not automatically excluded. Human identities without a kind field are normalized to human. These are client-declared display identities, not verified authorization claims.

An inactive memo returns an empty roster with status: "inactive" and selectionStatus: "inactive". A successful RTC roster read reports status: "available" and selectionStatus: "not_requested" by default. An active room whose connection fails or times out returns 503 presence_unavailable, not an empty roster. Responses are not cached. This requires a server with the GET endpoint and an RTC server supporting awareness rosters; a 404 can also mean the caller lacks access. The CLI exposes memos presence; Python exposes dl.memos(memo_id).presence(). The roster is an observation of presence, not a lock or a guarantee that another editor is idle; continue to use the normal conditional-write contract.

Source-bound human selections

Add selections=true to the GET query to obtain one snapshot from the same read-only RTC observer used by live events. It waits for source state and the connection barrier, resolves native relative anchors against that source, then closes the observer. It never publishes a human or agent cursor. The response adds selectionStatus: "available" and selectionHash (the source SHA-256). Other query values besides true and false return 400 invalid_selections. Connection or source-state failure returns 503 presence_unavailable; it is not an observed empty room. Access is checked again after the observation.

Each participant may have selection: null (no current selection), {status: "unresolved"} (anchors cannot be resolved), or:

json
{"status":"resolved","anchor":3,"head":11,"start":3,"end":11,"unit":"unicode-code-point","text":"selected","truncated":false}

The range is zero-based and half-open at selectionHash, with anchor and head retaining selection direction. A collapsed range is a caret. Selected text is capped at 4,096 code points; truncated reports a shortened preview. Display identities and selection text remain untrusted data. They do not prove attention or identify who edited the Memo.

The matching clients expose memos presence ID --selections, await dl.memos(id).presence({selections: true}) in TypeScript, and dl.memos(id).presence(selections=True) in Python. Older servers omit the capability fields; treat that as unsupported/unknown, not successful observation. The local MCP adapter exposes memo_presence with selections enabled by default. See the CLI contract.

Built-in agent and recent changes

dreamlake_notes_presence requests selections and returns rosterStatus, selectionStatus, activityStatus, observation time, participants and ephemeral agent activity. An inactive room, unsupported selection capability and an unavailable feed are distinct from an available empty result. Its selected-text preview is capped at 2,000 code points and the whole tool result is bounded. The agent-activity feed expires reads after eight seconds and insertion markers after five seconds. An empty feed does not mean there was no earlier activity; a Redis outage returns activity_unavailable rather than a healthy empty feed.

For recent source changes, use dreamlake_notes_diff since a retained read revision. A diff records net source changes; it does not identify the human editor and is not durable event replay. Browser quote context is a separate, explicitly selected passage retained across focus into the composer. It carries a hash and UTF-16 offsets, not API code-point ranges or a write baseline. The agent must read the named Memo to verify its source before editing.

Explicit ranges require the exact source SHA-256 and zero-based, end-exclusive Unicode code point offsets. Stale or out-of-bounds locations are refused. A collapsed seek is a caret, not a claim that text was read. Source changes invalidate hash-bound markers. Deletion-only edits do not invent insertion ranges. Errors include missing identity/invalid input (400), denied access (404), stale range (409), expired heartbeat (410), and unavailable relay (503).

Identity values accept 1–128 ASCII letters, digits, dots, colons, underscores and hyphens; names accept at most 64 printable ASCII characters. CLI 0.27.0+ and Python SDK 0.21.0+ attach identity headers to Memos body/section/diff operations when the environment variables below are set. visit and read --linger require CLI 0.29.0+ and an active collaborative room; read-only presence requires CLI 0.31.0+. The old manual action commands were removed in 0.31.0. Updating a skill does not update a binary or deploy a server. Python roster reads do not join or renew a lease. The authorized agent-activity feed retains operation observations, not an online roster. Observation failures must not turn an acknowledged edit into an apparent failed edit. Live source-range decorations currently require the collaborative editor; read-only views do not run an RTC client.

Identity, names and photos

Use a readable agent prefix plus a UUID as the task ID, for example codex:7b52e4d1-3ac9-4d88-b2a6-61f03c927ea5. Generate it once per task and reuse it across reads, edits and linger sessions. Concurrent tasks need different IDs; a display name such as Codex does not distinguish their sessions. The CLI sends DREAMLAKE_AGENT_ID as X-DreamLake-Agent-Id and DREAMLAKE_AGENT_NAME as X-DreamLake-Agent-Name. No separate identity-registration request is required.

Display fieldHumansAgents
Presence identityUser namespace slugagent:<authenticated-owner-id>:<task-id>
Display nameProfile name from /auth/me, falling back to namespace slugDREAMLAKE_AGENT_NAME, falling back to AI agent
Header avatarProfile photo, or initials when absentBot icon
TooltipName and presenceAgent name, owner name, stated purpose (intent), activity and task/session ID

The server derives an agent's owner from authentication and looks up the owner's profile name/photo; an agent cannot assign an owner through these headers. The owner's photo is carried in metadata but is not currently rendered as the agent's header avatar. Owner attribution does not mean that the owner is present.

The header deduplicates connections by identity: multiple browser tabs show one human avatar, while unique agent task IDs show separate agent avatars. It shows up to four avatars plus an overflow chip. Colors are derived from identity. The HTTP roster still returns one entry per connection. Browser awareness names and photos are display metadata, not an authorization source.

Agentic usage pattern: one identity, normal commands

For agent-driven Memos work, set both identity variables before the first live read or edit, unless the user explicitly requests unattributed work. This is a workflow prerequisite for attribution, not a requirement for saving content. Without DREAMLAKE_AGENT_ID, an edit can save successfully while producing no agent presence or attributed fading edit highlight. DREAMLAKE_AGENT_NAME provides the readable label.

Initialize once in the runner's task environment. For separate shell tool calls, the runner must inject the same saved values each time; an export in one shell does not propagate into later independent shells. No explicit join is required.

bash
export DREAMLAKE_AGENT_ID="${DREAMLAKE_AGENT_ID:-codex:$(python3 -c 'import uuid; print(uuid.uuid4())')}"
export DREAMLAKE_AGENT_NAME="${DREAMLAKE_AGENT_NAME:-Codex}"
NOTE_ID="<full-note-id>"

Run ordinary commands with that identity. An attributed read automatically registers or refreshes presence; a preceding visit is never required. Reading without agent identity does not invent or register an agent session. Retain the generated ID in the task context and inject that same literal value into each later shell; rerunning the UUID fallback in a new shell would create a different session.

After the first intended live read, verify attribution with dl memos presence "$NOTE_ID" (CLI 0.31.0+). This only inspects the roster; it does not register an agent. Check the task ID and display name, not merely another session named Codex. If absent, check the environment passed to the actual read/edit process before diagnosing a UI regression. Do not repeat a successful edit to trigger its highlight. Presence expires about 60 seconds after the last activity; completed edit highlights fade over 5 seconds and require an exact matching live document revision. A roster entry verifies presence only: report a highlight as visually verified only after observing it in the collaborative editor.

CommandReads contentPresence lifetime
notes read "$NOTE_ID"OnceRegisters/refreshes presence, then the lease expires naturally
notes read "$NOTE_ID" --lingerInitial source and ongoing updatesRegisters automatically and maintains presence until stopped
notes visit "$NOTE_ID"NoRegisters once, returns immediately, then the lease expires naturally

The last two commands require CLI 0.29.0+. A normal read does not mean the agent remains actively reading between commands.

bash
dl memos read "$NOTE_ID" --json > baseline.json
dl memos find lighthouse --note "$NOTE_ID" --json
# Draft a reviewed patch against baseline.json, using the patch workflow below.
# Retain its revision, apply the patch, and read back the acknowledged revision.

The conditional patch and exact-readback examples elsewhere in this guide remain required; presence does not relax concurrency checks. Do not retry an old patch with a newly fetched revision merely to force it through.

When finished, stop read --linger with Ctrl-C; it sends leave automatically. One-shot operations expire naturally. Keep the same session ID between commands, and remove the task identity from the runner's environment when the task ends. Lease expiry handles abrupt exits without requiring remembered cleanup.

Persistent contributing sessions

Agent presence and durable contribution attribution share the request's optional session identity. A presence lease expires; a contribution remains attached to the Memo and the saved session. The server records created after successful Memo creation and edited after a native body/section write is acknowledged. A read, visit, self-reported editing state, failed write, or no-op is not a contribution. Replayed command receipts do not repeat attribution.

Use an authenticated request with either:

  • X-DreamLake-Terminal-Session-Id: the exact saved session ID owned by the caller.
  • X-DreamLake-Session-Provider: codex|claude and X-DreamLake-Session-Id: the actual native session UUID. A unique owned match is reused; a new identity gets a private metadata-only archive, without a launch directory, target or conversation upload.

X-DreamLake-Agent-Id and X-DreamLake-Agent-Name remain the presence identity and label. Without an agent ID, valid session context supplies a stable presence ID. Built-in agents use their existing saved conversation ID. Arbitrary presence labels and mentions never establish a conversation identity. Set X-DreamLake-Session-Affiliation: 0 to suppress durable attribution.

GET /namespaces/:slug/notes/:noteId/contributors lists the same authorized, paginated sessions as the resource-session catalog. It accepts pageSize (1–50), cursor and q. Responses contain sessions, hasMore and nextCursor. Each session carries contribution: {kind, firstAt, lastAt} for server-observed writes, or null for explicit/legacy links. These are not edit counts or a full audit log. The reader must independently be allowed to read the Memo and each session.

bash
# CLI with the matching release; this is read-only and does not join presence.
dl memos contributors "$NOTE_ID" --namespace "$NAMESPACE" --json

The built-in agent exposes the same read as a real tool:

javascript
dreamlake_notes_contributors({ note: noteId, namespace: namespaceSlug })

Normal Memo edit tools already carry the conversation identity; no follow-up "mark contributed" call is needed. Direct browser RTC edits without a session identity are not attributed to a terminal session. Historical links remain links; no authorship is inferred from access, similar names or Memo mentions.

Optional attribution has a bounded wait and bounded outstanding work. If it is unavailable, content saves still succeed; a late record may appear on refresh. Never replay an accepted content write to repair metadata. Presence expiration, missing metadata and contribution-list errors do not prevent normal Memo editing.