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 / memo-lifecycle-and-collaboration

Memo lifecycle and collaboration

A memo is the main user-owned record for writing and sharing Markdown content. The memo service manages its active or archived state, space placement, access rules, related records, and derived content so that the same memo can support private notes, public posts, space discussions, comments, collaborative signals, and refreshed payload data. The web client presents this record as a card or detail view with editing, reactions, attachments, relations, comments, and navigation back to the originating list.

Memo resource

Core memo data

The memo resource combines user content with the state needed to find and present it. Its content is Markdown. The service also exposes the creator, timestamps, visibility, space placement, pin state, tags, a short plain-text snippet, a parent memo when the record is a comment, and computed properties such as links, code, and task lists. Attachments, relations, and reactions enrich the resource without changing its role as the central content record. The web view uses this composed resource to show the body, metadata, reactions, related memos, and location. See Markdown content processing for how content becomes tags, snippets, and other derived values. See Memo payload processing for how derived memo data is detected and refreshed. See Space management and membership for how space placement defines an audience. See Memo authoring and browsing UI for the wider client experience.

References: proto/…/memo_service.proto• L193-275 proto/…/memo.proto• L7-29 server/…/memo_service_converter.go• L26-102 web/…/MemoBody.tsx• L29-80 store/memo.go• L47-68

Memo state

An active memo has NORMAL state and participates in normal reads and lists. An archived memo remains owned by its creator but is kept out of normal listings and is not available to other readers. The API can list archived memos when the caller is the creator; deletion is a separate destructive action. A memo with an invalid creator cannot be returned as a readable resource. A memo with invalid SPACE placement fails closed for the SPACE audience, while a memo with another audience can still follow that audience rule and omits the stale space placement from its response.

References: proto/…/common.proto• L7-11 proto/…/memo_service.proto• L298-340 server/…/memo_service.go• L85-111 server/…/memo.go• L55-79 server/…/memo_resolve.go• L26-52 server/…/memo_service_converter.go• L105-137

Memo lifecycle

The memo lifecycle moves from authenticated creation through selective updates and access-controlled reads. Content changes and changes to related records are treated as one user-facing update, while space and audience changes follow the same ownership and membership rules as other writes. The service then returns the rebuilt memo view and signals downstream listeners.

This diagram shows the main path from memo creation to normal use, collaboration, archiving, sharing, and deletion.

flowchart LR
    A[Create memo] --> B[Build derived content data]
    B --> C[Bind attachments and relations]
    C --> D[Read or list active memo]
    D --> E[Update content or metadata]
    E --> F[Refresh derived data and collaboration view]
    D --> G[Archive]
    D --> H[Create share link]
    G --> I[Creator-only archived view]
    D --> J[Delete memo and linked data]

Memo creation

Creation requires an authenticated user and a memo body. The service assigns or validates a user-facing memo ID, applies the default private visibility when no visibility is supplied, checks the content limit, and derives payload data from the Markdown. Top-level memos and comments use the same preparation rules for visibility, space placement, content, attachments, and relations. A memo with the SPACE audience must name a valid space, and its placement must satisfy the space write rules. Attachments and relations supplied with the request are checked before the memo is made visible. Creation then produces webhook and live-refresh side effects.

References: proto/…/memo_service.proto• L17-26 proto/…/memo_service.proto• L288-296 server/…/memo_service.go• L25-82 server/…/memo_create_helpers.go• L25-92 server/…/memo_service_comments.go• L49-70 store/memo.go• L185-225

Memo updates

Updates use a field mask so a caller states which parts of the memo should change. The memo creator or an active instance administrator can perform named memo mutations. The write policy rechecks actor authority, source and target space state, membership, and share conflicts in the same write path; administrator authority does not remove structural validity rules.

Content updates rebuild derived data and re-check attachment references. Visibility, space placement, pin state, state, timestamps, location, attachments, and reference relations can be changed as separate fields, but an audience or placement transition must satisfy the current space and share rules.

Attachment and relation changes use a full replacement set rather than an append operation. The service prepares content, attachments, and relations before applying them as one memo mutation. It checks the memo and attachment state again when the mutation is committed, so a stale request cannot overwrite newer content or bindings. Detached attachment rows are removed in the same store operation; external object cleanup follows the commit. If an author loses membership in the current space, the remaining lifecycle path is limited to a real move or withdrawal. Merely naming the current space in an update does not bypass the membership check. That exception does not restore access to content or collaboration changes. Moving a SPACE memo also requires the caller to state the resulting visibility in the same update. A memo cannot enter the SPACE audience while it has an active share link.

References: proto/…/memo_service.proto• L360-367 server/…/memo_service.go• L286-486 server/…/memo_create_helpers.go• L32-92 store/memo.go• L126-170 store/memo.go• L277-356 store/memo_attachment.go• L9-44 store/memo_attachment.go• L88-166 server/…/memo_attachment_service.go• L191-255

Memo viewing and listing

GetMemo returns one memo after checking the memo and its parent when the record is a comment. ListMemos returns active memos by default, excludes comments from the main list, applies access rules before pagination, and joins the related reactions, attachments, and relations into each result. Space audience reads require active membership in the memo's space. Read the Memo query filtering page for the filter and sort model.

The returned memo is a composed view rather than only a stored row. The service adds creator names, snippets, computed properties, and the visible collaboration records. Relation and comment results are filtered again so a reader does not learn about a memo that the reader cannot access. For assigned memos, the space label is shown only to the creator or an active member; a non-member can read an assigned public memo without learning its space placement. If that placement is stale, the service omits it for non-SPACE audiences and rejects the SPACE audience. In the client, reactions refresh the memo detail and list queries after a change, while relation rows resolve current snippets and dates only when they are needed near the view.

References: server/…/memo_service.go• L85-283 server/…/memo_service_converter.go• L34-102 server/…/memo.go• L81-119 server/…/memo_resolve.go• L55-79 server/…/memo_service_converter.go• L105-137 web/…/hooks.ts• L43-67 web/…/RelationRows.tsx• L38-74

Memo archiving and deletion

Archiving changes the memo state without removing its content. Only the creator can read an archived memo through the normal memo access path, and active-only operations such as share-link creation and new comments reject archived records. In the web view, archived cards show their stored time as a fixed date and do not offer the normal reaction control. The action menu offers restore and delete for archived memos. Active memos offer edit, task-list completion or reset, pin, archive, open, copy-link or copy-content, and delete actions; comments omit pin and archive because they live under their parent. Read-only readers only get open and copy actions. Restoring returns a detail view to the active or archived list when the current route no longer fits the new state. See Memo archive import and export for interchange of memo data outside the live lifecycle.

Deletion requires the creator or an instance administrator. It removes the target memo and its full comment subtree, including nested replies, together with their owned database resources and any relation records that use those memos as endpoints. Attachment storage cleanup is part of attachment deletion, so a deleted memo does not leave its linked file records as active memo content. Relations do not grant lifecycle authority, and deleting one memo does not delete an unrelated memo at the other end of a reference. The delete path can remain available to the creator after the creator loses access to a SPACE memo, but it does not expose the memo content in the delete notification. A deleted comment also refreshes its parent's comment and detail views in the client.

References: server/…/memo_service.go• L489-559 store/memo_delete_policy.go• L9-58 store/…/memo_delete_policy.go• L12-66 store/memo.go• L392-408 server/…/memo.go• L72-79 server/…/memo_share_service.go• L48-55 web/…/MemoActionMenu.tsx• L27-33 web/…/MemoActionMenu.tsx• L103-161 web/…/hooks.ts• L84-110 web/…/hooks.ts• L136-156

Memo archive imports and exports

Archive export copies every memo created by one user, including comments and archived memos, with its linked attachments and collaboration data. It does not include records created by other users. Relations can name related memos outside the exporter's ownership, while reaction names and space details are included as context for the exported records. See Memo archive import and export for the archive format and interchange rules.

Archive import first plans conflicts without writing, then creates or replaces the importing user's records according to the selected conflict policy. It resolves spaces among the user's active memberships, falls back from SPACE to private when no space is available, and applies comments and reference relations after the memo records exist. Imported writes use the same content and upload limits as normal API writes. A successful import publishes a memo change event when records change.

References: server/…/user_service_memo_export.go• L21-70 server/…/user_service_memo_export.go• L72-165 server/…/user_service_memo_import.go• L27-67 server/…/user_service_memo_import.go• L129-188 server/…/user_service_memo_import.go• L195-335 server/…/user_service_memo_import.go• L589-626

Collaboration model

Collaboration is represented as records attached to a memo or as child memos linked to it. This lets the system keep the memo body as the source of truth while comments, reactions, mentions, and live events provide separate ways for people to respond.

Memo comments

A comment is a memo with an immutable parent relation to the memo being discussed. A signed-in active user must be able to read and participate in the active parent before creating a comment. If the parent has a space placement, active membership is required for participation even when the parent has a public or protected audience. An instance administrator can participate in a structurally valid memo. The new comment is prepared with the same core memo validation as a top-level memo, then authorized as its own memo; readers must still pass the access checks for both the comment and its parent.

The parent receives a comment-created notification and live refresh event rather than a generic standalone memo-created event. The inbox notification is sent only when the commenter is not the parent owner and the parent context can support that notification. In list views, the web client derives a comment count from the relation data, loads up to three previews when the card nears the viewport, and links each preview to the matching comment in the parent detail view. The detail view remains the place for the full conversation. A comment link copied from the action menu also opens the parent memo at that comment, and deleting a comment refreshes the parent conversation.

References: proto/…/memo_service.proto• L480-519 server/…/memo_service_comments.go• L18-95 server/…/memo_service_comments.go• L98-135 server/…/memo_service_comments.go• L137-240 store/memo.go• L192-209 store/memo_comment.go• L3-56 web/…/MemoView.tsx• L110-118 web/…/MemoView.tsx• L214-223 web/…/hooks.ts• L112-121

Memo relations

A reference relation connects one memo to another memo and is visible from either side of the connection. The API replaces the source memo's complete reference set, removes duplicate or self-links, and ignores comment relations because comment creation owns those links. A caller must pass the memo-local read rules for the target before creating the relation. Active instance administrators pass the audience checks, but endpoint structure and archived-memo boundaries still apply. Generic relation deletion accepts only REFERENCE relations; COMMENT relations remain immutable context and are removed through the comment memo lifecycle.

Relations are access-aware. A relation is not useful as a way around memo visibility; listing relations applies the reader's memo access rules to both ends of the connection. The relation read policy has no administrator bypass for invalid structure, and a SPACE endpoint requires active membership unless the reader is an instance administrator. In the editor, outgoing references are removable while backlinks remain read-only. In the memo view, both directions use one list with direction icons and current snippets and dates; inaccessible or removed targets disappear from the list. See Memo query filtering for how relation-aware results fit with memo browsing.

The editor finds reference targets through a search dialog that shows memo previews and marks already-linked memos as unavailable. Selecting a relation opens the target with the originating page preserved, so returning from a linked memo keeps the reader's place in the source list.

References: proto/…/memo_service.proto• L416-477 server/…/memo_relation_service.go• L16-100 server/…/memo_relation_service.go• L103-152 store/memo_relation.go• L23-82 store/memo_relation.go• L101-141 server/…/memo_service_converter.go• L225-342 web/…/RelationListEditor.tsx• L18-79 web/…/RelationRows.tsx• L15-74 web/…/useResolvedRelationMemos.ts• L9-45 web/…/LinkMemoDialog.tsx• L20-75 web/…/RelationRow.tsx• L24-40

Memo reactions

A reaction records a user's reaction type on a memo. A signed-in user who can read the memo can add or replace that user's reaction, and the reaction owner can remove it. Readers who can access the memo can list its reactions, and memo responses include reaction creator names and creation times. The write policy is checked again with the current memo state so a reaction cannot outlive the memo's access boundary.

Reaction changes produce live refresh events for the memo. If the reacted record is a comment, the event also carries the parent context so clients can refresh the related conversation. The web view groups visible reactions by type and resolves their users for labels and tooltips. After a reaction mutation, it refreshes the memo detail, list, and parent-comment queries so cards and conversations converge on the same state. Reactions remain outside the compact body clamp so they stay available with the card's collaboration controls.

The reaction picker offers a searchable emoji grid and lets an active signed-in reader add or remove reaction types when memo visibility and space membership allow it. Existing reactions appear as count pills with user details in a tooltip; allowed pills can be toggled, while archived memos keep those pills readable but do not offer mutation controls. On touch devices, a long press opens the user tooltip. The picker closes after a change and returns focus to its trigger when it was opened by keyboard.

References: proto/…/memo_service.proto• L159-191 server/…/reaction_service.go• L16-97 server/…/reaction_service.go• L100-147 store/reaction.go• L17-91 server/…/memo_service_converter.go• L177-221 web/…/hooks.ts• L12-48 web/…/ReactionSelector.tsx• L147-200 web/…/ReactionView.tsx• L15-99 web/…/MemoReactionListView.tsx• L14-31 web/…/MemoBody.tsx• L29-73 web/…/MemoHeader.tsx• L85-101

Memo mentions and notifications

Mentions connect Markdown content to active users and create inbox notifications only when the target can read the memo context. New mentions are compared with the previous content, so an unchanged mention does not create a second notification. Comment creation has its own parent-comment notification path and avoids duplicating that inbox item.

References: server/…/memo_mention_helpers.go• L26-89 server/…/memo_mention_helpers.go• L91-145 server/…/memo_service_comments.go• L85-91

Attachment enrichment

Attachments add files or external media to a memo. They are created as user-owned records, then linked to a memo through the memo's complete attachment set. The attachment service controls the file bytes and storage, while the memo service controls which attachments belong to the memo. See Attachment and object storage for the storage boundary.

Attachment binding

The memo API treats attachment updates as replacement of the full desired set. An empty set clears the memo's bindings. A new binding must be owned by the memo author, or by the acting instance administrator when administrator authority applies. An attachment already bound to another memo cannot be transferred through this path. Motion-media groups are kept together when the request describes them.

An image used as a managed Markdown attachment must be bound to the same memo. The service checks that the referenced record is an image and is stored by the instance rather than supplied as an external attachment. This keeps content references and attachment ownership consistent. The web view separates inline managed attachments from the attachment list so the same image is not shown twice. In the editor, saved attachments and new files share one order. A pending drawing edit keeps the replaced attachment's place until the file is saved.

References: proto/…/memo_service.proto• L51-64 server/…/memo_attachment_service.go• L21-61 server/…/memo_attachment_service.go• L258-385 store/memo_attachment.go• L13-64 proto/…/attachment_service.proto• L128-170 web/…/MemoBody.tsx• L34-70 web/…/memoService.ts• L131-188 web/…/attachmentOrder.ts• L4-68

Attachment access and removal

Reading a linked attachment follows the linked memo's visibility and parent rules. An unlinked attachment is private to its creator. Removing an attachment first checks that no memo body still references it and that any motion-media group remains complete; the binding is then detached before storage cleanup. Removing a bound attachment also requires ownership by the actor unless the actor is an instance administrator.

The client presents images, videos, and drawings as visual media and audio and documents as rows. A memo can preview supported media, open or download files, and open a drawing in its drawing viewer. The editor can add files, place supported images in Markdown, record audio, transcribe audio when configured, and reorder the complete attachment set. See Drawing attachments for the drawing format and viewer flow.

Audio rows support play and pause in place, while the file name opens a player with seeking, skip controls, speed selection, and download. Local images and PDFs can open in a new tab; other local files download, and external attachment links open as external resources. The editor keeps visual attachments in a gallery and other files in metadata rows while preserving one shared order across both groups.

References: server/…/attachment_service.go• L246-264 server/…/attachment_service.go• L316-350 server/…/attachment_service.go• L410-523 server/…/attachment_service.go• L542-571 store/memo_attachment.go• L56-64 web/…/AttachmentListView.tsx• L257-415 web/…/AudioAttachmentItem.tsx• L68-245 web/…/AttachmentListEditor.tsx• L378-670 web/…/EditSession.tsx• L151-216

Visibility and sharing

Visibility controls ordinary reads, while a share link provides a separate bearer-token path for one active top-level memo. The access decision is also applied to comments, relations, attachments, and collaboration actions so those records do not expose a hidden memo through a secondary endpoint. See Space management and membership for space audience rules.

Memo visibility rules

The four visibility levels have distinct audiences:

VisibilityOrdinary reader
PRIVATEThe creator only
PROTECTEDAny signed-in user
PUBLICAnonymous readers when the instance allows anonymous access, and signed-in users
SPACEActive members of the assigned space

Archived and invalid records are treated as not found for readers who are not the creator. A SPACE memo must have a valid space placement. A stale placement does not add a read restriction to PRIVATE, PROTECTED, or PUBLIC memos, but the response hides that placement from readers who cannot establish the space boundary. Relations never grant access to either endpoint, so each memo in a relation must pass its own check. The web client can also blur content when the current user's tag settings mark a memo as sensitive; this is a presentation layer that the reader can explicitly reveal and is not a replacement for server visibility.

References: proto/…/memo_service.proto• L148-157 store/memo.go• L29-41 store/memo_relation.go• L39-82 server/…/memo.go• L55-119 server/…/memo_resolve.go• L17-79 server/…/memo_access.go• L15-91 server/…/memo_service_converter.go• L105-137 web/…/MemoView.tsx• L52-65 web/…/MemoView.tsx• L146-181

A share link is an opaque bearer token that grants read-only access to one active, top-level memo. The memo's manager creates, lists, and revokes its links through the normal memo management permission. A SPACE memo cannot have a share link because its audience is defined by current space membership. A link can have a future expiry time; an invalid or expired token returns the same not-found result as a missing memo.

The token does not grant access to comments, parent conversations, or the memo's relation graph. It returns the shared memo and its attached reactions and attachments within that single-memo boundary. The web client treats a shared memo route as a memo detail page but preserves the same read-only resource boundary.

The client can also render a share image preview from that memo view. The preview keeps the memo identity, time, Markdown content, and a small set of visual attachments together; when more visual attachments exist, it shows a count rather than an unbounded gallery. The same sensitive-content blur state used by the memo view applies to the preview.

References: proto/…/memo_service.proto• L565-624 server/…/memo_share_service.go• L23-80 server/…/memo_share_service.go• L83-167 server/…/memo_share_service.go• L170-213 store/memo_share.go• L8-79 server/…/memo.go• L55-84 web/…/navigation.ts• L23-52 web/…/MemoShareImagePreview.tsx• L10-86

Memo presentation

The web memo view turns a composed memo resource into a readable card or detail page. It keeps editing, content display, collaboration controls, and navigation in one shared view context so the same memo behaves consistently across feeds, profiles, shared links, and detail routes.

Memo authoring

Memo authoring uses one Markdown document for new memos, edits, and comments. The editor keeps the document text unchanged while the author manages memo metadata such as visibility, attachments, relations, location, and time; a comment uses its parent memo for context instead of choosing an independent space. New top-level drafts can also restore local work before the author saves them. See Markdown content processing for how the saved Markdown is interpreted after authoring.

The editor has one read mode and one editing session. The read mode obtains the freshest memo by name from an existing list, comment page, calendar, detail, or shared-memo query. The editing session owns draft content and metadata, keeps new memo and comment drafts locally, and sends saves through the same create or update path. Existing memo edits do not persist a separate draft. A save uploads new files before the memo mutation, keeps completed uploads for retry when a later step fails, and refreshes every cached view of the memo after the server responds.

Authors can add files, place images in the document, record audio, transcribe audio when an AI provider is configured, and use context-based suggestions for tags, checklists, or an assignable visibility. Suggestions apply only to new top-level memos, disappear when the draft already satisfies the condition, and remain draft-local rather than becoming memo data. Source mode changes only the editing surface; it does not change the saved Markdown contract.

References: web/…/MemoEditor.tsx• L110-124 web/…/MemoEditor.tsx• L150-191 web/…/README.md• L3-7 web/…/README.md• L32-36 web/…/EditSession.tsx• L38-45 web/…/EditSession.tsx• L109-123 web/…/EditSession.tsx• L265-293 web/…/useMemoSave.ts• L33-37 web/…/useMemoSave.ts• L67-99 web/…/useMemoSave.ts• L129-180 web/…/EditorSuggestions.tsx• L49-66

Memo card

The card header can show the creator, time, visibility, pin state, and space placement. It offers the action menu and edit entry point according to the memo state and the current user's relationship to the memo. A pinned memo can show a separate corner marker, while a space badge uses the known space title when available and adds a short space identifier when the title is missing or not unique.

The header uses the timestamp as the memo link when the reader is not already on that memo's page. Its tooltip can distinguish creation and last-update times, while archived memos show their stored time as a fixed date. Signed-in readers can open the reaction picker from the header for active memos; the visibility control explains the audience without changing it.

The body shows Markdown content, managed attachments, reference relations, location data, and reactions. Compact cards clamp the content, attachments, and metadata as one body while keeping reactions visible below it. Attachment, relation, location, and comment metadata use a shared row pattern; a location row opens a read-only map with the place text and coordinates. Authored disclosure sections remain collapsible, and their nested Markdown keeps the same link and memo context as the surrounding body. A tag-based sensitive-content setting can blur the body until the reader chooses to show it. Image previews open from the content or attachment area without changing the memo's access decision. When a user edits in place, the card frame and header remain present while the editing session replaces the body; focus mode can temporarily release that card from the surrounding column layout.

References: web/…/MemoView.tsx• L35-43 web/…/MemoView.tsx• L75-106 web/…/MemoView.tsx• L183-223 web/…/MemoHeader.tsx• L26-125 web/…/MemoPinnedMark.tsx• L4-19 web/…/MemoBody.tsx• L29-80 web/…/MemoSpaceBadge.tsx• L8-53 web/…/MetadataSection.tsx• L7-143 web/…/LocationDisplayView.tsx• L9-35 web/…/MemoMarkdownRenderer.tsx• L76-183 web/…/Details.tsx• L7-20 web/…/README.md• L11-15 web/…/constants.ts• L3-15

Memo navigation

The client records the page that opened a memo and carries that origin into the detail route. This lets a reader return to the same list and filter instead of always returning to the home view. Canonical memo routes and shared-token routes both use the memo detail behavior, while comment previews link to the parent memo and the selected comment with the original list context. Relation rows use the same origin state when they open another memo.

References: web/…/navigation.ts• L23-73 web/…/MemoView.tsx• L44-50 web/…/MemoCommentListView.tsx• L40-74 web/…/RelationRow.tsx• L24-41

System signals

Memo change events

Memo creation, updates, deletion, comment creation, reaction changes, and successful archive imports emit live refresh events for connected clients. Memo create, update, and delete actions also send asynchronous webhooks to the memo creator's configured endpoints; comment creation sends a comment-specific webhook to the parent memo owner.

These signals are downstream effects of a successful state change. A webhook failure is logged without changing the completed memo operation, while the live event carries visibility and creator context so subscribers can decide whether to refresh.

References: server/…/memo_service.go• L53-82 server/…/memo_service.go• L465-486 server/…/memo_service.go• L534-559 server/…/user_service_memo_import.go• L177-188 server/…/memo_service_comments.go• L85-95 server/…/reaction_service.go• L79-97 server/…/reaction_service.go• L136-147 server/…/memo_service_webhooks.go• L14-73

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the visibility decision for a memo aligned with comment, attachment, relation, reaction, and share-link reads.
  • When changing space placement or audience transitions, preserve actor ownership, active membership checks, explicit audience confirmation for SPACE moves, the lost-membership lifecycle exception, the distinction between stale non-SPACE placement and invalid SPACE placement, and the rule that SPACE memos cannot have active share links.
  • When changing memo content parsing, preserve the link between derived properties, snippets, tags, mention notifications, and managed attachment references.
  • When changing attachment or relation updates, preserve the full-replacement contract, the atomic mutation boundary, and the stale-state check used by combined memo mutations.
  • When changing relation authorization or deletion, keep endpoint read checks separate from administrator authority and keep COMMENT relations under comment lifecycle control.
  • When changing comment creation or comment previews, keep the shared memo preparation rules, parent relation, parent participation rules, inbox notification, webhook, live event, count, copied comment link, and detail-navigation paths consistent.
  • When changing memo deletion, preserve creator or administrator authority, the full nested comment-subtree cleanup, incident relation cleanup, reactions, attachment bindings, attachment storage cleanup, deletion-time audience snapshot, and the rule that unrelated memos and independent inbox records survive.
  • When changing archive import or export, keep owner-only export scope, conflict planning, creator ownership, space matching, SPACE fallback, attachment cleanup, relation resolution, write limits, and post-import change events consistent.
  • When changing memo response fields or space projection, check the card, detail, shared-link, webhook, and live-event consumers because they reuse the composed memo view.
  • When changing memo routes or saved-view filter state, preserve the originating list and its query filter when the reader returns from detail or comment views.
  • When changing the editor contract or Markdown renderer, keep raw Markdown as the single authoring value and keep tags, mentions, task lists, disclosure blocks, managed images, and in-page links consistent between editing and reading.
  • When changing draft suggestions or editor placement, preserve the distinction between new top-level memos, edits, and comments, and keep accepted suggestions local to the draft.
  • When changing attachment presentation or ordering, keep saved files, local files, motion-media groups, inline managed images, pending drawing replacements, and the save order aligned across the editor and read-only view.
  • When changing reaction cache updates, refresh the memo detail, list, and parent-comment consumers together so a reaction does not remain stale on one surface.
  • When changing attachment or metadata rows, preserve the shared row interaction model and keep drawing viewers, audio playback, file open or download behavior, and location popovers aligned with their access-aware memo context.
  • When changing the header reaction or visibility controls, preserve the active-memo and signed-in-user gates, configured reaction set, archive read-only behavior, and focus return after the picker closes.
  • When changing memo action-menu state gates, preserve the separate controls for active, archived, read-only, and comment memos, including task-list actions and the rule that comments cannot be pinned or archived.

Important failure modes

TriggerConsequenceGuard
A caller submits a stale content or attachment setThe mutation can overwrite a newer memo state or detach a newer bindingThe combined memo mutation rechecks the memo content and attachment state and returns a failed-precondition result
A managed image URL has no matching memo attachmentThe memo can contain an image reference that the memo does not ownContent and attachment updates resolve every managed reference before applying the mutation
A reader follows a comment or linked attachment without access to its parent memoPrivate context can leak through a child resourceRead checks require the memo and its parent to pass the access decision
A memo has SPACE visibility but its space is missingThe memo could grant access without a valid space boundaryAccess resolution fails closed for invalid SPACE placement
A non-SPACE memo has a stale space assignmentA reader can see incorrect space metadata or a later write can use an invalid boundaryResponse projection omits the assignment for readers without a valid placement, and write validation rejects the stale source placement
A caller tries to update content after losing membership in the memo's spaceA former member could keep changing space-bound contentThe lost-membership exception permits only an actual move or withdrawal
A caller moves a SPACE memo without confirming its audience or creates a share for a SPACE memoThe memo can change its access boundary without an explicit audience choice or expose a space-bound memo through a bearer linkThe write policy requires explicit visibility for a SPACE move and rejects active shares for the SPACE audience
A share token targets an expired, archived, comment, or SPACE memoA bearer link could expose content outside its intended scopeShare resolution accepts only active top-level non-SPACE memos and returns not-found for invalid cases
A caller expects an assigned public memo to reveal its space to every readerA non-member could learn placement data outside the space audienceMemo response projection includes the space only for the creator, an active member, or an instance administrator
An archive contains SPACE visibility but no matching active member spaceImport can create a memo with an invalid audience boundaryImport warns and changes the imported memo to PRIVATE when it cannot resolve the space
A caller tries to remove one member of a motion-media groupThe memo can lose part of a media unitAttachment deletion and binding validation require the group to be handled together
A memo creator is deleted before a composed response is builtThe service cannot resolve the creator identity needed for the API resourceList paths skip affected records and single-resource reads return not-found
A memo is deleted while a nested reply is created or committedA comment subtree can be left partly alive or a newly committed reply can survive its parentThe deletion transaction locks and re-collects the target subtree before removing all collected memos and their incident resources
An author treats a draft suggestion as saved memo dataA tag, checklist, or visibility choice can be applied twice or appear after the draft is resetSuggestions track accepted IDs in draft state and check the current Markdown and metadata before applying
An upload or recording finishes after its editor context is goneThe file can be inserted at the wrong location or a save can start during an unfinished recordingUpload anchors resolve or cancel against the active document, and recorder activity gates save
A failed save forgets a file that already uploadedA retry can upload another copy and leave unused storage behindThe editor moves completed uploads into draft attachments and preserves their order for retry
A reaction refresh updates only the current cardLists or a parent conversation can show an old reaction count or groupReaction actions refresh the detail, list, and parent-comment query consumers together
A pending drawing edit is treated as a new attachmentThe saved drawing can move or the old file can remain in the memoReplacement files keep the saved attachment key and upload as a replacement during the memo save
A metadata row loses its shared focus or popup stateAttachments, relations, locations, or comments can become hard to use with keyboard or touch inputKeep the common metadata row states and engaged-row controls consistent across all metadata sections

Key files

FileWhy to read it
proto/…/memo_service.protoDefines the memo resource, lifecycle operations, collaboration records, visibility levels, and share-link contract
server/…/memo_service.goShows the main create, list, get, update, and delete lifecycle and its downstream effects
server/…/memo_create_helpers.goShows the shared preparation boundary for top-level memos and comments before either is stored
server/…/memo_access.goConnects memo reads and space placement to the shared access and membership decisions
server/…/memo.goDefines the shared read decision for normal memos, comments, archived records, space audiences, and share-token scope
server/…/memo_resolve.goResolves creator, placement, and viewer membership facts used by memo access checks
server/…/memo_service_converter.goShows how stored memo data becomes the composed API view returned to clients, including access-aware space placement
server/…/memo_service_comments.goShows comment creation, shared memo preparation, parent linkage, participation checks, notifications, and comment listing
store/memo_comment.goDefines the store-level rules for creating an immutable comment context relation
server/…/memo_relation_service.goShows reference relation replacement and access-aware relation listing
store/memo_relation.goDefines relation types, endpoint read rules, and the boundary between reference and comment relations
server/…/reaction_service.goShows reaction ownership, visibility checks, upsert behavior, and live events
server/…/memo_attachment_service.goShows memo attachment binding, managed content references, atomic mutation, and safe removal
store/memo_attachment.goDefines atomic memo, attachment, and relation mutation contracts and attachment ownership checks
server/…/memo_share_service.goShows share-link creation, expiry, revocation, and single-memo token reads
store/memo.goDefines memo audiences, actor-bound write policy checks, space placement rules, and deletion entry points
store/memo_delete_policy.goDefines deletion authority, deletion-time read state, and the resources removed with a memo and its comment subtree
store/memo_share.goDefines the share grant and its store operations
store/reaction.goDefines reaction records and protected reaction mutation entry points
server/…/user_service_memo_export.goShows the user-owned archive scope and how memo collaboration data and attachments enter an export
server/…/user_service_memo_import.goShows archive planning, conflict handling, space and attachment mapping, and delayed relation application
web/…/MemoEditor.tsxCoordinates read mode, edit mode, new memo and comment drafts, draft identity, and the editing session
web/…/README.mdExplains the editor's Markdown contract, data flow, attachments, ordering, drawings, and draft suggestions
web/…/EditSession.tsxConnects the editable document to metadata, uploads, audio, focus mode, suggestions, and save behavior
web/…/useMemoSave.tsShows the save transaction, upload retry handling, cache refresh behavior, and post-save state
web/…/memoService.tsMaps editor state to create or update operations and preserves attachment replacement and ordering rules
web/…/EditorMetadata.tsxConnects the editor to attachment, relation, location, and inline managed-image metadata
web/…/EditorSuggestions.tsxShows how draft-only tag, checklist, and visibility suggestions are filtered and applied
web/…/attachmentOrder.tsDefines the shared order for saved attachments, new files, motion groups, and drawing replacements
web/…/AttachmentListEditor.tsxShows attachment editing, inline placement, audio transcription, drawing actions, and reorder behavior
web/…/AttachmentListView.tsxShows read-only media galleries, drawing viewing, audio rows, and file open or download behavior
web/…/AudioAttachmentItem.tsxShows in-place audio playback and the expanded player controls
web/…/useDragReorder.tsDefines pointer, touch, and keyboard ordering behavior for attachment groups
web/…/MetadataSection.tsxDefines the shared row and section behavior used by memo metadata lists
web/…/LocationDisplayView.tsxShows how memo location metadata opens a read-only map and coordinate view
web/…/LinkMemoDialog.tsxShows reference search, memo previews, and duplicate-link handling
web/…/RelationRow.tsxShows relation navigation and preservation of the source page
web/…/RelationListEditor.tsxShows editable outgoing relations and read-only backlinks in the editor
web/…/RelationRows.tsxShows the combined incoming and outgoing relation view and near-viewport resolution
web/…/useResolvedRelationMemos.tsResolves fresh related memo snippets and dates without bypassing memo queries
web/…/hooks.tsGroups reactions by type, applies active memo and space gates, and keeps memo, list, and parent-comment views fresh after changes
web/…/ReactionSelector.tsxShows the searchable reaction picker, toggle behavior, and focus handling
web/…/ReactionView.tsxShows reaction counts, user tooltips, touch long-press behavior, and archived read-only behavior
web/…/MemoReactionListView.tsxShows how grouped reactions and the mutation control are placed on a memo
web/…/MemoActionMenu.tsxShows lifecycle, task-list, copy, and delete actions for active, archived, read-only, and comment memos
web/…/hooks.tsShows archive, restore, task, copy-link, and delete actions and their route or cache effects
web/…/MemoShareImagePreview.tsxShows the compact visual representation used for sharing a memo as an image
web/…/MemoView.tsxCoordinates the shared memo card, inline editing, blur state, comment previews, and presentation context
web/…/MemoHeader.tsxShows memo identity, time, audience, reaction entry, and action controls
web/…/constants.tsDefines the shared timestamp control and memo-card presentation boundary
web/…/navigation.tsPreserves detail-route type and the originating list context
web/…/MemoMarkdownRenderer.tsxMaps Markdown constructs to the read-only memo presentation and resolves managed images and in-page links
web/…/Details.tsxPreserves authored disclosure behavior and nested Markdown context