Upgrade

Memos applies database migrations automatically on startup, so an upgrade is: back up, replace the version, start, verify. Downgrading after a migration has run is not supported — your backup is the rollback path.

Before every upgrade

1. Back up the database and attachments — see Backup & Restore.
2. Read the changelog for the versions you are skipping. Both historical minor releases (0.x → 0.y) and calendar releases can contain breaking changes.
3. Note your current version so you can report it if something goes wrong.

API reference support window

The online API reference publishes the current main schema and the two newest minor release series. When a new minor series is added, the oldest rendered reference is retired. Historical OpenAPI YAML snapshots remain in the website repository for reproducibility, but they are not maintained as supported online documentation.

If your instance falls outside this window, upgrade it before developing or debugging an integration against the current API reference.

Upgrading to 26.10

26.10-rc.1 is a release candidate. Back up before upgrading and pin neosmemo/memos:26.10-rc.1 to test this release. It does not update the stable container tag. Read the release changelog.

Required upgrade path

• From 0.31.0, upgrade directly.
• From 0.22 through 0.30, first upgrade to 0.31.0 and start it successfully, then install 26.10.
• From a version earlier than 0.22, first run 0.25.3, then 0.31.0, then install 26.10.
• Fresh installations can start with 26.10 directly.

Clients and workflows

• Update every API client from /api/v1/... to /api/..., and update Connect/gRPC procedure paths, renamed fields, and types. Regenerate binary protobuf clients. The old paths return 410 Gone for this release and are removed in the next release. Use the 26.10 client migration checklist.
• Replace the removed built-in Tasks View with a View using has_task_list && has_incomplete_tasks.
• Move a top-level memo by editing its Space in the audience menu, then saving. The separate Move to Space action is removed.
• Deleting a memo now deletes its comments and nested replies as well. Review a discussion before deleting its parent.

After upgrading, verify sign-in, existing memos, attachments, creator and Space filters, and API integrations. Check that Calendar and Map expose only the memos each signed-in user or visitor can read.

Upgrading to 0.31

These notes apply to 0.31.0, the latest stable release. Back up before upgrading and use neosmemo/memos:0.31.0 to pin this release. Read the release changelog.

Access and deployment

• A missing ACCESS setting is initialized once from the previous URL-based behavior: configured URL means public, empty URL means private. Later URL changes do not change access policy.
• Upgrade or drain every older replica before changing access. Older binaries still use the URL to decide who may read anonymously.
• MEMOS_INSTANCE_URL must be absolute HTTP(S), without credentials, a query, or a fragment. Configure it separately from the access policy.
• Replace blanket private-webhook access with --webhook-private-network-allowlist or MEMOS_WEBHOOK_PRIVATE_NETWORK_ALLOWLIST. The older allow-private option remains compatible but is deprecated.
• Building from source requires Go 1.27 or newer.

Data and ownership

• Account emails remain optional, but are trimmed, lowercased, and unique per instance. The upgrade clears invalid addresses and keeps duplicate addresses only on the oldest account; affected usernames are logged.
• Existing memos remain Unassigned; no default Space is created. Their IDs, authors, visibility, and relations are preserved.
• Stored Shortcut resources migrate to Views automatically. Named storage configurations and legacy storage settings migrate across SQLite, MySQL, and PostgreSQL; generated-ID high-water marks are retained.
• Memo edits, attachments, references, and shares follow author and Space membership rules. Active instance administrators can read and manage individual memos, including private and Space-only memos, without authorship or Space membership. Collection listings still filter by audience. Space admin roles do not override authorship. Users control their own reactions.
• Comments have independent visibility, placement, and lifecycle. Deleting a parent does not delete its comment memos. Deleting a Space permanently deletes every directly assigned memo and its owned resources; removing a member leaves contributions in place.
• Active Space memberships block account deletion, including with force.
• New tag grammar takes effect immediately in rendering and editing. Stored filter and statistics indexes adopt it when each memo is saved again; there is no automatic full backfill.

Integrations and links

• Update app bookmarks from /shortcuts to /views. Replace ShortcutService, shortcut resource paths, and MCP tool names with their Views equivalents.
• Send comment visibility explicitly: CreateMemoComment defaults an omitted value to PRIVATE. SetMemoRelations rejects COMMENT relations.
• Stop reading Reaction.content_id. Existing reactions migrate to internal memo IDs; orphaned reactions are removed.
• Bind managed inline images before or during the memo mutation. Use authenticated Memos routes for S3 files instead of expecting presigned URLs in externalLink.
• Match username case exactly. Existing legacy spellings remain addressable, but unsupported spellings cannot be authored as new mentions.
• Allow unset message fields to be absent in gateway JSON while scalar defaults and empty lists remain present.

See API migration details.

Removed features

Built-in Explore and user RSS feeds were removed. /explore/rss.xml and /u/:username/rss.xml return 404; there is no replacement built-in feed endpoint. Update feed readers and integrations. Use the API for reads or webhooks for user-scoped change events when those match your needs.

The global Cmd/Ctrl+K shortcut was removed. Open Quick Find from the sidebar search action.

Verify the upgrade

Check exact-case sign-in, intended anonymous access, existing memos and Views, old and new storage attachments, share links, and your API/MCP/webhook clients. In Spaces, test invitation acceptance, members-only visibility, and author permissions with separate accounts before inviting your team.

If an old memo's displayed tags and filter results differ, save that memo again. If a migrated setting or attachment fails, inspect startup logs and the preserved configuration before changing or deleting storage entries.

Upgrading to 0.30

These historical notes describe 0.30. For 0.31, apply the newer access, RSS, and Views changes above as well. Version 0.30 changes several public access and integration behaviors. Before deploying it:

• Back up the database and attachments.
• Set MEMOS_INSTANCE_URL to the canonical public URL if the instance should remain publicly accessible. An empty value now enables private mode.
• Update saved CEL shortcut expressions that use now() or Unix timestamps. Use the now timestamp value, duration arithmetic such as now - duration, and CEL timestamps instead.
• Reconfigure MCP clients to use the /mcp endpoint and service-prefixed tool names. The old aliases, prompts, resources, and unprefixed tools were removed.
• Update clients that read shared memos from GetMemoByShare (/api/v1/shares/{shareId}) to GetSharedMemo (/api/v1/shares/{shareToken}/memo).
• Review shared-memo assumptions: a share token exposes the selected memo, attachments, and reactions, but not its parent, comments, or relations.
• Review tag display settings after the per-instance tag metadata migration. Tag colors and blur rules are now stored per user.

After the upgrade, verify sign-in, public memo and RSS access if enabled, shared links, and any MCP, webhook, or API integrations you operate.

Docker

docker pull neosmemo/memos:stable
docker stop memos
docker rm memos
# re-run your original docker run command — the data volume keeps your data

The exact docker run flags are in the Docker guide.

Docker Compose

docker compose pull
docker compose up -d

Binary

1. Stop the service (systemctl stop memos or your supervisor's equivalent).
2. Replace the binary with the new release from GitHub releases.
3. Start the service and watch the logs for migration output.

See the Binary guide for service setup.

Pinning versions

neosmemo/memos:stable tracks the latest stable release, which is convenient but upgrades implicitly on every pull. For production, pin a specific version tag (for example neosmemo/memos:0.31.0) and upgrade deliberately.

From 26.10 onward, release tags use calendar versions without a v prefix: 26.10 is a monthly release and 26.10.1 is a patch. Stable releases publish exact-version, monthly-series, and stable container tags. Release candidates publish only their exact tag, such as 26.10-rc.1.

Verify after upgrading

• the UI loads and you can sign in
• a new memo can be created and an existing one opens
• attachments load (storage config survived the upgrade)

Rolling back

Restore the pre-upgrade backup and start the previous version. Do not point an old version at a database that a newer version has already migrated.