# Memos — Full content
> Memos is an open-source, self-hosted note-taking app for your everyday thoughts. It’s a place to write what’s on your mind as you go about your day. A single sentence can be a whole memo, or you can take your time with a longer entry, using Markdown to give your words more structure.
These moments of writing gradually become a personal record. Each memo stays with the day you wrote it, bringing your thoughts together in a timeline you can look back through. Tags connect related thoughts across those days, making it easy to pick up a topic again or find something you remember writing.
That record lives on your own server, and your data stays yours. You choose what stays private, what to share with family and friends, and what to publish on the web. In shared spaces, you can write alongside others while each person keeps their own memos.
# Documentation
URL: https://usememos.com/docs
Memos is an open-source, self-hosted note-taking app for your everyday thoughts. It’s a place to write what’s on your mind as you go about your day. A single sentence can be a whole memo, or you can take your time with a longer entry, using Markdown to give your words more structure.
These moments of writing gradually become a personal record. Each memo stays with the day you wrote it, bringing your thoughts together in a timeline you can look back through. Tags connect related thoughts across those days, making it easy to pick up a topic again or find something you remember writing.
That record lives on your own server, and your data stays yours. You choose what stays private, what to share with family and friends, and what to publish on the web. In shared spaces, you can write alongside others while each person keeps their own memos.
Start with Getting Started, then move into deployment, configuration, and daily use.
The usage and configuration guides cover **0.31.0**, the latest stable release. Read the [release changelog](/changelog/0-31-0) and [0.31 upgrade notes](/docs/operations/upgrade#upgrading-to-031) before upgrading. The API reference provides separate version selections.
## Popular Paths [#popular-paths]
Start a local instance with one Docker command and write your first memo.
Run Memos in a single container with a persistent data directory.
Use a checked-in Compose file for repeatable self-hosted deployments.
Put Memos behind your public domain with TLS and proxy headers.
Lock down authentication, public access, and deployment defaults.
Protect your memos with a clear recovery path before you need it.
Explore the REST and gRPC APIs for automation and integrations.
Connect Memos to the rest of your stack with event-driven automation.
## Browse All Docs [#browse-all-docs]
Start an instance with Docker and write your first memo.
Run Memos with Docker, Compose, source builds, or Kubernetes.
Configure runtime flags, database, storage, authentication, and security.
Instance settings and user management.
Write memos in Markdown, then find them again with search, tags, and Views.
Explore Bullet Journal, GTD, and Zettelkasten in Memos.
API access, MCP, webhooks, and community tools.
Plan backups, upgrade safely, and tune production performance.
Common issues and fixes.
Quick answers about licensing, data, and limits.
REST and gRPC API reference.
Set up a local environment, build Memos, test changes, and contribute.
---
# Admin
URL: https://usememos.com/docs/admin
Instance administration shapes how people join and use your Memos instance. Start here to manage shared settings and accounts, and to understand how instance roles relate to Space membership and memo ownership.
Manage access and registration policies, storage, notifications, and memo behavior across the instance.
Understand instance and Space roles, manage accounts, and resolve memberships before removing a user.
## Choose the question you need to answer [#choose-the-question-you-need-to-answer]
| If you want to know… | Start with… |
| ---------------------------------------------------- | -------------------------------------------------------------------- |
| How do I control registration and public access? | [Instance Settings](/docs/admin/instance-settings) |
| Where do I configure uploads, email, or memo limits? | [Instance Settings](/docs/admin/instance-settings) |
| What can an instance admin or a Space admin do? | [Users & Roles](/docs/admin/users-roles) |
| What must I check before removing an account? | [Users & Roles](/docs/admin/users-roles#removing-access-or-accounts) |
Active instance administrators can read and manage individual memos, including private and Space-only content. Collection listings still filter by audience, and administrators do not automatically become Space members. Review roles and membership together when deciding who needs access.
For server configuration and sign-in setup, continue to [Configuration](/docs/configuration). For creating and using a shared workspace, see [Spaces](/docs/usage/spaces).
---
# Instance Settings
URL: https://usememos.com/docs/admin/instance-settings
Instance settings control authentication, storage, and memo policies. Admins can update these settings in the app or via the Instance Settings API.
Common areas include:
* Instance access policy: public or private access, stored independently of the canonical instance URL.
* General access controls: user registration, password auth, username and nickname changes, week start day, and custom instance profile.
* Storage settings: named database, local filesystem, or S3-compatible configurations with stable IDs, a default for new uploads, file path templates, and upload limits.
* Memo-related settings: content length limits, double-click editing, and allowed reaction values.
* Notification settings: SMTP email delivery, sender details, reply-to address, and the email test endpoint.
* AI settings: instance-level OpenAI or Gemini providers and speech-to-text transcription defaults.
Tag colors and content-blur rules are user settings in Memos 0.30 and later, not instance settings. See [Tags](/docs/usage/tags).
## Access policy [#access-policy]
In 0.31, the `ACCESS` setting determines whether anonymous visitors may read public content. `MEMOS_INSTANCE_URL` supplies the canonical external address and no longer changes an existing access policy. Use [deployment-managed access configuration](/docs/configuration/deployment-configuration#access-policy) when infrastructure should own this setting.
Active instance admins manage these policies and can read and manage individual memos, including other authors' private and Space-only memos. They do not automatically become Space members, and collection listings still filter by audience. See [Users & Roles](/docs/admin/users-roles).
## Sensitive settings [#sensitive-settings]
Storage, notification, and AI settings can contain credentials. API responses do not return stored S3 secrets, SMTP passwords, or AI provider API keys in plaintext. When updating those settings, submit a new secret only when you intend to replace it.
## Related API [#related-api]
* [Get Instance Setting](/docs/api/latest/instanceservice/GetInstanceSetting)
* [Batch Get Instance Settings](/docs/api/latest/instanceservice/BatchGetInstanceSettings)
* [Update Instance Setting](/docs/api/latest/instanceservice/UpdateInstanceSetting)
* [Test Instance Email Setting](/docs/api/latest/instanceservice/TestInstanceEmailSetting)
---
# Users & Roles
URL: https://usememos.com/docs/admin/users-roles
Memos has two instance roles: **Admin** and **User**. The first account created during setup becomes an instance admin. Instance admins manage accounts, instance configuration, and access policy.
## Instance roles and Space roles [#instance-roles-and-space-roles]
Each [Space](/docs/usage/spaces) has its own accepted **Admin** and **User** memberships. Instance roles and Space roles are independent: an instance User can create and administer a Space, while an instance Admin has no automatic membership in another user's Space.
Space admins manage the Space's metadata, invitations, and members. A Space admin role does not grant editing rights to another author's memos. Active instance administrators can read and manage individual memos, including private and Space-only memos, without being the author or a Space member. Collection listings still filter by audience; instance administrators do not automatically join Spaces.
## Usernames [#usernames]
Sign-in and username lookup are case-sensitive: `Alice` and `alice` are different spellings. New and renamed usernames must contain 1–36 ASCII letters or digits, with hyphens allowed only inside the name. Underscores, email addresses, and non-ASCII usernames cannot be newly assigned.
Legacy usernames remain addressable with their exact spelling. Spellings outside the new grammar cannot be written as new mentions. See [Authentication](/docs/configuration/authentication) and [Mentions](/docs/usage/reactions-comments#mentions).
## Removing access or accounts [#removing-access-or-accounts]
Removing a Space member leaves their contributions in that Space. A Space must always retain an active admin, so assign another admin before removing or archiving the last one.
Deleting an account is blocked while it has active Space memberships, including when the API request sets `force`. Resolve those memberships first. Deleting a Space instead permanently deletes all directly assigned memos; it is not an equivalent way to remove one user's access.
---
# Configuration
URL: https://usememos.com/docs/configuration
Configure Memos around how your instance runs, where its data lives, and how people sign in. These pages explain startup options, deployment-managed settings, database and attachment storage, and access controls.
Set the listen address, port, data directory, database connection, and canonical instance URL.
Load selected instance settings and identity providers from mounted JSON files at startup.
Configure SQLite, MySQL, or PostgreSQL and understand the operational tradeoffs.
Choose where attachments live and manage named storage configurations for new and existing files.
Configure password sign-in, SSO providers, and personal access tokens.
Review HTTPS, credentials, sharing, and recovery as part of operating your instance.
## Choose the question you need to answer [#choose-the-question-you-need-to-answer]
| If you want to know… | Start with… |
| ------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| How do I change the port, data path, or external URL? | [Environment Variables](/docs/configuration/environment-variables) |
| How do I keep settings under deployment or secret-manager control? | [Deployment-Managed Configuration](/docs/configuration/deployment-configuration) |
| Which database fits my deployment? | [Database](/docs/configuration/database) |
| Where should uploads be stored? | [Storage](/docs/configuration/storage) |
| How do I set up SSO or authenticate an integration? | [Authentication](/docs/configuration/authentication) |
| What should I review before exposing the instance? | [Security](/docs/configuration/security) |
## Configuration layers [#configuration-layers]
Runtime flags and `MEMOS_*` environment variables control server startup. Instance settings manage policies and services through the UI or API. When a supported setting is supplied by a deployment-managed file, that file is authoritative for the server process; changes to it require a restart.
In Memos 0.31, the `ACCESS` instance setting selects public or private access independently of `MEMOS_INSTANCE_URL`. Set the URL to the canonical external HTTP(S) address, including for private instances behind a proxy. Manage access in instance settings or a [deployment-managed access file](/docs/configuration/deployment-configuration#access-policy).
For the installation itself, start with [Deploy](/docs/deploy). Once Memos is running, use [Admin](/docs/admin) for ongoing instance and account management, and [Reverse Proxy](/docs/deploy/reverse-proxy) for HTTPS and forwarded headers.
---
# Authentication
URL: https://usememos.com/docs/configuration/authentication
Memos supports three primary authentication mechanisms:
* password-based sign-in
* OAuth2 or SSO identity providers
* personal access tokens for API use
Use password sign-in for simple private instances. Use SSO when your team already has a central identity provider and you want Memos sign-in to follow that identity system. Use personal access tokens for scripts and integrations.
## Session model [#session-model]
| Token type | Lifetime | Storage | Notes |
| --------------------------- | --------------------------------------- | ------------------ | -------------------------------------- |
| Access token (JWT) | 15 min | Client memory | Stateless; verified without a DB query |
| Refresh token (JWT) | 30 days | HTTP-only cookie | Database-backed, revocable |
| Personal access token (PAT) | User-selected; no expiration by default | SHA-256 hash in DB | Format: `memos_pat_<32 random chars>` |
The plain PAT is shown only once at creation time. Only its SHA-256 hash is stored in the database.
For automation or external tools, use personal access tokens instead of browser-style cookie flows.
## Password authentication [#password-authentication]
Password authentication is enabled by default. It is simple and works well for single-user or small private instances.
Password auth is usually the right starting point when:
* the instance is personal or very small
* you do not already have a central identity provider
* you want minimal setup complexity
Users sign in with their Memos username and password. Archived users cannot sign in. Failed sign-in attempts use the same error message for unknown usernames and wrong passwords, so the login page does not reveal whether a username exists.
### Username spelling [#username-spelling]
In 0.31, sign-in and lookup use exact-case usernames. `Alice` and `alice` are distinct spellings. New or renamed usernames must contain 1–36 ASCII letters or digits, with hyphens only inside the name. Existing legacy names remain addressable, but unsupported spellings cannot be used for new mentions. When diagnosing a failed sign-in after upgrading, check the stored username and its case before resetting credentials.
### Disable password authentication [#disable-password-authentication]
Admins can disable password sign-in for regular users after SSO is configured. When password auth is disabled:
* regular users must sign in with SSO
* password-based registration is unavailable
* admins can still use password sign-in through the admin sign-in path
* the regular sign-in page hides the password form
Keep at least one admin account with a known password. This gives you a recovery path if an SSO provider is misconfigured or temporarily unavailable.
## OAuth2 and SSO [#oauth2-and-sso]
SSO is the right choice for team instances that already use a central identity system. Configure the provider in instance settings, then test login with a non-admin account before forcing the whole instance onto SSO-only behavior.
The OAuth2 callback URL for your Memos instance is:
```text
https:///auth/callback
```
Register that exact URL in the OAuth2 application for your identity provider.
### How SSO users are matched [#how-sso-users-are-matched]
Memos stores local users separately from external SSO accounts. When a user signs in through SSO, Memos reads the configured identifier field from the provider's user info response and looks for an existing linked identity.
If a matching linked identity already exists, Memos signs in to the same local user. If no match exists and registration is allowed, Memos creates a regular local user and links that external account. If user registration is disabled, first-time SSO sign-in is rejected until an account is created or linked by another flow.
For a new SSO user, Memos first tries to use the mapped external identifier as the local username when it satisfies the username rules and is not reserved. If that value is invalid or already belongs to another account, Memos generates a UUID-based username instead. It never links an SSO identity to an existing account merely because the usernames match.
### OAuth2 provider fields [#oauth2-provider-fields]
Each identity provider requires:
* `clientId` and `clientSecret` from the OAuth2 application
* `authUrl`, `tokenUrl`, and `userInfoUrl` for the provider's OAuth2 endpoints
* `scopes` the token should request
* `fieldMapping` to map the provider's user info fields to Memos fields (`identifier`, `displayName`, `email`, `avatarUrl`)
* optional `identifierFilter`, a regex applied to the identifier value; users that do not match are denied
The `identifier` mapping is the most important setting. It becomes the external identity key that Memos uses for future sign-ins. Choose a stable provider field such as a subject ID, username, or email address depending on how your provider guarantees identity stability.
Changing the provider UID or the `fieldMapping.identifier` value after users have signed in can prevent Memos from finding existing linked identities. Treat those settings as stable once SSO is in use.
Use `identifierFilter` to restrict who can sign in. For example, a filter can allow only users from a specific email domain. Test the regex carefully; a bad filter can block every SSO user.
Memos only reads string fields from the user info response. If your provider returns nested objects or non-string values for a field, adjust the provider configuration or expose a flat string claim.
### GitHub [#github]
```json
{
"title": "GitHub",
"type": "OAUTH2",
"config": {
"oauth2Config": {
"clientId": "",
"clientSecret": "",
"authUrl": "https://github.com/login/oauth/authorize",
"tokenUrl": "https://github.com/login/oauth/access_token",
"userInfoUrl": "https://api.github.com/user",
"scopes": ["read:user", "user:email"],
"fieldMapping": {
"identifier": "login",
"displayName": "name",
"email": "email",
"avatarUrl": "avatar_url"
}
}
}
}
```
GitHub's `email` field can be empty depending on the user's profile privacy and granted scopes. If you need a guaranteed identifier, use `login` or another stable field from your identity policy.
### Google [#google]
```json
{
"title": "Google",
"type": "OAUTH2",
"config": {
"oauth2Config": {
"clientId": "",
"clientSecret": "",
"authUrl": "https://accounts.google.com/o/oauth2/v2/auth",
"tokenUrl": "https://oauth2.googleapis.com/token",
"userInfoUrl": "https://www.googleapis.com/oauth2/v2/userinfo",
"scopes": ["openid", "profile", "email"],
"fieldMapping": {
"identifier": "email",
"displayName": "name",
"email": "email",
"avatarUrl": "picture"
}
}
}
}
```
Google `email` works well for many private deployments, especially when combined with an `identifierFilter` that limits access to your domain. If your organization can rename or recycle email addresses, prefer a stable subject field if your provider exposes one through user info.
### Safe SSO rollout [#safe-sso-rollout]
1. Create the OAuth2 application with `https:///auth/callback` as the callback URL.
2. Add the identity provider in Memos and save the client ID, client secret, endpoints, scopes, and field mappings.
3. Test SSO sign-in with a non-admin account.
4. Confirm first-time SSO behavior matches your registration policy.
5. Keep admin password access available as a recovery path.
6. Disable password authentication for regular users only after SSO is working.
## Linked identities [#linked-identities]
Users can link an external SSO account to their existing Memos account from account settings. After a provider is linked, signing in with that SSO account opens the same Memos user.
Each Memos user can link at most one external account per identity provider. The same external account cannot be linked to multiple Memos users.
Unlinking removes only the relationship between the Memos user and the external account. It does not delete the Memos user, the identity provider configuration, or the external account. Before unlinking, make sure the user still has another usable sign-in method.
See [Linked Identities](/docs/usage/linked-identities) for the end-user workflow.
## Personal access tokens [#personal-access-tokens]
PATs are intended for scripts, integrations, and external tools.
Use PATs when:
* calling the API from automation
* integrating with external services
* avoiding interactive browser login flows
Operational guidance:
* create a separate token for each application or integration
* choose an expiration when the integration does not need a permanent credential; new tokens default to no expiration
* review the last-used timestamp to find abandoned credentials
* rotate tokens periodically
* delete tokens that are no longer needed
* do not embed PATs into public clients or front-end code
## API references [#api-references]
* [Auth Service: SignIn](/docs/api/latest/authservice/SignIn)
* [Identity Provider Service: CreateIdentityProvider](/docs/api/latest/identityproviderservice/CreateIdentityProvider)
---
# Database
URL: https://usememos.com/docs/configuration/database
Memos supports three database backends:
* `sqlite` for the default single-instance setup
* `mysql` for managed or larger deployments
* `postgres` for managed or larger deployments
## SQLite [#sqlite]
SQLite is the default and the best fit for most personal deployments or small teams running a single node.
Useful defaults in Memos include WAL mode and a busy timeout, which help reduce common lock contention problems.
Typical SQLite setup:
```bash
MEMOS_DRIVER=sqlite MEMOS_DATA=/var/opt/memos memos
```
If you need an explicit file path:
```bash
MEMOS_DRIVER=sqlite MEMOS_DSN=/opt/memos/memos.db memos
```
SQLite is usually enough when:
* one instance handles all writes
* your dataset is modest
* operational simplicity matters more than cluster-style scaling
## MySQL and PostgreSQL [#mysql-and-postgresql]
Use MySQL or PostgreSQL when:
* you want managed backups and tooling
* you already operate a database server
* you expect larger datasets or more operational controls
* you do not want the application host to carry the database file locally
Examples:
```bash
MEMOS_DRIVER=mysql \
MEMOS_DSN="memos_user:password@tcp(db:3306)/memos?charset=utf8mb4&parseTime=True&loc=Local" \
memos
```
```bash
MEMOS_DRIVER=postgres \
MEMOS_DSN="postgres://memos_user:password@db:5432/memos?sslmode=disable" \
memos
```
## Selection guidance [#selection-guidance]
* choose SQLite for one-node simplicity
* choose MySQL or PostgreSQL for operational flexibility
* keep backups aligned with your database choice
* if you store attachments outside the database, back those up separately
## Performance implications [#performance-implications]
Database choice changes where bottlenecks show up:
* SQLite tends to surface write contention first
* MySQL and PostgreSQL push complexity into networked DB operations and tuning
* attachment storage can dominate recovery and backup time even when the DB is healthy
---
# Deployment-Managed Configuration
URL: https://usememos.com/docs/configuration/deployment-configuration
Memos 0.30 and later can load selected configuration from JSON files mounted under `/etc/secrets`. Use this when settings such as SSO, storage credentials, or registration policy should be controlled by Docker Compose, Kubernetes, GitOps, or a secret manager instead of the admin UI.
File-backed configuration is loaded once at startup and remains authoritative for that server process. Settings not supplied by files continue to use the database and can be managed normally in Memos.
## Quick start with Docker Compose [#quick-start-with-docker-compose]
Create a directory for the configuration files:
```text
.
├── compose.yaml
└── memos-secrets/
└── memos-instance-setting-general.json
```
Add `memos-secrets/memos-instance-setting-general.json`:
```json
{
"key": "GENERAL",
"generalSetting": {
"disallowUserRegistration": false,
"disallowPasswordAuth": false,
"additionalScript": "",
"additionalStyle": "",
"weekStartDayOffset": 1,
"disallowChangeUsername": false,
"disallowChangeNickname": false,
"customProfile": {
"title": "Team Memos",
"description": "Notes for our team",
"logoUrl": "https://example.com/logo.png"
}
}
}
```
Mount the directory read-only at `/etc/secrets`:
```yaml
services:
memos:
image: neosmemo/memos:stable
ports:
- "5230:5230"
volumes:
- ./memos-data:/var/opt/memos
- ./memos-secrets:/etc/secrets:ro
```
Make sure the files are readable by the Memos container user, then recreate the container:
```bash
docker compose up -d --force-recreate
docker compose logs memos
```
The startup log reports how many identity providers and instance settings were loaded. It does not print configuration values or secrets.
## Supported files [#supported-files]
Memos scans direct children of `/etc/secrets` and reads only these filename patterns:
| Resource | Filename | Stable key |
| ------------------------ | ------------------------------------------ | -------------- |
| OAuth2 identity provider | `memos-idp-.json` | `uid` |
| Access policy (0.31+) | `memos-instance-setting-access.json` | `ACCESS` |
| General settings | `memos-instance-setting-general.json` | `GENERAL` |
| Storage settings | `memos-instance-setting-storage.json` | `STORAGE` |
| Memo behavior | `memos-instance-setting-memo-related.json` | `MEMO_RELATED` |
| Email notifications | `memos-instance-setting-notification.json` | `NOTIFICATION` |
| AI providers | `memos-instance-setting-ai.json` | `AI` |
Use lowercase kebab case for ``, such as `primary-sso` or `company-login`. The label makes the filename readable; the `uid` or `key` inside the file identifies the resource.
Each matching file must:
* contain exactly one JSON resource;
* use the fields shown in this guide, with no unknown fields;
* be no larger than 1 MiB; and
* be a regular file or a symlink that resolves to a regular file.
A missing `/etc/secrets` directory is a normal no-op. Unrelated files in the directory are ignored. A matching file that cannot be read or validated prevents Memos from starting.
## OAuth2 identity provider [#oauth2-identity-provider]
An identity-provider file contains one OAuth2 provider. The `uid` is required and should remain stable after users begin signing in. Do not include a database-generated `id`.
Example `/etc/secrets/memos-idp-primary-sso.json`:
```json
{
"uid": "primary-sso",
"name": "Company SSO",
"type": "OAUTH2",
"identifierFilter": "",
"config": {
"oauth2Config": {
"clientId": "client-id",
"clientSecret": "client-secret",
"authUrl": "https://idp.example.com/oauth/authorize",
"tokenUrl": "https://idp.example.com/oauth/token",
"userInfoUrl": "https://idp.example.com/oauth/userinfo",
"scopes": ["openid", "profile", "email"],
"fieldMapping": {
"identifier": "sub",
"displayName": "name",
"email": "email",
"avatarUrl": "picture"
}
}
}
}
```
Required values include `uid`, `name`, the client ID and secret, all three OAuth2 endpoint URLs, at least one scope, and `fieldMapping.identifier`. Duplicate UIDs across files are rejected.
The OAuth2 callback URL remains:
```text
https:///auth/callback
```
See [Authentication](/docs/configuration/authentication) for provider setup and identity-mapping guidance.
## Instance settings [#instance-settings]
Each instance-setting file contains a `key` and the matching settings object. A file supplies the complete effective group: omitted scalar fields use their default values instead of inheriting values from the database. Empty secret fields are also treated as empty values.
### Access policy [#access-policy]
In 0.31, use `memos-instance-setting-access.json` to select access independently of the canonical instance URL:
```json
{
"key": "ACCESS",
"accessSetting": {
"accessMode": "INSTANCE_ACCESS_MODE_PRIVATE"
}
}
```
Use `INSTANCE_ACCESS_MODE_PUBLIC` to allow eligible anonymous public reads. The mode must be explicit; an omitted or unspecified mode is rejected. This setting does not revoke existing share links.
Set `MEMOS_INSTANCE_URL` separately to the canonical external HTTP(S) URL. Credentials, queries, and fragments are not allowed. A private instance can have a canonical URL behind a reverse proxy.
The first upgraded startup initializes a missing database access setting from the old URL-based behavior. Later URL changes do not change access. Upgrade every replica before changing the policy; older binaries still infer public access from the URL. See [Upgrading to 0.31](/docs/operations/upgrade#upgrading-to-031).
### General [#general]
Use `memos-instance-setting-general.json` with `key: "GENERAL"`. The complete format is shown in the [Docker Compose quick start](#quick-start-with-docker-compose).
`weekStartDayOffset` accepts `0` for Sunday through `6` for Saturday.
### Storage [#storage]
For 0.31, use named entries in `storages` and select one with `defaultStorageId`. Each entry has a stable ID; existing attachments continue to use the configuration identified at upload time.
In deployment files, `storages[].type` must be `STORAGE_TYPE_DATABASE`, `STORAGE_TYPE_LOCAL`, or `STORAGE_TYPE_S3`. The shorter values used by the instance API are not accepted for this field.
```json
{
"key": "STORAGE",
"storageSetting": {
"filepathTemplate": "assets/{timestamp}_{uuid}_{filename}",
"uploadSizeLimitMb": "30",
"defaultStorageId": "team-assets",
"storages": [
{
"id": "team-assets",
"name": "Team assets",
"type": "STORAGE_TYPE_S3",
"s3Config": {
"accessKeyId": "access-key",
"accessKeySecret": "secret-key",
"endpoint": "https://s3.example.com",
"region": "us-east-1",
"bucket": "memos-assets",
"usePathStyle": false,
"insecureSkipTlsVerify": false
}
}
]
}
}
```
Keep every configuration referenced by existing attachments when replacing this complete settings group. Changing the default affects new uploads only. Legacy `storageType` and top-level `s3Config` remain supported for compatibility, but new configurations should use the named format. This example requires 0.31 or later; use `neosmemo/memos:0.31.0` to pin the release.
Only enable `insecureSkipTlsVerify` for a trusted S3-compatible endpoint using a self-signed certificate. It disables TLS certificate verification.
### Memo behavior [#memo-behavior]
```json
{
"key": "MEMO_RELATED",
"memoRelatedSetting": {
"contentLengthLimit": 1048576,
"enableDoubleClickEdit": true,
"reactions": ["👍", "❤️", "🎉"]
}
}
```
`contentLengthLimit` is measured in bytes. `reactions` supplies the allowed reaction values for the instance.
### Notifications [#notifications]
```json
{
"key": "NOTIFICATION",
"notificationSetting": {
"email": {
"enabled": true,
"smtpHost": "smtp.example.com",
"smtpPort": 587,
"smtpUsername": "memos",
"smtpPassword": "smtp-secret",
"fromEmail": "memos@example.com",
"fromName": "Memos",
"replyTo": "support@example.com",
"useTls": true,
"useSsl": false
}
}
}
```
When email is enabled, `smtpHost`, a positive `smtpPort`, and `fromEmail` are required. Do not enable both `useTls` and `useSsl`.
### AI providers [#ai-providers]
Every provider needs an explicit, unique `id`, a title, a supported type (`OPENAI` or `GEMINI`), and an API key.
```json
{
"key": "AI",
"aiSetting": {
"providers": [
{
"id": "openai-main",
"title": "OpenAI",
"type": "OPENAI",
"endpoint": "https://api.openai.com/v1",
"apiKey": "api-key"
}
],
"transcription": {
"providerId": "openai-main",
"model": "gpt-4o-mini-transcribe",
"language": "en",
"prompt": ""
}
}
}
```
`transcription.providerId` must reference a provider in the same file. An empty OpenAI endpoint defaults to `https://api.openai.com/v1`; an empty Gemini endpoint defaults to `https://generativelanguage.googleapis.com/v1beta`.
The `BASIC` and `TAGS` setting groups cannot be deployment-managed.
## SSO-only deployment [#sso-only-deployment]
An SSO-only instance needs both:
1. an identity-provider file such as `memos-idp-primary-sso.json`; and
2. `memos-instance-setting-general.json` with `disallowPasswordAuth` set to `true`.
Keep `disallowUserRegistration` set to `false` if first-time SSO users should be created automatically. Memos refuses to start if regular password sign-in is disabled without an effective identity provider. The administrator password sign-in path remains available for recovery.
## Precedence and removal [#precedence-and-removal]
A file-backed identity provider shadows a stored provider with the same `uid`. A file-backed instance-setting group shadows the database row with the same `key`. Other stored resources remain active.
Memos does not copy the file into the database or delete the value underneath it. If you remove a file and restart Memos, the previous database value becomes effective again. Delete or update an obsolete stored value yourself if you do not want it to return.
Updates and deletions of active file-backed resources are rejected by the API. Update the file and restart Memos instead.
## Apply changes [#apply-changes]
Configuration is loaded once per server process. After editing, adding, or removing a file, restart every Memos replica.
For Docker Compose:
```bash
docker compose restart memos
```
For Kubernetes, restart the workload after the mounted Secret changes:
```bash
kubectl rollout restart deployment/memos
```
All replicas in one deployment should mount identical files. Avoid routing traffic to replicas using different authentication or storage configurations during a rollout.
## Security [#security]
Treat `/etc/secrets` and every matching file as sensitive plaintext:
* mount the directory read-only;
* restrict host and container file permissions;
* do not commit real credentials to source control;
* use Docker secrets, Kubernetes Secrets, or your platform's secret manager; and
* keep the same files available for disaster recovery without placing them in a public backup.
Memos redacts secrets from API responses, validation errors, and startup summaries. File contents are held only in the private runtime configuration snapshot and are not persisted by the loader.
## Upgrading from the earlier identity-provider bootstrap [#upgrading-from-the-earlier-identity-provider-bootstrap]
Older versions of the `memos-idp-*.json` bootstrap copied identity providers and their client secrets into the database. The current loader does not remove those stored rows automatically.
If startup warns that a file-backed provider shadows a stored provider:
1. Back up the database and confirm administrator password access.
2. Temporarily remove the identity-provider file and restart Memos.
3. Delete or update the stored provider through the admin UI or API.
4. Restore the file and restart Memos again.
Until the stored provider is cleaned up, it can reappear when the file is removed.
## Troubleshooting [#troubleshooting]
### A file is ignored [#a-file-is-ignored]
Check that it is directly under `/etc/secrets`, uses a supported lowercase filename, and ends in lowercase `.json`. Memos warns about unrecognized direct children beginning with `memos-`.
### Memos does not start [#memos-does-not-start]
Check the startup error for the filename and field name. Common causes include unreadable files, unknown or misspelled fields, a setting object that does not match its `key`, missing S3 or SMTP fields, duplicate stable keys, and disabling password login without an identity provider.
### An API or UI update fails [#an-api-or-ui-update-fails]
Active file-backed resources cannot be changed through the API. Edit the corresponding deployment file and restart Memos.
### An old value returns after removing a file [#an-old-value-returns-after-removing-a-file]
This is expected when a database value was shadowed. Update or delete the stored value if it should no longer be used.
---
# Environment Variables
URL: https://usememos.com/docs/configuration/environment-variables
Memos maps runtime flags to environment variables with the `MEMOS_` prefix. In production, environment variables are usually the cleanest way to keep deployment config explicit and repeatable.
## Reference [#reference]
All flags and their corresponding environment variables:
| Flag | Environment variable | Default | Purpose |
| ------------------------------------- | ----------------------------------------- | -------- | --------------------------------------------------------------------- |
| `--port` | `MEMOS_PORT` | `8081` | HTTP listen port |
| `--addr` | `MEMOS_ADDR` | \`\` | Bind address (empty = all interfaces) |
| `--unix-sock` | `MEMOS_UNIX_SOCK` | \`\` | Unix socket path |
| `--data` | `MEMOS_DATA` | auto | Data directory |
| `--driver` | `MEMOS_DRIVER` | `sqlite` | Database backend (`sqlite`, `mysql`, `postgres`) |
| `--dsn` | `MEMOS_DSN` | auto | Database connection string |
| `--instance-url` | `MEMOS_INSTANCE_URL` | \`\` | Canonical external URL; independent of access policy |
| `--demo` | `MEMOS_DEMO` | `false` | Demo mode |
| `--webhook-private-network-allowlist` | `MEMOS_WEBHOOK_PRIVATE_NETWORK_ALLOWLIST` | empty | Allowed private destinations: exact hostnames, IP addresses, or CIDRs |
| `--allow-private-webhooks` | `MEMOS_ALLOW_PRIVATE_WEBHOOKS` | `false` | Deprecated blanket exception for private webhook destinations |
| `--log-level` | `MEMOS_LOG_LEVEL` | `info` | Log verbosity (`debug`, `info`, `warn`, `error`) |
### Data directory defaults [#data-directory-defaults]
`MEMOS_DATA` resolves automatically when not set:
* **Windows**: `%ProgramData%\memos`
* **Docker**: `/var/opt/memos` (when writable)
* **Linux / macOS**: current directory (`.`)
### DSN defaults [#dsn-defaults]
When `MEMOS_DRIVER=sqlite` and `MEMOS_DSN` is empty, the database file defaults to `{MEMOS_DATA}/memos_prod.db`. For MySQL and PostgreSQL, `MEMOS_DSN` is required.
### Public and private mode [#public-and-private-mode]
In Memos 0.31, access is controlled by the `ACCESS` instance setting, through `accessSetting.accessMode`:
* `INSTANCE_ACCESS_MODE_PRIVATE`: anonymous visitors are sent to sign-in; anonymous API access is limited to endpoints such as setup, authentication, registration when allowed, and explicit shared memos.
* `INSTANCE_ACCESS_MODE_PUBLIC`: eligible public memos, profiles, and Explore can be read anonymously.
Configure access in instance settings or with a [deployment-managed JSON file](/docs/configuration/deployment-configuration#access-policy). It is not a runtime flag or environment variable.
`MEMOS_INSTANCE_URL` supplies the canonical external address, including for a private instance behind a proxy. It must be an absolute HTTP(S) URL without credentials, a query, or a fragment, such as `https://memos.example.com`.
When the access setting is first initialized, Memos preserves the earlier behavior: a configured URL initializes public access; an empty URL initializes private access. Once the setting exists, changing the URL never changes the access policy. See [Upgrading to 0.31](/docs/operations/upgrade#upgrading-to-031).
## Priority order [#priority-order]
1. Command-line flags (highest)
2. Environment variables
3. Default values (lowest)
An explicit flag always wins over the environment variable for the same setting.
## Practical guidance [#practical-guidance]
* select private or public access explicitly in the `ACCESS` instance setting
* set `MEMOS_INSTANCE_URL` to the canonical external URL when the app sits behind a proxy
* prefer explicit `MEMOS_DRIVER` and `MEMOS_DSN` when you are not using SQLite defaults
* allow only required private webhook destinations with `MEMOS_WEBHOOK_PRIVATE_NETWORK_ALLOWLIST`; leave the deprecated blanket option disabled
* keep secrets such as database credentials outside committed compose files
* treat these values as part of deployment config and back them up accordingly
## Common patterns [#common-patterns]
SQLite with explicit data directory:
```bash
export MEMOS_DRIVER=sqlite
export MEMOS_DATA=/var/opt/memos
./memos
```
External PostgreSQL:
```bash
export MEMOS_DRIVER=postgres
export MEMOS_DSN="postgres://user:password@db:5432/memos?sslmode=disable"
export MEMOS_INSTANCE_URL=https://memos.example.com
./memos
```
Unix socket with Nginx (useful for local reverse proxy):
```bash
export MEMOS_UNIX_SOCK=/var/run/memos.sock
export MEMOS_DATA=/var/lib/memos
export MEMOS_INSTANCE_URL=https://memos.example.com
./memos
```
Nginx upstream for the socket:
```nginx
upstream memos {
server unix:/var/run/memos.sock;
}
```
---
# Security
URL: https://usememos.com/docs/configuration/security
Memos is self-hosted by design. You control the infrastructure, storage, and access policies.
## Token security model [#token-security-model]
Three token types handle authentication:
| Token type | Lifetime | Storage | Notes |
| --------------------- | --------------------------------------- | ------------------ | -------------------------------------------------------------------- |
| Access token (JWT) | 15 minutes | Client memory | Stateless; no DB query needed to verify |
| Refresh token (JWT) | 30 days | HTTP-only cookie | Stored in DB, revocable; `SameSite=Lax`, `Secure=true` in production |
| Personal access token | User-selected; no expiration by default | SHA-256 hash in DB | Prefix `memos_pat_`; plain token shown only once at creation |
The JWT secret is auto-generated as a UUID on first run and stored in the database. In demo mode, the fixed secret `usememos` is used — never deploy demo mode as production.
## Core recommendations [#core-recommendations]
* select private access in the `ACCESS` instance setting when anonymous public access is not intended
* set `MEMOS_INSTANCE_URL` to the canonical URL used by your reverse proxy; changing this URL does not change access policy
* disable user registration if your instance is private
* disable public memo visibility if you do not want any public content
* use HTTPS in front of the instance
* review who can create personal access tokens and who can publish public memos
## Session and auth hygiene [#session-and-auth-hygiene]
* protect the host admin account carefully
* prefer SSO for team deployments when available
* rotate credentials and tokens that are exposed or no longer needed
* use a separate PAT for each integration and review its last-used timestamp
* add an expiration when an integration does not need a permanent credential
* never enable demo mode on a production instance (it uses a hardcoded JWT secret)
## Reverse proxy requirements [#reverse-proxy-requirements]
Your proxy should:
* terminate TLS
* preserve `Host` and `X-Forwarded-*` headers
* expose the same public URL configured in `MEMOS_INSTANCE_URL`
## Attachment and sharing considerations [#attachment-and-sharing-considerations]
Security is not only about login. Public memos may expose:
* memo body content
* attached files
* links and references embedded in the memo
Treat visibility and attachment review as part of your security model.
## Backup and recovery [#backup-and-recovery]
Security is also about recoverability. Keep regular backups of:
* the database
* attachment storage when it is not stored in the database
* deployment configuration needed to recreate the instance
---
# Storage
URL: https://usememos.com/docs/configuration/storage
Memos supports three storage backends for attachments:
* database storage
* local filesystem storage
* S3-compatible object storage
Storage is usually configured at the instance level rather than purely through startup flags.
## Named storage configurations [#named-storage-configurations]
In 0.31, storage settings contain named configurations with stable IDs. Choose a default for new uploads. Existing attachments retain their storage ID, so switching the default does not move old files or change where Memos reads them.
Keep configurations that existing attachments still reference, including their credentials and backing objects. A new default is not a storage migration. Legacy settings migrate automatically on upgrade.
API and deployment-file clients should use `storages` and `defaultStorageId`. The older `storageType` and top-level `s3Config` fields remain compatibility fields. See the [deployment configuration example](/docs/configuration/deployment-configuration#storage).
## Database storage [#database-storage]
Database-backed attachments are the default.
Pros:
* simplest backup story
* no extra object store or directory layout to manage
* good default for smaller deployments
Tradeoffs:
* larger database size
* heavier database backups
* less attractive for media-heavy instances
## Local filesystem storage [#local-filesystem-storage]
Use local storage when:
* you want attachments outside the database
* you control the host or persistent volume
* you do not need cloud object storage
This is common for Docker or Kubernetes setups with a persistent volume.
## S3-compatible storage [#s3-compatible-storage]
Use S3-compatible storage when:
* you already operate object storage
* you want asset storage independent from the app host
* you expect many uploads or larger files
* you want storage behavior that is easier to scale operationally
For an S3-compatible endpoint that uses a self-signed certificate, enable
`insecureSkipTlsVerify` in the storage configuration. This disables TLS
certificate verification for that connection, so use it only for an endpoint
you control and trust. Prefer installing a trusted certificate whenever
possible.
### Authenticated delivery [#authenticated-delivery]
Memos proxies managed S3 files through its file routes and checks authorization there. Range requests support seeking and partial media reads. Managed S3 attachments no longer return presigned object URLs in `externalLink`; clients should use the Memos file route and preserve any share authorization supplied for a shared memo.
Back up all referenced storage configurations alongside the database and file objects. Changing the default storage only affects new uploads.
## Operational reminders [#operational-reminders]
* set an upload limit appropriate for your environment
* if you use local storage, back up the asset directory
* if you use S3 storage, verify credentials, bucket policy, and public/private access expectations
* remember that visibility rules still matter when files are attached to public memos
## File path templates [#file-path-templates]
For local filesystem storage, path templates are useful for organization. Timestamp-based naming is a common pattern because it avoids collisions and keeps uploaded files roughly ordered.
---
# Deploy
URL: https://usememos.com/docs/deploy
Run Memos on infrastructure you control, using the deployment method that fits your environment. These guides take you from starting the application to keeping data persistent and serving your instance over HTTPS.
Start a single container with a persistent data directory and a restart policy.
Keep service settings, volumes, and environment variables in a repeatable deployment file.
Install a native release and run it under your host's service manager.
Fit Memos into an existing cluster with persistent storage, service routing, and ingress.
Compile Memos yourself for forks, custom patches, and pinned deployments.
Serve HTTPS with the correct external URL, forwarded headers, and authentication behavior.
## Choose the question you need to answer [#choose-the-question-you-need-to-answer]
| If you want to know… | Start with… |
| --------------------------------------------------------- | --------------------------------------------- |
| How do I start one instance with Docker? | [Docker](/docs/deploy/docker) |
| How do I keep the deployment easy to recreate and update? | [Docker Compose](/docs/deploy/docker-compose) |
| How do I run Memos directly on my host? | [Binary](/docs/deploy/binary) |
| How do I deploy into a cluster I already operate? | [Kubernetes](/docs/deploy/kubernetes) |
| How do I run a fork or a build from a specific revision? | [Build From Source](/docs/deploy/development) |
| How do I serve my instance at an HTTPS URL? | [Reverse Proxy](/docs/deploy/reverse-proxy) |
Choose one installation path, then configure the external URL and proxy for that deployment. Confirm that your database and attachments survive a restart before relying on the instance for daily use.
Continue to [Configuration](/docs/configuration) for database, storage, and sign-in choices, and [Operations](/docs/operations) for backups and upgrades. To work on the Memos codebase, start with [Development](/docs/development).
---
# Binary
URL: https://usememos.com/docs/deploy/binary
Running Memos as a binary is useful when you do not want Docker in the stack or when you already manage services directly on the host.
## Supported platforms [#supported-platforms]
Pre-built binaries are available for:
* Linux: `amd64`, `arm64`, `armv7`
* macOS: Intel and Apple Silicon
* Windows: `amd64`
Release artifacts are published from the upstream GitHub releases page.
## Typical flow [#typical-flow]
1. download the archive for your platform
2. extract the binary
3. choose a persistent data directory
4. set `MEMOS_*` variables or flags
5. run the binary under a service manager
## Basic run command [#basic-run-command]
```bash
./memos --port 5230 --data /var/lib/memos
```
Defaults worth knowing:
* port `8081`
* SQLite database
* local data directory for DB and assets
## External databases [#external-databases]
Examples:
```bash
./memos \
--driver mysql \
--dsn "user:password@tcp(localhost:3306)/memos"
```
```bash
./memos \
--driver postgres \
--dsn "postgres://user:password@localhost:5432/memos?sslmode=disable"
```
## Service management [#service-management]
Binary installs work best when paired with:
* `systemd` on Linux
* `launchd` on macOS
* a Windows service wrapper or supervisor
## Why choose the binary path [#why-choose-the-binary-path]
* no container runtime dependency
* easy to integrate with existing host-level process supervision
* straightforward debugging and local inspection
## What you must manage yourself [#what-you-must-manage-yourself]
* upgrades and rollbacks
* process supervision
* data directory ownership and permissions
* reverse proxy and HTTPS in production
---
# Build From Source
URL: https://usememos.com/docs/deploy/development
Build from source when you deploy a fork, a custom patch, or a build pinned to an exact revision. If you want to work on the Memos codebase itself, start with the [Development](/docs/development) section instead — this page only covers turning a source build into a deployment.
## Produce a release build [#produce-a-release-build]
Follow [Setup](/docs/development/setup) for the toolchain, then [Building](/docs/development/building) for the build commands. A release build embeds the frontend assets into a single binary, so the result deploys exactly like a downloaded release.
For deployments, always build from a tagged or pinned revision rather than `main`:
```bash
git clone https://github.com/usememos/memos.git
cd memos
git checkout v0.31.0 # pin the version you intend to run
```
## Run the result as a deployment [#run-the-result-as-a-deployment]
The self-built binary behaves like the official release binary. Memos listens on `http://localhost:8081` by default.
Follow the [Binary](/docs/deploy/binary) guide for the production concerns:
* process supervision (systemd or similar)
* data directory ownership and permissions
* reverse proxy and HTTPS
## Before production use [#before-production-use]
* set explicit environment variables for instance URL and database
* run a smoke test against the new binary before switching traffic
* keep a backup before deploying a new build — see [Backup & Restore](/docs/operations/backup-restore)
---
# Docker
URL: https://usememos.com/docs/deploy/docker
Docker is the simplest production-style deployment for a single Memos instance.
## Quick start [#quick-start]
```bash
docker run -d \
--name memos \
--restart unless-stopped \
-p 5230:5230 \
-v ~/.memos:/var/opt/memos \
neosmemo/memos:stable
```
* The container listens on port `5230`.
* Memos stores persistent data in `/var/opt/memos` inside the container.
* The host path `~/.memos` will contain the SQLite database and local assets.
## Image tags [#image-tags]
Common tag choices:
* `stable`: safest default for production
* versioned tags such as `0.31.0`: fully pinned deployment
* branch-like tags such as `0.30`: latest patch in that line
* `latest`: development-oriented and less suitable for production
## Platform support [#platform-support]
The image ships multi-arch manifests and automatically selects the right variant:
* `linux/amd64` — x86\_64 processors
* `linux/arm64` — ARM 64-bit (Apple Silicon, Raspberry Pi 4+)
* `linux/arm/v7` — ARM 32-bit (Raspberry Pi 2/3)
## Container user [#container-user]
Memos runs as a non-root user inside the container:
* UID `10001`, GID `10001`, username `nonroot`
* The entrypoint script automatically fixes ownership of mounted volumes
If your host volume requires a different UID or GID, override them:
```bash
docker run -d \
--name memos \
-p 5230:5230 \
-v ~/.memos:/var/opt/memos \
-e MEMOS_UID=1000 \
-e MEMOS_GID=1000 \
neosmemo/memos:stable
```
## Environment variables [#environment-variables]
All `MEMOS_*` variables correspond directly to command-line flags. Common ones:
| Variable | Default | Purpose |
| ----------------------------------------- | ---------------- | ------------------------------------------------------------------------------- |
| `MEMOS_PORT` | `8081` | HTTP listen port (image default: `5230`) |
| `MEMOS_ADDR` | \`\` | Bind address (empty = all interfaces) |
| `MEMOS_DATA` | `/var/opt/memos` | Data directory |
| `MEMOS_DRIVER` | `sqlite` | Database backend |
| `MEMOS_DSN` | auto | Database connection string |
| `MEMOS_INSTANCE_URL` | \`\` | Canonical external URL; independent of access policy |
| `MEMOS_DEMO` | `false` | Demo mode |
| `MEMOS_WEBHOOK_PRIVATE_NETWORK_ALLOWLIST` | empty | Exact hostnames, IP addresses, or CIDRs allowed as private webhook destinations |
| `MEMOS_ALLOW_PRIVATE_WEBHOOKS` | `false` | Deprecated blanket exception for private webhook destinations |
| `MEMOS_LOG_LEVEL` | `info` | Log verbosity (`debug`, `info`, `warn`, `error`) |
Typical example:
```bash
docker run -d \
--name memos \
--restart unless-stopped \
-p 5230:5230 \
-v ~/.memos:/var/opt/memos \
-e MEMOS_PORT=5230 \
-e MEMOS_DRIVER=sqlite \
-e MEMOS_INSTANCE_URL=https://memos.example.com \
neosmemo/memos:stable
```
On a fresh instance, the quick-start command initializes private access because it omits `MEMOS_INSTANCE_URL`. A configured URL initializes public access only when the access setting does not yet exist. In 0.31, select the desired `ACCESS` policy in instance settings or [deployment configuration](/docs/configuration/deployment-configuration#access-policy); changing the URL of an existing instance does not change that policy.
## External databases [#external-databases]
SQLite is the default and works well for a single-node deployment. If you need MySQL or PostgreSQL, provide:
* `MEMOS_DRIVER=mysql` or `MEMOS_DRIVER=postgres`
* `MEMOS_DSN` with the appropriate connection string
MySQL example:
```bash
docker run -d \
--name memos \
-p 5230:5230 \
-v ~/.memos:/var/opt/memos \
-e MEMOS_DRIVER=mysql \
-e MEMOS_DSN="user:password@tcp(mysql-host:3306)/memos" \
neosmemo/memos:stable
```
PostgreSQL example:
```bash
docker run -d \
--name memos \
-p 5230:5230 \
-v ~/.memos:/var/opt/memos \
-e MEMOS_DRIVER=postgres \
-e MEMOS_DSN="postgres://user:password@postgres-host:5432/memos?sslmode=disable" \
neosmemo/memos:stable
```
When using an external database, the mounted volume is still relevant for local assets and instance data.
## Secrets with `_FILE` suffix [#secrets-with-_file-suffix]
The entrypoint script supports `*_FILE` variable suffixes so you can pass credentials via Docker secrets instead of plain environment variables:
```bash
echo "postgres://user:password@host:5432/memos" | docker secret create memos_dsn -
docker run -d \
--name memos \
-p 5230:5230 \
-v ~/.memos:/var/opt/memos \
-e MEMOS_DRIVER=postgres \
-e MEMOS_DSN_FILE=/run/secrets/memos_dsn \
--secret memos_dsn \
neosmemo/memos:stable
```
This works for any `MEMOS_*` variable.
## Container management [#container-management]
```bash
docker logs -f memos
docker stop memos
docker start memos
docker restart memos
```
## Upgrades [#upgrades]
```bash
docker pull neosmemo/memos:stable
docker stop memos
docker rm memos
docker run -d \
--name memos \
--restart unless-stopped \
-p 5230:5230 \
-v ~/.memos:/var/opt/memos \
neosmemo/memos:stable
```
Because data is stored in the mounted volume, replacing the container is usually safe as long as you keep the same data directory and have backups.
---
# Docker Compose
URL: https://usememos.com/docs/deploy/docker-compose
Docker Compose is a good default when you want a checked-in deployment file, predictable restarts, and easier upgrades than a one-off `docker run` command.
## Basic setup [#basic-setup]
```yaml
services:
memos:
image: neosmemo/memos:stable
container_name: memos
restart: unless-stopped
ports:
- "5230:5230"
volumes:
- ./data:/var/opt/memos
environment:
MEMOS_PORT: 5230
MEMOS_DRIVER: sqlite
MEMOS_INSTANCE_URL: https://memos.example.com
```
Run it with:
```bash
docker compose up -d
```
## Why Compose is often better than raw Docker [#why-compose-is-often-better-than-raw-docker]
* declarative configuration you can review in git
* easier upgrades and restarts
* cleaner environment variable management
* straightforward volume and network definitions
## Common operational commands [#common-operational-commands]
```bash
docker compose logs -f
docker compose down
docker compose pull
docker compose up -d
```
## Production notes [#production-notes]
* keep your data directory on persistent storage
* place Memos behind a reverse proxy for HTTPS
* set `MEMOS_INSTANCE_URL` to the canonical external URL and configure private or public access separately through the [ACCESS setting](/docs/configuration/deployment-configuration#access-policy)
* back up both the database and any local assets if you do not use database-backed attachment storage
## When to add more services [#when-to-add-more-services]
Compose becomes more useful when you also want:
* a reverse proxy container
* a dedicated MySQL or PostgreSQL container for local evaluation
* explicit secret and environment file handling
---
# Kubernetes
URL: https://usememos.com/docs/deploy/kubernetes
Use Kubernetes only if you already operate a cluster and want Memos to fit into your existing deployment model. For a single instance, Docker Compose is usually simpler.
## Core resources [#core-resources]
A typical deployment includes:
* a `Deployment` for the Memos container
* a `Service` for cluster networking
* an `Ingress` or gateway for public access
* a `PersistentVolumeClaim` for data
* a `Secret` for sensitive values such as DSNs
## SQLite vs external databases [#sqlite-vs-external-databases]
SQLite works for a single replica and is the easiest option, but it ties you to one writable pod and one persistent volume. If you need stronger operational flexibility, use MySQL or PostgreSQL and keep only local assets in persistent storage.
## Recommended shape [#recommended-shape]
* one Memos replica when using SQLite
* a persistent volume mounted at `/var/opt/memos`
* `MEMOS_INSTANCE_URL` set to the canonical external URL, with private or public access selected separately through the [ACCESS setting](/docs/configuration/deployment-configuration#access-policy)
* TLS termination at the ingress layer
* standard forwarded headers preserved
## Avoid the `MEMOS_PORT` collision [#avoid-the-memos_port-collision]
If your `Service` is named `memos`, Kubernetes injects link-style environment variables into pods in the same namespace — including `MEMOS_PORT=tcp://10.x.x.x:5230`. Memos reads `MEMOS_PORT` as its listen port, fails to parse the injected value, and falls back to port `0`, so the server starts on a random port and logs `Server running on port 0`.
Prevent this in the pod spec — either disable service links, set the port explicitly, or both:
```yaml
spec:
enableServiceLinks: false
containers:
- name: memos
image: neosmemo/memos:stable
env:
- name: MEMOS_PORT
value: "5230"
```
An explicit container `env` entry always overrides the injected variable. Renaming the `Service` to something that does not expand to a `MEMOS_*` prefix also works.
## Practical guidance [#practical-guidance]
* prefer external MySQL or PostgreSQL before attempting multi-replica patterns
* back up both the database and local asset storage if assets are not stored in the database
* start with conservative resource requests and tune based on real usage
* keep public access behind HTTPS
## When Kubernetes is worth it [#when-kubernetes-is-worth-it]
* Memos must fit into an existing platform standard
* you already rely on ingress, secrets, and persistent volume workflows
* you want deployment automation aligned with the rest of your cluster workloads
---
# Reverse Proxy
URL: https://usememos.com/docs/deploy/reverse-proxy
For production, run Memos behind a reverse proxy such as Nginx, Caddy, or Traefik and serve HTTPS.
## Recommended settings [#recommended-settings]
* set `MEMOS_INSTANCE_URL` to the public URL of your instance
* forward standard proxy headers such as `Host`, `X-Forwarded-Proto`, and `X-Forwarded-For`
* restrict access to the admin interface as needed
* make sure the externally visible URL matches what Memos uses for links and cookies
In Memos 0.31, `MEMOS_INSTANCE_URL` and access policy are independent. A private instance can have a canonical URL behind a publicly reachable proxy. Select private or public access through the `ACCESS` instance setting; changing the URL does not change an existing access policy. The URL must be absolute HTTP(S), without credentials, a query, or a fragment.
## Why this matters [#why-this-matters]
A reverse proxy gives you:
* TLS termination
* stable public routing
* easier integration with existing infrastructure
* a place to apply access control, logging, and rate limiting
## Typical concerns to verify [#typical-concerns-to-verify]
* redirects point to the correct external URL
* public links generated by Memos use the correct hostname
* cookies and auth flows behave correctly over HTTPS
* uploaded assets are still accessible through the public route layout
---
# Development
URL: https://usememos.com/docs/development
Work on Memos from a local checkout through to a reviewable contribution. These pages cover the backend and frontend toolchains, building the application, choosing useful checks, and explaining changes to maintainers.
Prepare the Go and frontend toolchains, install dependencies, and get a local checkout ready.
Build the frontend assets and backend binary, then verify that they work together.
Choose backend tests, frontend checks, and smoke tests that match the behavior you changed.
Scope a code or documentation change and prepare the context reviewers need.
## Choose the question you need to answer [#choose-the-question-you-need-to-answer]
| If you want to know… | Start with… |
| -------------------------------------------------------------- | ---------------------------------------------- |
| What do I need to work on Memos locally? | [Setup](/docs/development/setup) |
| How do I turn the source into a runnable application? | [Building](/docs/development/building) |
| Which checks should I run for my change? | [Testing](/docs/development/testing) |
| What should I include in a code or documentation contribution? | [Contributing](/docs/development/contributing) |
For a first code change, get an unchanged checkout building before editing. Use a focused test loop while developing, then verify the built application and describe the resulting behavior in your pull request. Update the relevant docs when that behavior changes.
For an overview of the application layers, read [Architecture](/docs/operations/architecture). To deploy the build you produce, continue to [Build From Source](/docs/deploy/development).
---
# Building
URL: https://usememos.com/docs/development/building
Memos combines a frontend build with a backend binary. Local build work should confirm both pieces still fit together.
## Typical build sequence [#typical-build-sequence]
```bash
cd web
pnpm install
pnpm release
cd ..
go build -o build/memos ./cmd/memos
```
## What to verify [#what-to-verify]
* the frontend build completes cleanly
* the backend binary starts
* local configuration still works with your chosen database
* any generated assets or code are up to date
## Common variants [#common-variants]
* use `go build -o memos ./cmd/memos` for quick local builds
* use versioned linker flags for release-oriented builds
* cross-compile only when you actually need alternate target binaries
---
# Contributing
URL: https://usememos.com/docs/development/contributing
Good contributions reduce review friction and make intent obvious.
## Contribution basics [#contribution-basics]
* keep changes scoped
* explain why the change is needed
* include tests when behavior changes
* update docs when user-facing behavior changes
## Before opening a PR [#before-opening-a-pr]
* check whether the issue or request already exists
* sync with upstream expectations for branch and review workflow
* make sure the change can be reviewed commit by commit
## For docs work [#for-docs-work]
* prefer clear structure over maximum volume
* keep examples realistic
* link related pages so readers can move through the docs naturally
* avoid copying upstream reference content verbatim when a curated explanation is better
---
# Setup
URL: https://usememos.com/docs/development/setup
You need both the backend and frontend toolchains available locally.
## Core tools [#core-tools]
* Go 1.27+
* Node.js 24+
* pnpm 11+
* Git
* additional repo tooling such as `buf` when you work on generated API code
## Setup flow [#setup-flow]
1. clone the repository
2. install backend and frontend dependencies
3. confirm Go builds successfully
4. choose SQLite first unless you specifically need MySQL or PostgreSQL testing
## Typical commands [#typical-commands]
```bash
git clone https://github.com/usememos/memos.git
cd memos
go mod download
cd web
pnpm install
```
If you are working on protocol or generated API changes, also install the tooling required by the upstream repo for code generation and linting.
---
# Testing
URL: https://usememos.com/docs/development/testing
Testing should stay close to the kind of change you made.
## Common checks [#common-checks]
* backend tests for server or store changes
* frontend build and targeted UI checks for web changes
* formatting and linting where required by the repo
* a local smoke test with the built app when behavior changed
## Typical commands [#typical-commands]
```bash
go test ./...
go test ./store/...
go test -cover ./...
go test -race ./...
```
If frontend changes are involved, also run the relevant web checks used by the repo.
## Practical habit [#practical-habit]
Run the smallest useful test loop while developing, then run a broader validation pass before asking for review.
---
# FAQ
URL: https://usememos.com/docs/faq
## What is Memos? [#what-is-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.
## Is Memos open source? [#is-memos-open-source]
Yes. Memos is released under the MIT License.
## Where is my data stored? [#where-is-my-data-stored]
Data is stored in your own database. Attachments can live in the database, on the local filesystem, or in S3-compatible storage.
## Does Memos have an API? [#does-memos-have-an-api]
Yes. Memos provides REST and gRPC APIs. See the [API reference](/docs/api).
## Is there a demo? [#is-there-a-demo]
Yes. You can try the live demo at [https://demo.usememos.com](https://demo.usememos.com).
## What is the easiest way to run it? [#what-is-the-easiest-way-to-run-it]
For most users, Docker with a mounted data directory is the simplest starting point. See [Getting Started](/docs/getting-started).
## Should I use SQLite or MySQL/PostgreSQL? [#should-i-use-sqlite-or-mysqlpostgresql]
SQLite is a strong default for a single-instance deployment. Use MySQL or PostgreSQL when you want an external managed database or more operational flexibility.
## Can I disable public memos? [#can-i-disable-public-memos]
Yes. Select private access in instance settings to require sign-in for ordinary memo pages and disable anonymous public discovery. In 0.31, access policy is independent of `MEMOS_INSTANCE_URL`. You can also disable `PUBLIC` memo visibility in instance settings. Explicit share links still grant access to their selected memo until revoked or expired. See [Sharing](/docs/usage/sharing).
---
# Getting Started
URL: https://usememos.com/docs/getting-started
The shortest path to a running instance is one Docker command with SQLite and a local data volume. Harden deployment and storage once the instance is up.
## Prerequisite [#prerequisite]
* Docker installed on the machine running Memos
## 1. Start a local instance [#1-start-a-local-instance]
```bash
docker run -d \
--name memos \
-p 5230:5230 \
-v ~/.memos:/var/opt/memos \
neosmemo/memos:stable
```
What this gives you:
* `5230` exposed on the host
* a persistent data directory at `~/.memos`
* SQLite by default
* one container that is easy to inspect and replace
On a fresh instance, this command initializes private access: ordinary memo pages require sign-in and anonymous Explore is unavailable. In 0.31, the saved `ACCESS` instance setting controls this policy independently of the canonical URL. The `stable` image follows stable releases; to pin this release explicitly, use `neosmemo/memos:0.31.0`.
If you want a checked-in deployment file, use [Docker Compose](/docs/deploy/docker-compose). If you need a custom or pinned build, use [Build From Source](/docs/deploy/development). Contributors should start with [Development](/docs/development).
## 2. Verify the instance [#2-verify-the-instance]
Open the UI after the container starts:
* Docker default: `http://localhost:5230`
* Binary default: `http://localhost:8081`
If you want to verify the service from the terminal first:
```bash
docker logs memos
```
## 3. Create the first admin account [#3-create-the-first-admin-account]
The first user becomes the host admin and can configure registration, authentication, storage, and other global settings.
Recommended first actions:
* use a strong password
* choose private or public access in instance settings; configure the canonical instance URL separately
* decide whether user registration should remain disabled or be opened later
* decide whether public memos should be allowed at all
## 4. Create your first memo [#4-create-your-first-memo]
Open the global composer from the sidebar. You can create a memo from any authenticated route. Check the selected Space and visibility, then try a memo that exercises the main features:
````markdown
# Welcome to Memos
This is my first memo.
## Tasks
- [x] Install Memos
- [ ] Write a real note
## Tags
Trying #memos and #getting-started
## Code
```ts
console.log("hello from memos");
```
````
Useful things to try immediately:
* choose `PRIVATE`, `PROTECTED`, `PUBLIC`, or `SPACE` visibility; `SPACE` requires an assigned Space
* add a checklist with `- [ ]`
* upload a screenshot or document
* create tags inline with `#tagname`
* pin an important memo so it stays visible
## 5. Understand visibility [#5-understand-visibility]
Each memo uses one of four visibility levels. New memos default to `PRIVATE`; you can change the default in your settings or pick a level in the editor.
* `PRIVATE`: only you can read it
* `PROTECTED`: authenticated users on the instance can read it
* `PUBLIC`: anonymous visitors can read it when public instance access is enabled
* `SPACE`: active members of the memo's assigned Space can read it
In private mode, ordinary `PUBLIC` memo pages still require sign-in. Explicit share links remain accessible without sign-in until revoked or expired. `SPACE` memos cannot have share links. Placement and visibility are independent; see [Spaces](/docs/usage/spaces).
## 6. Explore the core workflows [#6-explore-the-core-workflows]
After the first memo, the next high-value workflows are:
* [Writing Markdown](/docs/usage/writing-markdown)
* [Tags](/docs/usage/tags)
* [Spaces](/docs/usage/spaces)
* [Views](/docs/usage/views)
* [Sharing](/docs/usage/sharing)
* [Attachments](/docs/usage/attachments)
## Common first-run issues [#common-first-run-issues]
* If `http://localhost:5230` does not load, check `docker logs memos`.
* If the data directory is not writable, verify permissions on `~/.memos`.
* For anonymous public profiles and Explore, enable public access in instance settings. For a reverse proxy, set `MEMOS_INSTANCE_URL` to the canonical HTTP(S) URL independently of that policy.
* For version-specific changes, read [Upgrading to 0.31](/docs/operations/upgrade#upgrading-to-031).
---
# Guides
URL: https://usememos.com/docs/guides
Memos can support different ways of thinking without forcing every record into the same system. These guides combine the timeline, Markdown, tags, filters, pins, Relations, and Archive into complete practices you can adapt to your own needs.
Use rapid logging for tasks, events, and notes, then migrate what still matters through daily and monthly reflection.
Build a trusted system for next actions, projects, waiting items, and regular reviews.
Develop ideas from evidence into atomic claims and synthesis memos connected with Relations.
## Choose the question you need to answer [#choose-the-question-you-need-to-answer]
| If you want to know… | Start with… |
| -------------------------------------------------------------- | ------------------------------------------------------- |
| What happened, and what still deserves attention? | [Bullet Journal](/docs/guides/bullet-journal) |
| What is the next action, and where does each commitment stand? | [Getting Things Done](/docs/guides/getting-things-done) |
| How does this evidence change what I understand? | [Zettelkasten](/docs/guides/zettelkasten) |
Start with one primary practice instead of applying all three sets of tags to every memo. You can connect their outputs when useful: a journal observation may become a Zettelkasten idea, and a developed idea may create a concrete GTD action.
For individual product capabilities, return to [Usage](/docs/usage).
---
# Bullet Journal
URL: https://usememos.com/docs/guides/bullet-journal
Most days do not need a page prepared in advance. They need a quick place to record what happened, what it changed, and what deserves attention next. The [Bullet Journal method](https://bulletjournal.com/pages/how-to-bullet-journal)—often shortened to BuJo—builds that rhythm through rapid logging, reflection, and migration.
Memos gives the rhythm a simple home. The timeline becomes the Daily Log, a pinned memo becomes a focused Monthly Log, tags gather recurring subjects into Collections, and saved filters bring unfinished commitments back for a deliberate decision. The complete setup is one `#bujo` tag tree, one monthly compass, one future-decisions memo, and two filters.
## Adapt the Bullet Journal method to Memos [#adapt-the-bullet-journal-method-to-memos]
A digital Bullet Journal does not need to reproduce the geometry of a paper notebook. Translate each question in the practice into the Memos feature that answers it best:
| Question | Memos practice |
| --------------------------------- | ---------------------------------------------------- |
| What just happened? | Capture a short memo in the timeline |
| What matters this month? | Keep one monthly compass pinned |
| Where does this belong over time? | Add a Collection tag after a subject repeats |
| What still deserves attention? | Review incomplete tasks through a saved filter |
| When must I be interrupted? | Put the actual appointment or reminder in a calendar |
The important part is the return. Capturing should stay quick; reflection is where a record becomes a choice about what to finish, retain, schedule, or release.
## Let the timeline serve as your Daily Log [#let-the-timeline-serve-as-your-daily-log]
Write what happened, changed, or became clear as ordinary [Markdown](/docs/usage/writing-markdown). Add an unchecked `- [ ]` item only when the moment creates a real action, then check it with `- [x]` when finished. Supporting details stay beside the entry that gives them meaning. Memos can identify unfinished actions without making you maintain a separate symbol key.
Capture one moment while its context is still clear:
```markdown
Rain reached the inside of the east window this morning.
- [ ] Photograph the frame in daylight.
- [ ] Ask the building manager who handles exterior seals.
#bujo #collection/home-maintenance
```
The observation explains why the actions exist, and the memo's **Created at** timestamp places the whole record in the day's chronology. If the evidence matters, [attach the photograph](/docs/usage/attachments) to the same memo.
Related notes and tasks from one moment can stay together. Separate unrelated actions into their own memos, especially when they need different tags or will be reviewed independently. Fields such as `has_incomplete_tasks` describe the whole memo, not each checklist row, so a long daily page containing unrelated actions is harder to filter cleanly.
Use one tag from the `#bujo` tree on every memo in the practice. Ordinary log entries use `#bujo`; the monthly compass and later-decisions memo use `#bujo/monthly` and `#bujo/future`. A parent filter matches all three.
The timeline is already the running log. Use `#bujo` to isolate journal entries, and combine it with a date filter when you want to read one day; there is no need to add a date tag or prepare a master memo for every day. For a stable capture chronology, set **View options** to **Created at** and **Newest first**. Pinned memos remain the exception at the top when they match the current filter.
## Close the day with three questions [#close-the-day-with-three-questions]
A daily reflection can take two or three minutes:
1. **What actually finished?** Check the completed boxes.
2. **What changed because of today?** Create a new memo when the result happened later; update an existing memo only when clarifying the same moment.
3. **What deserves attention tomorrow?** Clarify the action and pin no more than three memos that genuinely need focus.
Unpin a memo when its action is completed, blocked, or no longer part of tomorrow's focus. Pins are a small focus set, not a permanent priority system.
Do not archive an ordinary log merely because one task inside it is complete; the record still belongs to the journal. Archive standalone operational memos when they remain worth keeping but no longer need to appear in active views.
## Use a pinned monthly compass as your Monthly Log [#use-a-pinned-monthly-compass-as-your-monthly-log]
In Memos, the Monthly Log becomes a compact compass that describes what a good month would look like:
```markdown
# September compass
## Direction
Make the flat ready for the wet season.
## This month is successful when
- [ ] The east-window leak is resolved.
- [ ] The power-outage kit has been tested.
## Protect
Keep two evenings each week free from household administration.
## Notice
Which maintenance problems keep returning instead of being solved?
#bujo/monthly
```
[Pin the current compass](/docs/usage/memos) and keep it small: one direction, one to three outcomes, one boundary to protect, and one pattern to notice. It is an orientation point, not a second copy of every task.
Keep the compass pinned until the monthly review; that review will decide what enters the next one.
## Keep a Future Log for later decisions [#keep-a-future-log-for-later-decisions]
Future intentions need somewhere to wait without pretending that every idea is a scheduled commitment. Keep one memo such as:
```markdown
# Later decisions
## Committed, but not active
- Renew the lease. The actual deadline is in the calendar.
## Worth reconsidering
- Replace the desk after the move.
## Waiting for a trigger
- Review storage options when the basement is cleared.
#bujo/future
```
Open `#bujo/future` during the monthly review. Move an item into its own task memo only when it becomes actionable.
Put appointments, hard deadlines, follow-up alerts, and the recurring review itself in a calendar or reminder app. Keep the Memos link with the calendar entry when it needs background. A date written in a memo remains context. Editing **Created at** changes where the memo appears when viewing or filtering by creation time; it does not set a due date or alert.
## Let Collections emerge from repetition [#let-collections-emerge-from-repetition]
Create a Collection when the same subject has appeared often enough that you want a reliable way back into it. In Memos, the right shape depends on how the subject grows:
* keep a bounded list, such as household emergency contacts, in one memo
* give an evolving subject, such as home maintenance or garden observations, a shared tag
Add a tag from the `#bujo` tree to a bounded Collection only when its checkboxes should appear in the Bullet Journal review. A reference-only list does not need to enter the unfinished-task view.
For an evolving Collection, add a focused tag such as `#collection/home-maintenance` to every relevant memo. Selecting the tag reconstructs the trail across observations, tasks, decisions, and attachments. When older entries have moved out of the active timeline, open [Archive and search for the same Collection tag](/docs/usage/search-archive) to recover them.
In a paper Bullet Journal, the Index points back to Collections by page number. In Memos, tags and search provide that route back without maintaining a manual page index.
Wait for repetition before creating a Collection. This keeps the [tag vocabulary](/docs/usage/tags) grounded in subjects you actually revisit instead of categories you may never use.
## Save two filters for reflection [#save-two-filters-for-reflection]
Create two reusable [Views](/docs/usage/views) to make the review repeatable. The first shows the recent journal:
```txt
tag in ["bujo"] && created_ts >= now - duration("168h")
```
The second shows Bullet Journal memos with unfinished tasks:
```txt
tag in ["bujo"] && has_incomplete_tasks
```
`tag in ["bujo"]` includes nested tags such as `#bujo/monthly` and `#bujo/future`. The task filter inspects Markdown checkboxes, so it does not depend on special symbols or task-state tags.
Keep these views broad. Capture time already lives in **Created at**, subjects live in Collection tags, and the monthly compass holds current direction.
## Make Migration a decision, not a copy [#make-migration-a-decision-not-a-copy]
[Migration](https://bulletjournal.com/pages/migration) creates a pause in which every unfinished commitment must justify following you forward. Memos can preserve that pause without manufacturing a duplicate entry each week or month.
During the monthly review, open the unfinished-task filter and decide what each memo deserves now:
* **Finished:** check the box and record the result when it adds useful context.
* **No longer relevant:** replace the checkbox with a plain line such as `Dropped — the building manager already owns this`, then archive the memo if it no longer belongs in active views.
* **Still vague:** rewrite the text of the unchecked checkbox as the next visible action.
* **Still important:** keep the task open and state which current compass outcome it supports. Pin it only when it belongs to the next day's three-item focus set.
* **Time-specific:** if the action was to schedule something, check it after creating the calendar entry. If the checkbox represented the future event itself, replace it with a plain line such as `Scheduled in calendar — inspection on October 8` so it leaves the unfinished-task view.
* **Becoming a recurring subject:** add a Collection tag so future observations join the same trail.
This is digital migration: the memo stays connected to its original context, while your latest decision becomes explicit. After the decisions are made, create the new monthly compass, unpin the old one, and archive anything that should leave active surfaces.
The review succeeds when stale tasks are gone and every remaining commitment has a clear reason to stay.
## Keep Bullet Journal, GTD, and Zettelkasten distinct [#keep-bullet-journal-gtd-and-zettelkasten-distinct]
All three practices can live in Memos, but they answer different questions:
| Practice | Use it to |
| ------------------------------------------------------- | ----------------------------------------------------------------------- |
| Bullet Journal | Record the day, notice patterns, and reconsider what deserves attention |
| [Getting Things Done](/docs/guides/getting-things-done) | Manage projects, next actions, waiting items, and delegated commitments |
| [Zettelkasten](/docs/guides/zettelkasten) | Develop sources and observations into connected, reusable knowledge |
Choose one primary practice for each memo. A journal observation can produce a separate Zettelkasten idea; a growing commitment can produce a separate GTD action. They may share a Collection or project tag without carrying every other system's state tags.
Keep personal journal entries `PRIVATE`, and do not create a share link unless sharing is intentional; a share link grants access to that one memo even when it is `PRIVATE`. If Memos becomes the long-term record of your days, [back up the database and attachments](/docs/operations/backup-restore) and test the restore process.
Try the practice for one week. Add a tag from the `#bujo` tree to every memo that belongs to it, keep one monthly compass pinned, and use the unfinished-task view during the daily close. Open the recent-journal view during the weekly or monthly review. Create a Collection only after a subject repeats. Keep the parts that help you notice, decide, and follow through.
---
# GTD
URL: https://usememos.com/docs/guides/getting-things-done
[Getting Things Done](https://gettingthingsdone.com/what-is-gtd/) is most reliable when capture is fast, next actions are visible, and every project has a clear place to resume. Memos gives that practice a simple foundation: quick memos for capture, Markdown checkboxes for actions, tags for project context, Views for reusable filters, and a searchable timeline that keeps the history.
This guide keeps the setup focused: one memo per commitment, one state tag for what happens next, and one project tag for related actions. Views keep next actions, waiting items, and active projects visible; checkboxes and Archive close the loop without discarding the record.
## Give every memo one clear GTD role [#give-every-memo-one-clear-gtd-role]
Start with four lifecycle states:
```markdown
#gtd/inbox
#gtd/next
#gtd/waiting
#gtd/someday
```
Use exactly one of those four states on a GTD memo. An item cannot need clarification and be ready to do at the same time. `#gtd/project` is not a state; use it only on an anchor memo that defines a project outcome.
There is no `#gtd/done` tag. A checked box already records completion, and Archive removes it from active surfaces. There is no `#gtd/reference` tag either. Reference is the rest of the searchable timeline: give useful material a topic or project tag, then archive it when it no longer needs to stay visible.
Keep system tags on the final line so the content remains easy to read. Memos recognizes [tags in ordinary Markdown text](/docs/usage/tags), but a consistent metadata line makes state changes obvious.
## Capture and clarify one commitment per memo [#capture-and-clarify-one-commitment-per-memo]
Capture should still feel like Memos: open the editor, write the thought, and move on. Add only `#gtd/inbox` so the item can return for a decision:
```markdown
Ask Mei whether the release screenshots are final.
#gtd/inbox
```
This tagged inbox is separate from the built-in [Memos Inbox](/docs/usage/inbox), which contains notifications about comments and mentions.
During a short daily sweep, decide what, if anything, must return. Delete what has no value. Give useful information a topic or project tag. Move an idea you may revisit to `#gtd/someday`. Turn a commitment you can advance into a concrete checkbox:
```markdown
- [ ] Ask Mei which release screenshots are approved.
#gtd/next #project/september-release
```
If someone else owns the next move, use `#gtd/waiting` instead. The state changes on the same open loop:
```txt
#gtd/inbox → #gtd/next → checked → archived
#gtd/inbox → #gtd/waiting → checked → archived
```
When the result you were waiting for arrives, close that Waiting memo and create a new Next memo for the action that follows. The expected result and your next action are different commitments, so they should not share one record.
The one-action rule comes from Memos itself. Tags, visibility, timestamps, and `has_incomplete_tasks` describe the whole memo, not individual checklist rows. A long memo containing calls, errands, and computer tasks cannot expose each row through a different context filter.
Keep a procedure or meeting record together when it reads as one document. When it creates several independent commitments, extract each commitment into its own action memo. The source can remain as project support.
## Connect each project through a shared tag [#connect-each-project-through-a-shared-tag]
A project does not need a folder or a master task document. Give it one anchor memo that defines the outcome:
```markdown
## Outcome
The September release post is live with reviewed screenshots and valid links.
## Done when
- The post is published.
- Metadata passes the site audit.
- The announcement links to the final URL.
#gtd/project #project/september-release
```
Every action, decision, waiting item, and useful reference for that outcome receives `#project/september-release`. Selecting the tag reconstructs the project's active trail instead of a checklist that must duplicate every detail. After records are archived, use [search and Archive](/docs/usage/search-archive) with the same tag to retrieve the closed history.
Every active project should show where progress resumes: at least one open `#gtd/next` memo or one open `#gtd/waiting` memo. When the next step is clear, create it before leaving the project; add several only for genuinely parallel actions.
A waiting memo should record the result you expect, not assign a task:
```markdown
- [ ] Mei confirms the approved screenshot set.
Requested September 1. Calendar reminder set for September 4.
#gtd/waiting #project/september-release
```
Writing `@mei` can send a real mention notification if that exact-case user exists and can read the memo. Use mentions for intentional collaboration, not as GTD contexts such as `@home` or `@phone`.
## Use Views for decisions and pins for focus [#use-views-for-decisions-and-pins-for-focus]
The home timeline tells you what was recorded recently. It should not also decide what deserves attention now. Save a few filters as [Views](/docs/usage/views), and let each one answer an operating question:
| Question | Filter |
| ---------------------------- | ----------------------------------------------- |
| What still needs a decision? | `"gtd/inbox" in tags` |
| What can I advance? | `"gtd/next" in tags && has_incomplete_tasks` |
| What am I waiting for? | `"gtd/waiting" in tags && has_incomplete_tasks` |
| Which outcomes are active? | `"gtd/project" in tags` |
The filter syntax is capable of much more, but these four questions are enough to run the system. `#gtd/someday` does not need a permanent place in the sidebar; selecting the tag during a monthly review is usually sufficient.
At the start of the day, choose no more than three memos from **What can I advance?** and pin them. A pin is a temporary focus limit, not a permanent priority label. Unpin an action when it is completed, blocked, or no longer part of today's focus.
Add a context only after the available-actions view becomes genuinely difficult to scan. For example:
```txt
"gtd/next" in tags && "context/computer" in tags && has_incomplete_tasks
```
If you can still choose the right action without that filter, the extra tag has not earned its maintenance cost.
## Run a daily reset and weekly review [#run-a-daily-reset-and-weekly-review]
A View can find a state, but it cannot prove that one memo in a project has a matching next action in another. Review exists to inspect those gaps.
A daily reset should take only a few minutes:
* bring **What still needs a decision?** to zero
* check, unpin, and archive completed action memos
* choose up to three pins from the available actions
Once a week, inspect the structure:
* open every active project anchor, select its `#project/...` tag, and confirm a current Next or Waiting memo exists
* review waiting items for responses that arrived or follow-ups that need scheduling
* archive finished projects and their closed action trail
Run this audit filter to catch unchecked tasks that have no GTD state:
```txt
has_incomplete_tasks && !tags.exists(t, t.startsWith("gtd/"))
```
Classify or archive anything it finds. Once a month, scan `#gtd/someday` and activate, retain, or discard each idea.
The goal is not to touch every memo. The review is complete when the decision queue is empty, the action queue is believable, and every active project shows where progress resumes.
## Pair Memos with a calendar for deadlines and reminders [#pair-memos-with-a-calendar-for-deadlines-and-reminders]
Memos owns the commitment, its context, and its history. It does not provide documented task due dates, recurring tasks, or task alarms. A date written in a memo is context. Editing a memo's creation time only moves it in the timeline and Calendar; it does not set a due date or alert.
Put appointments, hard deadlines, follow-up alerts, and the recurring review itself in a calendar or reminder app. Add the Memos URL to the event when it needs project context. The calendar decides when to interrupt you; Memos explains what the interruption is about.
Trust has an operational side too. Keep personal commitments `PRIVATE` unless sharing is intentional. If this becomes the only record of important commitments, [back up the database and attachments](/docs/operations/backup-restore) and test a restore.
GTD is strongest when it manages commitments rather than becoming a store for every idea. To develop research and observations alongside the action system, use a separate [Zettelkasten practice](/docs/guides/zettelkasten) and create a GTD memo only when knowledge produces a concrete next action.
For a chronological practice built around daily capture and reflection, use the [digital Bullet Journal guide](/docs/guides/bullet-journal).
Run the practice unchanged for one week. If the available-actions view is still easy to use, stop designing the system. Add a tag or view only when it answers a question you repeatedly struggle to answer.
The practice is healthy when the inbox reaches zero, the next-action list remains credible, and every active project shows where progress resumes. Everything else can become history.
---
# Zettelkasten
URL: https://usememos.com/docs/guides/zettelkasten
Good ideas rarely arrive as finished documents. The [Zettelkasten method](https://zettelkasten.de/overview/) develops them through focused notes that can be connected, tested, and reused. Memos gives the practice a simple home: the timeline keeps each observation close to its context, topic tags bring related material back into view, and Relations let you trace an answer to the claims and evidence behind it.
This guide uses one active question, three memo roles, and two saved filters. By the end, you will have a repeatable way to turn daily captures into a decision, draft, lesson, or plan.
## Start with a question worth returning to [#start-with-a-question-worth-returning-to]
Choose a real question connected to something you want to understand, decide, explain, or build. Create a synthesis memo for it:
```markdown
# What makes a backup genuinely recoverable?
## Current answer
A backup is recoverable when the database, attachments, and deployment configuration can be restored together and verified in a running instance.
## Still unclear
- Which failures can a database-only restore miss?
- How often should a restore drill run?
## Next thing to examine
Compare the documented restore steps with our current runbook.
#zk/synthesis #topic/backup-recovery
```
[Pin this memo](/docs/usage/memos) while the question is active. It is the main entry point to everything you learn about the subject. Pin only questions you are actively developing; the rest remain available through tags and search.
Beginning with a question makes the system useful on day one, even with only a handful of notes.
## Use three roles for knowledge memos [#use-three-roles-for-knowledge-memos]
Use a small vocabulary for the role each memo plays:
Here, `zk` is a short namespace that keeps the three role tags together; it is not a folder or a separate area of Memos.
| Role | What it contains | Tag |
| --------- | ---------------------------------------------------------------------------------- | --------------- |
| Evidence | A source, observation, result, or event with its original context | `#zk/evidence` |
| Idea | One claim that can be stated, supported, or challenged independently of its source | `#zk/idea` |
| Synthesis | The best current answer to a question, including tensions and gaps | `#zk/synthesis` |
These are roles, not folders. Add one broad [topic tag](/docs/usage/tags) such as `#topic/backup-recovery` to bring related memos into the same neighborhood. Keep the vocabulary deliberately small; a new tag should make a recurring body of knowledge easier to enter, not describe every detail in the memo.
In common Zettelkasten vocabulary, quick captures roughly correspond to fleeting notes, Evidence memos to source or literature notes, and Idea memos to permanent notes. A Synthesis memo acts as a structure note for one active question. The role matters more than the label.
Quick thoughts do not all need to become durable Zettelkasten notes. The Memos timeline already makes capture fast. Add a Zettelkasten role only when a record contributes evidence, develops an idea, or changes a synthesis.
## Preserve the source and record what it changed [#preserve-the-source-and-record-what-it-changed]
An evidence memo should let you recover both the observation and your interpretation. A bookmark alone preserves a location, but not why it mattered when you found it.
```markdown
## Observation
The restore process treats the database, attachments, and deployment configuration as one recovery set.
## Source
[Backup & Restore](https://usememos.com/docs/operations/backup-restore)
## Why it may matter
A database can import successfully while files or runtime settings remain unavailable.
#zk/evidence #topic/backup-recovery
```
Keep quotations short and use a Markdown link to the original source. For a conversation, experiment, or meeting, record enough context to understand who observed what and under which conditions. Attach a screenshot or document when the evidence depends on it; [attachments remain connected to their memo](/docs/usage/attachments).
**Why it may matter** is where a source becomes part of your thinking. It records which question the evidence could change, so you know why the memo deserves another look.
Keep the evidence memo intact. When it changes your view, create a separate `#zk/idea` memo and relate the new claim back to its evidence. Do not turn the evidence memo into the idea by replacing its role tag; the separation preserves provenance.
## Turn evidence into an atomic idea [#turn-evidence-into-an-atomic-idea]
An atomic note is not simply a short note. It makes one claim and contains enough reasoning to remain understandable when you encounter it from another topic or synthesis.
```markdown
# A backup is a recoverable system, not a database file
A restore is complete only when the database, referenced files, and required configuration function together in a running instance.
## Because
Each part can restore successfully on its own while links between them remain broken.
## What would change this view
Evidence that every dependency is embedded in one verified artifact.
#zk/idea #topic/backup-recovery
```
State the conclusion you currently hold, then explain why it follows from the evidence. If one source changes your thinking in three independent ways, create three idea memos. If an idea needs several paragraphs to explain one claim well, keep the paragraphs together. Atomicity is about conceptual focus, not a word limit.
Including **What would change this view** is optional, but it keeps important claims open to correction. The Zettelkasten becomes more valuable when notes can challenge one another instead of only accumulating support for what you already believe.
## Connect memos with an explicit reason [#connect-memos-with-an-explicit-reason]
Use [**Link memo** from the editor's add menu](/docs/usage/memos#linking-memos-with-relations) to search active memos you own and select one. After you save, the current memo's detail view shows the outgoing note under **Referencing**; the other memo shows the incoming connection under **Referenced by**.
A useful reading trail often looks like this:
```txt
synthesis → idea → evidence
```
Keep the direction consistent:
1. While creating or editing an Idea memo, open the add menu, choose **Link memo**, and select its Evidence memo.
2. While editing the Synthesis memo, link it to the Idea memo.
The resulting trail reads from the current answer into its reasoning: synthesis → idea → evidence.
Relations in Memos represent a general reference rather than a semantic label such as “supports” or “challenges.” State the reason for an important connection inside the memo:
```markdown
## Connection
Supports “A restore drill must cover every dependency”: attachments can fail independently of the database.
```
Useful connection verbs include **supports**, **challenges**, **narrows**, **explains**, and **gives an example of**. A handful of explained relations is more useful than many unexplained links.
Relations and [Markdown links](/docs/usage/writing-markdown) serve different purposes. A Markdown link puts a URL in the content; a Relation builds a navigable connection between two memos. Pasting a memo URL does not automatically create a Relation or an incoming reference. Use both when a link must remain visible in copied or shared content.
## Use tags for neighborhoods and Relations for arguments [#use-tags-for-neighborhoods-and-relations-for-arguments]
A topic tag helps you discover candidates that may belong together. A Relation records the specific connection you chose after reading them. Selecting `#topic/backup-recovery` may reveal ten nearby memos; the relation from one claim to one piece of evidence explains part of the argument.
[Search](/docs/usage/search-archive) by topic before finishing a new idea. Ask:
* Does an existing memo already make this claim?
* What supports or challenges it?
* Which synthesis would change if this is true?
If you are developing several questions, save a filter for active synthesis memos:
```txt
pinned && "zk/synthesis" in tags
```
A second [View](/docs/usage/views) can surface recent Zettelkasten memos for a connection pass:
```txt
tag in ["zk"] && created_ts >= now - duration("168h")
```
Do not use `has_link` to find memo Relations. That property detects Markdown links in the memo body, not structured relations.
## Revise the synthesis while the question is active [#revise-the-synthesis-while-the-question-is-active]
Return to the pinned synthesis whenever a new idea materially changes the answer. Update four things:
* the best answer you can give now
* the evidence or ideas that support it
* meaningful contradictions or uncertainty
* the next source, test, or question worth pursuing
Link the synthesis to the idea memos that carry the detailed reasoning. This keeps the synthesis readable while preserving a path into the evidence.
When a central claim changes completely, leave the earlier memo intact. Create a new Idea memo, state what changed and why, and relate it to the old one. The two memos preserve the earlier position and the reason it changed without relying on edit history.
A Synthesis memo is the current entry point for one live question. It fills the role often called a structure note without requiring a master index for every memo you have written. Create one when a topic needs an answer or output, not merely because it has accumulated many notes.
## Follow one reasoning trail into an output [#follow-one-reasoning-trail-into-an-output]
The backup example now has a visible path:
```txt
What makes a backup genuinely recoverable? #zk/synthesis
└─ A backup is a recoverable system #zk/idea
└─ Recovery covers data, files, and configuration #zk/evidence
```
The Synthesis holds the current answer. The Idea explains the conclusion, and its Evidence preserves the source context. Together they can become a restore-drill runbook with explicit checks for data, files, configuration, and access. For a reading project, the same pattern can connect a passage, an interpretation, and a developing essay argument.
The output could instead be a design decision, article, lesson plan, proposal, or experiment. The synthesis already contains the current answer; its Relations let you verify or revisit each part before you publish or act on it.
## Run a weekly connection pass [#run-a-weekly-connection-pass]
Once a week, open the recent-memos filter and spend ten to fifteen minutes moving one active question forward:
* Which recent evidence changed an existing claim or deserves a new one?
* Does each important Relation have a reason you can explain?
* Does a new idea support, challenge, or narrow something already in the system?
* Which pinned synthesis needs a better current answer?
* Which captures are duplicates or no longer useful enough to keep active?
[Archive](/docs/usage/search-archive) records that remain useful but no longer belong in daily views. The review is successful when at least one question becomes clearer or produces a next output—not when you reach a target number of notes, tags, or relations.
## Keep knowledge and commitments separate [#keep-knowledge-and-commitments-separate]
Zettelkasten and [Getting Things Done](/docs/guides/getting-things-done) can share one Memos instance without becoming one system. Zettelkasten develops ideas; GTD tracks commitments. Keep their namespaces separate:
```markdown
Knowledge memo: #zk/idea #topic/backup-recovery
Action memo: #gtd/next #project/restore-drill
```
When a synthesis creates an action, make a separate GTD memo and relate it to the relevant synthesis. Avoid adding a task checkbox to every knowledge memo simply because an idea could someday become actionable.
Keep personal research `PRIVATE` unless sharing is intentional. A standalone share link does not expose the surrounding relation graph, so put essential context and source URLs in the memo body when another reader needs them. If Memos becomes your long-term research record, [back up the database and attachments](/docs/operations/backup-restore) and test the restore process.
For a chronological practice that combines tasks, events, and observations, use the [digital Bullet Journal guide](/docs/guides/bullet-journal).
Start with one question for one week. Pin its synthesis, capture only evidence that changes the question, turn one or two observations into claims, and explain each Relation you add. Keep the practice if the answer becomes easier to defend or use.
---
# Integrations
URL: https://usememos.com/docs/integrations
Connect Memos to the tools you use to capture and work with notes. Use the API for scripts and applications, MCP for AI assistants, webhooks to react to memo events, or a separate Telegram integration to capture messages.
Create a personal access token, authenticate requests, and review client migration requirements.
Connect an assistant to the built-in MCP endpoint to search, create, and update memos.
Run Memogram to send text and images from Telegram into your Memos instance.
Receive memo events and implement signature verification and delivery responses.
## Choose the question you need to answer [#choose-the-question-you-need-to-answer]
| If you want to know… | Start with… |
| ----------------------------------------------------- | ----------------------------------------------- |
| How do I read or write memos from my own application? | [API Access](/docs/integrations/api-access) |
| How do I let an AI assistant work with my memos? | [MCP Server](/docs/integrations/mcp) |
| How do I capture a note from Telegram? | [Telegram Bot](/docs/integrations/telegram-bot) |
| How do I trigger another service when a memo changes? | [Webhooks](/docs/integrations/webhooks) |
API and MCP calls act with the permissions of the account behind the token. Create a separate token for each application so you can revoke its access independently. For webhook receivers, follow the signing and response requirements before processing events.
For request and response details, open the [API Reference](/docs/api) and choose the version that matches your instance; Latest tracks `main`. For instance-wide sign-in setup, see [Authentication](/docs/configuration/authentication).
---
# API Access
URL: https://usememos.com/docs/integrations/api-access
Every Memos feature is available over the API. To call it programmatically, create a personal access token and send it as a Bearer credential.
## Create a personal access token [#create-a-personal-access-token]
Create and revoke tokens from your **user settings** in the app. Tokens use the `memos_pat_` prefix, and the plain token value is shown only once at creation — store it somewhere safe.
New tokens default to no expiration; you can choose an expiration when creating one. The settings page shows whether each token has ever been used, its last-used time, and its expiration status. Use a separate token for each application so you can revoke one integration without disrupting another.
Tokens are scoped to your user: API calls made with a token can do what your user can do.
## Call the API [#call-the-api]
Pass the token in the `Authorization` header. Memos 26.10 and the Latest API on `main` use `/api`:
```bash
curl -H "Authorization: Bearer memos_pat_..." \
https://memos.example.com/api/memos
```
Memos 0.30 and 0.31 use `/api/v1` instead. Select the [API reference for your instance version](/docs/api) before using an endpoint in an integration.
When moving a client from 0.31 to 26.10, follow the [migration checklist](#2610-client-migration). The Latest API reference tracks `main` and may include later changes.
For browser-based integrations, bearer-token requests may be sent cross-origin. Cookie authentication remains same-origin; do not build third-party API clients around a user's browser session cookie.
## 26.10 client migration [#2610-client-migration]
These breaking changes apply to **26.10-rc.1**. Use the [tagged API changelog](https://github.com/usememos/memos/blob/26.10-rc.1/proto/api/CHANGELOG.md) and [OpenAPI specification](https://github.com/usememos/memos/blob/26.10-rc.1/proto/gen/openapi.yaml) for the exact release contract.
### Paths and encoding [#paths-and-encoding]
* REST routes change from `/api/v1/...` to `/api/...`; server-sent events use `/api/sse`.
* The proto package changes from `memos.api.v1` to `memos.api`. Connect and gRPC procedures use `/memos.api./`.
* Resource types use `memos.api/` and `google.rpc.ErrorInfo.domain` becomes `memos.api`.
* In this release, old REST and procedure paths return `410 Gone` with an `UNIMPLEMENTED` error. They are removed in the next release.
* Protobuf field numbers change. Regenerate clients that use binary protobuf encoding; JSON clients must update the renamed fields below. Proto field names are shown in `snake_case`; gateway JSON uses their `camelCase` equivalents.
### Renamed methods, fields, and types [#renamed-methods-fields-and-types]
| Area | Required client change |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Memo child operations | `ListMemoAttachments`, `ListMemoRelations`, `ListMemoComments`, `CreateMemoComment`, `ListMemoReactions`, and `UpsertMemoReaction` take `parent` instead of `name`. `ListMemoCommentsResponse.memos` becomes `comments`. |
| Memo resources | `MemoRelation.Memo` becomes `MemoRelation.MemoRef`; the `MemoShare` singular/plural becomes `memoShare`/`memoShares`. |
| User statistics | `ListAllUserStats` becomes `ListUserStats`, with required `parent` (`users/-` for all users or `users/{user}` for one user). The all-user REST path becomes `GET /api/users/-/stats`; response `stats` becomes `user_stats`, and `UserStats.tag_count` becomes `tag_counts`. |
| Batch users | `BatchGetUsersRequest.usernames` becomes `names`, accepting `users/{user}` resource names instead of bare usernames. |
| Personal access tokens | `created_at`, `expires_at`, and `last_used_at` become `create_time`, `expire_time`, and `last_use_time`. |
| Linked identities | `LinkedIdentity.idp_name` and `extern_uid` become `identity_provider` and `external_uid`; `CreateLinkedIdentityRequest.idp_name` becomes `identity_provider`. |
| Views and notifications | Resource singulars become `memoView` and `userNotification`; `UserNotification.SpaceInvitationPayload.State` becomes `InvitationState`. |
| Imports | `MemoImportPlan`, `MemoImportReport`, and `MemoImportIssue` become `ImportMemosPlan`, `ImportMemosReport`, and `ImportMemosIssue`. Plan fields `memos`/`attachments` become `memo_count`/`attachment_count`; issue field `memo` becomes `memo_uid`. |
| Settings | `UpdateUserSettingRequest.setting` and `ListUserSettingsResponse.settings` become `user_setting` and `user_settings`. `UpdateInstanceSettingRequest.setting` and `BatchGetInstanceSettingsResponse.settings` become `instance_setting` and `instance_settings`. |
| Authentication | `SignInResponse.access_token_expires_at` and `RefreshTokenResponse.expires_at` become `access_token_expire_time`. `SignInRequest.SSOCredentials` becomes `SsoCredentials`, with `identity_provider` replacing `idp_name`. |
## 0.31 client migration [#031-client-migration]
Review these changes before pointing an existing integration at 0.31:
| Area | Required client change |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Views | Replace `ShortcutService` with the `MemoView` operations in `UserService`, shortcut resources with view resources, and `/api/v1/users/*/shortcuts/*` with `/api/v1/users/*/views/*`. Stored filters migrate automatically. |
| Authorization | Run mutations as the memo author. Assigned memo edits also require Space membership. Active instance administrators can read and manage individual memos without authorship or Space membership; Space admin roles do not override authorship. Users manage their own reactions. |
| Comments | Send visibility and placement intentionally. `CreateMemoComment` defaults omitted visibility to `PRIVATE`; `SetMemoRelations` rejects `COMMENT`. Parent deletion does not delete comment memos. |
| Reactions | Stop reading `Reaction.content_id` (`contentId` in JSON). Identify the memo from the request or the reaction resource name. |
| Inline images | Bind managed attachments to the memo before or during the same mutation that references them in Markdown. An uploaded but unbound attachment is not enough. |
| S3 files | Use the authenticated Memos file route. Managed S3 attachments no longer expose presigned object URLs through `external_link` (`externalLink` in JSON). Preserve share authorization on shared attachment and thumbnail URLs. |
| JSON responses | Allow absent unset protobuf message fields. Scalar defaults and empty lists are still emitted; do not depend on every message field appearing as `null`. |
| Usernames | Use the exact username case for lookup and authentication. See [Users & Roles](/docs/admin/users-roles#usernames). |
### Spaces in API clients [#spaces-in-api-clients]
A memo's `space` is a resource name such as `spaces/team-notes`, or absent when Unassigned. `visibility: "SPACE"` requires placement in a Space. Filters support `space == null`, `space == "spaces/team-notes"`, and `has_location`.
When moving a `SPACE` memo, include both `space` and `visibility` in the update mask and explicitly confirm `SPACE` visibility for the destination. When withdrawing it to Unassigned, select a non-Space visibility in the same update. Share links cannot be created for `SPACE` memos; revoke existing links before changing a memo to that audience.
The [Latest API reference](/docs/api/latest) tracks `main`, which may include changes after the latest stable release. The [0.31 reference](/docs/api/0-31) is generated from v0.31.0, and the [0.30 reference](/docs/api/0-30) covers the previous release series. For the exact 0.31.0 schema, use the [tagged OpenAPI specification](https://github.com/usememos/memos/blob/v0.31.0/proto/gen/openapi.yaml).
## Where to go next [#where-to-go-next]
* [API Reference](/docs/api) — every service and method, REST and gRPC
* [Webhooks](/docs/integrations/webhooks) — push events instead of polling
* [MCP Server](/docs/integrations/mcp) — connect AI assistants using the same tokens
* [Security](/docs/configuration/security) — the full token security model
---
# MCP Server
URL: https://usememos.com/docs/integrations/mcp
Memos includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server, available since v0.27.0. It lets AI assistants such as Claude search, create, and update your memos through a curated set of tools.
The server is part of the main Memos binary — there is nothing extra to install or enable. It runs at:
```
https:///mcp
```
## Upgrading older MCP clients [#upgrading-older-mcp-clients]
Memos 0.30 replaced the earlier MCP implementation with a stateless, tools-only endpoint generated from the OpenAPI schema. Existing clients must use `/mcp` and the service-prefixed tool names listed below.
The previous prompts, resources, tool-filtering headers, route aliases, and unprefixed tool names are no longer available. Tool failures now use the standard MCP `isError` result with readable text content.
### Migrating to 0.31 [#migrating-to-031]
Replace `shortcut_list_shortcuts` with `user_list_memo_views`. Existing saved filters migrate automatically, but client tool names and request mappings must change. Tool calls also follow the new author and Space membership permissions. Comments created without an explicit visibility default to `PRIVATE`. See [API migration notes](/docs/integrations/api-access#031-client-migration).
## Connecting a client [#connecting-a-client]
The server uses the **Streamable HTTP** transport. Point any MCP client that supports it at your instance's `/mcp` endpoint and authenticate with a [personal access token](/docs/integrations/api-access) as a Bearer credential:
```json
{
"mcpServers": {
"memos": {
"type": "http",
"url": "https:///mcp",
"headers": {
"Authorization": "Bearer "
}
}
}
}
```
With Claude Code, the equivalent one-liner is:
```bash
claude mcp add --transport http memos https:///mcp \
--header "Authorization: Bearer "
```
## Authentication [#authentication]
Tool calls run against the same REST API as the web app, with the same permissions:
* The token identifies you; tools can only see and change what your account can.
* Mutating tools (create, update, delete) require a valid token.
* Public reads may work without a token only when the instance access policy permits public reads and the underlying REST endpoint allows anonymous access. The canonical instance URL does not select that policy.
Create and revoke personal access tokens from your user settings in the app. See [API Access](/docs/integrations/api-access).
## Available tools [#available-tools]
The server exposes a curated, memo-focused toolset:
| Tool | Description |
| ------------------------------ | ----------------------------------------- |
| `memo_list_memos` | List and search memos |
| `memo_create_memo` | Create a memo |
| `memo_get_memo` | Get a single memo |
| `memo_update_memo` | Update a memo |
| `memo_delete_memo` | Delete a memo |
| `memo_list_memo_comments` | List comments on a memo |
| `memo_create_memo_comment` | Comment on a memo |
| `memo_list_memo_attachments` | List a memo's attachments |
| `memo_set_memo_attachments` | Set a memo's attachments |
| `memo_list_memo_reactions` | List reactions on a memo |
| `memo_upsert_memo_reaction` | Add or update a reaction |
| `memo_delete_memo_reaction` | Remove a reaction |
| `memo_list_memo_relations` | List a memo's relations |
| `memo_set_memo_relations` | Set a memo's relations |
| `attachment_list_attachments` | List attachments |
| `attachment_create_attachment` | Upload an attachment |
| `attachment_get_attachment` | Get an attachment |
| `attachment_delete_attachment` | Delete an attachment |
| `user_list_memo_views` | List the current user's Views |
| `auth_get_current_user` | Resolve the user represented by the token |
Each tool maps to an endpoint of the [REST API](/docs/api), so request and response shapes match the API reference. Tools carry standard MCP annotations (read-only, destructive, idempotent) so clients can ask for confirmation before destructive actions.
## Browser clients and origins [#browser-clients-and-origins]
Desktop MCP clients work out of the box. Browser-based clients are subject to an origin check: requests are accepted when the `Origin` header is absent, matches the instance's own host, or matches the configured instance URL. Anything else is rejected with `403` to protect against DNS rebinding.
## Troubleshooting [#troubleshooting]
* **`401` / permission errors** — the token is missing, expired, or lacks access to the resource. Create a fresh token in your user settings.
* **`403` on connect** — your client sends an `Origin` header that doesn't match the instance. Use a desktop client, or set the instance URL so it matches.
* **Tool errors** — API failures are returned with `isError: true` and readable text containing the HTTP status and message, so the assistant can react without trying to validate the error as a successful output schema.
---
# Telegram Bot
URL: https://usememos.com/docs/integrations/telegram-bot
Memogram is the Telegram integration for Memos. It syncs text and images from a Telegram bot into your Memos instance.
Repository and releases:
```text
https://github.com/usememos/telegram-integration
https://github.com/usememos/telegram-integration/releases
```
## Prerequisites [#prerequisites]
* A running Memos instance
* A Telegram bot token
## Configuration [#configuration]
Create a `.env` file and set:
```text
SERVER_ADDR=dns:localhost:5230
BOT_TOKEN=your_telegram_bot_token
BOT_PROXY_ADDR=https://api.your_proxy_addr.com
ALLOWED_USERNAMES=user1,user2,user3
```
### Configuration options [#configuration-options]
* `SERVER_ADDR`: gRPC address where Memos is running.
* `BOT_TOKEN`: Telegram bot token.
* `BOT_PROXY_ADDR`: Optional proxy for Telegram API.
* `ALLOWED_USERNAMES`: Optional comma-separated list of allowed usernames (without `@`).
When `ALLOWED_USERNAMES` is set, only those users can use the bot.
## Run Memogram [#run-memogram]
### Binary [#binary]
1. Download the release binary.
2. Put `.env` next to the binary.
3. Run:
```sh
./memogram
```
### Docker [#docker]
```sh
docker build -t memogram .
docker run -d --name memogram \
-e SERVER_ADDR=dns:localhost:5230 \
-e BOT_TOKEN=your_telegram_bot_token \
memogram
```
### Docker Compose [#docker-compose]
```yaml
services:
memogram:
env_file: .env
build: memogram
container_name: memogram
```
## Commands [#commands]
* `/start `: Authenticate with your Memos access token.
* Send text: Saves the message as a memo.
* Send files: Saves files as resources attached to a memo.
* `/search `: Search your memos.
---
# Webhooks
URL: https://usememos.com/docs/integrations/webhooks
Memos can send webhooks when memos change. Webhooks are configured per user in the Settings page and can be edited or deleted later.
## Events [#events]
Webhooks are dispatched on:
* Memo created
* Memo updated
* Memo deleted
* Memo comment created
## Payload [#payload]
Memos sends a JSON payload containing `activityType`, `creator`, and the affected `memo`. Comment-created payloads include the parent relation so receivers can identify the conversation.
Refer to the [API reference](/docs/api) for the current webhook-related endpoints.
## Signing and verification [#signing-and-verification]
New webhooks receive a Standard Webhooks-compatible signing secret in the form `whsec_`. Copy it when the webhook is created and store it as a secret in the receiving service. You can reveal an existing secret later from the edit dialog; older unsigned webhooks can generate one there.
Signed deliveries include:
| Header | Value |
| ------------------- | --------------------------------------- |
| `webhook-id` | Unique message ID beginning with `msg_` |
| `webhook-timestamp` | Unix timestamp in seconds |
| `webhook-signature` | `v1,` |
Verify the signature before parsing or acting on the payload:
1. Read the raw request body bytes.
2. Remove the `whsec_` prefix and Base64-decode the remaining secret.
3. Build the signed content as `..`.
4. Compute HMAC-SHA256 with the decoded secret and Base64-encode the result.
5. Compare `v1,` with `webhook-signature` using a constant-time comparison.
6. Reject timestamps outside a small tolerance window and deduplicate `webhook-id` values to reduce replay risk.
Do not reserialize parsed JSON before verification; even an equivalent JSON representation produces a different signature.
## Delivery response [#delivery-response]
The receiver must return a `2xx` response with a JSON body whose `code` is `0`, for example:
```json
{ "code": 0 }
```
Non-`2xx` responses, invalid JSON, or a nonzero `code` are treated as delivery failures.
## Network safety [#network-safety]
Webhook URLs must use `http` or `https` and must resolve successfully when they are created or updated.
By default, Memos rejects webhook targets that resolve to reserved or private IP ranges, including loopback, RFC 1918 private networks, link-local addresses, and IPv6 local ranges. This protects the instance from server-side request forgery.
In 0.31, allow only the private destinations your integration needs with `--webhook-private-network-allowlist` or `MEMOS_WEBHOOK_PRIVATE_NETWORK_ALLOWLIST`. Entries are exact hostnames, IP addresses, or CIDRs; hostnames are not wildcard patterns.
```bash
./memos --webhook-private-network-allowlist=hooks.internal.example,10.0.0.8,10.20.0.0/24
```
The equivalent environment variable is a comma-separated list:
```bash
export MEMOS_WEBHOOK_PRIVATE_NETWORK_ALLOWLIST="hooks.internal.example,10.0.0.8,10.20.0.0/24"
```
The default empty list keeps private-network protection enabled. The older `--allow-private-webhooks` / `MEMOS_ALLOW_PRIVATE_WEBHOOKS=true` option remains compatible but is deprecated because it allows every private destination. Replace it with the narrowest entries your receivers require.
---
# Operations
URL: https://usememos.com/docs/operations
Keep your Memos instance running as its data and usage grow. These pages connect the application's architecture to practical work: recovering memos and attachments, changing versions, and investigating slow or unreliable behavior.
Understand how the frontend, API, database, and attachment storage fit together.
Back up the database, attachments, and deployment configuration, then verify a restore.
Prepare for migrations, replace the running version, and check the instance after startup.
Investigate database contention, storage, and deployment constraints before changing settings.
## Choose the question you need to answer [#choose-the-question-you-need-to-answer]
| If you want to know… | Start with… |
| ---------------------------------------------------------- | --------------------------------------------------------- |
| Which parts of the system store data or handle requests? | [Architecture](/docs/operations/architecture) |
| What do I need to recover a complete instance? | [Backup & Restore](/docs/operations/backup-restore) |
| How do I move to a new version and prepare for migrations? | [Upgrade](/docs/operations/upgrade) |
| Where should I look when the instance becomes slow? | [Performance Tuning](/docs/operations/performance-tuning) |
Establish and test a restore procedure before your first upgrade. Memos applies database migrations at startup; after a migration, recovery depends on restoring a compatible backup rather than simply restarting the older binary. Include every attachment store still in use in that recovery plan.
For a specific failure, start with [Troubleshooting](/docs/troubleshooting). For planned database or storage changes, return to [Configuration](/docs/configuration).
---
# Architecture
URL: https://usememos.com/docs/operations/architecture
At a high level, Memos is a lightweight web application with a frontend UI, an API and service layer, a database backend, and optional attachment storage outside the database.
## Technology stack [#technology-stack]
| Layer | Technology |
| ------------------- | ----------------------------------- |
| Backend language | Go 1.27+ |
| HTTP router | Echo v5 |
| API protocol | gRPC + Connect RPC (dual) |
| Schema | Protocol Buffers v2 |
| Databases | SQLite (default), MySQL, PostgreSQL |
| Frontend framework | React 19 + TypeScript |
| Frontend build | Vite 8 |
| State management | React Query v5 + React Context |
| Frontend API client | Connect RPC |
| Frontend styling | Tailwind CSS v4 |
## Main layers [#main-layers]
* frontend UI for writing, browsing, and managing memos
* API and service layer for authentication, memo operations, and instance settings
* database layer for persistent content and metadata
* optional filesystem or object storage for attachments
## Dual-protocol API [#dual-protocol-api]
Memos exposes two API surfaces backed by the same service implementations:
* **Connect RPC** at `/memos.api./` — used by the browser frontend; speaks HTTP/JSON with type-safe generated clients
* **gRPC-Gateway** at `/api/*` — provides REST-compatible HTTP/JSON endpoints for external tools, CLI clients, and integrations
These are the paths on Memos `main`. Memos 0.30 and 0.31 use `/memos.api.v1./` and `/api/v1/*`.
Both go through the same interceptor chain (metadata extraction, request logging, panic recovery, auth validation).
## Authentication tokens [#authentication-tokens]
Three token types are in use:
| Type | Lifetime | Storage | Validated |
| --------------------- | --------------------------------------- | ------------------ | --------------------------- |
| Access token (JWT) | 15 minutes | Client memory | Stateless signature check |
| Refresh token (JWT) | 30 days | HTTP-only cookie | Database lookup (revocable) |
| Personal access token | User-selected; no expiration by default | SHA-256 hash in DB | Database lookup |
Personal access tokens use the prefix `memos_pat_` followed by 32 random characters and are stored only as their SHA-256 hash.
## In-memory cache [#in-memory-cache]
The store layer maintains an in-memory cache for hot data:
| Cached resource | Cache key | TTL |
| ----------------- | --------------------- | ------ |
| Instance settings | `setting_key` | 10 min |
| Users | `user_id` | 10 min |
| User settings | `user_id-setting_key` | 10 min |
Cache entries are evicted on write operations and after their TTL expires.
The database-backed `ACCESS` setting bypasses the ordinary settings cache so another replica observes an access-policy change on its next policy check. Deployment-file overrides remain fixed until that process restarts.
## Why the architecture matters [#why-the-architecture-matters]
Understanding these layers helps with:
* choosing SQLite versus MySQL or PostgreSQL
* planning backups correctly
* reasoning about storage and proxy configuration
* deciding where to troubleshoot performance problems first
## Practical deployment reading [#practical-deployment-reading]
For most teams, architecture questions become operational questions:
* where does data live
* which layer terminates TLS
* what happens to attachments during backup and restore
* how many instances need to write to the database
---
# Backup & Restore
URL: https://usememos.com/docs/operations/backup-restore
Your backup plan depends on both the database backend and the attachment storage backend.
To download or move only your own memos, use **Settings → Export & Import** instead. The [Export & Import guide](/docs/usage/export-import) explains the ZIP format, conflict choices, and Space handling. A personal export does not include other users' memo content, accounts, settings, or Space memberships, so it does not replace the instance backups described here.
## Default data directory layout [#default-data-directory-layout]
```
~/.memos/
├── memos_prod.db # SQLite database (default)
└── assets/ # Uploaded files and attachments
```
The location is controlled by `MEMOS_DATA`. Override it at runtime or use the default.
## What to back up [#what-to-back-up]
* the database itself
* local attachment storage when attachments are not stored in the database
* deployment configuration such as environment variables, compose files, and proxy config
## SQLite backup [#sqlite-backup]
The safest offline approach is to stop Memos and copy the database file:
```bash
sudo systemctl stop memos
tar -czf memos-backup-$(date +%Y%m%d).tar.gz -C ~/.memos .
sudo systemctl start memos
```
For online backups while Memos is running, use SQLite's built-in `.backup` command which handles WAL mode correctly:
```bash
sqlite3 ~/.memos/memos_prod.db ".backup ~/.memos/memos_backup.db"
```
Automated daily backup with 7-day retention:
```bash
#!/bin/bash
BACKUP_DIR="/var/backups/memos"
DATE=$(date +%Y%m%d-%H%M%S)
MEMOS_DATA="${MEMOS_DATA:-$HOME/.memos}"
mkdir -p "$BACKUP_DIR"
sqlite3 "$MEMOS_DATA/memos_prod.db" ".backup $BACKUP_DIR/memos-$DATE.db"
tar -czf "$BACKUP_DIR/assets-$DATE.tar.gz" -C "$MEMOS_DATA" assets
find "$BACKUP_DIR" -name "memos-*.db" -mtime +7 -delete
find "$BACKUP_DIR" -name "assets-*.tar.gz" -mtime +7 -delete
```
Add to cron: `0 2 * * * /usr/local/bin/backup-memos.sh`
## MySQL backup [#mysql-backup]
```bash
# Backup
mysqldump -u memos_user -p memos_db | gzip > memos-backup-$(date +%Y%m%d).sql.gz
tar -czf assets-backup-$(date +%Y%m%d).tar.gz -C ~/.memos assets
# Restore
gunzip < memos-backup.sql.gz | mysql -u memos_user -p memos_db
tar -xzf assets-backup.tar.gz -C ~/.memos
```
## PostgreSQL backup [#postgresql-backup]
```bash
# Backup
pg_dump -U memos_user -d memos_db -F c -f memos-backup-$(date +%Y%m%d).dump
tar -czf assets-backup-$(date +%Y%m%d).tar.gz -C ~/.memos assets
# Restore
pg_restore -U memos_user -d memos_db memos-backup.dump
tar -xzf assets-backup.tar.gz -C ~/.memos
```
## Recovery mindset [#recovery-mindset]
Backups only matter if restore is realistic. Keep enough information to answer:
* where the data lived
* which database driver was in use
* whether attachments were in the database, on disk, or in object storage
* how the instance URL, separate access policy, and proxy were configured
* every named storage configuration still referenced by attachments, including configurations no longer selected for new uploads
## Operational advice [#operational-advice]
* test restore at least once before you depend on the backup plan
* record the storage backend alongside the backup process
* treat attachment recovery as a first-class part of restore, not an afterthought
---
# Performance Tuning
URL: https://usememos.com/docs/operations/performance-tuning
Memos is lightweight by default, so performance work should stay targeted. Start with storage, database choice, and deployment shape before reaching for low-level tuning.
## Built-in caching [#built-in-caching]
Memos maintains an in-memory cache for frequently accessed data. The cache runs entirely in-process with no external dependency:
| Cached resource | TTL | Max items |
| ----------------- | ------ | ---------- |
| Instance settings | 10 min | — |
| Users | 10 min | 1000 total |
| User settings | 10 min | — |
Cache entries are invalidated immediately on write operations and automatically expired after their TTL.
The database-backed `ACCESS` setting bypasses the ordinary settings cache so another replica observes an access-policy change on its next policy check. Deployment-file overrides remain fixed until that process restarts.
## SQLite tuning [#sqlite-tuning]
Memos applies these SQLite pragmas by default:
| Pragma | Default value | Effect |
| -------------- | -------------- | ----------------------------------------------------------- |
| `journal_mode` | `WAL` | Write-Ahead Logging; allows concurrent reads during writes |
| `busy_timeout` | `10000` (10 s) | Waits up to 10 s for a write lock before returning an error |
| `foreign_keys` | `0` | Disabled for flexibility |
| `mmap_size` | `0` | Memory-mapping disabled to avoid OOM on some systems |
For higher write loads, you can extend the defaults through the DSN:
```bash
export MEMOS_DSN="/path/to/memos.db?_pragma=cache_size(-64000)&_pragma=synchronous(NORMAL)&_pragma=temp_store(MEMORY)"
```
SQLite limitations to keep in mind:
| Dimension | Recommendation |
| ------------------ | ----------------------------------------------------- |
| Concurrent writers | 1 (serialized through WAL) |
| Concurrent readers | Unlimited |
| Practical DB size | Up to \~100 GB |
| When to migrate | High concurrent writes or multi-server write patterns |
## Live updates and write contention [#live-updates-and-write-contention]
In 0.31, browser tabs coordinate one SSE connection through a visible tab instead of opening redundant streams. Keep reverse proxies compatible with long-lived event streams and avoid response buffering on the SSE route.
SQLite memo mutations begin with `BEGIN IMMEDIATE`, allowing concurrent writers to wait for the write lock earlier in the transaction. Writes are still serialized; this reduces intermittent `SQLITE_BUSY` failures without making SQLite a multi-writer database.
## First-order decisions [#first-order-decisions]
* SQLite is fine for many single-instance deployments
* move to MySQL or PostgreSQL when operational needs justify it
* choose the attachment backend based on file volume and backup expectations
* keep the instance behind a reverse proxy in production
## Where to look first [#where-to-look-first]
* database latency or lock contention
* slow storage volumes
* oversized attachment handling
* under-provisioned container or pod resources
## Tuning advice [#tuning-advice]
* measure first
* tune the database only after confirming the bottleneck
* keep caching and proxy behavior simple unless usage data says otherwise
* prefer structural fixes such as better storage placement before micro-tuning runtime flags
---
# Upgrade
URL: https://usememos.com/docs/operations/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 [#before-every-upgrade]
1. Back up the database and attachments — see [Backup & Restore](/docs/operations/backup-restore).
2. Read the [changelog](/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 [#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 [#upgrading-to-2610]
**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](/changelog/26-10-rc-1).
### Required upgrade path [#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 [#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](/docs/integrations/api-access#2610-client-migration).
* Replace the removed built-in Tasks View with a [View](/docs/usage/views) 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 [#upgrading-to-031]
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](/changelog/0-31-0).
### Access and deployment [#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](/docs/configuration/deployment-configuration#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 [#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 [#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](/docs/integrations/api-access#031-client-migration).
### Removed features [#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](/docs/integrations/api-access) for reads or [webhooks](/docs/integrations/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 [#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 [#upgrading-to-030]
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]
```bash
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](/docs/deploy/docker).
## Docker Compose [#docker-compose]
```bash
docker compose pull
docker compose up -d
```
## Binary [#binary]
1. Stop the service (`systemctl stop memos` or your supervisor's equivalent).
2. Replace the binary with the new release from [GitHub releases](https://github.com/usememos/memos/releases).
3. Start the service and watch the logs for migration output.
See the [Binary guide](/docs/deploy/binary) for service setup.
## Pinning versions [#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 [#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 [#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.
---
# Troubleshooting
URL: https://usememos.com/docs/troubleshooting
Work through the section that matches your symptom. Most problems trace back to ports, file permissions, database connection strings, or proxy headers.
## Port already in use [#port-already-in-use]
Change the port with `--port` or `MEMOS_PORT` and restart the server.
## Cannot write to the data directory [#cannot-write-to-the-data-directory]
Ensure the data directory exists and is writable by the Memos process. You can set it with `--data` or `MEMOS_DATA`.
## Database connection errors [#database-connection-errors]
Verify the driver and DSN:
* `MEMOS_DRIVER` should be `sqlite`, `mysql`, or `postgres`.
* `MEMOS_DSN` should use the correct DSN format for your database.
## Reverse proxy issues [#reverse-proxy-issues]
If you run behind a reverse proxy, make sure:
* `MEMOS_INSTANCE_URL` matches the public URL
* the proxy forwards standard headers (`Host`, `X-Forwarded-*`)
## Docker starts but the app does not respond [#docker-starts-but-the-app-does-not-respond]
Check:
* `docker logs memos`
* whether the host port is already occupied
* whether the mounted data directory is writable
## Attachments are missing after migration [#attachments-are-missing-after-migration]
Confirm which storage backend the instance uses. If attachments are stored outside the database, they must be migrated and backed up separately.
## Access changed unexpectedly after an upgrade [#access-changed-unexpectedly-after-an-upgrade]
In 0.31, inspect the effective `ACCESS` setting and any `memos-instance-setting-access.json` deployment override. Changing `MEMOS_INSTANCE_URL` does not change an existing access policy. Upgrade all replicas before changing the policy, and restart replicas when changing file-backed settings.
## Sign-in fails after upgrading to 0.31 [#sign-in-fails-after-upgrading-to-031]
Check the exact stored username, including capitalization. Username lookup and password sign-in are case-sensitive.
## A displayed tag is missing from filters [#a-displayed-tag-is-missing-from-filters]
Existing tag indexes are not rebuilt automatically for 0.31's grammar. Save the affected memo again so filters and statistics adopt the parsed tags.
## An integration returns permission or file errors [#an-integration-returns-permission-or-file-errors]
Check author identity and Space membership. Active instance administrators can read and manage individual memos without authorship or Space membership; Space admin roles do not grant that authority. For managed inline images, bind the attachment before or during the memo update, and use Memos file routes with the appropriate authentication or share token. See [API migration notes](/docs/integrations/api-access#031-client-migration).
## Still stuck? [#still-stuck]
Check the [FAQ](/docs/faq) or search [GitHub issues](https://github.com/usememos/memos/issues).
---
# Usage
URL: https://usememos.com/docs/usage
Capture a thought, find it again, and decide who can read or respond to it. These pages explain the individual Memos features you can combine into a daily practice, from writing and attachments to Views, Spaces, and sharing.
## Write and capture [#write-and-capture]
Write and edit memos, browse by date or location, and choose placement and visibility.
Add images and files to a memo, browse the attachment library, and review unused uploads.
Format plain-text notes with headings, checklists, tables, code blocks, and links.
## Organize and find [#organize-and-find]
Add searchable hashtags in memo content and organize related topics with tag hierarchies.
Name and reuse filter conditions to see the memos that currently match.
Find notes by content or metadata, archive older memos, and restore them when needed.
## Share and collaborate [#share-and-collaborate]
Bring members and memos together while keeping authorship, placement, and visibility independent.
Choose a memo's audience, manage share links, or export a memo as an image.
Acknowledge memos, participate in discussions, and mention other users with the right access.
Review comments and mentions, respond to Space invitations, and manage notifications.
Link an external SSO account so it signs in to your existing Memos user.
## Keep or move your data [#keep-or-move-your-data]
Download your memos and attachments as a ZIP, then import them into another account or instance.
## Choose the question you need to answer [#choose-the-question-you-need-to-answer]
| If you want to know… | Start with… |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| How do I write a note with a checklist or image? | [Memos](/docs/usage/memos), [Writing Markdown](/docs/usage/writing-markdown), and [Attachments](/docs/usage/attachments) |
| How do I return to the same set of related notes? | [Tags](/docs/usage/tags) and [Views](/docs/usage/views) |
| How do I find an older note or clear it from my timeline? | [Search & Archive](/docs/usage/search-archive) |
| How do I revisit notes from a date or place? | [Browsing your memos](/docs/usage/memos#browsing-your-memos) |
| How do I work with a group and control who can read a memo? | [Spaces](/docs/usage/spaces) and [Sharing](/docs/usage/sharing) |
| How do I join a discussion and keep track of replies? | [Reactions & Comments](/docs/usage/reactions-comments) and [Inbox](/docs/usage/inbox) |
| How do I connect SSO to the account I already use? | [Linked Identities](/docs/usage/linked-identities) |
| How do I download my memos or move them to another instance? | [Export & Import](/docs/usage/export-import) |
Start with a few memos and add tags or Views when you have something you want to revisit. When collaborating, check placement and visibility separately: assigning a memo to a Space does not automatically make it visible to that Space's members.
To combine these capabilities into a complete, repeatable practice, explore [Guides](/docs/guides).
---
# Attachments
URL: https://usememos.com/docs/usage/attachments
Attachments let you keep files close to the notes they belong to. This is useful for screenshots, design references, PDFs, exported data, and other supporting material.
## Typical attachment flow [#typical-attachment-flow]
* drag a file into the editor
* use the upload control in the toolbar
* paste screenshots directly from the clipboard when supported
The app uploads files in smaller chunks automatically. No separate setting is needed; the instance's file-size limits still apply.
## Inline images and drafts [#inline-images-and-drafts]
Images can be inserted at the cursor through upload, paste, drag and drop, or selection from existing attachments. They become Markdown images in the memo body. Other files remain attachments you can open from the memo.
Failed inline uploads can be retried. Returning to an unfinished draft restores its inline upload state so you can continue composing. Confirm uploads have completed before publishing, and keep the local draft until the memo is saved.
Removing an image from the Markdown body does not by itself prove the file is unused: attachment binding and inline references are separate. Use the attachment library's unused status when cleaning up.
## Optional media metadata [#optional-media-metadata]
Enable **Save media metadata** in your preferences to preserve normalized details from future uploads. This is off by default. Depending on the file, details can include dimensions, camera information, capture time, location, and video duration. Inspect available details in the attachment viewer.
The preference applies to future uploads; it does not backfill existing files. Location and capture details can reveal where and when media was recorded, so inspect them before sharing. Disabling metadata extraction is not a promise that embedded metadata has been stripped from the original file.
## Common attachment types [#common-attachment-types]
* images and screenshots
* PDFs and documents
* audio or video files when your storage policy allows them
* exported artifacts such as logs or data files
## Transcribing audio [#transcribing-audio]
If an admin has configured an AI provider with transcription (Admin → Instance Settings → AI), audio attachments can be transcribed into text.
* transcription is off until a provider is configured, so the option only appears on instances that have AI enabled
* in 26.10, open the memo editor and transcribe an existing audio attachment; the transcript is inserted into the draft for you to review and save, preserving the existing text and original audio
* providers are bring-your-own-key (OpenAI or Gemini), so transcription uses the instance's own AI account
This is useful for voice notes and recorded snippets you want to search later as plain text.
## The attachment library [#the-attachment-library]
In 26.10, the Attachments page includes files from memos you can read and identifies their uploaders. Its results follow the selected creator and Space, preserving that scope when you switch from Timeline, Calendar, or Map. File management remains subject to your permissions.
* files are grouped into **Media**, **Audio**, and **Documents** tabs, each with a live count
* media is shown as a grid grouped by month; images, videos, and motion photos open in a full-screen lightbox
* audio files play inline, with playback-speed choices including 0.5× and 0.75×; documents are listed as rows you can open in a new tab
* every attachment links back to the memo it belongs to, or is flagged when it isn't linked to any memo
* long lists load in pages with a **Load more** button
In image previews, pinch to zoom and drag to pan a zoomed image. At fit zoom, swipe to move between gallery images.
There is no upload control here — attachments are added from the memo editor. The library is for browsing, previewing, and cleanup.
## Cleaning up unused attachments [#cleaning-up-unused-attachments]
An attachment is **unused** when it is not bound to any memo, such as an upload you never attached to a saved memo. Deleting a memo removes its owned attachment resources; removing only an inline image reference does not necessarily remove the attachment binding.
When you have unused attachments, the library shows an expandable **Unused** panel listing them. From there you can **Delete all unused** in one action (with a confirmation step) to reclaim storage.
Deleting unused attachments is permanent, so review the list before confirming. Attachments that are still linked to a memo are never touched.
## Storage implications [#storage-implications]
Open **Settings → My Account** and look under **Statistics → Attachment storage** to see your account's attachment storage usage. Review unused uploads in the attachment library when you want to reclaim space.
Attachments depend on the storage backend chosen for the instance:
* database storage keeps everything together
* local filesystem storage keeps files on the host or volume
* S3-compatible storage separates files from the app host
Admins can configure multiple named storage backends. Changing the backend for new uploads does not move existing files. A [personal memo export](/docs/usage/export-import) includes the managed files attached to your exported memos, regardless of their storage backend.
## Access to managed files [#access-to-managed-files]
Managed files follow the memo's access rules. Memos serves S3-backed attachments through its authenticated file route, including range requests for media playback. A shared memo supplies authorized attachment URLs; preserve their share tokens when copying or rendering thumbnails.
API clients must bind a managed image to the memo before or during the mutation that references it in Markdown. Do not use a presigned S3 object URL from `externalLink`; managed S3 attachments no longer expose one there. See [API Access](/docs/integrations/api-access#031-client-migration).
## Operational guidance [#operational-guidance]
* match your backup plan to your attachment storage backend
* use sensible upload limits
* review public memo visibility carefully when attachments are involved
* remember that media-heavy instances need stronger storage planning than text-only instances
---
# Export & Import
URL: https://usememos.com/docs/usage/export-import
Use **Settings → Export & Import** to keep a portable copy of your memos or move them to another instance. Export and import are available starting in Memos 0.31.
## Export your memos [#export-your-memos]
1. Sign in to the account whose memos you want to export.
2. Open **Settings → Export & Import**.
3. Under **Export memos**, choose **Export memos** and wait for the ZIP download.
The file is named `memos-export--.zip`. It uses Memos Export Format, with Markdown content and JSON metadata for each memo, plus attached files. You can read the Markdown outside Memos; keep the original ZIP intact for importing.
The export includes all memos you authored across Spaces, regardless of the current sidebar filters:
* active and archived memos, including comments you wrote
* creation and update times, visibility, pinned state, location, and Space references
* memo Relations and comment-parent references
* files attached to those memos, including files stored in the database, on disk, or in S3-compatible storage
External attachment links remain links; their remote files are not downloaded into the ZIP. Unused uploads and other people's memo content are not included, even when you can read them. An export of your memos is therefore not a complete export of a shared Space or its discussions.
The ZIP can contain private notes and files and is not encrypted. Store it somewhere appropriate for that content.
## Import a Memos export [#import-a-memos-export]
1. Sign in to your account on the destination instance.
2. Open **Settings → Export & Import** and select **Choose file** under **Import memos**.
3. Select the Memos export ZIP. Memos uploads and validates it before showing a preview; this step does not create or replace memos.
4. Review the memo and attachment counts, existing-memo count, and warnings.
5. If matching memos already exist in your account, choose how to handle them.
6. Choose **Import … memos**, then review the result.
Older files using the `memos-archive` format name are also accepted. A ZIP containing arbitrary Markdown files is not a Memos export.
### Choose how to handle existing memos [#choose-how-to-handle-existing-memos]
Memos identifies an existing memo by its ID, not by identical text or title.
| Option | Result for a matching memo in your account |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Keep mine** | Skip it and keep your current version. This is the default. |
| **Replace with the imported version** | Replace it with the exported content and settings. Export before using this if you need to retain the current version. |
| **Create a copy** | Leave it unchanged and create a separate memo with a new ID. Repeating this option creates more copies. |
Memos without a match are created in your signed-in account. An ID collision with another user's memo creates a new ID rather than replacing their memo.
### Spaces, visibility, and discussions [#spaces-visibility-and-discussions]
Import does not create Spaces or memberships. It tries to match each exported Space to one you actively belong to, first by ID and then by name. If you want to keep that placement, create or join the destination Spaces before importing.
If no Space matches, the memo becomes **Unassigned**. A `SPACE` memo without a matching Space becomes `PRIVATE`, and the import reports a warning. Other visibility values are preserved, so review the audience before importing into an instance with different users or public-access settings.
Relations and comment threads are restored when their target memos can be resolved. A missing parent causes a new comment to become a top-level memo; missing references are omitted, with warnings. Replacing an existing memo does not change its comment parent. Reactions are recorded in the export for reference but are not recreated by import.
### Review the result [#review-the-result]
The report lists **Created**, **Updated**, **Skipped**, and **Failed** counts, plus warnings and individual failures. Some memos can succeed while others fail, so inspect the report before deciding whether to retry. Destination content and attachment limits still apply.
If the uploaded file expires before you confirm the import, choose the file again. Keep the source account and ZIP until you have checked the imported content, attachments, placement, and visibility.
## Personal exports and instance backups [#personal-exports-and-instance-backups]
Use this feature for your own memo content. It does not transfer user accounts, account or instance settings, access tokens, share links, revision history, or Space membership. For recovery of an entire instance, back up its database, attachment storage, and configuration following [Backup & Restore](/docs/operations/backup-restore).
To share a picture of one memo instead, use [Share as image](/docs/usage/sharing#share-as-image).
---
# Inbox
URL: https://usememos.com/docs/usage/inbox
The inbox is your notification center for collaboration activity. It collects events that involve you so you don't have to revisit memos to find replies.
## What shows up [#what-shows-up]
The inbox surfaces collaboration notifications:
* **Comments** — someone commented on one of your memos
* **Mentions** — someone mentioned you with `@` in a memo or comment
* **Space invitations** — someone invited you to join a Space on this instance
Rows show the sender, activity, and time, with memo context when available. The sidebar Inbox action carries an unread-count badge. Inbox remains global when you select a Space.
## Reading and filtering [#reading-and-filtering]
Open the inbox to see notifications newest-first. The contextual sidebar filters the list:
* **All** — every notification
* **Unread** — notifications you haven't opened yet
* **Archived** — notifications you've cleared
Clicking a comment or mention notification opens the related memo or comment and marks the notification read.
## Respond to a Space invitation [#respond-to-a-space-invitation]
An invitation shows the Space, sender, and proposed role. Choose **Accept** to join or **Decline** to dismiss the invitation. After accepting, choose **Open space** to browse it.
You do not gain membership until you accept. Archiving or deleting the notification does not accept the invitation; you can also manage pending invitations in **Settings → Spaces**. See [Spaces](/docs/usage/spaces) for member roles and visibility rules.
## Managing notifications [#managing-notifications]
* **Archive** an unread notification to clear it without opening the memo
* **Delete** a read or archived notification to remove it permanently
* notifications whose required memo is missing or unreadable are omitted; deleting a memo does not itself delete independent inbox records
## Good habits [#good-habits]
* skim **Unread** regularly so mentions and comments don't pile up
* archive notifications once you've acted on them to keep the list focused
* pair the inbox with [reactions and comments](/docs/usage/reactions-comments) as your main collaboration loop
---
# Linked Identities
URL: https://usememos.com/docs/usage/linked-identities
Linked identities connect your Memos account to external SSO accounts from configured identity providers. After a provider is linked, you can use that SSO account to sign in to the same Memos user.
## Sign in with SSO [#sign-in-with-sso]
If your instance has SSO providers configured, the sign-in page shows a button for each provider. Choose a provider, finish the authorization flow on the provider's site, and return to Memos.
The first time you sign in with an SSO account, one of two things happens:
* if the external account is already linked, Memos signs in to the linked user
* if the external account is new and registration is allowed, Memos creates a regular local user and links the SSO account
* if registration is disabled, the sign-in is rejected until the account is created or linked another way
For a new SSO user, Memos uses the mapped external identifier as the local username when it is valid, non-reserved, and available. In 0.31, new usernames allow 1–36 ASCII letters or digits and interior hyphens; lookup is case-sensitive. Otherwise it generates a UUID-based username. Your display name, email, and avatar can still come from the SSO provider when those fields are available.
## Link an SSO account [#link-an-sso-account]
Use account settings when you already have a Memos account and want to connect it to an external SSO account.
1. Sign in to Memos with your existing account.
2. Open account settings.
3. Find the linked identities or SSO account section.
4. Choose the provider you want to link.
5. Complete the provider authorization flow.
6. Return to Memos and confirm that the provider now appears as linked.
After linking, signing in with that provider account will open your existing Memos account instead of creating a separate user.
## Linking rules [#linking-rules]
Memos keeps local users and external identities separate. A linked identity records which provider account belongs to which Memos user.
The current rules are:
* one Memos user can link multiple SSO providers
* one Memos user can link only one external account per provider
* one external account can be linked to only one Memos user
* linking the same provider account again is treated as already linked
If you try to link a provider account that is already connected to another Memos user, Memos rejects the link. If your Memos account already has a different account linked for the same provider, unlink the current provider first or use the existing linked account.
## Unlink an SSO account [#unlink-an-sso-account]
Unlinking removes the connection between your Memos account and the external provider account. It does not delete:
* your Memos account
* the external provider account
* the identity provider configuration for the instance
* any memos, attachments, or settings in your account
Before unlinking, make sure you still have another way to sign in. You may lock yourself out if you unlink your only SSO account while password sign-in is disabled or unavailable for your account.
Admins can also remove linked identities for users when cleaning up accounts or recovering from a mistaken link.
## Troubleshooting [#troubleshooting]
If an SSO sign-in creates a different Memos user than expected, sign out and ask an admin to check which provider account is linked to each Memos user.
If SSO sign-in used to work but now fails, the identity provider configuration may have changed. Provider UID, identifier mapping, and identifier filters all affect whether Memos can match your external account to the existing linked identity.
For administrator setup details, see [Authentication](/docs/configuration/authentication).
---
# Memos
URL: https://usememos.com/docs/usage/memos
A memo is one thought, written down: short, untitled, and saved to your timeline in the order it happened. A good memo practice keeps writing quick while still making memos readable and searchable later.
## Core actions [#core-actions]
* create a memo from the global composer on any authenticated route
* edit content inline
* link related memos with Relations
* pin important memos
* set visibility before sharing
* archive memos that are no longer active
## Navigation and creation [#navigation-and-creation]
The resizable sidebar contains [Calendar](#calendar), [Map](#map), Views, tags, Quick Find, and navigation for the current route. Open the global composer from the sidebar to write without returning to Home.
Selecting a Space scopes browsing and memo creation to that Space. Check placement and visibility before saving; assigning a memo does not change its audience. Existing memos remain Unassigned after upgrading. See [Spaces](/docs/usage/spaces) for scope and membership rules.
Authors can edit their own memos; editing an assigned memo also requires active membership in its Space. Active instance administrators can read and manage individual memos without authorship or Space membership. Space admin roles do not grant editing rights to another author's content.
## What the editor supports [#what-the-editor-supports]
* Markdown formatting
* decorated source editing that keeps Markdown syntax directly editable
* a formatting toolbar and keyboard shortcuts
* focus mode for a quieter writing surface
* list indentation with `Tab` and `Shift+Tab`
* inline tags such as `#project-x`
* code blocks and checklists
* file attachments
* memo visibility controls
* tag suggestions when you type `#`
* auto-saved drafts cached locally so content is not lost on page reload
In 26.10, new drafts offer optional tag, checklist, and visibility suggestions based on your current filters or selected View. Apply a suggestion to add it to the draft; it disappears once fulfilled. Choose the Space and visibility together in the audience menu, then save the memo.
## Browsing your memos [#browsing-your-memos]
In 26.10, Timeline, Calendar, Map, and Attachments retain the selected creator and [Space](/docs/usage/spaces) when you switch between them. Combine that scope with a [View](/docs/usage/views) or tag filters to narrow readable memos. Select the main **Memos** context to browse across Spaces. Archived memos are available separately under [Archived](/docs/usage/search-archive#archive).
Calendar and Map also support signed-out visitors when public access is enabled; visitors only see memos they can read. Photos and author avatars help distinguish entries when browsing several creators.
### Feed [#feed]
Choose one, two, three, or automatic columns in your display preferences.
Compact mode and link previews are configurable there too, and the choices are
saved for your account. Link previews discover metadata from oEmbed, Open Graph, Twitter Cards, JSON-LD, and ordinary HTML when the linked site supplies it. Sites without usable metadata may still appear as plain links. The single-column layout shows full memo content by
default; multi-column and compact layouts favor faster scanning.
Single-creator feeds show pinned memos with a corner marker; mixed-author feeds stay chronological. When you return from a memo detail
page, Memos restores your previous feed position so you can continue where you
left off.
### Calendar [#calendar]
Open **Calendar** from the sidebar to revisit a day's notes or review a month. Use the previous and next month controls, or select the month heading to choose another month and year. **Today** returns to the current month.
Select a day to read its memos in a panel on desktop or below the grid on mobile. Days show counts and previews when available. The calendar uses your local time zone and the selected creation or update time setting, with creation time as the default.
To fill in an entry for a particular date, open that day and choose **New memo on this day**. The composer starts with that date as the creation and update time and uses the current Space. Check the date, placement, and visibility before saving. Later edits can move a memo to a different day when browsing by update time; use creation time to review a journal by its entry dates.
Calendar groups notes by their timestamps; it does not assign due dates to checklist items. If a day looks empty, check the active filters and time setting.
### Map [#map]
Open **Map** from the sidebar to browse memos with saved locations. Select a marker to read the notes at that location, or choose **Show all results** to fit the matching locations into view. With a single location selected, **Write here** starts a memo with that location and the current Space filled in.
To add a location to a memo:
1. Create or edit the memo and choose **Add location** from the editor's add menu.
2. Select a point on the map or enter latitude and longitude. Allowing browser location access can help set your current position; you can also choose manually.
3. Enter a location label, choose **Confirm**, and save the memo.
Writing a place name or attaching a photo with location metadata does not by itself place the memo on Map. Anyone who can read the memo can see its saved location, so check visibility before sharing.
If no markers appear, check for saved locations and active filters; use **Clear filters** when offered. A newly saved memo may fall outside the current filters. If the map background fails to load, use **Retry**; your memo results remain available.
## Memo detail [#memo-detail]
Opening a memo shows its full content and discussion alongside a property rail
for metadata and actions such as visibility, tags, relations, attachments,
reactions, and sharing. On smaller screens, the same controls remain available
in a responsive layout.
## Memo properties [#memo-properties]
Memos automatically computes properties from memo content. These can be used in filter expressions:
| Property field | Meaning |
| ---------------------- | ------------------------------------- |
| `has_link` | Contains one or more Markdown links |
| `has_code` | Contains code blocks or inline code |
| `has_task_list` | Contains at least one task list item |
| `has_incomplete_tasks` | Contains unchecked `- [ ]` task items |
| `has_location` | Has location data attached |
## Linking memos with Relations [#linking-memos-with-relations]
Choose **Link memo** from the editor's add menu, search active memos you own, and select one. After you save, the current memo displays the outgoing connection under **Referencing**; the selected memo displays the incoming connection under **Referenced by**.
Relations are separate from Markdown links. Pasting a memo URL into the content creates a normal link but does not create a Relation or an incoming reference. Use Relations to connect memos to each other, and use Markdown links when the URL itself should be part of the memo.
A Relation does not grant access to either memo. Each side keeps its own visibility, and readers only see connections to memos they can already access.
## Useful memo metadata [#useful-memo-metadata]
* placement: Unassigned or exactly one [Space](/docs/usage/spaces)
* visibility: `PRIVATE`, `PROTECTED`, `PUBLIC`, or `SPACE`
* tags extracted from inline hashtags
* attachments such as screenshots and documents
* checklist items for lightweight task tracking
* creation and update times — the timeline and Calendar order and group memos by one of them (creation time by default); when editing a memo, select the timestamp at the top of the editor to change either time
## Good habits [#good-habits]
* keep each memo focused on one topic or update
* use headings when a memo gets long
* add tags while writing, not later
* archive stale memos instead of leaving everything active forever
* pin only the memos that truly deserve persistent attention
## Related guides [#related-guides]
* [Use Memos as a Digital Bullet Journal](/docs/guides/bullet-journal) for rapid logging and reflection.
* [Use Memos for GTD](/docs/guides/getting-things-done) for action management.
* [Build a Zettelkasten in Memos](/docs/guides/zettelkasten) to develop ideas from evidence.
* [Export & Import](/docs/usage/export-import) to download your memos and attachments or move them to another instance.
---
# Reactions & Comments
URL: https://usememos.com/docs/usage/reactions-comments
Beyond writing your own notes, Memos supports lightweight collaboration on memos: emoji reactions, threaded comments, and user mentions. Participation requires sign-in and read access. For a memo assigned to a Space, commenting and reacting also require active membership in that Space.
## Reactions [#reactions]
React to a memo with an emoji from the reaction selector in the memo header.
* reactions are available on readable, non-archived memos when you have permission to participate
* each reaction belongs to the user who added it; administrators cannot remove someone else's reaction merely because of their role
* click an emoji to add your reaction; click it again to remove it
* the set of allowed reactions is configured by admins in **Settings → Memo**
Reactions are a fast way to acknowledge a memo without writing a comment.
## Comments [#comments]
Open a memo's detail page to read and add comments.
* commenting requires sign-in, read access, and membership when the context memo is assigned to a Space
* comments support the full Markdown editor, just like memos
* each comment is an independent, author-owned memo connected to its context memo, so it can be reacted to and linked directly
* each comment has its own placement and visibility; a relation does not grant access to either memo
* in 26.10, deleting the context memo also deletes its comments and nested replies
* the memo's author is notified in their [inbox](/docs/usage/inbox) when a new comment is posted
Comments live on the memo's detail page rather than in the main timeline, which keeps feeds focused on top-level notes.
### Comment visibility and API behavior [#comment-visibility-and-api-behavior]
A discussion only includes comments the reader can independently access. Check the comment's placement and audience before posting; they are not inherited by the API. `CreateMemoComment` defaults omitted visibility to `PRIVATE`.
Use `CreateMemoComment` to create a comment and its context relation together. `SetMemoRelations` rejects `COMMENT` relations. In 26.10, removing a parent memo deletes the comment subtree; in 0.31, parent deletion only removed its incident relations. An eligible comment can also be shared independently through the API; its share exposes only that comment.
## Mentions [#mentions]
Reference another user inside a memo or comment with `@`, for example `@alice`. Mentions use exact-case usernames: `@Alice` does not refer to `alice`. New usernames contain 1–36 ASCII letters or digits, with hyphens only inside the name. Mentions respect Markdown context, so code, links, and escaped text do not create ordinary mentions. Legacy names outside the supported grammar, including email-like names, underscores, or non-ASCII spellings, cannot be authored as new mentions.
Mentioned users with access to the memo receive a notification in their [inbox](/docs/usage/inbox) linking back to the memo, which makes mentions useful for looping someone into a note or comment thread.
## Good habits [#good-habits]
* use reactions for quick acknowledgement and comments for anything that needs a reply
* keep comment threads on-topic with the parent memo
* mention people sparingly so notifications stay meaningful
* anonymous viewers can read reactions and comments on normal public memo pages when public mode is enabled
* a share-token page includes the selected memo and its reactions, but not the surrounding comment thread or relation graph
---
# Search & Archive
URL: https://usememos.com/docs/usage/search-archive
## Search [#search]
Use search to narrow memos by:
* content text
* tags
* visibility
* time range
* whether location data is present
* reusable filters with Views
A memo has no separate title field, so search works best when you keep opening lines, headings, and tags consistent.
## Quick Find and browsing scope [#quick-find-and-browsing-scope]
Open Quick Find with the sidebar search action. The global Cmd/Ctrl+K shortcut was removed in 0.31.
* **Text** searches for words in memo content. Matching text is highlighted in the results.
* **Expression** accepts the same [CEL filter syntax as Views](/docs/usage/views#filter-expression-syntax), for example `has_location && tag in ["travel"]` or `space == null && has_incomplete_tasks`.
Press **Enter** to search. In Expression mode, **Shift+Enter** adds a new line. Check the scope shown at the top of Quick Find: the current collection, Space, View, and filters can narrow the results. To reuse an expression, copy it into a new [View](/docs/usage/views#create-a-view).
Searching from Calendar, Map, or Attachments opens the matching memo list in Home within the same Space context.
Home and Explore filters follow the selected Space. [Views](/docs/usage/views) reuse CEL expressions, including `has_location`, `space == null` for Unassigned memos, and `visibility == "SPACE"` for members-only memos.
## Archive [#archive]
Archived is global across Spaces. Archived memos are kept but hidden from the main timeline. Use archiving when a memo is still worth keeping but no longer belongs in active daily views.
Typical archive routine:
* archive finished projects or stale references
* restore a memo when it becomes relevant again
* combine archive review with search when looking for older material
## Public sharing and discovery [#public-sharing-and-discovery]
Search only returns memos you can read. The instance access policy determines whether anonymous visitors can discover `PUBLIC` memos; the canonical instance URL does not control that policy. Use `PRIVATE` for author-only notes, `SPACE` for members of the assigned Space, or `PROTECTED` for signed-in instance users. See [Sharing](/docs/usage/sharing).
## Related guides [#related-guides]
* The [Memos Bullet Journal guide](/docs/guides/bullet-journal) uses recent-log and incomplete-task filters for daily and monthly reflection.
* The [Memos GTD guide](/docs/guides/getting-things-done) shows how checking and archiving completed actions keeps active views focused without discarding their history.
* The [Memos Zettelkasten guide](/docs/guides/zettelkasten) uses search to find nearby ideas before creating meaningful Relations.
---
# Sharing
URL: https://usememos.com/docs/usage/sharing
Sharing in Memos has two layers: **visibility**, which decides who can reach a memo through the app, and **share links**, which create a standalone URL for a single memo.
## Visibility levels [#visibility-levels]
Every memo has one of four visibility levels, set from the editor before or after posting:
* `PRIVATE`: only you can read the memo
* `PROTECTED`: any signed-in user on the instance can read it
* `PUBLIC`: anonymous visitors can read it when the instance is in public mode
* `SPACE`: active members of the memo's assigned Space can read it
The `ACCESS` instance setting controls public or private access independently of `MEMOS_INSTANCE_URL`. With public access enabled, public memos can be discovered through Explore and public profiles. In private mode, ordinary `PUBLIC` memo pages require sign-in.
Placement and visibility are independent. Putting a memo in a Space does not change its audience: an assigned `PRIVATE` memo stays author-only, and an assigned `PROTECTED` memo remains readable by other signed-in users. `SPACE` visibility requires a Space assignment. See [Spaces](/docs/usage/spaces).
## Share links [#share-links]
Open a memo's detail page and use the **Share** section in the sidebar to create a public link for that single memo:
* **Open share panel** — create, list, and revoke share links. Each link can be set to expire **never, after 1 day, 7 days, or 30 days**.
* A share link resolves without sign-in, including for `PRIVATE` and `PROTECTED` memos, and signs attachment URLs so images and files load for anonymous viewers.
* The token exposes only the selected memo, its attachments, and its reactions. It does not expose the surrounding parent memo, comments, or relation graph.
* Revoke a link at any time to immediately stop access.
Only the memo's author can manage its share links; assigned memos also require active Space membership. The API can share a comment independently, exposing that comment alone rather than the parent or discussion.
`SPACE` memos cannot have share links. Revoke active links before changing a memo's visibility to `SPACE`. An existing share link is a separate grant of access, so switching the instance to private mode does not revoke it.
## Share as image [#share-as-image]
The same **Share** section offers **Open image**, which renders the memo as a self-contained image you can download and post anywhere — handy for chat apps or social media where a link would not render the content.
## What viewers can and can't do [#what-viewers-can-and-cant-do]
Anonymous public-mode viewers can follow the normal public memo page, including its readable discussion context. A share-token viewer receives the narrower standalone representation described above. Neither anonymous route allows editing, reacting, commenting, or managing shares.
## Safe sharing habits [#safe-sharing-habits]
* choose visibility intentionally before posting, especially for operational or sensitive notes
* review attachments before publishing a memo openly or minting a share link
* prefer time-limited share links over `PUBLIC` when you only need to share temporarily
* disable public memos entirely (Admin → Instance Settings) if your instance is private
---
# Spaces
URL: https://usememos.com/docs/usage/spaces
Spaces bring members and memos together inside one Memos instance. Each memo still belongs to its author. A Space provides a shared place to contribute and browse; it does not grant shared editing rights.
## Create or join a Space [#create-or-join-a-space]
1. Open the Space switcher in the sidebar and choose **Create Space**.
2. Enter a name and an optional description. Memos generates a stable ID, or you can supply a custom ID during creation.
3. Open **Settings → Spaces** to manage the Space. Its creator becomes the first Space admin.
4. In the members section, invite an existing user and choose the **User** or **Admin** role.
5. The invited user opens **Inbox** and chooses **Accept** or **Decline** on the invitation. Invitations are also available in **Settings → Spaces**. After accepting, choose **Open space** or select it from the sidebar switcher.
An invitation grants no access until accepted. It is an invitation to an existing account on the instance, not an email invitation or an account registration link.
A Space's ID stays stable when its name changes. Newly generated IDs use UUIDv4. Custom IDs contain 1–36 ASCII letters or digits, with hyphens allowed inside the ID. Spaces can have the same display name, so use their IDs to distinguish them in integrations.
Space admins can change the name, description, and icon from **Settings → Spaces**. Use the icon picker to choose an icon or emoji so the Space is easier to recognize in the sidebar and invitations.
## Placement and visibility [#placement-and-visibility]
A memo is either **Unassigned** or assigned to exactly one Space. Unassigned means it has no Space; it is not a default Space or a visibility level. Upgrading to 0.31 leaves existing memos Unassigned.
Choose placement and visibility separately:
| Visibility | Who can read the memo through normal memo access |
| ----------- | ------------------------------------------------------------------------------- |
| `PRIVATE` | Its author |
| `PROTECTED` | Signed-in users on the instance |
| `PUBLIC` | Signed-in users, plus anonymous visitors when public instance access is enabled |
| `SPACE` | Active members of its assigned Space |
Active instance administrators can also read and manage individual private and Space-only memos without Space membership. Collection listings still filter by audience.
`SPACE` requires a Space assignment. Assigning a `PRIVATE` memo does not make it visible to the other members. Assigning a `PROTECTED` or `PUBLIC` memo does not restrict it to members. A non-member who can read such a memo does not gain access to the Space feed, membership list, or settings.
Choose the Space when composing a memo, or change placement on a memo you authored. You must be a member of the destination Space. Moving a memo preserves its identity and relations. For a `SPACE` memo, confirm the destination audience when moving it; choose a different visibility when returning it to Unassigned.
### Move an existing memo [#move-an-existing-memo]
In 26.10, Space placement is part of the editor's audience menu:
1. Open a top-level memo you can edit and choose **Edit**.
2. Open the audience menu and choose a destination Space or **Unassigned**.
3. Review visibility in the same menu. Moving a members-only memo changes which members can read it; Unassigned memos cannot use `SPACE` visibility.
4. Save the memo to apply content, Space, and visibility changes together.
This replaces the separate **Move to Space** action available in 0.31.
Existing reactions stay with the memo. Comments and linked memos keep their own placement and access rules; moving one memo does not move a whole discussion.
`SPACE` memos cannot have share links. Revoke active share links before changing a memo to `SPACE`. See [Sharing](/docs/usage/sharing).
## Browse in context [#browse-in-context]
Select a Space from the sidebar switcher to scope browsing, new memo creation, statistics, filters, and attachments to that Space. Choose the main **Memos** context to browse across the memos available to you. In 26.10, switching between Timeline, [Calendar](/docs/usage/memos#calendar), [Map](/docs/usage/memos#map), and Attachments preserves both the creator and Space selection; Calendar and Map can show readable memos from several creators.
Opening a memo and returning to its collection preserves the Space and filters, so you can continue browsing where you left off.
Archived, Inbox, user profiles, and Settings remain global. Selecting a Space does not restrict these pages to that Space. The [global composer](/docs/usage/memos) remains available on authenticated routes; check its placement and visibility before saving.
[Views](/docs/usage/views) and tags still organize and filter memos within the current browsing scope. A Space feed only shows assigned memos that you can read, and excludes comment memos from the main timeline.
## Roles and authorship [#roles-and-authorship]
| Role | Responsibilities |
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
| Space User | Browse readable Space memos and contribute their own memos, comments, and reactions |
| Space Admin | The same participation rights, plus Space metadata, invitations, member roles, member removal, and Space deletion |
Apart from active instance administrators, only a memo's author can edit its content or visibility and manage its attachments, references, and share links. For an assigned memo, these actions also require active membership. Reactions belong to the user who added them. Commenting or reacting to an assigned memo requires both read access and membership in its Space.
Active instance admins can read and manage individual memos without authorship or Space membership, but are not automatically Space members. Space admins govern the Space, but also cannot edit another author's memo. A Space must retain at least one active admin: promote another member before the last admin leaves, is removed, or is archived.
## Leave or delete a Space [#leave-or-delete-a-space]
Leaving a Space or removing a member keeps their memos in place. A former member loses members-only read access. As an author, they retain authority to delete their own memos or withdraw or move them; they cannot otherwise edit memos left in the former Space. Moving to another Space requires membership there.
**Deleting a Space permanently deletes every memo directly assigned to it**, including assigned comments and the resources those memos own. It does not follow relations into another Space or into Unassigned memos. There is no Space archive or restore action; a backup is the recovery path.
Accounts with active Space memberships cannot be deleted, even through an API request with `force`. Resolve memberships first. Removing membership and deleting the Space have different effects on contributed memos, so choose the action that matches your intent.
## Related pages [#related-pages]
* [Users & Roles](/docs/admin/users-roles)
* [Reactions & Comments](/docs/usage/reactions-comments)
* [Export & Import](/docs/usage/export-import) — how Space placement is handled when moving your memos between instances
* [Upgrading to 0.31](/docs/operations/upgrade#upgrading-to-031)
---
# Tags
URL: https://usememos.com/docs/usage/tags
Tags are created directly from memo content. Write `#tagname` in ordinary Markdown text and Memos extracts it automatically. The same grammar is used by rendering, editing, filtering, statistics, and the API.
## Tag basics [#tag-basics]
```markdown
Working on the #backend API today.
This relates to #project-alpha and #development.
Meeting with #team tomorrow to discuss #roadmap.
```
Tags can contain multilingual letters, combining marks, digits, underscores, emoji, `-`, `+`, and `&`. Numeric-only tags such as `#2026` are valid. Word-internal apostrophes work in tags such as `#O’Brien` and `#team's`.
Use `/` between non-empty segments for hierarchy: `#project/backend` also contributes the ancestor tag `project`. A slash cannot start or end a tag or separate empty segments. Tag values are case-sensitive; `#Work` and `#work` remain distinct.
Tags are recognized in ordinary text, including headings and list items. Code, links, images, URLs, and other opaque Markdown contexts do not create tags. Escape a literal hash with a backslash, such as `\#not-a-tag`. Spaces and unsupported punctuation end a tag: `#release.notes` produces `release`, while `#C++` and `#R&D` remain complete tag values.
### Existing memos after upgrading [#existing-memos-after-upgrading]
0.31 does not automatically rebuild stored tag indexes. Rendering and editing use the new grammar immediately, while filters, counts, and statistics adopt it as each memo is saved again. If an older memo displays a tag but does not yet appear in its filter, save that memo again.
## Personal tag appearance [#personal-tag-appearance]
Open your user settings to assign a background color or content-blur rule to a tag. These rules are personal: each user controls how matching tags and memo content appear in their own account.
Rules accept exact tag names or anchored regular-expression patterns. For example, `project/.*` applies to every tag under that prefix. Memos validates a pattern before saving it.
When upgrading to 0.30, existing instance-level tag metadata is copied to current users during migration. Later changes are stored per user.
## Good tag habits [#good-tag-habits]
* pick a consistent case style
* avoid near-duplicate tags for the same concept
* use hyphens for multi-word tags
* prefer a small, predictable vocabulary over endless one-off tags
## Filters [#filters]
Memos also supports richer filtering beyond plain text search. Views can combine tags with memo properties.
Examples:
```txt
tag in ["work"]
tag in ["work"] && visibility == "PRIVATE"
has_incomplete_tasks
has_link
tags.exists(t, t.startsWith("project"))
```
## When tags help most [#when-tags-help-most]
* ongoing projects
* meeting notes
* recurring areas of work
* public knowledge you want to group consistently
## Related guides [#related-guides]
* use [Views](/docs/usage/views) to save filters you run often
* combine tags with [search](/docs/usage/search-archive) when browsing older memos
* align tag naming with how your team expects to browse content
* let recurring subjects become Collections with the [digital Bullet Journal guide](/docs/guides/bullet-journal)
* build a complete GTD practice with the [GTD guide](/docs/guides/getting-things-done)
* use topic tags as entry points with the [Zettelkasten guide](/docs/guides/zettelkasten), while Relations carry specific connections
---
# Views
URL: https://usememos.com/docs/usage/views
A View is a named, reusable set of memo filter conditions. Opening a View shows the memos that currently match those conditions. A View does not store copies of memos or specify a display layout such as a list or cards.
Use Views for filters you revisit, such as work items, incomplete tasks, or recent public posts.
## Upgrading existing filters [#upgrading-existing-filters]
Views replace the legacy `Shortcut` resource in 0.31. Stored filters migrate automatically. Update bookmarks to `/views` and integrations to `UserService` (`MemoView` resources) and the MCP tool `user_list_memo_views`. REST paths use `/api/users/*/views/*` in 26.10 and `/api/v1/users/*/views/*` in 0.31.
In 26.10, the built-in Tasks View is removed. Create a View with `has_task_list && has_incomplete_tasks` to keep browsing unfinished tasks.
## Create a View [#create-a-view]
Views are created and managed on the **Views** page at `/views`, which you open from the sidebar.
1. open the Views page and choose **Create**
2. give the View a clear title and optionally choose a custom icon or emoji with the icon picker
3. enter a [filter expression](#filter-expression-syntax)
4. choose **Validate** to dry-run the expression — this checks the filter without saving, so you catch typos before committing
5. choose **Save**
Title and filter are both required, and an invalid expression is rejected on save.
Views appear in the sidebar. Select one to apply its filter to your memo list; the selection also syncs to the URL, so you can bookmark it. To keep a search you tried in [Quick Find](/docs/usage/search-archive#quick-find-and-browsing-scope), copy its expression into a new View.
## Edit and delete Views [#edit-and-delete-views]
The Views page lists every View with its title and filter. Each row has a menu to:
* **Edit** — load the View back into the form to change its title, icon, or filter
* **Delete** — remove a View you no longer use, after a confirmation step
## Filter expression syntax [#filter-expression-syntax]
Views use CEL (Common Expression Language) filter expressions. A View filter must evaluate to `true` for memos you want included.
### Supported fields [#supported-fields]
| Field | Type | Example |
| ---------------------- | --------------------- | ------------------------------------------------- |
| `content` | string | `content.contains("meeting")` |
| `creator` | string | `creator == "users/1"` |
| `creator_id` | integer | `creator_id == 42` |
| `created_ts` | timestamp | `created_ts >= now - duration("24h")` |
| `updated_ts` | timestamp | `updated_ts >= timestamp("2026-01-01T00:00:00Z")` |
| `visibility` | string | `visibility == "PUBLIC"` |
| `pinned` | boolean | `pinned` |
| `tags` | string list | `"project/backend" in tags` |
| `tag` | tag-tree alias | `tag in ["work"]` |
| `has_task_list` | boolean | `has_task_list` |
| `has_link` | boolean | `has_link` |
| `has_code` | boolean | `has_code` |
| `has_incomplete_tasks` | boolean | `has_incomplete_tasks` |
| `has_location` | boolean | `has_location` |
| `space` | resource name or null | `space == "spaces/team-notes"` |
### Operators and functions [#operators-and-functions]
* comparisons: `==`, `!=`, `<`, `<=`, `>`, `>=`
* logic: `&&`, `||`, `!`, and parentheses `()`
* membership: `tag in ["work", "team"]`, `"project/backend" in tags`, `visibility in ["PUBLIC", "PROTECTED"]`
* string functions: `contains()`, `startsWith()`, `endsWith()`, and `matches()`
* collection functions: `exists()`, `all()`, `exists_one()`, and `size()`
* set functions: `sets.contains()`, `sets.intersects()`, and `sets.equivalent()`
* time values: `now`, `duration("24h")`, and `timestamp(...)`
Boolean fields can be used directly without `== true`:
```
pinned && has_incomplete_tasks
```
### Tag matching [#tag-matching]
Use `tag in [...]` when you want to match one or more tag trees:
```txt
tag in ["work"]
tag in ["project", "team"]
```
`tag in ["project"]` also matches nested tags such as `project/backend`.
Use `tags.exists()` for more specific tag patterns:
```txt
tags.exists(t, t.startsWith("archive"))
tags.exists(t, t.endsWith("/bug"))
tags.exists(t, t.contains("todo"))
```
Other collection predicates and set operations are also available:
```txt
tags.all(t, t.startsWith("work/"))
tags.exists_one(t, t.startsWith("project/"))
sets.intersects(tags, ["work", "urgent"])
sets.equivalent(tags, ["inbox"])
size(tags) == 0
```
`tags.all()` matches only non-empty tag sets. Use `size(tags) == 0` when you specifically want untagged memos.
### String matching [#string-matching]
Content matching is case-insensitive for `contains()`, `startsWith()`, and `endsWith()`:
```txt
content.contains("meeting")
content.startsWith("TODO")
content.endsWith("done")
```
Use `matches()` for regular expressions:
```txt
content.matches("v[0-9]+")
```
Regular expressions are validated before a View is saved. Keep patterns portable: SQLite, PostgreSQL, and MySQL use different regular-expression engines.
### Time-based filters [#time-based-filters]
`created_ts` and `updated_ts` are CEL timestamps. `now` is a timestamp variable, not a function. Use durations for relative windows and `timestamp()` for fixed instants or Unix epoch seconds:
```txt
created_ts >= now - duration("1h")
created_ts >= now - duration("168h")
updated_ts >= timestamp("2026-01-01T00:00:00Z")
created_ts >= timestamp(1767225600)
```
Timestamp accessors support calendar filters:
```txt
created_ts.getFullYear() == 2026
created_ts.getMonth() == 0
created_ts.getDayOfWeek() == 0
created_ts.getMonth() == now.getMonth() && created_ts.getDate() == now.getDate()
```
Months are zero-based (`0` is January), and days of the week are zero-based (`0` is Sunday). Accessors are evaluated in UTC for SQLite and PostgreSQL; MySQL reads timestamp columns in the database session time zone.
## Example Views [#example-views]
| Name | Filter | | |
| ------------------ | ------------------------------------------------------------------------------------- | - | ------------ |
| Work TODOs | `tag in ["work"] && has_incomplete_tasks` | | |
| Public posts | `visibility == "PUBLIC"` | | |
| Posts with links | `has_link` | | |
| Recent notes | `created_ts >= now - duration("168h")` | | |
| Team updates | `tag in ["team"] && visibility == "PROTECTED"` | | |
| Unfinished tasks | `has_task_list && has_incomplete_tasks` | | |
| Pinned references | \`pinned && (has\_link | | has\_code)\` |
| Active projects | `tags.exists(t, t.startsWith("project")) && !tags.exists(t, t.startsWith("archive"))` | | |
| Untagged | `size(tags) == 0` | | |
| With location | `has_location` | | |
| Unassigned | `space == null` | | |
| Members-only notes | `visibility == "SPACE"` | | |
| One Space | `space == "spaces/team-notes"` | | |
| Release notes | `content.matches("v[0-9]+\\.[0-9]+")` | | |
## Good View patterns [#good-view-patterns]
* incomplete tasks for one project
* pinned or high-signal memos
* public notes you review before sharing
* recent memos from a time window
* resource collections with links or attachments
## Management tips [#management-tips]
* keep names short and obvious
* delete stale Views you no longer use
* update filters when your tag vocabulary changes
* prefer a few durable Views over dozens of narrow one-off views
## Limits to remember [#limits-to-remember]
Views are personal filters, not shared Space settings. They apply within the current browsing scope and never grant access to additional memos. If a Space filter conflicts with the selected Space, it can return no results. Switch to the main Memos context when you want to filter across available Spaces. Use the actual stable Space ID in a `spaces/...` filter; `team-notes` above is an example custom ID.
Memos supports a deliberate subset of CEL that can be translated consistently to SQLite, MySQL, and PostgreSQL. Use the **Validate** action before saving; it reports unsupported fields, type mismatches, invalid regular expressions, and operations that cannot be translated.
## Related guides [#related-guides]
* [Use Memos as a Digital Bullet Journal](/docs/guides/bullet-journal) with recent-log and unfinished-task filters.
* [Use Memos for GTD](/docs/guides/getting-things-done) with action, waiting, project, and review filters.
* [Build a Zettelkasten in Memos](/docs/guides/zettelkasten) with active-question and recent-memo filters.
---
# Writing Markdown
URL: https://usememos.com/docs/usage/writing-markdown
Memos stores memo content as plain text and renders it with Markdown. That keeps
content portable while still supporting rich formatting such as checklists,
tables, code blocks, links, and footnotes.
The editor keeps the Markdown source editable while decorating recognized
syntax. Use the formatting toolbar or keyboard shortcuts for common formatting,
and press `Tab` or `Shift+Tab` to indent or outdent list items.
## Core syntax [#core-syntax]
````markdown
# Heading 1
## Heading 2
**bold**
_italic_
~~strikethrough~~
- [ ] open task
- [x] completed task
```go
fmt.Println("hello from memos")
```
````
## Common patterns [#common-patterns]
* headings for longer notes
* task lists for planning
* fenced code blocks for snippets
* blockquotes for references
* tables when structure matters
* tags like `#project-x` inline in the memo body
## Inline images [#inline-images]
Place the cursor where the image belongs, then upload, paste, drop an image, or choose an existing attachment. The editor inserts its Markdown image reference into the text. You can mix prose and images in the order you need.
Retry a failed inline upload from the draft before publishing. See [Attachments](/docs/usage/attachments) for draft restoration, file access, and optional media metadata.
## Math and currency [#math-and-currency]
Ordinary currency amounts should remain text. Use supported explicit math delimiters for formulas; 0.31 no longer treats ordinary currency as inline math.
## Code blocks [#code-blocks]
Use fenced code blocks with a language identifier when useful:
````markdown
```ts
const visible = memo.visibility === "PUBLIC";
```
````
## Checklists [#checklists]
Task lists are especially useful in Memos because they turn ordinary notes into lightweight work queues:
```markdown
- [ ] Draft release notes
- [ ] Review production config
- [x] Create backup
```
## Footnotes [#footnotes]
Add a footnote reference in the text and define it elsewhere in the memo:
```markdown
This statement needs context.[^context]
[^context]: Supporting details can live at the end of the memo.
```
## Writing tips [#writing-tips]
* keep one memo focused on one topic or update
* use headings in longer memos so they remain readable
* prefer plain Markdown over screenshots of text
* use tags consistently so search and Views stay useful
* choose visibility carefully before sharing externally
* use code fences and blockquotes to make technical notes easier to scan later
## Related guides [#related-guides]
* [Use Memos as a Digital Bullet Journal](/docs/guides/bullet-journal) to rapid-log tasks, events, and notes with ordinary prose and Markdown checkboxes.
* [Build a Zettelkasten in Memos](/docs/guides/zettelkasten) to develop focused Markdown memos into connected ideas.
---
# 20k GitHub Stars in Just 2 Years 🤩
URL: https://usememos.com/blog/20k-github-stars-in-2-years
In early November 2023, we achieved a major milestone - Memos had reached 20,000 stars on GitHub. This achievement is a result of our continuous efforts and the support of our community. In this article, we'll look back at the journey of the past two years, dive into what led to this achievement, and see what's in store for the future.
## What We've Done in Two Years [#what-weve-done-in-two-years]
Over the past two years, Memos is more than just a note-taking service; it's an entire ecosystem designed to meet the evolving needs of its users. And it has incorporated a diverse range of enhancements:
* **Multilingual Support**: Memos now supports over 20 languages, making it accessible to a diverse global audience.
* **Flexible Database Options**: You have the choice between using the built-in SQLite for a single-file setup or opting for the popular MySQL, providing you with more control and versatility in managing your data.
* **Impressive Features**: We've introduced a range of amazing features, including support for AWS S3 storage, Single Sign-On (SSO), and integration with Telegram Bot. These enhancements have made Memos even more powerful and advanced.
* **Simplified Note-Taking**: Memos primarily focuses on plain text note-taking while also providing support for common markdown formatting for those who like to stylize their notes.
* **Enhancing Social Interaction**: We've boosted the social aspect by introducing personal profiles, memo comments and RSS feeds. This allows you to share your greate ideas with others simply.
* **Robust Community**: The Memos community offers a range of services, including mobile apps, browser extensions, and integration with other software applications. This enhances Memos' user-friendliness and usability.
## Letting the Data Tell the Story [#letting-the-data-tell-the-story]
The statistics and data surrounding Memos serve as a compelling testament to the incredible journey this project has embarked on. They paint a vivid picture of its progress and success. These numbers aren't just figures; they are the milestones that reflect the dedication, hard work, and passion of the Memos community.
* **Over 800,000 Downloads**: The Docker image of Memos has been downloaded over 800,000 times, underlining its broad popularity within the community.
* **53 Releases in Two Years**: Memos has been released 53 versions, with an impressive average release interval of just 13.77 days. This consistent improvement ensures that this project stays up-to-date.
* **Contributions from 150+ Developers**: Over 150+ contributors have actively participated in the project, resulting in over 1,200+ pull requests. Memos is not just a project; it's a collective effort.
```
Replace `` with the URL of the GitHub repository you created in Step 1.
### Step 3: Syncing Your Data [#step-3-syncing-your-data]
Now you're set up to sync your data between devices. Here's how:
* **Uploading Data to GitHub:**
Whenever you have new data or updates on one device that you want to access on another, use the following commands:
```shell
git add .
git commit -m "Your commit message"
git push origin main
```
* **Downloading Data on Another Device:**
When you switch to another device, use this command to fetch the latest data from your GitHub repository:
```shell
git pull origin main
```
## Benefits and Considerations [#benefits-and-considerations]
* **Data Access Anywhere**: With your data on GitHub, you can access it from any device with an internet connection.
* **Version Control**: GitHub provides a version history, so you can always go back to previous versions of your files.
* **Data Security**: As a private repository, your data is secure and accessible only by you.
* **Collaboration**: In the future, if you need to collaborate with others, GitHub's collaboration features are readily available.
In summary, GitHub is a versatile platform that goes beyond code collaboration. It's a valuable resource for everyday users who want to keep their data in sync across multiple devices. Whether you need to access work documents, personal notes, or any other data, GitHub simplifies the process, ensuring your information is at your fingertips, no matter where you are or which device you're using.
---
# Syncing Data Across My MacBooks with iCloud
URL: https://usememos.com/blog/syncing-data-with-icloud
In all honesty, I don't have a suitable cloud service for deploying memos, but I do have two trusty MacBooks - a MacBook Air in home and a MacBook Pro in company. Each served its unique role, but the problem was keeping data in sync between them.
The solution began with the realization that the Memos' startup command could hold the key. The recommand command looked like this:
```shell
docker run -d --name memos -p 5230:5230 -v ~/.memos/:/var/opt/memos neosmemo/memos:stable
```
I had an idea - what if I replaced `~/.memos` with a folder in iCloud? This simple change held the promise of realizing multi-device data sharing, and potentially, it meant I could set up a memos instance on my work MacBook Pro without relying on external cloud servers. It was a challenge worth taking, so let's explore how I embarked on this endeavor.
## The Experiment [#the-experiment]
### Step 1: Creating an iCloud Shared Folder [#step-1-creating-an-icloud-shared-folder]
The journey started with a visit to my MacBook Air, where I aimed to create a shared space in iCloud that both my MacBooks could access. Here's how I did it:
1. I opened Finder and ventured into iCloud Drive.
2. A right-click later, I had a brand new folder in iCloud, aptly named `memos` in **Documents**.
3. Then came the sharing. A few more clicks, and I'd selected my work email to share the folder with, granting my MacBook Pro access.
## New Contributors [#new-contributors]
Welcome to our new contributors who made their first contributions in this release:
* @nicolasluckie - Accessible confirmation dialogs (#5111)
* @asttool - Concurrent operations improvements (#5162)
* @bmitchinson - Manual location input (#5152)
* @simoncarrignon - Bug fixes and improvements
* @FloDwld - Enhancement contributions
***
**Full Changelog**: [v0.25.1...v0.25.2](https://github.com/usememos/memos/compare/v0.25.1...v0.25.2)
---
# Release v0.25.3
URL: https://usememos.com/changelog/0-25-3
This release introduces a distraction-free focus mode for writing, enhanced attachment management capabilities, and improved markdown parsing with CommonMark/GFM compliance.
## New Features [#new-features]
### Writing Experience [#writing-experience]
* **Focus mode** - New writing mode that minimizes distractions for focused memo creation
* **Improved markdown list auto-completion** - Fixed auto-completion to properly create new lines (#5238)
### Attachment Management [#attachment-management]
* **Delete unused attachments** - Ability to delete unused attachments to reclaim storage space (#5272)
* **Attachments page pagination** - Load more button and pagination added for better navigation (#5258)
### Theme System [#theme-system]
* **System theme sync** - Theme now syncs with system preferences automatically (#5231)
## Improvements [#improvements]
### Technical Enhancements [#technical-enhancements]
* **CommonMark and GFM compliance** - Markdown parser/renderer now adheres to CommonMark and GFM specifications for enhanced compatibility
* **Memory optimization** - Prevented memory exhaustion during thumbnail generation processes
## Bug Fixes [#bug-fixes]
### User Interface [#user-interface]
* **Tag sidebar improvements** - Resolved tag sidebar filtering and reactivity issues for proper sidebar categorization
* **Markdown list formatting** - Corrected markdown list auto-completion behavior
***
**Full Changelog**: [v0.25.2...v0.25.3](https://github.com/usememos/memos/compare/v0.25.2...v0.25.3)
---
# Release v0.26.0
URL: https://usememos.com/changelog/0-26-0
> This version includes significant changes to authentication and the database. Please backup your data before upgrading. Learn more in [https://github.com/usememos/memos/compare/v0.25.3...v0.26.0](https://github.com/usememos/memos/compare/v0.25.3...v0.26.0).
## Major Features [#major-features]
* feat: refresh token rotation with sliding window sessions for enhanced authentication security
* feat: streaming for video/audio files to fix memory exhaustion issues
* feat: EXIF metadata stripping for image uploads (privacy enhancement)
* feat: role refactor - HOST role migrated to ADMIN for clearer terminology
* feat: React Query migration for improved frontend state management and caching
* feat: memo map in user profile with Google Maps integration
* feat: HDR image and video support
* feat: midnight theme option
## Other Improvements [#other-improvements]
* feat: new locale - Galician (gl, gl\_ES)
* feat: iframe support for embedded videos in markdown content
* feat: enhanced attachment handling with MIME type validation
* feat: glassmorphism map controls with Google Maps integration
* feat: slash commands tooltip to InsertMenu
* refactor: migrate to connect-rpc
* refactor: user auth improvements
* refactor: consolidate MemoEditor components
* refactor: remove legacy session cookie authentication
* style: improve code block styling and formatting
* perf: optimize memory usage for statistics and image processing
* perf: optimize backend tests with parallel execution
## Bug Fixes [#bug-fixes]
* fix: add access control checks for attachments, comments, and reactions
* fix: math render issues
* fix: correct calendar header month parsing
* fix: editor auto-scroll and Safari IME handling
* fix: prevent browser cache from serving stale memo data
* fix: return Unauthenticated instead of PermissionDenied on token expiration
* fix: apply theme and locale changes immediately on login screen
* fix: allow public memo API access without authentication
* fix: KaTeX math rendering with underscores
* fix: ensure attachments are properly linked when creating memos
* fix: improve text contrast in default dark mode
* fix: disable setext header syntax
* fix: todo command does nothing
* fix: clean up memo\_relation and attachments when deleting memo
* fix: allow guests to view public memo comments
## Localization [#localization]
* Updated British English, Chinese, Korean, German, French, Polish, and Italian translations
**Full Changelog**: [https://github.com/usememos/memos/compare/v0.25.3...v0.26.0](https://github.com/usememos/memos/compare/v0.25.3...v0.26.0)
---
# Release v0.26.1
URL: https://usememos.com/changelog/0-26-1
> This is a patch release focused on stability and upgrade reliability.
## Bug Fixes [#bug-fixes]
* fix: avoid inbox crashes by gracefully handling deleted memos in the activity service
* fix: correctly parse environment variables that contain underscores
* fix: return consistent gRPC-style errors instead of Echo HTTP errors
* fix: video attachment handling
* fix: prevent 401 errors on window focus when an access token expires
* fix: ensure the shortcut edit button opens edit mode instead of create mode
* fix: block `Ctrl+Enter` from saving while editor content is still loading
* fix: nested task list rendering and checkbox interactions
* fix: make OAuth PKCE optional during sign-in
* fix: prevent private memos from disappearing during token refresh
* fix: add Unicode case-insensitive search support for SQLite
* fix: correct handling of pasted files in the memo editor
* fix: restore the access token creation flow
* fix: preserve tag case when extracting Markdown tags
* fix: auto-fix permission issues when upgrading from v0.25.3 to v0.26.0
**Full Changelog**: [https://github.com/usememos/memos/compare/v0.26.0...v0.26.1](https://github.com/usememos/memos/compare/v0.26.0...v0.26.1)
---
# Release v0.26.2
URL: https://usememos.com/changelog/0-26-2
> This is a patch release focused on stability, security, and usability improvements.
## Notable Changes [#notable-changes]
* feat: add ampersand support in tags for compound tag functionality
* feat: replace EditableTimestamp with a timestamp popover component
* feat: extend calendar year picker navigation back to 1970
* feat: improve PAT PostgreSQL handling with better error management
## Bug Fixes [#bug-fixes]
* fix: spurious logout on page reload with expired access token
* fix: cross-tab session loss via localStorage persistence improvements
* fix: calendar navigation and month label language support
* fix: memo visibility defaults not correctly applied
* fix: query invalidation for comment reactions and deletions
* fix: SSRF vulnerability in webhook dispatcher
* fix: explore page privacy filtering for tags
* fix: task list item scoping to memo containers
* fix: attachment and memo deletion resilience when local files are missing
* fix: memo batch attachment truncation
* fix: MemoEditor layout and styling corrections
* fix: redirect logic for expired sessions
* fix: eliminate redundant fetch operations when opening inline memo editor
**Full Changelog**: [https://github.com/usememos/memos/compare/v0.26.1...v0.26.2](https://github.com/usememos/memos/compare/v0.26.1...v0.26.2)
---
# Release v0.27.0
URL: https://usememos.com/changelog/0-27-0
> This release adds real-time updates, richer memo authoring, AI transcription, and a new MCP integration. It also includes security hardening, attachment improvements, and many editor and API fixes.
## New Features [#new-features]
### Real-Time and Memo Creation [#real-time-and-memo-creation]
* **Live refresh** - Memo updates now arrive through Server-Sent Events, with a visual indicator for the connection state.
* **Voice notes** - The memo composer can record voice notes with a compact waveform panel.
* **AI transcription** - Audio transcription now supports instance-level providers, bring-your-own-key providers, and Gemini.
* **MCP integration** - The new MCP server supports PAT authentication, a standard protocol structure, expanded tools, and safer tool exposure.
* **Memo mentions** - Memos can mention other memos, render those mentions, and send related notifications.
* **Memo sharing** - Private memos can be shared with links, and memo detail pages can share images directly.
### Reading and Navigation [#reading-and-navigation]
* **Detail outline** - Memo detail pages now include outline navigation in the sidebar.
* **Automatic titles** - The first H1 heading can be extracted into the memo title property.
* **Inline previews** - Memo lists can show comment previews, and memo previews understand comment metadata.
* **Media browsing** - Image previews support arrow-key navigation, Live Photo playback is improved, audio attachments render inline, and SVG attachments can be previewed.
### Tags and Metadata [#tags-and-metadata]
* **Tag metadata controls** - Instance admins and users can configure tag metadata, including canonical tags and blur rules.
* **Anchored matching** - Tag setting keys are treated as anchored regular expressions for more predictable matching.
* **Better snippets** - Memo snippets include plain URLs and tags, and tag parsing now preserves emoji variation selectors.
## Admin and Security [#admin-and-security]
* **Webhook controls** - Memos can dispatch webhooks for comment creation, attachment changes, and relation changes.
* **Private webhook opt-in** - The `--allow-private-webhooks` flag allows intentionally sending webhooks to private targets.
* **Storage default** - The default storage type is now local filesystem.
* **Notification transport** - Instance settings now include notification transport configuration.
* **Sensitive settings** - Credentials are write-only, sensitive settings are restricted to admins, and user emails are visible only to the user and admins.
* **Access hardening** - Archived memos are restricted to their creator, memo content iframes and HTML sanitization are hardened, local attachment uploads cannot overwrite files, and Unix socket permissions are reduced from `755` to `660`.
## Authentication and API Reliability [#authentication-and-api-reliability]
* **Identity resources** - Identity provider resource names now use UIDs, and user resource names now use usernames.
* **Token refresh** - Access token refresh is more reliable in the web app and across browser tabs.
* **Session recovery** - Sessions can recover from the refresh cookie when local storage is empty.
* **Public routing** - Unauthenticated users are redirected to `/explore` when public visibility is enabled.
* **API resilience** - Memo conversion tolerates missing related users, legacy installations with empty schema versions are detected, MySQL custom timestamps are handled correctly, and CEL filter syntax is enforced.
## User Interface Fixes [#user-interface-fixes]
* **Editor reliability** - Drafts are preserved across tab suspension and editor remounts, `Cmd+Enter` only saves the active editor, and newly linked memos appear while editing memos with attachments.
* **Comment layout** - Comments span the full memo detail width, and the comment editor appears above the comment list.
* **Markdown rendering** - KaTeX and Mermaid errors are handled more gracefully, Markdown image `height` and `width` attributes are supported, and memo content prop leaks are prevented.
* **Navigation polish** - Selecting a shortcut clears the content search filter, focus mode no longer resets editor height, and memo detail cache refreshes after saving.
* **Visual polish** - Metadata styling is unified across memo views and the editor, map styling is refined for dark mode, and the HTML `lang` attribute syncs with the active locale.
## Performance and Maintenance [#performance-and-maintenance]
* **Faster memo lists** - Memo relations are batch loaded when listing memos.
* **Lower memory pressure** - Backend paths use less memory.
* **SSE reliability** - SSE broadcasts avoid duplicate comment events, and clients close cleanly during server shutdown.
* **Deployment resilience** - Chunk load errors after redeployment trigger automatic reloads.
* **Project maintenance** - Sitemap and robots routes were restored, and installer compatibility and documentation were improved.
**Full Changelog**: [v0.26.2...v0.27.0](https://github.com/usememos/memos/compare/v0.26.2...v0.27.0)
---
# Release v0.27.1
URL: https://usememos.com/changelog/0-27-1
> This patch release fixes user resource naming edge cases introduced around identity provider handling and ensures release artifacts carry the correct build version.
## Bug Fixes [#bug-fixes]
* **Mixed-case user names** - User resource names now support mixed-case values.
* **Identity provider subjects** - User resource names can now be UUIDv4 values from identity provider `sub` claims.
* **Release artifacts** - Build versions are now injected into release artifacts.
**Full Changelog**: [v0.27.0...v0.27.1](https://github.com/usememos/memos/compare/v0.27.0...v0.27.1)
---
# Release v0.28.0
URL: https://usememos.com/changelog/0-28-0
> This release improves SSO account handling by linking external provider identities to local Memos users instead of treating provider identifiers as local usernames. It also refreshes account and SSO management, adds memo time display controls, and includes several authentication and editor fixes.
## Breaking Change [#breaking-change]
* **Existing SSO users must link their identity again** - If you previously signed in through SSO, sign in once with your username and password after upgrading, then go to Account Settings to link your SSO identity. After the identity is linked, future SSO sign-ins will resolve to your existing Memos account.
## New Features [#new-features]
### SSO User Identity Linkage [#sso-user-identity-linkage]
* **Linked SSO identities** - Memos now stores external SSO subjects in a dedicated `user_identity` model and links them to local users.
* **Stable local usernames** - SSO sign-ins now resolve users through the identity linkage table, so external provider IDs no longer need to become local usernames.
* **Cleaner first-login flow** - New SSO users get usernames derived from profile data, with collision handling and cleanup for concurrent first-login races.
* **Linked identity management** - Account settings now include a clearer linked identity view so users can understand which SSO accounts are connected.
### Account and SSO Management [#account-and-sso-management]
* **Redesigned SSO settings** - SSO providers, linked identities, and members now use a clearer information-flow layout.
* **Improved provider editing** - The SSO create and update dialog is grouped into clearer sections with better create-versus-edit behavior.
* **Safer account deletion** - Account deletion moved into a dedicated danger area, and user deletion now cleans up related database resources transactionally before reporting attachment storage cleanup failures.
* **More reliable OAuth userinfo** - OAuth userinfo requests now propagate context, use timeout handling, and report non-2xx responses more clearly.
### Memo Display Controls [#memo-display-controls]
* **Shown time preference** - Memo lists can now use either created time or updated time as the displayed and ordered time basis, with created time remaining the default.
## Bug Fixes [#bug-fixes]
* **Authorization hardening** - Archived users are rejected in access-token flows, memo ownership is required before attachment changes, and Connect CORS origin checks are stricter.
* **Username validation** - Writable username validation is separated from legacy resource-name lookup, preserving legacy username auth flows while tightening new username changes.
* **Memo list performance** - List memo queries do less overhead.
* **Task checkbox state** - Task checkbox state is preserved in the web app.
* **Dropdown scrolling** - Dropdown menus no longer force scroll disappearance through modal behavior.
* **Markdown lists** - Mixed task and bullet lists are split more predictably.
**Full Changelog**: [v0.27.1...v0.28.0](https://github.com/usememos/memos/compare/v0.27.1...v0.28.0)
---
# Release v0.29.0
URL: https://usememos.com/changelog/0-29-0
> This release adds richer link previews, notification email settings, shortcut and memo workflow improvements, and a set of security, media, and editor fixes. It also adds new instance statistics APIs and performance improvements for the initial screen.
## New Features [#new-features]
### Link Previews and Metadata [#link-previews-and-metadata]
* **Link metadata APIs** - Memos now includes endpoints for fetching and batching metadata for links attached to memos.
* **Rendered link cards** - The web app can render metadata cards for shared links, making memo references easier to scan.
* **DNS rebinding protection** - Link metadata fetching now rejects DNS rebinding attempts.
### Notification and Transcription Settings [#notification-and-transcription-settings]
* **SMTP email settings** - Instance notification settings now include SMTP email configuration.
* **Email test endpoint** - Admins can test notification email settings through the instance API.
* **Explicit speech-to-text settings** - Transcription settings now expose provider, model, and prompt configuration.
### Memo and Workspace Improvements [#memo-and-workspace-improvements]
* **Task list quick actions** - Memos with task lists now support faster task interactions.
* **Calendar-aware memo creation** - Creating a memo from the calendar uses the selected calendar date.
* **Dedicated shortcuts page** - Shortcut management is available from a dedicated page.
* **About page and placeholder refresh** - The app includes a refreshed about page and new placeholder states.
### Administration and Statistics [#administration-and-statistics]
* **Instance resource statistics** - Admin instance stats now include resource statistics.
* **Filtered all-user stats** - All-user statistics can be filtered for more focused administration views.
* **Configurable log level** - The server now accepts a `--log-level` flag.
## Bug Fixes [#bug-fixes]
* **Attachment ownership enforcement** - Memo updates now enforce attachment ownership.
* **Comment visibility** - Comments now respect parent memo visibility.
* **User response privacy** - User list responses omit internal settings.
* **Memo creation events** - Creating memos with attachments no longer emits an extra update event.
* **Avatar sync** - Profile avatar changes sync immediately after update.
* **Release media handling** - HDR image metadata is preserved in thumbnails, and motion media payloads are preserved through S3 presigned uploads.
* **Editor and markdown polish** - URL paste wrapping and task-list alignment are improved.
* **Static cache and sitemap paths** - Frontend static cache headers and public memo sitemap paths are corrected.
* **SSE refresh behavior** - Initial SSE responses stream correctly and refresh tokens are handled.
## Performance Improvements [#performance-improvements]
* **Initial screen loading** - Heavy first-screen dependencies are lazy loaded.
**Full Changelog**: [v0.28.0...v0.29.0](https://github.com/usememos/memos/compare/v0.28.0...v0.29.0)
---
# Release v0.29.1
URL: https://usememos.com/changelog/0-29-1
> This patch release tightens up memo rendering and media previews. It improves task-list layout in markdown, reads standard meta description tags for link previews, and restores video attachment posters on mobile devices.
## Bug Fixes [#bug-fixes]
* **Markdown task lists** - Task item content now stays in a single grid column, keeping checkbox rows aligned with the rest of the memo body.
* **Link preview descriptions** - Link metadata parsing now supports `)` instead of comparing time fields with bare epoch values.
* **New MCP endpoint and tool names** - The MCP server is now a stateless, tools-only endpoint generated from the OpenAPI schema. Clients must use `/mcp` and the new service-prefixed tool names. The previous prompts, resources, tool-filtering headers, route aliases, and unprefixed tool names have been removed.
## New Features [#new-features]
### Markdown Editing [#markdown-editing]
* **Decorated-source editor** - The editor has been rebuilt with CodeMirror 6, preserving Markdown verbatim while styling headings, formatting, tags, and mentions in place.
* **Formatting toolbar** - A toggleable toolbar provides controls for headings, lists, task lists, code blocks, bold, italic, strikethrough, and inline code.
* **Smarter authoring** - Tag completion and list indentation make it faster to write and organize memos.
* **GFM footnotes** - Markdown rendering now supports GitHub Flavored Markdown footnotes with footnote navigation.
### MCP and API Tools [#mcp-and-api-tools]
* **OpenAPI-driven MCP server** - The hand-written MCP implementation has been replaced by a curated tool surface generated from the public API schema.
* **Expanded operations** - MCP tools cover memos, comments, relations, reactions, shortcuts, identities, and attachments, including attachment uploads.
* **Shared authorization** - MCP reuses the public API's authentication and authorization behavior for more consistent access control.
### Memo Feed Customization [#memo-feed-customization]
* **Flexible columns** - Memo feeds support one, two, three, or automatically fitted columns, with balanced layouts as cards resize.
* **Persisted display preferences** - Column count, compact mode, and link preview settings are saved between visits.
* **Predictable memo placement** - Newly created memos remain easy to find above pinned content.
* **Full content by default** - Compact rendering is now opt-in for single-column feeds.
### Webhooks and Deployment [#webhooks-and-deployment]
* **Signed webhooks** - Standard Webhooks HMAC-SHA256 secrets can be generated, revealed, and used to verify webhook payloads.
* **Webhook management** - Existing webhooks can be edited, and the interface shows whether signing is configured.
* **File-backed settings** - Identity providers and supported instance settings can be supplied as validated JSON files under `/etc/secrets`.
* **Protected runtime overrides** - File-backed settings cannot be changed through the UI or API until their files are removed.
* **Self-signed S3 support** - S3-compatible storage can use the `insecure_skip_tls_verify` option when connecting with self-signed certificates.
### Filters, Tags, and Localization [#filters-tags-and-localization]
* **More powerful CEL shortcuts** - Filters now support string matching, regular expressions, collection predicates, timestamp accessors, set operations, and an untagged-memos example.
* **Per-user tag settings** - Tag colors and content-blur rules are now user-specific. Existing instance tag settings are copied to current users during migration.
* **Searchable locale picker** - The locale selector is easier to navigate, European locale coverage has expanded, and missing Japanese and Simplified Chinese translations are complete.
## Improvements and Bug Fixes [#improvements-and-bug-fixes]
### Authentication and Security [#authentication-and-security]
* **More reliable SSO setup** - SSO option loading is more stable, and OAuth client authentication can be detected automatically.
* **Clearer instance setup state** - Setup now distinguishes new instances from populated instances that no longer have an administrator.
* **Cross-origin bearer authentication** - Cross-origin API requests work with bearer tokens while cookie authentication remains restricted to same-origin requests.
* **Consistent user pagination** - `ListUsers` now returns predictable paginated results.
### Editor and Memo Reliability [#editor-and-memo-reliability]
* **Editor polish** - Formatting toggles, keyboard shortcuts, file paste and drop handling, focus-mode layout, empty-space caret behavior, and CodeMirror spacing are improved.
* **Persistent task expansion** - Expanded task-list state is preserved.
* **Complete comment loading** - Memo detail views load every page of comments.
* **Richer webhook payloads** - Comment webhook events include the parent memo relation.
### Tags and Interface [#tags-and-interface]
* **More accurate tag parsing** - Tags inside links are ignored, literal tags can be escaped with a backslash, and tag names support Unicode combining marks.
* **Refreshed account pages** - Sign-in, sign-up, and About pages have updated layouts, with common controls aligned across the app.
* **Improved loading feedback** - Mismatched memo skeletons have been replaced by a delayed spinner.
* **Mobile and location polish** - Mobile control spacing is improved, and long location labels are truncated without hiding the full address.
* **Container startup fix** - The container entrypoint no longer restarts indefinitely when `MEMOS_UID=0`.
**Full Changelog**: [v0.29.1...v0.30.0-rc.1](https://github.com/usememos/memos/compare/v0.29.1...v0.30.0-rc.1)
---
# Release v0.30.0-rc.2
URL: https://usememos.com/changelog/0-30-0-rc-2
> This release candidate introduces the Memos Web Clipper, redesigns memo details and settings, and makes feeds and Explore faster. It also refreshes the demo experience and improves API compatibility, error messages, and interface polish.
## New Features [#new-features]
### Memos Web Clipper [#memos-web-clipper]
* **Capture from the browser** - Save pages, selected text, and images as Markdown directly to your Memos instance.
* **Review before saving** - Edit each clip, choose its visibility, and confirm exactly what will be added to Memos.
* **Custom Markdown templates** - Control how page content, titles, URLs, descriptions, and default tags are arranged in saved memos.
* **Chrome and Firefox support** - Install the extension from the [Chrome Web Store](https://chromewebstore.google.com/detail/memos-web-clipper/nebaoebnljalfegiidibihhkebeiklbl) or [Firefox Add-ons](https://addons.mozilla.org/en-US/firefox/addon/memos-web-clipper/). The source and setup details are available in the [Memos Web Clipper repository](https://github.com/usememos/web-clipper).
### Memo Details and Navigation [#memo-details-and-navigation]
* **Redesigned detail sidebar** - Memo details now use a property rail with quick actions, editable visibility, metadata, attachments, relations, and a scroll-aware outline.
* **Restored feed position** - Returning to a feed after viewing another page restores the previous scroll position, making it easier to continue where you left off.
### Settings and Access Tokens [#settings-and-access-tokens]
* **Refreshed settings navigation** - Settings are reorganized for clearer navigation across account and instance options.
* **Practical access-token guidance** - The access-token page now includes setup instructions, a copyable API example, security notes, and last-used timestamps.
* **Web Clipper discovery** - The About page and project documentation now link to the Memos Web Clipper.
## Performance Improvements [#performance-improvements]
* **Faster initial loading** - Fingerprinted assets are cached more effectively, while media and rich renderers are deferred until needed.
* **Viewport-aware feeds** - Feed content near the viewport is prioritized to reduce initial browser work.
* **Shared data lookups** - User and memo lookups are reused across creators, reactions, comments, mentions, and relations to reduce duplicate requests and improve Explore performance.
## Improvements and Bug Fixes [#improvements-and-bug-fixes]
### Demo Experience [#demo-experience]
* **More representative sample data** - Demo memos now showcase nested tags, references, comments, mentions, reactions, locations, attachments, and rich Markdown across public and protected content.
### API Compatibility and Errors [#api-compatibility-and-errors]
* **AIP-aligned resources** - New resource IDs and annotations follow AIP conventions while remaining compatible with legacy UUID-based identifiers.
* **Correct user-stat names** - User statistic resources now return canonical resource names.
* **Cleaner error messages** - User-facing errors no longer expose internal RPC prefixes.
### Interface Polish [#interface-polish]
* **Radio-group alignment** - Selection indicators are correctly aligned with their controls.
* **Tooltip arrows** - Tooltip arrows now sit outside their content panels for cleaner positioning.
**Full Changelog**: [v0.30.0-rc.1...v0.30.0-rc.2](https://github.com/usememos/memos/compare/v0.30.0-rc.1...v0.30.0-rc.2)
---
# Release v0.31.0
URL: https://usememos.com/changelog/0-31-0
> Memos 0.31 brings shared Spaces, Calendar and Map pages, and personal export and import. It also improves writing, search, attachments, and navigation.
## Upgrade notes [#upgrade-notes]
* **Administrator access** - Active instance administrators can read and manage individual memos, including private and Space-only memos, without being the author or a Space member. Collection listings still filter by audience, and administrators do not automatically join Spaces.
* **Views and API clients** - Existing Shortcuts migrate to Views. Integrations using the Shortcut API need to switch to the `UserService` View operations at `/api/v1/users/{user}/views`. The reaction API no longer accepts `contentId`; reactions belong to their memo.
* **Account emails** - Email is optional, but addresses are trimmed, lowercased, and unique within an instance. The upgrade clears invalid addresses and retains duplicate addresses only on the oldest account. Affected usernames appear in server logs.
* **RSS removal** - RSS is no longer supported, and existing feed URLs stop serving feeds.
## New features [#new-features]
### Spaces, Calendar, and Map [#spaces-calendar-and-map]
* **Shared Spaces** - Organize memos with other people, receive invitations in Inbox, move memos between Spaces, and choose custom icons or emoji. Space-only memos are visible to active members, with the administrator access described above.
* **Calendar** - Browse memos by month, open a date to read its entries, and write a memo for that day.
* **Map** - Explore memos with location data on a dedicated Map page.
### Views and search [#views-and-search]
* **Reusable filters** - Save filters as Views and give them custom icons.
* **More precise search** - Filter by Space or location, find memos outside any Space, and use expressions in Quick Find.
* **Highlighted matches** - See matching text highlighted within memo content.
### Export, import, and attachments [#export-import-and-attachments]
* **Move between instances** - Use Settings → Export & Import to download and import Memos Export Format ZIP files. Personal exports contain archived memos, comments you wrote, and attachment files. They exclude instance settings and other users' data. Older exports remain importable.
* **Flexible storage** - Configure multiple named attachment storage backends and check your storage usage in account settings.
* **Attachment uploads** - Upload files in smaller chunks and insert attachment images into memo content.
### Writing and navigation [#writing-and-navigation]
* **Faster capture** - Create memos from the sidebar and format Markdown with keyboard shortcuts.
* **Adjustable sidebar** - Resize the sidebar on desktop.
* **Preserved context** - Keep your Space and filters when opening a memo and returning to the previous page.
## Improvements and fixes [#improvements-and-fixes]
* **Editor input** - Improved IME and Windows emoji input, restored mobile text assistance, fixed pasted attachments and timestamp edits, and expanded tag autocomplete.
* **Markdown** - Improved tag recognition, fixed currency being parsed as inline math and numbered task-list toggles, and enabled telephone and SMS links.
* **Maps and media** - Restored OpenStreetMap tiles without an API key, fixed leaving Map after a WebGL failure, improved HEIC/HEIF detection, and added 0.5× and 0.75× audio playback.
* **Interface and languages** - Refined memo navigation and comment menus, fixed focus-mode and right-to-left layouts, and aligned the installed app's status bar with dark mode. Added Azerbaijani and Hebrew and updated translations.
## Administration and integrations [#administration-and-integrations]
* **Security and reliability** - Added rate limits and stricter request, image-processing, and import limits. Strengthened remote-fetch validation, prevented S3 object-key collisions, and fixed attachment cleanup.
* **Sessions and files** - Changing your password signs out your other sessions. An administrator password reset signs out all sessions for that account. S3 attachments use authenticated file routes.
* **Instance access** - Public/private access mode is stored separately from the instance URL.
* **MCP and CLI** - Added Space operations and corrected MCP tool schemas. Fixed scheduled-job day matching and added `-V` and `--version` CLI options.
**Release**: [v0.31.0 on GitHub](https://github.com/usememos/memos/releases/tag/v0.31.0)
**Full changelog**: [v0.30.0...v0.31.0](https://github.com/usememos/memos/compare/v0.30.0...v0.31.0)
---
# Release v0.31.0-rc.1
URL: https://usememos.com/changelog/0-31-0-rc-1
> This release candidate introduces first-class Spaces for collaboration while preserving individual memo ownership. It also unifies navigation and memo creation, adds inline attachment images and optional media metadata, migrates legacy filters to Views, enriches link previews, and strengthens access controls, database upgrades, and live-update performance.
## Breaking Changes [#breaking-changes]
* **Views replace legacy filters** - `ShortcutService`, shortcut resource names, MCP tools, persisted settings, and `/api/v1/users/*/shortcuts/*` have moved to `MemoViewService`, view resources, and `/api/v1/users/*/views/*`. The web route is now `/views`. Stored shortcuts migrate automatically, but API clients, MCP integrations, and saved links must be updated.
* **Author-controlled memo mutations** - Instance administrators are no longer implicit memo collaborators or Space members. Memo, attachment, reaction, relation, and share mutations are controlled by the memo author. Space administrators manage Space settings and membership but cannot edit another author's memo.
* **Independent comment lifecycle** - Comments now have their own visibility, placement, and lifecycle. `CreateMemoComment` no longer inherits the parent memo's visibility, so an omitted value defaults to `PRIVATE`. `SetMemoRelations` rejects `COMMENT` relations, and deleting a memo no longer cascades into comment memos.
* **Reaction API changes** - `Reaction.content_id` has been removed from the public API. Integrations must identify the memo from the request or reaction resource name. Existing reactions are migrated to internal memo IDs, while orphaned reactions are removed.
* **Managed attachment requirements** - Managed Markdown images must be bound to a memo before or during the same mutation. S3-backed attachments no longer expose presigned object URLs through `external_link`; clients should use the authenticated Memos file route.
* **Exact-case usernames and mentions** - Username lookup and authentication are now case-sensitive. New or renamed usernames must contain 1–36 ASCII letters, digits, or interior hyphens, and mentions use the same Markdown-aware grammar. Legacy usernames remain addressable, but unsupported legacy spellings cannot be authored as new mentions.
* **Quick Find shortcut removed** - The global Cmd/Ctrl+K keyboard shortcut has been removed. Quick Find remains available from the sidebar search action.
* **RSS feeds removed** - Explore and per-user RSS feeds are no longer available. `/explore/rss.xml` and `/u/:username/rss.xml` now return `404`.
## Upgrade Notes [#upgrade-notes]
* **Instance access is independent of the public URL** - Public or private access is now stored separately from `instance-url`. The first upgraded startup preserves previous behavior: instances with a configured URL become public, while those without one remain private. Later URL changes no longer change access policy. Upgrade every replica before changing the mode because older binaries still infer access from the URL.
* **Stricter instance URL validation** - `instance-url` must be an absolute HTTP or HTTPS URL without credentials, a query, or a fragment.
* **Existing memos remain Unassigned** - Upgrading does not create a default Space or move existing memos. Their identity, author, visibility, and relations are preserved.
* **Space deletion is destructive** - Deleting a Space permanently deletes every memo directly assigned to it and the resources owned by those memos. Removing a member leaves their contributions in place, and accounts with active Space memberships cannot be deleted, including with `force`.
* **Cross-database migrations** - SQLite, MySQL, and PostgreSQL migrations preserve existing memo data, migrate Views and legacy storage settings, and retain generated-ID high-water marks.
* **Tag indexes update incrementally** - Existing memo payloads are not rebuilt automatically for the new tag grammar. Rendering and editing use the new rules immediately, while filters and statistics adopt them after each memo is saved again.
* **Deployment changes** - Private webhook destinations can be restricted to exact hostnames, IP addresses, or CIDRs with `--webhook-private-network-allowlist`. The broader `--allow-private-webhooks` option remains compatible but is deprecated. Building Memos from source now requires Go 1.27.
## New Features [#new-features]
### Collaborative Spaces [#collaborative-spaces]
* **First-class collaboration** - Spaces support `ADMIN` and `USER` memberships while keeping every memo, including comments, owned by its author.
* **Independent placement and audience** - A memo can remain Unassigned or belong to exactly one Space without changing its identity. The new `SPACE` visibility limits reading to Space members independently of memo placement.
* **Space-aware browsing** - The Space switcher scopes Home, Explore, memo creation, statistics, filters, and attachments. Archived, Inbox, profiles, and Settings remain global.
* **Membership management** - Space administrators can manage metadata and roles and invite existing users. Invitations grant no access until accepted.
* **Stable identifiers** - New Spaces use UUIDv4 identifiers by default and can also use custom stable UIDs.
### Navigation and Writing [#navigation-and-writing]
* **Unified sidebar** - The previous dual navigation rails have been replaced by one route-aware, resizable sidebar containing the calendar, Views, tags, Quick Find, and contextual resource navigation.
* **Global composer** - Authenticated users can create a memo from any route without returning to the main feed.
* **Views** - Views are named, reusable Memo filters. Opening a View shows the Memos that currently match; it does not store Memo copies or choose a display layout. Existing filters migrate automatically.
### Attachments and Media [#attachments-and-media]
* **Inline image insertion** - Images can be inserted at the cursor from uploads, paste, drag and drop, or existing attachments.
* **Resilient drafts** - Inline uploads support retries and restoration when returning to an unfinished draft.
* **Optional media metadata** - Memos can preserve normalized dimensions, camera details, capture time, location, and video duration for inspection in the attachment viewer.
* **Stable storage configurations** - Named storage configurations use stable IDs so existing S3 attachments remain readable when storage settings change.
* **Authenticated S3 delivery** - Managed S3 files are proxied through authenticated Memos routes with range-request support.
### Discovery, Filtering, and Live Updates [#discovery-filtering-and-live-updates]
* **Unified tag parsing** - The backend, renderer, editor, filters, statistics, and API now share the same Markdown-aware tag grammar. Tags consistently support multilingual text, emoji, hierarchy, numeric values, `-`, `+`, `&`, and word-internal apostrophes.
* **Consistent mentions** - Mention parsing now follows the same exact-case username rules throughout the product.
* **Richer link previews** - Preview discovery now supports oEmbed, Open Graph, Twitter Cards, JSON-LD, HTML metadata, and semantic fallbacks, with bounded fetching, caching, request coalescing, and SSRF protection.
* **Location-aware filters** - Memo filtering can now include location data.
* **Efficient live updates** - Browser tabs share one visible-tab SSE connection, reducing redundant connections and server fanout work.
## Improvements and Bug Fixes [#improvements-and-bug-fixes]
* **Editor and Markdown** - IME composition is preserved, Windows emoji input works again, tag completion matches hierarchical path segments, task checkboxes remain controlled, currency is no longer parsed as inline math, outline links match rendered headings, and presentation toggles are scoped correctly.
* **Attachments and sharing** - Shared-memo thumbnails retain share tokens, attachment-library media links back to its source memo, and HEIC and HEIF uploads are detected reliably from filename extensions.
* **Database reliability** - SQLite memo mutations now begin with `BEGIN IMMEDIATE`, allowing concurrent writers to queue instead of intermittently returning `SQLITE_BUSY`. Upgrade handling is also hardened against malformed legacy settings and generated-ID reuse.
* **Navigation and layout** - Memo scope is preserved across global navigation, Archived remains outside Space scope, sidebar and outline behavior is restored, the resizable month calendar is constrained correctly, and select menus remain above parent popovers.
* **Maps and localization** - Keyless OpenStreetMap tiles are restored, Hebrew and comprehensive right-to-left layout support are added, Japanese, Traditional Chinese, and Russian translations are refreshed, and the French memo-link label is corrected.
* **API and settings** - Gateway JSON omits unset protobuf message fields while preserving scalar defaults and empty lists, and the configured memo-content length limit is enforced.
* **Security dependency** - `golang.org/x/crypto` is updated to 0.52.0 to address CVE-2026-39829.
**Full Changelog**: [v0.30.0...v0.31.0-rc.1](https://github.com/usememos/memos/compare/v0.30.0...v0.31.0-rc.1)
---
# Release v0.31.0-rc.2
URL: https://usememos.com/changelog/0-31-0-rc-2
> The second 0.31 release candidate adds Calendar and Map pages for browsing memos by date and location. It also makes moving between Spaces easier, adds icons for Views, improves writing and search, and tightens account email rules.
## Upgrade Notes [#upgrade-notes]
* **Unique account emails** - Email remains optional, but an address can belong to only one account per instance. During the upgrade, duplicate addresses stay on the oldest account and are cleared from the others. Administrators can find affected usernames in the server logs; those users can add a different address in account settings.
* **Upgrading from 0.30** - Review the [0.31.0-rc.1 upgrade notes](/changelog/0-31-0-rc-1) for the earlier API, access-control, and migration changes in this release series.
## New Features [#new-features]
### Calendar and Map [#calendar-and-map]
* **Calendar** - Browse a month of memos, open a date to read its entries, and create a memo for that day.
* **Dedicated Map page** - Explore memos that have location data on a map.
### Spaces, Views, and Search [#spaces-views-and-search]
* **Move memos between Spaces** - Change a memo's Space from the interface.
* **Invitations in Inbox** - Receive Space invitations alongside other notifications.
* **Custom icons** - Choose icons or emoji for Spaces and personalize Views with icons.
* **Keep your browsing context** - Switching Spaces preserves the current page and filters.
* **More precise search** - Find memos by Space and use filter expressions in Quick Find.
### Writing and Account Settings [#writing-and-account-settings]
* **Markdown shortcuts** - Apply formatting from the keyboard. On desktop, the Home editor receives focus when the page opens so you can start writing immediately.
* **Attachment storage usage** - See how much attachment storage your account uses in settings.
* **Slower audio playback** - Listen at 0.5× or 0.75× speed.
* **Azerbaijani support** - Use Memos in Azerbaijani.
## Improvements and Bug Fixes [#improvements-and-bug-fixes]
* **Navigation and memo details** - Refined the memo detail sidebar and compact navigation, with more visible active filters and adjusted spacing.
* **Editor behavior** - Improved mobile typing assistance and tag suggestions. Pasted files appear as attachments, and closing the date picker saves date edits.
* **Focus mode and blurred content** - Fixed focus mode in multi-column layouts. Memo headers and reactions remain interactive when content is blurred.
* **Appearance and translations** - Improved dark-mode status bar colors and Chinese translations.
* **Server reliability and security** - Added protections against abusive requests and unsafe webhook destinations, improved MCP compatibility, and fixed scheduled-job timing.
**Release**: [v0.31.0-rc.2 on GitHub](https://github.com/usememos/memos/releases/tag/v0.31.0-rc.2)
**Full Changelog**: [v0.31.0-rc.1...v0.31.0-rc.2](https://github.com/usememos/memos/compare/v0.31.0-rc.1...v0.31.0-rc.2)
---
# Release v0.4.0
URL: https://usememos.com/changelog/0-4-0
* Support multiple languages: English and 中文;
* Set the default memo visibility;
## What's Changed [#whats-changed]
* chore: update `i18nStore` by @lqwakeup in [https://github.com/usememos/memos/pull/141](https://github.com/usememos/memos/pull/141)
* chore: add docker-compose.yaml by @leopold7 in [https://github.com/usememos/memos/pull/142](https://github.com/usememos/memos/pull/142)
* feat: add `manifest.json` for pwa by @lqwakeup in [https://github.com/usememos/memos/pull/144](https://github.com/usememos/memos/pull/144)
* feat: add `user_setting` model by @boojack in [https://github.com/usememos/memos/pull/145](https://github.com/usememos/memos/pull/145)
***
**Full Changelog**: [v0.4.0](https://github.com/usememos/memos/releases/tag/v0.4.0)
---
# Release v0.4.1
URL: https://usememos.com/changelog/0-4-1
/`. Clients must also update renamed fields and types; binary protobuf clients must regenerate from the new schema. Old paths return `410 Gone` for this release and will be removed in the next release. Follow the [26.10 API migration checklist](/docs/integrations/api-access#2610-client-migration).
* **Tasks View** - The built-in Tasks View is removed. Create a [View](/docs/usage/views) with `has_task_list && has_incomplete_tasks` to browse unfinished tasks.
* **Space placement** - To move a memo, edit it and choose its Space in the audience menu alongside visibility. The separate Move to Space action is removed.
See the [upgrade guide](/docs/operations/upgrade#upgrading-to-2610) before updating an existing installation.
## New features [#new-features]
### Writing in context [#writing-in-context]
* **Editor suggestions** - New drafts offer tags, checklist formatting, and visibility choices based on your current filters or selected View. Apply the suggestions you want; they disappear when the draft fulfills them.
* **Audio transcription** - Transcribe an existing audio attachment from the editor using your configured provider. Review the transcript in your draft before saving. Your existing text and original audio stay intact.
* **Space and visibility together** - Select a memo's Space and visibility from the editor's audience menu. Edit a top-level memo to add, change, or remove its Space, then save the changes together.
### Browsing by creator and Space [#browsing-by-creator-and-space]
* **Keep your scope** - Switch between Timeline, Calendar, Map, and Attachments while keeping the selected creator and Space.
* **Calendar and Map for visitors** - Signed-out visitors can browse memos they can read in Calendar and Map. Photos and author avatars help identify days and map pins across several authors; the desktop calendar makes room for its day panel.
* **Shared attachment browsing** - The attachment library includes files from readable memos and identifies their uploaders.
## Improvements and fixes [#improvements-and-fixes]
* **Markdown and editing** - Collapsible sections have clearer indicators and spacing, with keyboard controls and nested sections preserved. Headings match between editing and reading, block spacing is more consistent, and formatting shortcuts keep surrounding whitespace outside Markdown delimiters.
* **Image previews** - Pinch to zoom, drag to pan a zoomed image, and swipe between gallery images at fit zoom. Preview controls stay within the visible mobile viewport.
* **Memos and filters** - Pinned memos have a clearer corner marker in single-creator feeds; mixed-author feeds stay chronological. Filters such as `has_task_list == false` include memos without that property. Deleting a memo also deletes its comments and nested replies.
* **Navigation and appearance** - Open memo timestamps in a new tab. Theme and language controls use sidebar submenus that stay on screen in narrow viewports. Notifications follow the active theme, and reaction pickers close without flashing at the page corner.
* **Languages and link previews** - Norwegian Nynorsk is available, the Korean hidden-content label uses neutral wording, and large web pages produce more reliable preview titles and images.
Report regressions in [GitHub issues](https://github.com/usememos/memos/issues).
**Release**: [26.10-rc.1 on GitHub](https://github.com/usememos/memos/releases/tag/26.10-rc.1)
**Full changelog**: [v0.31.0...26.10-rc.1](https://github.com/usememos/memos/compare/v0.31.0...26.10-rc.1)