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 / web-settings-and-account-management

Web settings and account management

The web client gives signed-in users one place to manage their account, personal choices, saved access, and service connections. It also gives administrators control over members, instance policy, storage, notices, sign-in providers, media services, and resource use. These experiences sit inside the authenticated shell described in Web application experience and depend on the identity model in Identity, authentication, and access.

Account and profile experience

Account controls

The account area lets a user maintain the identity shown across Memos and control account-level actions. A user can edit the avatar, username, display name, email, and profile description. The same area supports password changes, linked external identities, permanent account deletion, and views of attachment storage use and current usage against any limits that apply.

The public profile presents the display name, username, avatar, description, and public memos. It also offers a map view when memo locations are available. A profile link can be copied for sharing without exposing the private account controls.

References: web/…/MyAccountSection.tsx• L23-76 web/…/UserStatsSection.tsx• L8-27 web/…/UpdateAccountDialog.tsx• L34-159 web/…/UserProfile.tsx• L21-115

Account menu

The account menu is the short path to the profile, Inbox, archived memos, settings, and about areas. It also gives quick controls for language and theme. The menu marks the active Inbox or archived-memo page and shows the unread Inbox total. A live-connection marker shows when updates are connecting or unavailable. Signing out clears the active session and user-specific client state before sending the browser to the sign-in page.

References: web/…/UserMenu.tsx• L45-123 web/…/UserMenu.tsx• L126-245

Authentication experience

Sign-in and registration

The authentication pages adapt to the instance policy. Sign-in can offer a password form and configured identity providers. Registration can create a normal user, create the first administrator during initial setup, or direct new users to an external identity provider when password sign-up is disabled. If no permitted method exists, the page explains that sign-in or registration is unavailable.

The client preserves a safe return path through the flow. After success, it reloads the user and instance state before returning to the requested page. The callback route completes external identity flows without treating an already signed-in browser as a guest.

This diagram shows the user-facing authentication paths and their common return point.

flowchart TD
    Visit[Open protected or auth page] --> Policy{Instance policy}
    Policy -->|Password allowed| Password[Password sign-in or sign-up]
    Policy -->|Identity provider configured| Provider[External provider sign-in]
    Policy -->|First run| Setup[Create first administrator]
    Password --> Session[Create or restore session]
    Provider --> Callback[OAuth callback]
    Setup --> Session
    Callback --> Session
    Session --> Ready[Reload user and instance state]
    Ready --> Return[Return to safe target or home]

References: web/…/SignIn.tsx• L13-62 web/…/SignUp.tsx• L24-171 web/…/AuthCallback.tsx• L19-138 web/…/AdminSignIn.tsx• L8-29

Linked identities

Account settings list the administrator-configured OAuth2 providers that a user can link to the current account. Each row shows the provider type, stable provider ID, link state, and external account ID. Linking starts from the signed-in account and returns to the account page. A user can unlink a locally managed link, while a configuration-managed link is shown without a local unlink action. Administrators decide which providers exist; users decide which available provider identifies their account. For provider setup and sign-in behavior, see Identity provider integration.

References: web/…/LinkedIdentitySection.tsx• L30-91 web/…/LinkedIdentitySection.tsx• L93-125 web/…/LinkedIdentitySection.tsx• L127-209 web/…/sso-display.ts• L15-25

Settings workspace

Settings access

The Settings page is a signed-in workspace with a selected section in the URL hash. Basic sections are visible to every signed-in user. Administrator sections appear only to users with the administrator role, so the navigation and the page use the same role boundary.

The settings surface has two groups:

GroupUser-facing areas
BasicAccount, spaces, access tokens, preferences, editor, webhooks, tag rules, and memo export
AdministratorMembers, instance, storage, usage limits, notifications, SSO, AI, resource statistics, and configuration

Instance-backed administrator sections can preload the setting they need. After a save, shared instance state is refreshed so other pages use the new policy.

References: web/…/Setting.tsx• L13-67 web/…/settingSections.ts• L41-69 web/…/settingSections.ts• L71-193 web/…/useInstanceSettingUpdater.ts• L8-41 web/…/AppSidebar.tsx• L356-382

Configuration ownership

The configuration view explains which settings come from an external configuration source instead of local edits. It shows the applied configuration version and time, then identifies each managed resource, its source, and the fields that the source controls. Managed settings remain visible for review but their local controls are disabled. Chips with long values can open the full value on hover or by click for review.

This boundary lets administrators distinguish a service policy they can change in the web client from one they must change at its source. The same ownership state protects linked identities, members, sign-in providers, AI settings, storage, usage limits, and other service settings from conflicting local actions. For the wider configuration model, see Declarative configuration management.

References: web/…/ConfigurationSection.tsx• L14-67 web/…/InfoChip.tsx• L4-44 web/…/SSOSection.tsx• L34-107

Personal settings

Personal settings change how a user works with the client and how new content starts. Preferences set the language, theme, default memo visibility, and upload metadata choice. Device choices control link previews and double-click editing. The editor setting selects rich editing or Markdown source editing.

Tag rules match tag patterns for the current user. A rule can add a color or blur matching content. Users can add, edit, and remove rules, and the page shows how many memos match each configured rule. The add control also offers tag names already used in memos, while only tags with saved metadata appear as configured rules. New patterns are checked before they are saved.

Access tokens provide named credentials for tools and external clients. The page shows last use and expiry state, copies a new token only at creation time, and lets the user revoke old tokens. It also gives a short API example and a link to the web clipper. Webhooks give the user-managed integrations a URL-based event destination that can be created, edited, or removed.

References: web/…/PreferencesSection.tsx• L18-177 web/…/EditorSection.tsx• L7-24 web/…/TagsSection.tsx• L47-163 web/…/TagsSection.tsx• L165-314 web/…/AccessTokenSection.tsx• L209-299 web/…/WebhookSection.tsx• L15-149

Memo archive

The memo export area lets users move memo data into or out of the instance. Administrators can export a user's memos from the archive settings or a member row. Users can import an archive by first reviewing its contents and then applying a selected rule for memos that already exist. The result reports created, updated, skipped, and failed items so the user can see what the operation changed.

References: web/…/MemoExportSection.tsx• L37-43 web/…/MemoExportSection.tsx• L56-115 web/…/MemoExportSection.tsx• L117-210 web/…/useExportMemos.ts• L7-29

Space management

The Spaces area lets a user create and manage shared spaces from the same settings workspace. The overview shows available spaces and pending invitations. Each space has a stable custom ID, description, icon, member count, and current user role. A user can accept or decline an invitation from the overview or Inbox, then open a space to view its details and membership.

The selected space opens general and member views. Space administrators can edit details, invite an active user with a selected role, change member roles, remove members, and cancel pending invitations. The invitation flow waits for a settled username lookup and rejects the current user, an existing member, or a pending invitee. Members can leave a space, but the last administrator cannot leave. An administrator can delete the space. The stable custom ID appears in detail views and destructive confirmations. For the wider membership model, see Space management and membership.

This diagram shows how a user moves from the space overview into membership or space administration actions.

flowchart TD
    Settings[Open Spaces settings] --> Overview[View spaces and invitations]
    Overview -->|Accept or decline| Invitation[Resolve invitation]
    Overview -->|Create| NewSpace[Create a space]
    Overview -->|Select| Detail[Open space details]
    Detail --> General[View or edit general details]
    Detail --> Members[View members]
    Members -->|Member| Leave[Leave space]
    Members -->|Administrator| Admin[Invite, change roles, remove, or cancel]
    Admin --> Delete[Delete space]

References: web/…/SpacesSection.tsx• L103-181 web/…/SpacesSection.tsx• L182-323 web/…/SpacesSection.tsx• L330-453 web/…/SpacesSection.tsx• L455-721 web/…/InviteSpaceMemberDialog.tsx• L26-107 web/…/InviteSpaceMemberDialog.tsx• L109-197

Administration experience

Member administration

Administrators manage the people who can use the instance. The member view identifies each person by profile details and shows the account role, active or archived state, and email when available. Administrators can create and edit members, export a member's memos, archive active members, restore archived members, or permanently delete archived members when the account is not managed by configuration. The current administrator’s row has no member actions, which prevents self-directed account changes from this view.

References: web/…/MemberSection.tsx• L26-112 web/…/MemberSection.tsx• L113-205 web/…/MemberSection.tsx• L207-237 web/…/useExportMemos.ts• L7-29

Usage limits

Usage limits let administrators set shared defaults and user-specific limits for instance use. The user-facing account page shows current use only when at least one effective limit applies. The administrator view becomes read-only when an external configuration source manages the usage-limit setting. For the wider quota model, see Usage limits and quotas.

The administrator view combines the shared default row with optional rows for individual users. Named rows are checked from top to bottom, so the first row that names a user supplies that user’s limit set. The all-users row is the default and is kept last. A named row that is fully covered by earlier rows is marked as never applying. New named rows start with the shared default values, and administrators can move them to the position where they should take effect.

MetricUser-facing meaning
MemosMaximum number of memos
Memo contentMaximum size of one memo's content
StorageTotal attachment storage for the user
File sizeMaximum size of one uploaded file

An empty value or zero means no limit. The form uses whole numbers for memo counts, KiB for memo content, and MiB for storage and file size. The client converts these values before saving and formats stored values for display.

References: web/…/UsageLimitsSection.tsx• L40-65 web/…/UsageLimitsSection.tsx• L67-109 web/…/UsageLimitsSection.tsx• L130-179 web/…/UsageLimitsSection.tsx• L237-259 web/…/UsageLimitDialog.tsx• L35-77 web/…/UsageLimitDialog.tsx• L80-87 web/…/usageLimitValues.ts• L6-65 web/…/UsageSection.tsx• L8-45

Instance policy

Instance settings define the public identity and access policy of the Memos service. Administrators can set the server name, logo, and description. They can also control public access, new registration, password authentication, username changes, nickname changes, and the start day used by calendar views. The client does not allow password authentication to be disabled when no identity provider is configured, so the instance keeps a sign-in path.

The same area accepts additional style and script content for instance customization. Changes are held as a draft until the administrator saves them, which keeps a multi-field policy change together.

References: web/…/InstanceSection.tsx• L28-237 web/…/useInstanceSettingUpdater.ts• L17-41

Service integrations

The administrator settings connect the instance to services that extend the core product. SSO manages the identity providers shown on sign-in and available for account linking. Notification settings configure instance email delivery and provide a test action for the current administrator. Storage selects the active attachment backend and its path or object-store settings. It supports local, database, and S3-backed choices while keeping known storage choices available when administrators switch between them. S3 settings also support reuse of an existing credential when the provider scope matches.

AI manages administrator-configured provider connections and optional audio transcription. A provider can define its type, endpoint, and secret key. Transcription selects one configured provider and can set a model, language, and prompt. Provider changes do not overwrite an in-progress transcription draft. Removing a provider clears a saved transcription link that points to it. Resource statistics give administrators a view of database and local storage use.

These controls change service-wide behavior rather than one user’s view. For attachment records and object operations, see Attachment and object storage.

References: web/…/SSOSection.tsx• L34-201 web/…/sso-display.ts• L67-113 web/…/NotificationSection.tsx• L77-181 web/…/NotificationSection.tsx• L183-333 web/…/StorageSection.tsx• L147-190 web/…/StorageSection.tsx• L268-435 web/…/AISection.tsx• L100-224 web/…/AISection.tsx• L317-345 web/…/ResourceStatsSection.tsx• L35-91

Attachment library

Attachment views

The attachment library gives a signed-in user a view of objects linked to memos. It groups visual media by month and separates media, documents, and audio so each type has a suitable preview or open action. The sidebar also shows counts and provides an all-items view.

The library keeps objects without a memo in a separate unused view. This makes orphaned uploads visible without mixing them with content that a memo still references. Administrators choose the storage system and its limits in the attachment and storage settings; the library is the user-facing view of those objects.

References: web/…/Attachments.tsx• L60-205 web/…/useAttachmentLibrary.ts• L16-263 web/…/AppSidebar.tsx• L282-316

Attachment cleanup

Unused attachments can be reviewed and removed in one confirmed action. The client first gathers the complete unused set, deletes it in bounded groups, and refreshes both the main library and the unused view. A media preview can open from the visual grid without changing the memo that owns the object.

References: web/…/Attachments.tsx• L27-57 web/…/Attachments.tsx• L90-115 web/…/Attachments.tsx• L228-244 web/…/AttachmentMediaGrid.tsx• L16-83 web/…/AttachmentFileRows.tsx• L101-125

Inbox experience

Notification triage

The Inbox collects user notifications from memo activity and space invitations. The current client renders comment, mention, and invitation notices, sorts them from newest to oldest, and shows the unread total in the page and the sidebar.

The user can switch between all, unread, and archived notices. An unread notice can be archived directly. Opening an unread comment or mention takes the user to its memo and archives the notice. Read notices can be deleted. A pending space invitation can be accepted or declined in place. If notification data cannot be read, the Inbox shows a failure state and allows deletion instead of presenting a misleading action.

References: web/…/Inboxes.tsx• L13-77 web/…/MemoCommentMessage.tsx• L24-73 web/…/MemoMentionMessage.tsx• L24-75 web/…/SpaceInvitationMessage.tsx• L39-197 web/…/AppSidebar.tsx• L318-353 web/…/AppSidebarContext.tsx• L6-46

User-facing lifecycle

Protected workspace entry

Attachments, Inbox, and Settings require both an authenticated user and a fully initialized instance. This prevents a page from using incomplete account or instance settings. If a visitor reaches one of these routes without a session, the client sends them to sign-in and keeps a safe return target.

The main lifecycle is:

  1. The shell restores or refreshes the session and loads the instance profile.
  2. Route guards confirm the user and the required initialization state.
  3. The selected page loads its own user or instance data.
  4. A successful change updates shared state or the query cache so the shell and related pages reflect it.

References: web/…/index.tsx• L73-114 web/…/guards.tsx• L8-61 web/…/AuthContext.tsx• L86-145 web/…/InstanceContext.tsx• L122-165

Change checklist

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

  • A new settings section must agree across the section registry, hash selection, sidebar links, role scope, preload setting keys, and settings that must load before display.
  • Configuration-managed fields must stay read-only in the matching local form. The configuration status view and managed-resource markers must identify the same resource and fields.
  • Space changes must keep the overview, selected-space detail route, custom space identity, member roles, invitation state, confirmation steps, and last-administrator safeguards aligned.
  • Changes to instance access or authentication policy must keep sign-in, sign-up, private-route redirects, and identity-provider choices consistent.
  • Profile updates must refresh both current-user state and cached user details so the account menu and public profile do not disagree.
  • Memo archive imports and exports must keep review counts, conflict policy, staged archive lifetime, final reports, administrator actions, and busy state aligned with the archive service.
  • Attachment type rules and unused-object filters must stay aligned between sidebar counts, library groups, previews, and cleanup actions.
  • Notification status changes must preserve the meaning of the all, unread, and archived counts across the sidebar, account menu, and Inbox page.
  • Service settings with secret values must preserve existing credentials when a form does not return the secret again.
  • Storage backend changes must keep the active backend, stored backend choices, path template, object-store fields, and credential reuse rules aligned.
  • Usage-limit changes must keep ordered first-match rules, the all-users default row, shadowed-row status, effective account display, managed-setting lock state, and metric-specific unit conversion consistent.
  • AI transcription must keep its selected provider valid when providers are added or removed, without replacing an in-progress transcription draft during a provider save.
  • SSO summaries and account-link rows must use the same provider identity and configuration mapping so an administrator’s view matches the user’s link choices.
  • Access-token creation must keep the one-time token display and clipboard behavior aligned with the token list and revoke action.
  • Member administration changes must keep role and account-state labels aligned with create, edit, export, archive, restore, and delete actions. Managed accounts and the current administrator must remain protected.
  • Linked-identity changes must keep provider type, stable provider ID, external account ID, link state, managed state, and OAuth return state aligned across account settings and provider configuration.

Important failure modes

TriggerConsequenceGuard
An administrator-only section is exposed to a normal userThe client may show controls for service-wide changes that the user cannot performSettings sections have an administrator scope and are filtered by the current role
A setting field is managed by external configuration but remains editable locallyA local save can conflict with the configured source or appear to succeed without changing the serviceManaged fields are marked in the settings UI and their local controls are disabled
Password authentication and registration are disabled with no identity providerUsers have no available sign-in or account-creation pathInstance policy keeps a sign-in path and auth pages show an unavailable state where needed
OAuth callback is treated as a guest-only pageA valid provider flow can fail when another tab already has a sessionThe callback route remains outside the guest-only guard
A named usage-limit row is placed below an earlier row that names the same userThe lower row never appliesRows are checked in order and fully covered rows are marked as never applying
A space invitation targets the current user, an existing member, or a pending inviteeThe user can receive a duplicate or unusable invitationInvitation search reports the state and disables selection
The last space administrator tries to leaveThe space can have no administratorThe leave action is disabled while the current user is the last administrator
An unused attachment is deleted while the library still uses stale listsCounts and cleanup results can show objects that no longer existCleanup refreshes the linked and unused library queries after the batch completes
A staged memo archive expires before confirmationThe import cannot use the reviewed archiveThe client returns to file selection when the service reports that the staged archive no longer exists
An AI provider used by transcription is deletedThe saved transcription can point to a provider that no longer existsProvider deletion clears the provider reference before saving the new provider list
A provider save replaces a transcription draft that the user is still editingThe user loses unsaved transcription changesProvider saves keep persisted transcription separate from the current draft
An S3 or notification secret is omitted from a returned settingSaving another field can erase a working service credentialStorage and notification forms preserve existing secret values when the server does not return them
A new access token is expected to be shown again laterA user may lose the only usable copy of the credentialThe client copies the token at creation and does not treat the token list as a secret display
A configuration-managed linked identity is offered for unlinkingA local change can conflict with the source-of-truth configurationManaged links omit the unlink action

Key files

FileWhy to read it
web/…/index.tsxRoute placement and protection for auth, profile, attachments, Inbox, and settings
web/…/guards.tsxAuthentication and initialization boundaries for protected experiences
web/…/AppSidebar.tsxUser-facing navigation, settings scopes, attachment filters, and Inbox filters
web/…/UserMenu.tsxAccount menu, unread Inbox status, quick preferences, and sign-out behavior
web/…/Setting.tsxSettings section selection and administrator visibility
web/…/settingSections.tsThe map of basic and administrator settings areas
web/…/SettingList.tsxShared accessible, responsive presentation for settings and record lists
web/…/ConfigurationSection.tsxConfiguration ownership and managed resource visibility
web/…/SpacesSection.tsxSpace overview, identity, invitations, membership, and role-based actions
web/…/MemberSection.tsxInstance member list and administrator lifecycle actions
web/…/MyAccountSection.tsxAccount editing, password changes, linked identities, usage views, and deletion
web/…/UsageLimitsSection.tsxOrdered shared and per-user usage-limit rows and configuration lock state
web/…/MemoExportSection.tsxArchive export, staged import review, conflict choices, and import results
web/…/SignIn.tsxPolicy-aware sign-in choices
web/…/SignUp.tsxRegistration and first-run administrator setup
web/…/AuthCallback.tsxCompletion of external identity-provider flows
web/…/Attachments.tsxAttachment browsing, preview, and unused-object cleanup
web/…/Inboxes.tsxNotification sorting, filtering, and message presentation
web/…/InstanceSection.tsxInstance identity, access policy, and sign-in safety controls
web/…/SSOSection.tsxAdministrator identity-provider management
web/…/StorageSection.tsxAttachment storage choices and object-store settings
web/…/NotificationSection.tsxInstance email delivery settings and test delivery
web/…/AISection.tsxAI provider connections and audio transcription settings
web/…/AccessTokenSection.tsxNamed credentials, one-time token display, usage state, and revocation
web/…/TagsSection.tsxPer-user tag rules, colors, blur behavior, known tags, and usage counts
web/…/WebhookSection.tsxUser-managed event destinations
web/…/LinkedIdentitySection.tsxPer-user provider linking and managed-link state