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

This is the **implementation target**, not a claim that the redesigned methods, flags or server guarantees are released. Code tabs compare the same intended action through each interface. Current behavior is called out separately. See the [API index](/notes/api/) for migration boundaries.

## List accessible Memos

Require an explicit namespace or a configured default. `--namespace` and `--ns` are source context everywhere. List with `limit` and zero-based row `offset`, not a page index. Do not store a shared current page on the client.

**CLI**

```bash
dl memos list --ns your-workspace --limit 20 --offset 0
```

**TypeScript**

```typescript
const page = await dl.notes.list({ namespace: "your-workspace", limit: 20, offset: 0 })
```

**Python**

```python
page = dl.notes.list(namespace="your-workspace", limit=20, offset=0)
```

**Tool call**

```javascript
notes_list({ namespace: "your-workspace", limit: 20, offset: 0 })
```

Continue with offset 20, 40, and so on for pages of 20 under the defined response contract. Keep filters and ordering unchanged. The current frontend returns `notes` and `total`; final cross-interface continuation/end fields remain to specify. A short page alone is not a universal end-of-list guarantee. Return ready-to-use stable IDs, resolved namespace and URL where available.

Offset browsing can skip/duplicate resources under concurrent insertion, deletion or reordering. Parallel requests reduce elapsed time but do not guarantee a complete scan. A frozen complete scan needs a separately specified snapshot contract. No cursor migration is part of the consolidation. Search is a separate action.

## Create an empty Memo

`name` and `text` are optional. Omitted text means exact empty source; proposed omitted-name display is `Untitled`. Default visibility is private. Namespace comes from an explicit argument or a configured default; fail clearly when neither exists.

**CLI**

```bash
dl memos create --ns your-workspace
```

**TypeScript**

```typescript
const note = await dl.notes.create({ namespace: "your-workspace" })
console.log(note.id)
```

**Python**

```python
note = dl.notes.create(namespace="your-workspace")
print(note.id)
```

**Tool call**

```javascript
notes_create({ namespace: "your-workspace" })
```

SDKs return a usable Memo handle exposing the stable ID. Structured tool/CLI results include `id`, qualified `ref`, canonical `url` and acknowledged initial-source `revision`; include source hash when finalizing the receipt schema. Do not invent a source acknowledgment if only catalog creation succeeded.

TTY output should show the title, stable ID and a clickable canonical link, with plain URL fallback. A link never grants permission by itself.

## Create with initial source

Every tab creates a Memo titled `Review` with exactly `# Review` followed by one LF.

**CLI**

```bash
printf '# Review\n' | dl memos create "Review" --ns your-workspace --file - --json
```

**TypeScript**

```typescript
const note = await dl.notes.create({ namespace: "your-workspace", name: "Review", text: "# Review\n" })
```

**Python**

```python
note = dl.notes.create(namespace="your-workspace", name="Review", text="# Review\n")
```

**Tool call**

```javascript
notes_create({ namespace: "your-workspace", name: "Review", text: "# Review\n" })
```

Creation plus source initialization must be atomic or expose partial completion with the created stable ID and recovery action. A lost response must not cause the caller to create a second Memo blindly. Existing Python `create_note(text=...)` uses a second legacy forced body write; current TS creates metadata. Those paths are not equivalent atomic creation. Replace that divergence during implementation.

Source input preserves Unicode, CRLF/LF and trailing-newline state. `--file -` explicitly consumes stdin; no body option means empty content, without waiting on piped input. See [CLI streams](/notes/api/cli/).

## Rename a Memo

Rename changes display name. Preserve stable ID and source/RTC history. Slug changes and redirect policy are separate decisions, not an undocumented side effect. No body RTC revision is required for a catalog rename; metadata concurrency needs its own resource version.

**CLI**

```bash
dl memos rename "$NOTE_ID" --name "New title"
```

**TypeScript**

```typescript
const result = await dl.notes(noteId).rename({ name: "New title" })
```

**Python**

```python
result = dl.notes(note_id).rename(name="New title")
```

**Tool call**

```javascript
notes_rename({ note: noteId, name: "New title" })
```

A name-only [move](/notes/api/moving/) may delegate to this same rename implementation. A simple rename must not accidentally require an ownership transfer or change access. Return stable ID, resulting name and canonical URL. Collision/empty-name rules and concurrent rename preconditions remain to finalize.

## Saved versions

Named immutable versions differ from retained RTC revisions. Listing versions, reading one, saving one and restoring it are distinct actions. The following names are proposed; Python helpers and shared receipt contracts are not yet verified as implemented.

**CLI**

```bash
dl note hist "$NOTE_ID" --ns your-workspace
dl note read "$NOTE_ID" --ns your-workspace --version "$VERSION_ID"
```

**TypeScript**

```typescript
const versions = await dl.notes(noteId).versions.list()
const saved = await dl.notes(noteId).versions.read({ versionId })
```

**Python**

```python
versions = dl.notes(note_id).versions.list()
saved = dl.notes(note_id).versions.read(version_id=version_id)
```

**Tool call**

```javascript
notes_versions_list({ note: noteId })
notes_versions_read({ note: noteId, versionId })
```

Version reads return saved content and immutable version metadata, not a baseline for an unguarded current write. A restore must read current source and explicitly apply the saved target with conflict/recovery guarantees. Define retention, pagination, save preconditions and restore receipt before exposing new helpers. Do not equate durable watch catch-up with an archive of every intermediate version.

The CLI snippets here use target `--ns`; the installed command's current namespace flag remains authoritative until the alias ships.

## Archive a Memo or folder

Archive is separate from deletion, sharing, tags and saved versions. The
[archive API contract](/api/archival/) documents the concrete HTTP operations,
current CLI/TS/Python methods, registered built-in tools and query filters. These
additions use the existing client interfaces; they do not imply that the broader
handle redesign on this page has shipped.

An archived Memo retains its source, stable identity, attachments, project filings
and Bindr memberships. Active listings exclude archived items unless requested
with `includeArchived`; changed durable edits and explicit unarchive restore the
item and its valid live folder paths. Reads and unchanged saves do not.
Independently archived siblings and deleted items remain unchanged. Keep archive
changes as their own metadata operation; never encode archival as a delete or tag.

## Delete a whole Memo

Reserve `delete()` for deleting the Memo resource. [Remove](/notes/api/editing/#remove-selected-source) deletes selected text instead. Do not use one ambiguous delete method for both. A final delete tool/CLI spelling, soft-delete/restore guarantees, ownership requirements and confirmation behavior remain to review; this page deliberately does not invent a callable mutation.

Delete must distinguish an accepted deletion from an unknown outcome. Never recreate a Memo to simulate recovery. Resolve current authority and stable identity before mutation; body revision and metadata permission are separate concerns.

## Remaining resource families

The following need method-by-method review before publication as executable reference:

- Metadata summary/visibility: distinguish catalog properties from source; visibility and sharing are independent.
- Shares: granting, revoking, listing recipients and removing grants need explicit resource authorization and results; sharing success proves no body save.
- Project filing: clarify additional affiliations versus moving one existing filing. See [multiple filings](/notes/api/moving/).
- Attachments: file identity, exact paths, conditional versions, collision behavior and byte upload/download receipts.
- Media: hosted URLs have different permission semantics from Memo attachments; do not silently substitute one for the other.
- Cross-Note file move/copy and resource restore: negotiate actual server capability, preserve operation identity, and report partial/unknown results honestly.

Current command inventory is not authority to mutate user resources. Once each contract is settled, add a four-interface example for the same action here or in its owning method-family page.
