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 / usage-limits-and-quotas

Usage limits and quotas

Usage limits let an instance control how much memo and file data each user can create or keep. Administrators set an ordered policy for all users and named users. The server measures current use when a request needs a decision, blocks work that would exceed the active limit, and exposes the same state to users and settings screens.

Quota model

Limit scopes

A usage limit is a ceiling for one metric in one ordered entry. An entry names users or applies to all users. The first entry that matches a user wins for all four metrics, so a named-user entry replaces the whole default entry rather than only selected fields.

The value 0 means unlimited. This lets an administrator remove a restriction without changing the resource shape. Limits apply to administrators as well as regular users.

References: proto/…/instance_setting.proto• L247-269 core/…/usagelimit.go• L41-63 store/usage_limit.go• L52-113

Usage metrics

The system measures four kinds of use. Each metric protects a different shared resource or user action.

MetricMeaningMain effect
MEMOSMemos created by the user. Comments count as memos. Archived memos and memos in Spaces also count.Blocks new memo and comment creation.
MEMO_CONTENT_BYTESThe size of one memo's content.Blocks memo content that is too large.
STORAGE_BYTESPersisted bytes in the user's uploads. Unattached uploads count. External links do not count.Blocks an upload when the resulting stored total would be too large.
UPLOAD_BYTESBytes in one file.Blocks a file that is too large even when the user's total storage has room.

The memo and storage figures are current totals. The content and per-file metrics describe the request itself rather than a stored total.

References: proto/…/instance_setting.proto• L260-268 core/…/usagelimit.go• L104-177 proto/…/user_service.proto• L687-729

Effective limits

For each user, the server resolves one effective entry. It scans the ordered list and uses the first entry that names the user. If no named entry matches, it uses the all-users entry. If no entry matches, every metric is unlimited.

This resolution is visible in the account usage response through the effective limit fields and the entry index. The index identifies which ordered policy entry applies, while an index of -1 means that no configured entry applies.

The following flow shows how an ordered policy becomes the decision used by a request.

flowchart LR
    A[Ordered limit entries] --> C[Find first matching entry]
    B[All-users entry] --> C
    C --> D[Measure current use]
    D --> E{Within limit?}
    E -->|Yes| F[Continue request]
    E -->|No| G[Return quota refusal]

References: core/…/usagelimit.go• L51-63 core/…/usagelimit.go• L187-201 server/…/user_service_usage.go• L47-64 web/…/UsageLimitsSection.tsx• L40-44

Usage measurement

Live usage

The server counts memo rows and sums stored attachment bytes when it needs a usage decision or a usage display. It measures memo content and file size from the request being checked. It does not maintain a separate counter. This avoids stale quota state, but concurrent requests can pass checks before either request changes the stored total.

When no limit applies to a check, the server skips the related count or sum. Lowering a limit never deletes existing memos or files. It only prevents new work until the measured use is below the new ceiling.

References: core/…/usagelimit.go• L104-177 core/…/usagelimit.go• L187-201 docs/…/user-usage-limits.md• L42-46

Enforcement points

Quota checks sit at the point where the server can still refuse the operation without leaving partial user work. Memo creation and comments check the memo count. Memo content checks compare the submitted content size. One-shot and chunked attachment uploads check file size and total storage. Chunked uploads check at both start and finish because limits or other uploads can change while a file is in progress.

The same file-size check also protects binary attachments created during memo import. External-link attachments do not consume stored bytes and therefore do not use the storage-byte total.

The request path follows a common pattern:

  1. Resolve the user's effective entry.
  2. Measure the needed current value or inspect the submitted content or file size.
  3. Refuse the operation if the new state would exceed a limit.
  4. Continue to the normal write path when the check succeeds.

References: server/…/usage_limit.go• L13-50 server/…/memo_service.go• L25-54 server/…/memo_service_comments.go• L60-69 server/…/attachment_service.go• L163-180 server/…/attachment_upload.go• L105-140 server/…/attachment_upload.go• L158-184 server/…/user_service_memo_import.go• L487-517

API contracts

Administrative interface

The InstanceService exposes usage limits as the USAGE_LIMITS instance setting. Only an administrator can read or replace this setting. The API names users with user resource names, while the stored policy keeps stable user IDs.

An update replaces the complete ordered list. The server validates the list and resolves every named user before it stores the setting. A malformed user resource name returns INVALID_ARGUMENT, and a user that does not exist returns NOT_FOUND. When a referenced user no longer exists, reads omit that user from the API view. Deployment-provided settings are read-only at runtime. The setting allows at most 100 entries and can name at most 1,000 users across those entries.

OperationPurpose
GetInstanceSettingRead the ordered usage-limit policy.
UpdateInstanceSettingReplace the ordered policy when deployment configuration does not own it.

References: proto/…/instance_service.proto• L1-48 server/…/instance_service.go• L143-169 server/…/instance_service.go• L200-290 server/…/instance_service_usage_limits.go• L17-95

Account usage interface

UserService.GetUserUsage returns the user's current memo count and stored bytes. It also returns the effective limit for memo count, memo content size, storage bytes, and upload bytes. The response includes the index of the entry that supplies those limits. The user can read their own resource. An administrator can read any user's resource.

The resource is users/{user}/usage. An unset or zero limit means unlimited. A limit index of -1 means that no policy entry applies. This contract gives account screens and other clients enough state to show both actual use and the policy that governs it.

References: proto/…/user_service.proto• L687-740 server/…/user_service_usage.go• L15-64 web/…/UsageSection.tsx• L8-45

Refusal contract

When a memo or upload would exceed a usage limit, the API returns RESOURCE_EXHAUSTED with the message quota exceeded. The error uses QUOTA_EXCEEDED in the memos.api error domain and reports the metric, limit, and measured usage. It also includes a quota violation that identifies the affected user.

Quota refusals do not include retry information. They do not recover by waiting. The user must reduce use or an administrator must raise or remove the limit. A check or database failure instead returns an internal error, so an infrastructure problem cannot silently disable enforcement.

The API and web client distinguish this contract from a temporary rate-limit refusal:

RefusalRecoveryClient signal
Usage quotaFree space, reduce the file or memo, or change the configured limit.QUOTA_EXCEEDED; no retry delay.
Request rate limitWait for the advertised window to pass.RATE_LIMITED; retry details may be present.

References: server/…/ratelimit.go• L75-130 server/…/usage_limit.go• L35-51 web/…/error.ts• L73-106

Settings interfaces

Account settings

The My Account view shows usage only when at least one limit applies to the current user. It presents memo use and storage use against their active ceilings. A memo-content limit appears as a maximum content size, and a per-file limit appears as a file-size value rather than as current usage because both apply to one request.

The account UI reads the user usage resource and formats byte values for people. A quota error keeps the cause visible: memo errors ask the user to delete memos, storage errors show current storage use, and file errors show the per-file ceiling.

References: web/…/MyAccountSection.tsx• L72-76 web/…/UsageSection.tsx• L8-45 web/…/usageLimitValues.ts• L62-65 web/…/error.ts• L83-106

Administrative settings

The admin Usage limits view presents the ordered policy as one table. Named-user entries appear before the all-users entry. The first matching named entry controls a user, so a later entry may never apply to a user already matched by an earlier row. The view marks an entry as never applying when all of its users already match earlier entries.

An administrator can edit the all-users row, add or edit a named-user entry, choose users from the instance user list, move named entries, or remove an entry. New entries start immediately above the all-users row, and their position can then change which users they control. The form covers memo count, memo content size, total storage, and per-file size. A new entry starts with the all-users values, so leaving a field unchanged keeps that default. Clearing a field means no limit in that entry. Memo content values use KiB in the form. Other byte limits use MiB. Stored values remain bytes.

When deployment configuration manages the setting, the view shows that state and disables changes. The database policy remains visible, but runtime administration cannot replace it.

References: web/…/UsageLimitsSection.tsx• L40-63 web/…/UsageLimitsSection.tsx• L130-246 web/…/UsageLimitDialog.tsx• L35-85 web/…/UsageLimitDialog.tsx• L97-175 web/…/usageLimitValues.ts• L6-60

Quota state

Instance configuration

All limits share the USAGE_LIMITS instance setting. The instance settings API owns this state. A deployment can provide the setting as part of instance configuration. When it does, runtime updates are rejected.

The stored state validates the entry order, user IDs, non-negative values, and the size caps. Reads for enforcement use the current setting so a change reaches the next check on each replica. If the setting is absent, the instance uses one all-users entry with a 32 MiB per-file limit and an 8 KiB memo-content limit. A stored setting replaces that built-in policy as a whole. It must contain an all-users entry as its last entry.

References: proto/…/instance_setting.proto• L247-269 store/usage_limit.go• L13-131 server/…/instance_service.go• L214-287

User lifecycle

Limits refer to a stable user ID rather than a username. A username change therefore keeps the user's limits. When a user is removed, the system removes or ignores the limits that refer to that user so stale entries do not remain active or consume the instance limit budget.

User removal updates the shared policy only when the stored value is still the one that was read. If another writer changed the policy first, the cleanup retries a bounded number of times and reports a write conflict if it cannot safely apply the change.

References: proto/…/instance_setting.proto• L253-259 store/usage_limit.go• L27-37 store/usage_limit.go• L134-186 server/…/instance_service_usage_limits.go• L31-49

Change checklist

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

  • Keep the four metric meanings aligned across the store schema, live measurement, API fields, form units, and web labels.
  • Preserve ordered first-match resolution when changing limit reads, admin forms, or account usage responses.
  • Keep memo content limits in bytes on the service boundary and KiB in the admin form.
  • Keep QUOTA_EXCEEDED distinct from RATE_LIMITED, including the absence of retry details for quota errors.
  • Update both the start and finish checks when changing chunked attachment upload behavior.
  • Keep deployment-provided limits read-only through every runtime write path and visible as managed in the admin view.
  • Keep user deletion and username changes consistent with limits stored by user ID.
  • Keep the all-users entry last and within the store's entry and user caps.
  • Preserve conditional writes and bounded retries when user lifecycle actions modify the shared policy.

Important failure modes

TriggerConsequenceGuard
A memo count or storage sum cannot be readThe request fails with INTERNAL instead of proceeding without a limit.Quota checks fail closed.
A chunked upload passes its start check but the limit changes before finishThe upload is refused at finish and is not saved.The upload is checked at both stages.
Memo content exceeds the active content-size limitThe memo request is refused before the normal write path.The service checks submitted content size and maps the refusal to QUOTA_EXCEEDED.
A named-user entry is removedThe user falls through to the next matching entry, usually the all-users entry.Effective-limit resolution scans entries in order.
An admin lowers a limit below current useExisting data stays intact, but new matching work is refused.Usage is measured live; limits do not delete data.
Runtime code tries to change deployment-provided limitsThe write fails with FAILED_PRECONDITION.Deployment configuration has precedence over database state.
A policy names a user that does not existThe update fails instead of creating a policy that cannot be resolved.The API resolves every user name before storing the setting.
User deletion races with another policy updateThe deletion may report a usage-limit write conflict instead of overwriting the newer policy.Cleanup uses conditional writes with bounded retries.

Key files

FileWhy to read it
core/…/usagelimit.goDefines ordered effective-limit resolution and live usage reads.
server/…/usage_limit.goDefines enforcement entry points and conversion of quota decisions into service errors.
server/…/instance_service.goDefines administrator access to the instance setting and deployment-owned write protection.
server/…/instance_service_usage_limits.goConverts API user names to stored user IDs and back.
server/…/user_service_usage.goDefines the account-facing usage resource and its access rules.
server/…/ratelimit.goDefines the wire-level difference between quota and temporary rate-limit errors.
store/usage_limit.goDefines shared instance state, default limits, validation, deployment precedence, and user cleanup.
proto/…/instance_setting.protoDefines the stored policy model and metric meanings.
proto/…/user_service.protoDefines the user usage resource and effective-limit fields.
web/…/UsageSection.tsxShows how users see current usage and request-size limits.
web/…/UsageLimitsSection.tsxShows how administrators view, order, and manage the policy entries.
web/…/UsageLimitDialog.tsxShows how administrators select users and edit metric values.
web/…/usageLimitValues.tsDefines the units and conversion used by limit forms and displays.
web/…/error.tsShows how quota metadata becomes a user-facing message.
server/…/usage_limit_service_test.goVerifies the API permissions, policy order, enforcement, and refusal contract.
store/…/usage_limit_test.goVerifies defaults, policy validation, conditional updates, and user cleanup.