Attachment and object storage
Attachments give Memos a durable record for a file and a controlled link to the memo that uses it. The system keeps file metadata and media facts with the record while placing the bytes in database storage, local storage, or an S3-compatible object store. It uses the record and the memo's access rules to save, read, stream, and remove the file.
See Persistence and data evolution for the store and migration model. See Memo lifecycle and collaboration for memo changes that can affect attachment links. See Drawing attachments for canvas-specific attachment behavior. See MCP, RSS, and file delivery for file delivery, and API contracts and services for the service boundary.
Attachment records
An attachment record is the stable application identity for a file. It holds the creator, filename, MIME type, size, storage location, optional memo link, and optional media payload.
Record identity and content
The record separates file facts from byte location. Its UID is the public identity. Storage fields say whether the bytes are a database blob, local file, external URL, or S3 object.
| Record part | System purpose |
|---|---|
| Identity and ownership | Names the attachment and records its creator and time |
| File description | Stores the filename, normalized MIME type, and size |
| Byte location | Routes reads and deletes to the selected storage |
| Memo link | Binds the file to at most one memo |
| Media payload | Stores media facts and motion-photo grouping |
The upload flow validates the filename, selects a MIME type, and checks the size limit. A missing type uses curated extensions such as HEIC and HEIF, then normal extension data or content sniffing. Chunked uploads stage bytes in a temporary file and repeat access, quota, MIME, and media checks with the complete content at finalization. A rejected new upload is not registered, and a finalization that returns an uncertain post-commit error can resolve the existing record on retry. Storage receives the bytes before the row is saved. If a memo is named, the service also checks the actor's right to write that memo.
References: proto/…/attachment_service.proto• L128-170 store/attachment.go• L16-45 server/…/attachment_service.go• L73-181 server/…/attachment_upload.go• L105-185 server/…/attachment_mime_test.go• L9-54 server/…/attachment_upload_test.go• L54-126
Memo association
An attachment can be unlinked or linked to one memo. An unlinked attachment is private to its creator or an administrator. A linked attachment follows the memo's read rules, so the link is part of the access boundary.
The memo attachment operation replaces the full attachment set. It checks ownership, prevents binding a file already used by another memo, and applies the memo change with the binding changes in one database mutation. Removed rows are cleaned from storage afterward. A lifecycle-only space action cannot change attachment bindings.
Managed attachment references are image URLs in memo content that point to Memos' file route. Each reference must name a bound image attachment that uses managed storage. Root-relative paths are the normal form. Absolute paths must match the configured instance URL. Malformed paths, unsafe URL parts, and raw HTML references are rejected. The editor mirrors this classification and resolves valid references through the attachment record, so visible memo content and attachment ownership stay in step.
References: server/…/memo_attachment_service.go• L21-61 server/…/memo_attachment_service.go• L70-150 server/…/memo_attachment_service.go• L191-255 server/…/memo_attachment_service.go• L360-447 store/memo_attachment.go• L13-165 web/…/managed-attachment.ts• L34-107 web/…/managed-attachment.ts• L120-168 web/…/managed-attachment.ts• L178-234
Attachment deletion
Deletion checks the attachment owner and every linked memo before it removes rows. It also checks managed content references and motion groups. The database repeats the actor, memo, target, and content checks so a concurrent memo change cannot bypass the preflight.
Direct deletion attempts storage cleanup before row deletion. Local cleanup errors stop the row delete. S3 cleanup is best effort, so the row can be deleted while the remote object remains. Bulk deletion removes rows first and then cleans storage from the saved snapshots. Thumbnail and motion caches are removed only after backend cleanup succeeds.
References: server/…/attachment_service.go• L498-608 store/attachment.go• L194-328 store/attachment_delete.go• L19-113 server/…/attachment_service_storage.go• L227-249
Storage selection
Storage selection controls where new bytes go and how old records find their bytes. The instance setting has a default storage and named entries, so a deployment can change the destination for new uploads without moving old objects.
Storage types
Memos supports database, local, and S3 storage for uploaded bytes. External links are also represented as attachments, but Memos does not upload or manage those bytes.
| Storage choice | Byte location | Record location |
|---|---|---|
| Database | Attachment row | Database blob |
| Local | Profile data area | File reference |
| S3 | S3-compatible service | Object key and storage ID |
| External link | Other service | URL |
The default setting also supplies the local path or S3 key template. A missing setting becomes a local default with the normal upload limit and path template.
References: proto/…/instance_setting.proto• L77-139 proto/…/attachment.proto• L9-17 store/instance_setting.go• L359-387 server/…/attachment_service_storage.go• L67-176
Named storage registry
Each configured storage has a stable ID. New S3 records save that ID with the object key. A later read or delete can therefore use the namespace where the object was created. Changing the default affects only new uploads.
Storage updates retain entries still referenced by attachments. Endpoint, region, or bucket changes create a new physical namespace. Credential and transport changes can rotate within the same namespace. Client caches are rebuilt after a setting change.
References: proto/…/instance_setting.proto• L87-124 store/storage.go• L88-207 store/storage.go• L319-347 server/…/instance_service.go• L235-245
Legacy S3 resolution
Older S3 records can contain a full S3 configuration instead of a storage ID. Resolution first uses a matching named storage. If none exists, it uses the embedded configuration. This keeps old objects readable and removable after an upgrade.
References: proto/…/attachment.proto• L78-97 store/storage.go• L210-265 store/attachment.go• L288-373 store/…/01__migrate_storage_setting.sql• L66-88
Object operations
Object operations use the attachment record as the routing point and hide the backend from callers. Upload, full read, streamed read, and delete all select the backend from the saved storage information.
Upload and read paths
The upload path selects the instance default, stages the content, writes it to that backend, and saves the metadata needed for later access. Local writes move a complete temporary file into place. S3 records save a key and storage ID. Database records save the blob.
The resumable upload path accepts bounded chunks at a declared offset. A finish request reads the staged content again, applies the final MIME and media checks, then uses the same processing and storage path as a one-call upload. Repeated finish requests return the saved attachment after completion, which prevents a retry from creating another object under the same UID.
The upload service is available through its HTTP JSON and Connect RPC transports. Both require authentication and bound request size before message decoding. The Connect path also bounds compressed messages, so compression cannot bypass the request limit.
The object contract supports full reads and one byte range. File delivery streams audio and video so clients can seek. It uses the same application behavior for local, S3, and database-backed objects.
This diagram shows how an attachment record routes a request to bytes and then to protected delivery.
flowchart LR
R[Attachment record] --> S{Storage type}
S -->|Database| DB[Database blob]
S -->|Local| FS[Local file]
S -->|S3| O[S3 object by storage ID and key]
S -->|External| X[External URL]
DB --> D[File delivery or API response]
FS --> D
O --> D
X --> D
The file route checks access before serving bytes. Unlinked files require the creator. Linked files use the linked memo's visibility or a valid share context. Managed storage is not returned as a presigned URL in attachment metadata.
References: server/…/attachment_service_storage.go• L26-50 server/…/attachment_service_storage.go• L67-178 server/…/attachment_service_storage.go• L252-307 server/…/attachment_upload.go• L37-103 server/…/attachment_upload.go• L143-185 internal/…/driver.go• L20-33 server/…/fileserver.go• L127-166 server/…/fileserver.go• L222-275 server/…/attachment_upload_test.go• L53-98 server/…/attachment_upload_test.go• L100-185 server/…/attachment_upload_transport_test.go• L34-110 web/…/attachment.ts• L3-40
S3 object lifecycle
The S3 driver uploads with the attachment MIME type, reads whole objects or one byte range, and deletes by key. Named drivers are reused. A storage setting change invalidates the cache so later requests use current connection settings.
An invalid range carries an object length when available. The file service can then return a normal range response. Multipart ranges are served as a complete response rather than passed to S3.
References: internal/…/driver.go• L24-49 internal/…/s3.go• L52-89 internal/…/s3.go• L142-226 store/storage.go• L251-327 server/…/fileserver.go• L334-370
Deletion and cleanup
Deleting an attachment removes its row and its backend object or file. Derived thumbnail and motion caches are also removed. A memo update detaches rows in the database first and performs byte cleanup afterward.
The different ordering of direct and bulk deletion creates different retry cases. Direct deletion can leave a row without bytes when storage cleanup succeeds first. Bulk deletion can leave bytes without a row when cleanup fails after the database commit.
References: store/attachment.go• L194-328 server/…/attachment_service_storage.go• L181-249 store/attachment_delete.go• L19-27
Media metadata
Media metadata describes how an image or video should be shown and what source facts the application can display. The client supplies it at creation. The server validates it and stores it with the attachment.
Normalized media facts
Image metadata can include dimensions, capture time, location, camera and lens facts, exposure values, ISO, focal length, and source EXIF orientation. Video metadata can include dimensions and duration. The attachment API does not update this metadata after creation.
The server accepts metadata only for image and video MIME types. Dimensions must be a positive pair. Time, location, numbers, and text must use safe formats and ranges. Source EXIF orientation describes the input file and must not be applied twice. Unknown fields from a newer client are dropped before storage. For resumable uploads with no declared MIME type, these checks wait until finalization identifies the type from the actual content.
References: proto/…/attachment_service.proto• L76-126 proto/…/attachment_service.proto• L162-169 server/…/attachment_media_metadata.go• L27-79 server/…/attachment_media_metadata.go• L82-203 server/…/attachment_upload.go• L127-140 server/…/attachment_upload.go• L172-184
Media presentation
The client uses one attachment model across memo views, the attachment library, and the editor. MIME type selects the broad presentation group, with formats such as PSD and MIDI kept out of the image and playable-audio groups. Images, videos, and motion photos use visual previews. Audio uses deferred playback. Other files use open or download actions. Thumbnail and motion options remain part of the protected file URL, including share links that already carry a share token.
The editor parses memo content to find valid managed image references and warns about references that the API will reject. It keeps a managed image represented in memo content out of the repeated attachment list while preserving its binding, including the rest of its motion group. It can build, resolve, reorder, or remove attachment references, preview supported media, and send an existing audio attachment for transcription without changing the stored file. Any image can also open in the drawing editor from its local source or managed attachment; an existing drawing file is edited in place through a replacement, while another image is treated as a new annotation.
References: web/…/attachment.ts• L3-40 web/…/attachment.ts• L42-99 web/…/managed-attachment.ts• L67-107 web/…/managed-attachment.ts• L120-168 web/…/managed-attachment.ts• L178-234 web/…/AttachmentIcon.tsx• L25-113 web/…/AttachmentFileRows.tsx• L12-131 web/…/AttachmentMediaGrid.tsx• L18-113 web/…/AttachmentListEditor.tsx• L282-551 web/…/AttachmentListView.tsx• L149-225 web/…/attachmentHelpers.ts• L5-44 web/…/useAttachmentTranscription.ts• L8-44
Privacy and motion media
Uploads inspect the declared MIME type and the leading bytes before applying the EXIF privacy policy. Supported formats are re-encoded with their orientation applied, so location and other EXIF data are removed without changing the displayed direction. A JPEG labeled as a non-image type still receives this treatment. If stripping fails, the original image remains and the upload records a warning. Oversized image dimensions are rejected before decode. Android motion-photo containers stay intact because re-encoding would remove their video.
Thumbnail delivery creates a smaller JPEG for supported images. It avoids conversions that could lose important color or HDR information. Thumbnail and motion outputs are cached locally and removed with the attachment.
Motion media groups related still and video records. Apple Live Photo metadata can be supplied by the client. Android motion photos are detected from JPEG content. Memo association and deletion treat a multi-member group as one unit.
References: server/…/attachment_service.go• L35-71 server/…/attachment_service.go• L190-246 server/…/attachment_service_image.go• L19-69 server/…/attachment_service_image.go• L83-124 server/…/attachment_exif_sniff_test.go• L45-81 server/…/attachment_exif_test.go• L195-208 server/…/attachment_mime_test.go• L9-54 server/…/memo_attachment_service.go• L300-355 server/…/attachment_service.go• L542-585 server/…/fileserver.go• L243-275 server/…/attachment_upload_test.go• L330-364 web/…/attachment.ts• L83-99
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the storage type, record payload, and object read/delete paths aligned.
- Preserve storage IDs when changing the default or rotating S3 credentials.
- Keep legacy embedded S3 fallback behavior for records without a storage ID.
- Keep upload staging and finalization checks aligned for size, MIME, and media metadata.
- Keep memo content validation and memo attachment bindings aligned.
- Keep deletion preflight snapshots aligned with database transaction checks.
- Keep media metadata validation, API immutability, and store payload fields in step.
- Keep motion group rules aligned across set, delete, and file delivery flows.
- Keep range handling consistent for local, S3, and database-backed reads.
- Keep MIME extension fallback and content sniffing aligned with EXIF handling.
- Keep storage compensation aligned with database commit detection.
- Keep direct and bulk deletion ordering aligned with their cleanup contracts.
- Keep client media grouping aligned with motion metadata and managed-image references.
- Keep managed URL classification aligned between the memo API and editor parsing.
- Keep managed attachment filtering aligned with motion-group membership.
- Keep share-token URL handling aligned for thumbnails and motion clips.
- Keep resumable upload ownership, offsets, expiry, and finalization recovery aligned with attachment identity.
- Keep upload-time quota checks aligned at both session start and finalization.
- Keep authentication and request-size limits aligned across HTTP JSON and Connect upload transports.
- Keep compressed message limits enforced before Connect request decoding.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A storage still referenced by old records is removed | Existing S3 objects cannot be read or deleted | Retain inactive named storages and resolve by storage ID |
| An old S3 record has neither a registry entry nor embedded configuration | The object key has no usable connection settings | Keep the legacy configuration or restore its namespace |
| A managed image is not in the memo attachment set | The memo mutation is rejected | Bind each managed image before saving content |
| A resumed upload skips final checks | Invalid content can reach storage | Recheck complete staged content |
| HEIC or HEIF uses only the host MIME table | Image handling can miss the media type | Use the curated extension fallback |
| A rejected upload registers a session before validation completes | Temporary state can remain for invalid input | Validate metadata, quota, and request data before registration |
| A finish request uses stale memo or quota state | A deleted memo can receive an attachment or an over-limit file can be stored | Recheck memo access, media metadata, and quota at finalization |
| A finalization error follows a committed database row | A retry can create a duplicate object or report a false failure | Resolve the stable UID before saving again |
| An upload transport decodes an unbounded request body | A client can consume excess request memory before validation | Bound HTTP bodies and Connect messages before decoding |
| Compression hides an oversized Connect message | The decoded request can exceed the intended transport limit | Enforce the compressed-message limit during transport handling |
| Local cleanup fails during direct deletion | The row remains and deletion returns an error | Retry local cleanup |
| S3 cleanup fails after direct deletion | The row is gone while the object remains | Retry cleanup using the saved storage identity |
| Bulk row deletion succeeds but cleanup fails | Objects or caches remain without rows | Retain snapshots and retry cleanup |
| S3 setting changes do not invalidate the driver cache | Requests use stale connection settings | Reset the driver cache after setting changes |
| Media metadata has invalid dimensions, coordinates, or detail type | Creation is rejected | Validate values against the MIME type |
| Only part of a motion group is removed | The mutation is rejected | Submit the complete group |
| A JPEG is mislabeled and content is not sniffed | EXIF data can remain in the stored image | Sniff bytes before the privacy decision |
| An image exceeds the pixel limit | Privacy processing is rejected before decode | Check dimensions before decoding |
| Creation returns an error after the row commits | Compensation can delete valid bytes or leave an orphan | Compare the persisted row and managed storage identity |
| A lifecycle-only memo action includes attachment changes | The mutation is rejected | Separate lifecycle changes from attachment mutations |
| A managed URL has an unexpected host, query, fragment, encoding, or UID | The editor can show content that the API will reject | Use the same URL classification and invalid-reference checks as the API |
| A share link receives a thumbnail or motion flag without preserving its share token | Protected media preview fails or loses its access context | Add media parameters only to recognized share URLs |
| An inline attachment is filtered without its motion group | Related still or video media remains duplicated in the attachment list | Filter all attachments in the referenced motion group |
Key files
| File | Why to read it |
|---|---|
| proto/…/attachment_service.proto | Defines the public attachment and media metadata contract |
| proto/…/attachment.proto | Defines persisted storage, motion, and media payloads |
| proto/…/instance_setting.proto | Defines default and named storage settings |
| store/attachment.go | Shows the record boundary, storage resolution, and cleanup responsibility |
| store/attachment_delete.go | Shows safe deletion policy and snapshots |
| store/memo_attachment.go | Defines atomic memo and attachment mutation rules |
| store/storage.go | Shows storage identity, legacy resolution, driver reuse, and cache invalidation |
| server/…/attachment_service.go | Coordinates validation, upload processing, access, and deletion |
| server/…/attachment_upload.go | Shows staged chunk upload, finalization, and recovery |
| server/…/attachment_upload_test.go | Demonstrates resumable upload, retry, expiry, quota, and media behavior |
| server/…/attachment_upload_transport_test.go | Demonstrates authenticated HTTP and Connect upload transport limits |
| server/…/attachment_service_storage.go | Maps records to database, local, and S3 bytes |
| server/…/attachment_service_image.go | Shows content sniffing and image privacy processing |
| server/…/attachment_media_metadata.go | Defines normalized media metadata safety rules |
| server/…/memo_attachment_service.go | Shows memo binding, managed content checks, and motion groups |
| internal/…/driver.go | Defines backend-neutral object operations and range errors |
| internal/…/s3.go | Shows S3 upload, read, range, and delete behavior |
| server/…/fileserver.go | Turns stored attachments into protected file and media responses |
| web/…/AttachmentListEditor.tsx | Shows editor grouping, annotation and drawing replacement, preview, reorder, and removal behavior |
| web/…/attachment.ts | Defines client URL variants, media groups, and motion-family checks |
| web/…/managed-attachment.ts | Mirrors managed-image URL rules and keeps memo content aligned with attachment records |
| web/…/AttachmentMediaGrid.tsx | Shows library presentation of visual and motion media |
| web/…/useAttachmentTranscription.ts | Shows transcription of an existing audio attachment |