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

Use this guide to implement and review one Memos contract across CLI, TypeScript, Python and model tools. The pages below specify the redesigned API; the [Memos reference](/notes/) and installed CLI help describe the currently supported product. Publishing this design does not implement the client or server changes.

## Method families

- [Read, map and inspect](/notes/api/reading/): complete and focused reads, retained revisions, mapped addresses, exact source, outline, find and diffs.
- [Edit source](/notes/api/editing/): replace, insert, remove, append, whole-body targets and explicit patches.
- [Presence, watch and catch-up](/notes/api/collaboration/): presence locations, bounded event delivery and durable net-content recovery.
- [Create, list and metadata](/notes/api/resources/): optional creation inputs, IDs, pagination, rename, archival, versions and remaining resource decisions.
- [Archive memos and folders](/api/archival/): the concrete HTTP contract, current client interfaces, listing filters and saved-edit restoration.
- [Move across collections](/notes/api/moving/): source IDs, namespace context, destination projects/deep folders and ownership/filing semantics.
- [CLI input, output and errors](/notes/api/cli/): stdin, stdout, stderr, structured results and outcome handling.

Select CLI, TypeScript, Python or Tool call in any code group. The selection is shared across this guide and remembered when local storage is available. Keyboard navigation and copy behavior remain owned by the shared Dockit/UIKit tabs.

## Shared rules

1. Stable resource IDs are primary; a resource handle remembers identity and client context. Opening by ID is synchronous and makes no network request. Names and slugs need explicit or configured namespace context; do not infer ownership from deep folder paths.
2. The callable namespace exposes both a handle factory and collection operations: `dl.notes(noteId)`, `dl.notes.list(...)`, `dl.notes.create(...)`. There is no namespace-then-get sequence.
3. TypeScript operations take one named object; Python uses keyword arguments. Network calls are async in TS. Python's target is sync by default, with a separate async client and matching methods. No mixed value/awaitable method.
4. Model tools have explicit named targets and baselines. Authentication, per-turn capability restrictions and attribution come from trusted invocation context. A tool name is not proof of registration or authority.
5. Preserve original source, revision and hash together. Source hashes, RTC revisions, legacy ETags and event continuation tokens are different values. Do not substitute them.
6. Mapped reads are first-class. Agents and CLI default to mapped output; SDK results retain exact source with structured provenance and can request the mapped view. Partial source can support precise edits but is not a whole-body replacement baseline.
7. Public methods have ordinary names. Converge on RTC/v2 without a legacy/v2 choice, silent weaker fallback or a second body-edit baseline contract. Keep useful conditional overwrite protection and exact exports.
8. A successful source mutation returns an accepted revision; a rejected call confirms no write; an uncertain outcome requires reconciliation. Public command identity is needed before promising safe replay of a lost-response append.

## Open a handle

**CLI**

```bash
export NOTE_ID="507f1f77bcf86cd799439011"
# Pass the ID directly to Notes commands.
```

**TypeScript**

```typescript
const note = dl.notes(noteId)
// No network request yet.
```

**Python**

```python
note = dl.notes(note_id)
# No network request yet.
```

**Tool call**

```javascript
// No handle-creation tool call is needed.
// Pass noteId explicitly to each subsequent operation.
```

`dl` denotes an authenticated client/module configured by its host. `noteId` is an accessible stable Memo ID. Tool snippets use the proposed names, not a claimed portable MCP registration. Keep tokens and private resource IDs out of committed examples.

## Implementation boundaries

Share a browser-compatible TS operation layer between CLI, integrations and built-in agent adapters. It owns validation, edit planning, addressing and receipts. The agent plugin supplies policy, schemas, attribution and presentation; the server owns resource authorization and durable acceptance. React hooks keep UI state around this client.

The live web editor remains a local RTC replica using native operations and a durable outbox. Snapshot-based Memo commands produce edit plans; the server compiles those against retained identities into native RTC operations. Identical transport calls are not required, but operation identity, conflict and recovery guarantees must agree. Do not route every browser keystroke through REST.

Raw RTC operations are an advanced interface, not the default agent contract. A local `commit()` is not a durable server acknowledgment.

## Current versus target

Released-package evidence for the original review was CLI/TS 0.94.0 and Python 0.32.1; inspect the selected installed versions and deployed server independently before running commands. That evidence is not a current-version availability matrix.

- Current TS `source` and `patch` use the original-revision contract; existing `write`/`append` retain body/ETag compatibility behavior. They must not silently back the redesigned RTC names.
- Current CLI uses separate start/end flags for legacy line reads and explicit mapped views; mapped default and `--lines 40:80` are target changes.
- Current list clients use offsets; preserve that behavior during consolidation. Cursors are not required for listing.
- Current SSE/linger notifications are not a durable replay log. Watch continuation/catch-up requires backend support, retention and explicit gap handling.
- Existing move/transfer commands vary by collection. The [move comparison](/notes/api/moving/) preserves current syntax separately from target examples.

The remaining choices are in their owning family pages: source-map encoding/element spelling, method-specific conflict defaults, retention and event budgets, metadata/version/file/sharing schemas, and multiple-project filing ambiguity. Do not fill a missing guarantee by changing an old baseline or silently weakening a call.

## Creating and inserting Memo references

Creation returns the immutable full ID separately from its display name. REST
Memo metadata includes `directive`, a ready-to-insert `:memo[<24-hex-id>]`.
The built-in `dreamlake_notes_create`, list and search tools expose the same
canonical directive. Existing tool names and REST response envelopes remain
compatible; their historical `note` spelling does not select Markdown syntax.

Copy that directive into new Memo or Chat content. Never use the title, slug,
URL, namespace-qualified lookup reference or short display hash in its brackets.
Titles are display labels, so duplicate titles, renames and namespace changes
cannot retarget the immutable identity. Missing/unconfirmed creation identity
requires inspection before retrying, not a guessed directive or another create.

New authored references always use `:memo`; never generate `:note`, including
when older examples or conversations contain it. Saved legacy directives remain
readable and are preserved during unrelated edits. Plain Markdown links remain
supported. A reference does not grant access or publish its target.
