Introducing a new way to review your PRs.

Read the announcement

usememos / memos

Memos is an open-source, self-hosted note-taking app that brings your everyday thoughts together in a personal timeline. Your data stays yours, and you choose what to keep private or share.

View on GitHub

25 documents · Updated Nov 20, 2026

docs / attachment-and-object-storage

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 partSystem purpose
Identity and ownershipNames the attachment and records its creator and time
File descriptionStores the filename, normalized MIME type, and size
Byte locationRoutes reads and deletes to the selected storage
Memo linkBinds the file to at most one memo
Media payloadStores 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 choiceByte locationRecord location
DatabaseAttachment rowDatabase blob
LocalProfile data areaFile reference
S3S3-compatible serviceObject key and storage ID
External linkOther serviceURL

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

TriggerConsequenceGuard
A storage still referenced by old records is removedExisting S3 objects cannot be read or deletedRetain inactive named storages and resolve by storage ID
An old S3 record has neither a registry entry nor embedded configurationThe object key has no usable connection settingsKeep the legacy configuration or restore its namespace
A managed image is not in the memo attachment setThe memo mutation is rejectedBind each managed image before saving content
A resumed upload skips final checksInvalid content can reach storageRecheck complete staged content
HEIC or HEIF uses only the host MIME tableImage handling can miss the media typeUse the curated extension fallback
A rejected upload registers a session before validation completesTemporary state can remain for invalid inputValidate metadata, quota, and request data before registration
A finish request uses stale memo or quota stateA deleted memo can receive an attachment or an over-limit file can be storedRecheck memo access, media metadata, and quota at finalization
A finalization error follows a committed database rowA retry can create a duplicate object or report a false failureResolve the stable UID before saving again
An upload transport decodes an unbounded request bodyA client can consume excess request memory before validationBound HTTP bodies and Connect messages before decoding
Compression hides an oversized Connect messageThe decoded request can exceed the intended transport limitEnforce the compressed-message limit during transport handling
Local cleanup fails during direct deletionThe row remains and deletion returns an errorRetry local cleanup
S3 cleanup fails after direct deletionThe row is gone while the object remainsRetry cleanup using the saved storage identity
Bulk row deletion succeeds but cleanup failsObjects or caches remain without rowsRetain snapshots and retry cleanup
S3 setting changes do not invalidate the driver cacheRequests use stale connection settingsReset the driver cache after setting changes
Media metadata has invalid dimensions, coordinates, or detail typeCreation is rejectedValidate values against the MIME type
Only part of a motion group is removedThe mutation is rejectedSubmit the complete group
A JPEG is mislabeled and content is not sniffedEXIF data can remain in the stored imageSniff bytes before the privacy decision
An image exceeds the pixel limitPrivacy processing is rejected before decodeCheck dimensions before decoding
Creation returns an error after the row commitsCompensation can delete valid bytes or leave an orphanCompare the persisted row and managed storage identity
A lifecycle-only memo action includes attachment changesThe mutation is rejectedSeparate lifecycle changes from attachment mutations
A managed URL has an unexpected host, query, fragment, encoding, or UIDThe editor can show content that the API will rejectUse the same URL classification and invalid-reference checks as the API
A share link receives a thumbnail or motion flag without preserving its share tokenProtected media preview fails or loses its access contextAdd media parameters only to recognized share URLs
An inline attachment is filtered without its motion groupRelated still or video media remains duplicated in the attachment listFilter all attachments in the referenced motion group

Key files

FileWhy to read it
proto/…/attachment_service.protoDefines the public attachment and media metadata contract
proto/…/attachment.protoDefines persisted storage, motion, and media payloads
proto/…/instance_setting.protoDefines default and named storage settings
store/attachment.goShows the record boundary, storage resolution, and cleanup responsibility
store/attachment_delete.goShows safe deletion policy and snapshots
store/memo_attachment.goDefines atomic memo and attachment mutation rules
store/storage.goShows storage identity, legacy resolution, driver reuse, and cache invalidation
server/…/attachment_service.goCoordinates validation, upload processing, access, and deletion
server/…/attachment_upload.goShows staged chunk upload, finalization, and recovery
server/…/attachment_upload_test.goDemonstrates resumable upload, retry, expiry, quota, and media behavior
server/…/attachment_upload_transport_test.goDemonstrates authenticated HTTP and Connect upload transport limits
server/…/attachment_service_storage.goMaps records to database, local, and S3 bytes
server/…/attachment_service_image.goShows content sniffing and image privacy processing
server/…/attachment_media_metadata.goDefines normalized media metadata safety rules
server/…/memo_attachment_service.goShows memo binding, managed content checks, and motion groups
internal/…/driver.goDefines backend-neutral object operations and range errors
internal/…/s3.goShows S3 upload, read, range, and delete behavior
server/…/fileserver.goTurns stored attachments into protected file and media responses
web/…/AttachmentListEditor.tsxShows editor grouping, annotation and drawing replacement, preview, reorder, and removal behavior
web/…/attachment.tsDefines client URL variants, media groups, and motion-family checks
web/…/managed-attachment.tsMirrors managed-image URL rules and keeps memo content aligned with attachment records
web/…/AttachmentMediaGrid.tsxShows library presentation of visual and motion media
web/…/useAttachmentTranscription.tsShows transcription of an existing audio attachment