Memo export and import
Memo export and import provide a versioned way to move one user's memos and linked attachments between Memos instances or accounts. The system writes a readable ZIP archive, validates the complete archive before import writes, and exposes the process through authenticated UserService operations and the Settings page. For the wider memo flow, see Memo lifecycle and collaboration; related memo context is in Memo query and filtering, Markdown content processing, and Space management and membership. Related user-facing flows are in Web settings and account management and Memo authoring and browsing UI.
Export format
The Memos Export Format is a personal transfer format, not a full instance backup. Version 1.0 carries a user's memos, memo content, memo state, visibility, pin state, location, Space hints, comment parents, reference relations, and linked attachments. It does not carry users, settings, tokens, Spaces themselves, revision history, soft-deleted memos, share links, or encryption.
The archive is a normal ZIP file identified by manifest.json. Its main entries are:
- manifest.json, which states the format, version, generator, export time, user scope, and optional counts.
- memos/<uid>.json, which stores one memo record.
- memos/<uid>.md, which stores the exact memo content bytes.
attachments/<uid>/<filename>, which stores local attachment bytes when an attachment is not external.
Memo records use public API JSON names and values. Timestamps use RFC 3339 form. A memo record points to its content file and lists attachment metadata. Local attachment records include a SHA-256 digest so the reader can check that the bytes match the record. External attachments carry a link instead of export bytes.
Export versions use MAJOR.MINOR form. A reader accepts later minor versions of a known major and ignores unknown optional data. It rejects an unknown major because that can change the meaning of existing data. Version 1.0 writes the USER scope and uses NORMAL or ARCHIVED state, the four public visibility values, and REFERENCE relations.
References: docs/…/memos-export-format.md• L13-35 docs/…/memos-export-format.md• L56-96 core/…/format.go• L8-35
Memo and attachment identity
Memo and attachment UIDs are the stable keys inside an export. The archive uses UIDs instead of database IDs. On import, the target account becomes the creator of each imported memo. This lets an archive move between accounts and instances without copying database identity.
The exporter includes every memo created by the requesting user. This includes comments, archived memos, and references to other memos. It includes only attachments linked to those memos. Reactions may be recorded for information, but version 1.0 does not restore them.
References: docs/…/memos-export-format.md• L82-86 docs/…/memos-export-format.md• L126-186 server/…/user_service_memo_export.go• L34-70 server/…/memo_export_test.go• L154-216
ZIP read and write flow
The writer collects the user's export data before it writes the archive. It writes the manifest first, then attachment bytes and their observed digests, followed by memo records and exact Markdown content. The result is a complete ZIP file.
The reader opens the ZIP without extracting it to a directory. It indexes entries, checks expansion and size limits, reads the manifest, validates memo records, checks paired content and attachment entries, and orders parents before comments. It returns a complete validated export or an error. It does not return a partial export after a hard failure.
This diagram shows how user data becomes a checked archive and how an import uses it.
flowchart LR
A[User memos and attachments] --> B[Collect export data]
B --> C[Write manifest and ZIP entries]
C --> D[ZIP export]
D --> E[Read and index entries]
E --> F[Validate format records paths and limits]
F --> G[Ordered validated export]
G --> H[Plan or import into target account]
Unsafe paths, duplicate entries, unsupported compression, encryption, missing paired files, invalid records, oversized entries, and excessive compression expansion stop validation. The reader applies only documented soft fallbacks: unknown state becomes NORMAL, unknown visibility becomes PRIVATE, and unknown relation types are skipped with warnings.
References: core/…/writer.go• L15-116 core/…/reader.go• L19-94 core/…/reader.go• L101-122 core/…/validate.go• L47-187 core/…/path.go• L26-91 server/…/memo_export_test.go• L547-556
Memo export operation
Export is an authenticated file download operation that returns the caller's personal export as a ZIP response. The server gathers the caller's memos and related data before writing the manifest so its counts describe the archive. The response uses application/vnd.usememos.export+zip and the client saves it with the user and export time in the filename.
The current Settings client exposes export only to an instance administrator and requests the current user's archive. It sends a HEAD preflight before downloading the ZIP, so a refused export appears as an error instead of a downloaded error document. The export includes a comment's parent, outgoing REFERENCE targets when readable, reaction details for information, and a memo's Space UID and title as a matching hint.
References: server/…/user_service_memo_export.go• L34-70 server/…/user_service_memo_export.go• L72-165 server/…/user_service_memo_export.go• L168-245 web/…/MemoExportSection.tsx• L56-115 web/…/useExportMemos.ts• L7-29 web/…/memo-export.ts• L19-43 server/…/memo_export_test.go• L415-434
Memo import operation
Import uses a staged upload so the server can validate the complete archive and show its effect before it changes memo state. The caller uploads the ZIP in bounded chunks. A finishing request with validate_only returns a plan and keeps the staged file. A later finishing request applies the selected conflict policy and returns a report.
The import process follows this order:
- Authenticate the target user and stage the upload under that user's upload session.
- Read and validate the complete ZIP before writing memos.
- Compare archive UIDs with memos visible to the target user and build the plan.
- Create, update, skip, or duplicate memo records according to the conflict policy.
- Resolve Spaces, attachments, parents, and reference relations.
- Return counts plus memo-specific warnings and failures.
The importer preserves content and supported metadata where the target account can resolve it. A Space is matched by UID and then by title among active Spaces where the user is a member. If no match exists, the memo is unassigned. A memo with SPACE visibility and no resolved Space becomes PRIVATE with a warning. Parent and reference links use a UID map, so links can follow fresh UIDs when a memo is duplicated or belongs to another account.
Attachments use the normal upload and storage checks. Local bytes are checked against their recorded size and digest. Their media type and file name are checked again. The instance upload limit also applies. An identical unlinked local attachment already owned by the importing user can be bound again instead of stored twice. Other UID conflicts receive a fresh attachment UID. If a memo fails after attachments were created, those new unlinked attachments are removed. A memo failure does not stop other records from being processed. Imported memos and newly stored attachment bytes also use the normal per-user write and upload budgets.
References: server/…/user_service_memo_import.go• L27-87 server/…/user_service_memo_import.go• L129-188 server/…/user_service_memo_import.go• L195-382 server/…/user_service_memo_import.go• L385-427 server/…/user_service_memo_import.go• L430-586 server/…/memo_export_test.go• L227-307 server/…/memo_export_test.go• L609-680
Conflict policies
Conflict policy applies when the importing user already owns a memo with the archive UID. A UID held by another account always receives a fresh UID. The policy does not change the comment parent of an existing memo during replacement.
| Policy | Existing memo owned by caller | UID held by another account |
|---|---|---|
SKIP | Leave it unchanged and count it as skipped. | Create a new memo with a fresh UID. |
REPLACE | Update content and supported metadata in place. | Create a new memo with a fresh UID. |
DUPLICATE | Keep the existing memo and create an export copy with a fresh UID. | Create a new memo with a fresh UID. |
The UID map also makes repeated imports predictable. With SKIP, importing the same archive again leaves existing records unchanged. The report separates created, updated, skipped, and failed records. Warnings remain separate from failures.
References: server/…/user_service_memo_import.go• L195-217 server/…/user_service_memo_import.go• L272-313 server/…/memo_export_test.go• L309-409
Client import and export flow
The Settings page exposes both operations in the Memo export and import section. The export action is visible only to administrators and starts a preflight followed by a ZIP download. Import uses a review step so the user can see the source, export time, memo and attachment counts, new and existing memo counts, and validation warnings before choosing a policy.
The client follows this state flow:
stateDiagram-v2
[*] --> Idle
Idle --> Review: Choose ZIP and validate
Review --> Done: Confirm policy and import
Review --> Idle: Cancel
Done --> Idle: Import another
Review --> Idle: Expired staged upload
The browser uploads the file in chunks. It checks each committed offset and retries a recent unavailable chunk with the same offset and bytes. The default chunk size is 2 MiB, but the server response controls the maximum. If the staged upload expires before confirmation, the page returns the user to the file picker.
The review asks for SKIP, REPLACE, or DUPLICATE only when existing memos are found. The final view shows created, updated, skipped, and failed counts with separate warning and failure lists.
References: web/…/MemoExportSection.tsx• L19-43 web/…/MemoExportSection.tsx• L56-215 web/…/useExportMemos.ts• L7-29 web/…/memo-export.ts• L8-110 docs/…/memos-export-format.md• L237-248
Related interfaces
The feature connects the portable format layer to the public UserService contract. The export file route is /file/users/{username}/export; the client sends HEAD to this route for preflight and then downloads the ZIP from the same route. The import RPC is POST /api/v1/{name=users/*}:importMemos and uses the same request for upload chunks, validation, and the final import.
The import response has three useful stages:
- Progress: upload ID, committed byte count, and maximum chunk size.
- Plan: export details, counts, conflict classes, and validation warnings.
- Report: created, updated, skipped, and failed counts with issue details.
Both operations use normal authentication and access rules. A staged export is limited to 4 GiB, tied to the caller, and expires after inactivity. The server can parse the same staged export more than once for review. A completed import removes the staged file and keeps its report available through the upload ID. Staged files do not survive a server restart.
The product actions are Export memos and Import memos. Memos Export Format names the file format. It is unrelated to a memo's Archived state. Older prerelease files may use format: "memos-archive" and the old archive media type. The reader accepts the old manifest value, and the file picker accepts the old media type. Import validates the manifest and does not depend on the filename or media type.
References: docs/…/memos-export-format.md• L230-270 server/…/memo_export_test.go• L436-570 web/…/MemoExportSection.tsx• L101-215 web/…/memo-export.ts• L19-110
Change checklist
When these files or sections are changed, remember to consider these:
- Update the export reader and writer together when changing entry names, record pairing, supported compression, version rules, or export size limits.
- Keep the plan's UID classes aligned with the importer's conflict and ownership rules.
- Preserve the UID mapping across memo creation, duplicate handling, parent links, reference links, and attachment reuse.
- Keep attachment digest, size, media type, file name, deduplication, and upload-limit checks consistent with the normal attachment pipeline.
- Keep imported memo writes and stored attachment bytes aligned with the per-user write and upload budgets.
- Keep the staged-upload lifecycle aligned across total-size caps, chunk offsets,
validate_only, conflict policy, expiry, and replayed final reports. - Keep the client review state aligned with the RPC result variants and the server's expired-upload error.
- Keep the current
memos-exportidentifier and media type compatible with the legacymemos-archiveidentifier and media type.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Export has an unsafe path, duplicate entry, unsupported method, or encryption | The whole export is rejected before import writes | Validate every ZIP entry name and method in the reader |
| Export declares excessive uncompressed expansion | The export is rejected before entry data is read | Compare declared compressed and uncompressed sizes with the expansion limit |
| Manifest or memo major version is unknown | The export cannot be read | Check format and accept only a supported major version |
| Memo record or content pair is missing | Export validation fails | Require each memo record and its content entry to have a matching pair |
| Attachment size or SHA-256 differs from its record | The affected memo can fail and new attachments are cleaned up | Check entry length and digest before storing bytes |
| Staged export exceeds 4 GiB or its upload session expires | The upload or later import cannot continue | Enforce the total-size cap and bind each session to the caller with an inactivity expiry |
SPACE visibility has no matching active Space | Memo is imported as private and unassigned with a warning | Resolve Space by UID then title and apply the visibility fallback |
| Existing memo has a UID owned by the caller | Import result depends on the selected conflict policy | Show the plan and require SKIP, REPLACE, or DUPLICATE when needed |
| Staged upload belongs to another user | Import cannot continue | Bind sessions to the caller before reading or writing upload data |
| Imported memo or stored attachment exceeds the user's write or upload budget | The import cannot use the normal create or upload allowance | Charge imported memo writes and newly stored attachment bytes through the user rate limits |
Key files
| File | Why to read it |
|---|---|
| docs/…/memos-export-format.md | Format goals, layout, version rules, compatibility, and import/export semantics |
| core/…/format.go | Export vocabulary, paths, version, and media type |
| core/…/reader.go | ZIP validation, expansion limits, attachment checks, and record ordering |
| core/…/writer.go | ZIP creation, digest capture, and entry order |
| core/…/validate.go | Hard validation rules and soft fallbacks |
| server/…/user_service_memo_export.go | User memo selection and export record creation |
| server/…/user_service_memo_import.go | Import plan, conflict handling, attachment import, cleanup, budget charging, and relation restore |
| server/…/memo_export_test.go | Export, staged import, compatibility, conflict, cleanup, budget, and rate-limit behavior |
| web/…/memo-export.ts | Client download, chunk upload, validation, and final import calls |
| web/…/MemoExportSection.tsx | User-facing export, review, policy, and result flow |