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 / space-management-and-membership

Space management and membership

A Space is an instance-level collaboration context for users and their memos. It gives members a shared place to browse, create, and discuss content while keeping memo authorship, memo audience, and user-global areas separate. This page complements memo lifecycle and collaboration with the rules for creating, joining, selecting, and governing Spaces. See also memo query filtering, markdown content processing, and memo archive import and export for related memo flows.

Space model

Space resources

A Space has an immutable resource identity and editable descriptive data. Its resource name uses the form spaces/{space-id}. A Space can also have an optional display icon. The response includes the caller's role and the count of accepted active members when the caller has membership.

Space icons use either one fully qualified emoji or a lower-case Lucide icon name. A nil icon means that the client can use the default Space mark. The web client uses the same Space identity in creation, settings, invitations, and Space selectors. Only an administrator can change the title, description, or icon.

Spaces are flat collaboration contexts. They are not tenants, folders, or nested work areas. A Space does not own a memo or change its author. A memo has either no Space placement or placement in exactly one Space.

References: docs/…/multi-spaces.md• L63-73 proto/…/space_service.proto• L134-160 server/…/space_service_converters.go• L21-69 store/space.go• L67-76 store/space_icon.go• L9-23 store/custom_icon.go• L11-32 web/…/SpaceMark.tsx• L20-30

Resource hierarchy

The API models memberships and invitations as child resources of a Space. This hierarchy groups administration requests under a Space without creating a hierarchy between Spaces.

ResourceName patternMeaning
Spacespaces/{space-id}A collaboration context
Membershipspaces/{space-id}/members/{username}An accepted member and role
Invitationspaces/{space-id}/invitations/{username}A pending offer to join

The user invitation list is a separate user-scoped collection. It lets an invitee find pending offers without granting access to the Space itself.

References: proto/…/space_service.proto• L162-215 proto/…/space_service.proto• L295-312 server/…/space_service_converters.go• L9-19

Membership and invitations

Membership states and roles

Membership is an accepted relationship between one active user and one Space. The relationship has one of two roles: ADMIN, which governs the Space, or USER, which participates in it. A pending invitation is not membership and does not grant Space access.

The first administrator is added in the same operation as Space creation. Every later membership comes from an accepted invitation. The system rejects a change that would leave a Space without an active administrator.

RelationshipAccess
Pending invitationOnly the invitee can accept or decline it; an administrator can revoke it
Active USER membershipBrowse the Space, use its feed, and participate in assigned content
Active ADMIN membershipAll member access plus Space metadata, invitation, role, removal, and deletion control

Application-wide administrator status does not bypass Space membership. A user must belong to the Space to read its member-only resources.

References: store/space.go• L36-66 server/…/space_service.go• L30-58 server/…/space_service_test.go• L77-126

Invitation flow

An administrator invites an existing active Memos user and selects the role that will apply after acceptance. The invitee sees a read-only Space summary with the offer. The summary contains Space metadata but does not expose active membership fields. The invitee must explicitly accept to become a member.

The invitation lifecycle follows this sequence:

sequenceDiagram
    actor Admin
    actor Invitee
    participant API
    participant Space
    participant Inbox

    Admin->>API: Create invitation with invitee and role
    API->>Space: Store pending invitation
    API->>Inbox: Add invitation notification
    Space-->>Invitee: Show Space summary and offered role
    alt Invitee accepts
        Invitee->>API: Accept invitation
        API->>Space: Activate membership
        API->>Inbox: Archive invitation notification
        Space-->>Invitee: Return active membership
    else Invitee declines
        Invitee->>API: Decline invitation
        API->>Space: Remove pending invitation
        API->>Inbox: Remove invitation notification
    else Administrator revokes
        Admin->>API: Revoke invitation
        API->>Space: Remove pending invitation
        API->>Inbox: Remove invitation notification
    end

Only the invited user can accept or decline. A later invitation is possible after decline or revocation because those actions remove the pending relationship. Accepting keeps the notification as archived history while the user remains a member. The client can open the Space from an accepted invitation, while a pending invitation still offers accept and decline actions. If the user leaves or the Space is deleted, the related notification is hidden.

Notification creation is secondary to the invitation write. If notification creation fails, the invitation remains valid and the user can still use the invitation list.

References: server/…/space_service.go• L261-310 server/…/space_service.go• L443-568 server/…/space_service_notifications.go• L12-80 server/…/space_service_notifications.go• L82-183 proto/…/space_service.proto• L54-103 server/…/space_service_test.go• L426-501 web/…/SpaceInvitationMessage.tsx• L81-105

Membership administration

An administrator can update an accepted member's role, remove another member, and manage pending invitations. Any member can leave by deleting their own membership. The last active administrator cannot leave, be removed, or be changed to USER until another active administrator exists.

Space administration does not include direct editing or relocation of another user's memo. Memo lifecycle authority remains with the memo author. Account archival and deletion also respect the administrator invariant; a user cannot be hard-deleted while active Space memberships remain.

References: server/…/space_service.go• L657-742 store/space.go• L260-340 store/…/space.go• L334-422 server/…/user_service.go• L380-428 docs/…/multi-spaces.md• L100-136

Space-scoped memo behavior

Memo placement and audience

Placement and audience are separate memo properties. Placement says which Space feed contains a memo. Audience says who can read the memo. A memo can be assigned to one Space while still using PRIVATE, PROTECTED, or PUBLIC audience rules.

SPACE is the Space-members-only audience. It is valid only when the memo has a Space placement. The web client offers this audience as a contextual choice rather than as a global default because it has no meaning for an unassigned memo.

Memo stateSpace browsingOrdinary read access
UnassignedNot in a Space feedControlled by PRIVATE, PROTECTED, or PUBLIC
Assigned with PRIVATEVisible in the Space feed only to the author when readableThe active author
Assigned with PROTECTED or PUBLICVisible in the Space feed to active members who can read itThe normal audience rule; placement alone adds no read gate
Assigned with SPACEVisible in the Space feed to active membersActive members of the assigned Space

References: docs/…/multi-spaces.md• L75-98 server/…/memo_create_helpers.go• L32-56 web/…/memo.ts• L15-71

Memo participation and movement

An active member must create or assign a memo in a Space. The memo author controls later placement changes through the memo update API. A move into another Space requires active membership in the target Space.

Changing placement and audience can be one atomic update. A SPACE memo must state its new audience when it moves, and it must choose a non-Space audience when it is withdrawn. A memo with active share links cannot change to the SPACE audience until those links are revoked.

Comments remain independent memos. A comment does not inherit its context memo's Space placement or audience, so its own placement and read rules still apply.

References: server/…/memo_service.go• L306-363 server/…/memo_access.go• L94-182 server/…/memo_share_service.go• L43-57 docs/…/multi-spaces.md• L100-130

Space deletion

An administrator can hard-delete a Space. The operation removes the Space, its memberships, and every memo directly placed in it. It also removes resources owned by those memos and relations that point to them, but it never follows a relation to delete a memo in another Space or an unassigned memo.

Leaving or being removed from a Space does not move or delete the member's memos. A former member loses access to SPACE audience memos in that Space but keeps the narrow author actions that allow deletion or a permitted move.

References: proto/…/space_service.proto• L47-52 store/space.go• L227-240 store/…/space_delete.go• L12-47 docs/…/multi-spaces.md• L128-136

API and client flows

Space lifecycle API

The Space service is the control surface for Space creation, discovery, metadata, membership, invitations, and deletion. It exposes HTTP and RPC forms through the same resource model.

When an active user creates a Space, the service validates its title, optional custom ID, and optional icon. The operation creates the Space and its first ADMIN membership together. Listing returns only Spaces where the caller has active membership. A non-member, including a pending invitee, cannot use Space metadata, member, or feed requests to discover the Space.

The main lifecycle is:

flowchart LR
    A[Active user] -->|CreateSpace| B[Space plus first ADMIN]
    B --> C[ListSpaces for active members]
    C --> D[Get or update Space metadata]
    D --> E[Manage members and invitations]
    E --> F[DeleteSpace by ADMIN]
    F --> G[Space and directly placed memos removed]

References: proto/…/space_service.proto• L14-52 server/…/space_service.go• L86-117 server/…/space_service.go• L120-233 server/…/space_service.go• L236-258 server/…/space_icon_test.go• L17-72 web/…/CreateSpaceDialog.tsx• L28-79

Membership administration API

The service separates pending invitations from active memberships. Administrators create and list invitations under a Space, while users list their own received invitations. Member lists contain active relationships only.

The authorization boundary is applied before resource details are returned. A caller must be an active member to read Space metadata and members. An administrator is required for Space metadata changes, invitation management, role changes, member removal, and Space deletion. The invitee alone can accept or decline an invitation.

Invitation summaries are deliberately weaker than Space resources. They identify the Space and the offered role, but they do not claim that the invitee has active membership. The API also treats inactive users as unable to accept an invitation, even if an old pending offer remains for an administrator to revoke.

References: proto/…/space_service.proto• L54-131 server/…/space_service.go• L295-422 server/…/space_service.go• L443-547 server/…/space_service.go• L632-763 server/…/space_service_converters.go• L31-40 server/…/space_service_converters.go• L105-114 web/…/InviteSpaceMemberDialog.tsx• L41-106

Space selection flow

The web client loads the authenticated user's Spaces and keeps the selected Space as a browsing scope. Selecting a Space changes the collection filter to space == "spaces/{space-id}"; selecting Memos clears that filter and returns to the unassigned global collection view.

The selected Space is stored per user in session storage. If the selected Space is no longer in the user's active membership list, the client clears the selection. Routes that do not support collection scopes fall back to Home when the scope changes, while Inbox, archived content, and profiles remain user-global.

References: web/…/SpaceContext.tsx• L11-35 web/…/SpaceContext.tsx• L71-129 web/…/cel-filter.ts• L6-9 docs/…/multi-spaces.md• L171-173

Space settings flow

Settings provide the administration surface rather than a second browsing switcher. The Spaces section shows received invitations and the user's active Spaces. A selected Space opens general metadata and member views.

The client enables invitation administration only for an administrator. It resolves users before inviting them and prevents inviting the current user, an existing member, or an already invited user. Mutation success updates the relevant cached lists and invalidates memo, attachment, and statistics queries when membership changes can affect their results. Space creation can set a title, description, optional custom ID, and optional icon; the creator becomes the first administrator.

References: web/…/SpacesSection.tsx• L103-183 web/…/SpacesSection.tsx• L331-457 web/…/SpacesSection.tsx• L603-730 web/…/InviteSpaceMemberDialog.tsx• L29-107 web/…/CreateSpaceDialog.tsx• L28-79 web/…/useSpaceQueries.ts• L96-100

Client synchronization

Space, invitation, and membership mutations publish a generic Space change event. Clients invalidate their Space-related data and refetch through the normal API authorization rules. Invitation actions also update the invitee's inbox state: pending offers are actionable, accepted offers remain as archived history, and offers that no longer have a pending or accepted relationship are hidden.

The event does not contain member, invitation, or Space data. The query layer follows page tokens until it has the full list for the current user or Space. It updates local lists after successful mutations, then refreshes membership-sensitive memo and related-resource queries when a membership boundary changes.

References: server/…/space_service.go• L116-117 server/…/space_service.go• L300-310 server/…/space_service.go• L515-546 server/…/space_service_notifications.go• L37-80 server/…/space_service_notifications.go• L128-183 web/…/useSpaceQueries.ts• L102-195 web/…/useSpaceQueries.ts• L197-377 docs/…/multi-spaces.md• L175-190

Change checklist

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

  • Keep the invitation state transition aligned across the API resource, membership storage, invitation notifications, and client invitation caches. An invitation must not become active without the invitee's accept action.
  • Preserve the last-active-ADMIN rule in role changes, member removal, leaving, and account deletion.
  • When changing memo placement or audience, keep the one-Space limit, SPACE validation, target-membership check, and share-link restriction aligned.
  • If Space visibility or feed rules change, update point reads, collection filters, attachments, relations, notifications, search, statistics, and client invalidation together.
  • Keep membership-based Space fields out of invitation-only summaries. Do not use an invitation summary as an authoritative active membership record.
  • Keep user-global routes independent from the selected Space scope when changing the client context or route support rules.
  • Keep icon validation and conversion aligned across create, update, storage, and client display. A nil icon means a default mark; an invalid icon must not replace a valid stored icon.

Important failure modes

TriggerConsequenceGuard
A pending invitation is treated as membershipThe invitee could read Space metadata or use the Space feed before consentInvitation and membership are separate states; only active relationships authorize Space access
The last active administrator leaves, is removed, or is demotedThe Space has no user who can govern itReject the mutation with a failed-precondition error
A memo uses SPACE audience without a placementThe read policy has no Space to checkReject the create or update request
A user assigns or moves a memo without target membershipContent could enter a Space without member participationRequire the author to be an active member of the target Space
A non-member requests a private Space resourceSpace existence or membership data could leakReturn NotFound for member-only Space resources
Space deletion follows memo relationsUnrelated memos in other Spaces or global content could be deletedDelete only memos whose direct space_id is the deleted Space
A client uses invitation summary fields as active membership fieldsRole or member-count data can be stale or intentionally absentRemove the invitation and refetch the authoritative Space list after acceptance
Invitation notification state is used as the source of invitation truthAn inbox failure or stale notification could hide a valid offer or expose an invalid oneResolve notification payloads from the current pending invitation or active membership
An invalid icon passes through a client or gateway updateA Space can store unsupported display data or a valid icon can be lostValidate the icon at the service and store boundary, and apply updates only after validation

Key files

FileWhy to read it
docs/…/multi-spaces.mdProduct boundary and access model for Spaces, memberships, memo placement, and deletion
proto/…/space_service.protoPublic resource names and Space, membership, invitation, and lifecycle operations
server/…/space_service.goAPI authorization and the end-to-end Space administration flow
server/…/space_service_converters.goPublic Space, member, invitation, and icon representations
server/…/space_service_notifications.goInvitation notification creation, visibility, and state changes
store/space.goDomain states, roles, and store-level membership rules
store/space_icon.goAccepted Space icon forms and validation boundary
store/…/space.goTransactional persistence for Space relationships and administrator checks
store/…/space_delete.goAggregate deletion boundary for a Space and its directly placed memos
server/…/memo_access.goMembership checks used by Space-scoped memo reads and writes
server/…/memo_service.goAuthor-controlled memo placement and audience transitions
web/…/SpaceContext.tsxAuthenticated client scope, selection persistence, and route behavior
web/…/useSpaceQueries.tsClient API queries, mutation updates, pagination, and cache invalidation
web/…/SpacesSection.tsxUser-facing Space list, invitations, metadata, members, and destructive actions
web/…/InviteSpaceMemberDialog.tsxExisting-user lookup, role selection, and invitation submission flow
web/…/SpaceInvitationMessage.tsxPending and accepted invitation actions in the user inbox
web/…/SpaceMark.tsxShared Space identity display used by settings and selectors
web/…/CreateSpaceDialog.tsxSpace creation fields, custom ID validation, icon selection, and creator-admin flow