Memos User Guide

Memos is a self-hosted, open-source note-taking service built for speed and privacy. Write short-form notes in Markdown, organize them with tags, attach files, share publicly or keep private, and access everything through a clean web interface. Because Memos runs on your own server, your notes never touch a third-party cloud.

This guide covers everything a Memos user needs: getting the server running, daily note-taking workflows, advanced features like AI transcription and MCP integration, and a thorough troubleshooting reference. Architecture, API, and deep operational details belong in the companion Admin Guide.

Table of Contents

1. Quick Start
2. Installation
3. Configuration
4. Core Usage
5. Common Tasks
6. Advanced Features
7. Troubleshooting
8. FAQ

1. Quick Start

Get Memos running in under five minutes using Docker.

1.1 Prerequisites

• Docker 20.10+ (or Docker Desktop on Windows/Mac)
• A free port (default: 5230)
• A directory for persistent data

1.2 One-Command Start

docker run -d \
  --name memos \
  -p 5230:5230 \
  -v ~/.memos:/var/opt/memos \
  ghcr.io/usememos/memos:latest

Open your browser at http://localhost:5230. The first page you see is the account-creation screen — fill in a username and password to create the administrator account.

Tip

The very first account created on a fresh Memos instance automatically becomes the administrator. Create it immediately after first boot — don't leave the instance open without an admin account.

1.3 Write Your First Memo

1. Click the text area at the top of the home page (it says "Any thoughts…").
2. Type your note. Markdown is supported natively.
3. Press Ctrl+Enter (Windows/Linux) or Cmd+Enter (Mac) to save.

Your memo appears in the timeline below the editor. That's it — you're using Memos.

1.4 What Happens Next

2. Installation

2.1 Docker (Recommended)

Docker is the simplest and most reliable way to run Memos.

2.1.1 Minimal Run Command

docker run -d \
  --name memos \
  -p 5230:5230 \
  -v ~/.memos:/var/opt/memos \
  ghcr.io/usememos/memos:latest

• Port 5230 is Memos's default Docker port (set via MEMOS_PORT). The binary's built-in default is 8081; Docker overrides it.
• /var/opt/memos is the container's data directory. Bind-mount a host directory so data survives container restarts.

Important

Always bind-mount a host directory to /var/opt/memos. Without it, your SQLite database lives inside the container layer and is destroyed when the container is removed.

2.1.2 Alternate Image

docker run -d \
  --name memos \
  -p 5230:5230 \
  -v ~/.memos:/var/opt/memos \
  neosmemo/memos:stable

Both ghcr.io/usememos/memos and neosmemo/memos are official. The ghcr.io image is preferred for new deployments.

2.1.3 Pin to a Specific Version

Replace latest with a version tag to avoid unexpected upgrades:

docker run -d \
  --name memos \
  -p 5230:5230 \
  -v ~/.memos:/var/opt/memos \
  ghcr.io/usememos/memos:0.26.2

2.1.4 Docker Compose

A compose.yaml is included in the Memos repository under scripts/compose.yaml. A production-ready example:

services:
  memos:
    image: ghcr.io/usememos/memos:0.26.2
    container_name: memos
    restart: unless-stopped
    ports:
      - "5230:5230"
    volumes:
      - ./data:/var/opt/memos
    environment:
      - MEMOS_PORT=5230
      - MEMOS_INSTANCE_URL=https://memos.example.com

Start with:

docker compose up -d

Expected output:

[+] Running 1/1
 ✔ Container memos  Started

Check logs:

docker logs memos

Expected output (first run):

time=2026-05-07T... level=INFO msg="Version: 0.26.2"
time=2026-05-07T... level=INFO msg="Data directory: /var/opt/memos"
time=2026-05-07T... level=INFO msg="Database driver: sqlite"
time=2026-05-07T... level=INFO msg="Server started" addr=:5230

2.2 Binary (Linux / macOS / Windows)

Download the pre-built binary from the GitHub Releases page.

Linux/macOS

# Download (adjust version and OS/arch as needed)
curl -L https://github.com/usememos/memos/releases/download/v0.26.2/memos_linux_amd64.tar.gz \
  -o memos.tar.gz

tar -xzf memos.tar.gz
chmod +x memos

# Run
./memos --port 8081 --data ./data

Expected output:

time=2026-05-07T... level=INFO msg="Server started" addr=:8081

Open http://localhost:8081 in your browser.

Windows

Download memos_windows_amd64.zip from the releases page, extract it, and run from PowerShell:

.\memos.exe --port 8081 --data C:\ProgramData\memos

Note

On Windows, if you omit --data, Memos defaults to %ProgramData%\memos (typically C:\ProgramData\memos).

2.3 Build from Source

Requirements: Go 1.22+, Node.js 18+, pnpm.

git clone https://github.com/usememos/memos.git
cd memos

# Build frontend
cd web
pnpm install
pnpm build
cd ..

# Build backend (embeds frontend)
go build -o memos ./cmd/memos/main.go

# Run
./memos --port 8081 --data ./data

2.4 Data Directory

Memos selects its data directory in this order:

The data directory contains:

• memos_prod.db — SQLite database (all memos, users, settings)
• Uploaded files (if using local storage)

2.5 Upgrading

Docker

docker pull ghcr.io/usememos/memos:latest
docker stop memos && docker rm memos
docker run -d \
  --name memos \
  -p 5230:5230 \
  -v ~/.memos:/var/opt/memos \
  ghcr.io/usememos/memos:latest

Memos runs database migrations automatically on startup. Back up your data directory before upgrading.

Warning

Always back up your data directory before upgrading. Copy the entire directory including memos_prod.db:

cp -r ~/.memos ~/.memos.backup.$(date +%Y%m%d)

Binary

Stop the running process, replace the binary, and restart.

3. Configuration

Memos accepts configuration through command-line flags, environment variables, or both. Environment variables take the prefix MEMOS_ with hyphens replaced by underscores.

3.1 All Configuration Options

3.2 Common Configuration Scenarios

Bind to a Specific Address (Localhost Only)

./memos --addr 127.0.0.1 --port 8081

Use this when a reverse proxy (nginx, Caddy, Traefik) sits in front of Memos.

Using Environment Variables in Docker

environment:
  - MEMOS_PORT=5230
  - MEMOS_DRIVER=postgres
  - MEMOS_DSN=postgres://memos:secret@db:5432/memos
  - MEMOS_INSTANCE_URL=https://memos.example.com

Unix Socket (Advanced)

./memos --unix-sock /run/memos/memos.sock

Note

Unix socket permissions may require the Memos process and your reverse proxy to share a group. See GitHub issue #5827 for known permission edge cases.

3.3 Database Configuration

SQLite (Default)

No DSN needed. Memos creates memos_prod.db in the data directory automatically.

./memos --driver sqlite --data /srv/memos

MySQL

./memos \
  --driver mysql \
  --dsn "memos:password@tcp(127.0.0.1:3306)/memos?charset=utf8mb4&parseTime=True"

PostgreSQL

./memos \
  --driver postgres \
  --dsn "postgres://memos:password@127.0.0.1:5432/memos?sslmode=disable"

Important

Create the database and user before starting Memos — Memos handles schema creation and migrations, but not database/user provisioning.

3.4 Setting the Instance URL

The instance URL is used for share links, RSS feed URLs, and MCP integration. Set it to the public URL where users reach Memos:

./memos --instance-url https://memos.example.com

Or in Settings → Instance (admin only) within the web UI.

4. Core Usage

4.1 The Home Page

When you log in, you land on your personal home page. The layout from top to bottom:

4.2 The Memo Editor

The editor is the heart of Memos. Click the text area labeled "Any thoughts…" to start writing.

Editor Controls

Visibility Options

New memos default to Private unless you change the visibility selector before saving.

4.3 Writing in Markdown

Memos renders GitHub Flavored Markdown (GFM) plus several extensions.

Basic Formatting

**bold** or __bold__
*italic* or _italic_
~~strikethrough~~
`inline code`

Headings

# H1
## H2
### H3

Lists

- Unordered item
- Another item
  - Nested item

1. Ordered item
2. Second item

Task Lists

- [x] Completed task
- [ ] Pending task
- [ ] Another pending task

Task list checkboxes are interactive — click them in the rendered memo to toggle completion.

Tables

| Column A | Column B | Column C |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Code Blocks

Use fenced code blocks with a language identifier for syntax highlighting:

```python
def greet(name: str) -> str:
    return f"Hello, {name}!"
```

```bash
echo "Hello, world!"
```

```json
{
  "key": "value",
  "number": 42
}
```

Math (KaTeX)

Inline math uses single dollar signs; display math uses double:

Inline: $E = mc^2$

Display:
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

Mermaid Diagrams

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do it]
    B -->|No| D[Skip it]
    C --> E[End]
    D --> E
```

Blockquotes

> This is a blockquote.
> It can span multiple lines.

> [!NOTE]
> GitHub-style alert in a blockquote.

Links and Images

[Link text](https://example.com)
![Alt text](https://example.com/image.png)

4.4 Tags

Tags are Memos's primary organizational system. Add a tag anywhere in a memo by typing #tagname.

Tag Syntax

#meeting
#work/project-alpha
#daily-log

Hierarchical Tags

Tags support hierarchy using /:

#work/project-alpha/design
#work/project-alpha/dev
#personal/health
#personal/fitness

The tag tree in the right sidebar shows hierarchical tags as collapsible folders.

Tag Autocomplete

As you type # in the editor, Memos suggests existing tags. Press Tab or click to autocomplete.

Tag Metadata (Colors and Blur)

In Settings → Tags, you can assign a color to any tag and optionally enable "blur" (which blurs memos with that tag until hovered — useful for sensitive content).

Filtering by Tag

• Click any tag in the right sidebar tag tree to filter your timeline.
• Click a #tag link inside a memo to filter by that tag.
• Click the × on the active filter to clear it.

4.5 Viewing Memos

Timeline View (Default)

The home page shows memos in reverse-chronological order. Scroll down to load older memos.

Calendar View

Click the calendar icon in the right sidebar to switch to calendar view. Days with memos are highlighted; click a day to see memos from that date.

Note

Known issue (GitHub #5816): in some versions, calendar view does not color days from the previous month in the current view. This is a display-only issue; your memos are unaffected.

Map View

If memos have location tags, switch to map view to see them plotted geographically.

4.6 Searching Memos

Use the search icon or bar in the top navigation. Type any text to search across all your memo content, including tags.

Search is real-time — results update as you type.

4.7 User Menu and Account

Click your avatar or username in the top-right corner to access:

• Profile — public profile page
• Settings — account, preferences, API tokens
• Sign out

5. Common Tasks

5.1 Creating and Editing Memos

Create a Memo

1. Click the editor text area at the top of the home page.
2. Write your content (Markdown supported).
3. Optionally set visibility, add tags, attach files.
4. Press Ctrl+Enter / Cmd+Enter or click the Save button.

Edit a Memo

1. Hover over a memo in the timeline.
2. Click the ⋯ (more options) menu that appears.
3. Select Edit.
4. Make changes in the editor that opens.
5. Press Ctrl+Enter / Cmd+Enter to save.

Delete a Memo

1. Hover over the memo.
2. Click ⋯ → Delete.
3. Confirm the deletion.

Warning

Memo deletion is permanent. There is no recycle bin. Consider archiving instead (see §5.4).

Pin a Memo

Pinned memos always appear at the top of your timeline regardless of date.

1. Hover over the memo.
2. Click ⋯ → Pin.

To unpin, repeat the same steps and select Unpin.

5.2 Attachments

Uploading Files

1. Open the memo editor.
2. Click the paperclip icon, or drag and drop files directly into the editor.
3. Supported types include images, videos, audio files, PDFs, and documents.
4. Files appear as inline previews (images/video) or download links.

Attachment Library

Access all your uploaded files at once:

1. Click Resources or the attachment library icon in the navigation.
2. Browse by tab: Media (images/video), Documents, Audio.
3. Images show as thumbnails; click to open full-size.

Storage Backends

Where attachments are stored depends on your admin's configuration:

Contact your instance admin if you are unsure which storage backend is configured.

5.3 Reactions

Add emoji reactions to any memo (your own or others' public/protected memos).

1. Hover over a memo.
2. Click the emoji/reaction icon that appears.
3. Pick an emoji from the picker.

Your reaction appears below the memo. Click it again to remove it.

5.4 Archiving Memos

Archive moves a memo out of your active timeline without deleting it.

1. Hover over a memo.
2. Click ⋯ → Archive.

To view archived memos, click Archive in the left sidebar. To restore, open the archived memo and select Unarchive.

5.5 Relations Between Memos

Link related memos together to build a knowledge graph.

1. Open a memo's edit view.
2. Click the Relations option in the editor toolbar (or the link icon).
3. Search for and select another memo to link.

Relations appear at the bottom of the memo card. Click a related memo to navigate to it.

5.6 Comments

Comment on any memo you can see.

1. Click the comment icon (speech bubble) below a memo.
2. Type your comment in the text box that appears.
3. Press Ctrl+Enter / Cmd+Enter to post.

Comments support Markdown. You can edit or delete your own comments.

5.7 Mentions

Mention another user in a memo or comment using @username. The mentioned user receives a notification in their inbox.

Discussing this with @alice — she had a similar issue last week.

Type @ to trigger username autocomplete.

5.8 Sharing Memos

Share a Single Memo Publicly

Any memo can be shared via a unique link, even if the memo is Private (the link acts as an access token):

1. Hover over a memo.
2. Click ⋯ → Share (or the share icon).
3. Copy the generated link.
4. Send the link to anyone — they can view the memo without logging in.

Make a Memo Publicly Discoverable

Set the memo's visibility to Public (using the visibility dropdown before saving). Public memos appear on the Explore page at /explore.

5.9 Shortcuts (Saved Filters)

Shortcuts let you save a filter as a named bookmark in the left sidebar.

1. Apply a filter (e.g., click a tag to filter by it).
2. Click Add Shortcut (or the bookmark/star icon).
3. Give the shortcut a name.

The shortcut appears in the left sidebar. Click it anytime to jump back to that filtered view.

5.10 Inbox / Notifications

The Inbox (bell icon in the left sidebar) shows notifications for:

• Comments on your memos
• @mention notifications

Click a notification to jump to the relevant memo or comment. Mark notifications as read individually or all at once.

5.11 RSS Feeds

Each user's public memos are available as an RSS feed:

https://memos.example.com/u/{username}/rss.xml

The global public feed:

https://memos.example.com/rss.xml

Subscribe with any RSS reader (Feedly, NetNewsWire, etc.).

Note

RSS feeds only include Public memos. Private and Protected memos never appear in feeds.

5.12 Personal Access Tokens (PATs)

PATs allow you to access the Memos API from scripts or third-party tools.

1. Go to Settings → My Account → Access Tokens.
2. Click Create Token.
3. Give it a name and optionally an expiration date.
4. Copy the token immediately — it is only shown once.

Use the token in API requests:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://memos.example.com/api/v1/memos

Important

Treat PATs like passwords. If a token is compromised, revoke it immediately from Settings → My Account → Access Tokens.

6. Advanced Features

6.1 Voice Memos and AI Transcription

Memos supports voice recording directly in the browser, with optional AI-powered transcription.

Recording a Voice Memo

1. Open the memo editor.
2. Click the microphone icon.
3. Allow microphone access when the browser prompts.
4. Speak your note.
5. Click the stop button.

Without AI configured, the audio is saved as an attachment.

AI Transcription

With AI configured (Settings → AI — admin only), Memos sends the audio to OpenAI's Whisper or Google Gemini and inserts the transcript as memo text automatically.

Supported AI providers:

• OpenAI — requires an OpenAI API key; uses Whisper for transcription and optionally GPT for other AI features
• Google Gemini — requires a Gemini API key

Note

AI transcription requires the instance admin to configure an API key in Settings → AI. Contact your admin if the microphone icon doesn't produce a transcript.

6.2 Location Tagging

Add a geographic location to a memo:

1. Open the memo editor.
2. Click the map pin icon.
3. Allow location access or enter coordinates/place name manually.
4. The location is attached to the memo.

Memos with locations appear in Map View, plotted on an interactive map.

6.3 Themes

Switch between visual themes in Settings → Preferences → Theme:

The selected theme persists across sessions on that device.

6.4 Language / i18n

Memos supports 30+ languages. Change your display language:

1. Go to Settings → Preferences.
2. Select your language from the Language dropdown.

The UI updates immediately. This is a per-user setting; each user picks their own language independently.

Supported languages include English, Chinese (Simplified/Traditional), German, French, Spanish, Japanese, Korean, Russian, Portuguese, Italian, Dutch, Polish, Turkish, Arabic, Hebrew, Thai, Vietnamese, and many more.

6.5 MCP Integration (AI Clients)

Memos exposes a Model Context Protocol (MCP) server that lets AI clients (Claude Desktop, Cursor, Windsurf, Continue, etc.) interact directly with your memos.

MCP Endpoint

https://memos.example.com/mcp

Connecting Claude Desktop

Add the following to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "memos": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://memos.example.com/mcp"],
      "env": {
        "Authorization": "Bearer YOUR_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}

Replace YOUR_PERSONAL_ACCESS_TOKEN with a PAT generated in Settings → My Account → Access Tokens.

Once connected, your AI client can create memos, search memos, and retrieve memo content through natural language.

Tip

The MCP integration is one of Memos's most powerful features for AI-augmented workflows. You can ask Claude to "create a memo about today's meeting" or "find my notes on project alpha" without opening the browser.

Connecting Cursor / Other MCP Clients

Follow the same pattern: point the MCP client at https://memos.example.com/mcp with your PAT as a Bearer token. Consult your specific client's documentation for the exact configuration format.

6.6 Webhooks

Webhooks fire HTTP POST requests to a URL you specify when memo events occur.

Note

Webhooks are configured in Settings → Webhooks. By default, webhooks cannot target private/RFC-1918 IP ranges. This restriction can be lifted by the instance admin with --allow-private-webhooks.

Common uses:

• Trigger automations in n8n, Make, or Zapier when a new memo is created
• Post new public memos to Slack or Discord
• Index memos in a search engine

6.7 Progressive Web App (PWA)

Memos works as a PWA — you can install it on mobile devices for an app-like experience.

iOS (Safari): Tap the Share button → Add to Home Screen.

Android (Chrome): Tap the browser menu → Add to Home Screen or Install App.

Note

Known issues with PWA on some platforms:

• iOS PWA may show an empty feed after install (GitHub #5823) — try refreshing or reinstalling.
• Android PWA may behave unexpectedly in some browser versions (GitHub #5831).

6.8 Keyboard Shortcuts

6.9 Auto-Save and Draft Recovery

The memo editor auto-saves your draft locally in the browser. If you accidentally close the tab or browser, your unsaved text may be restored when you reopen Memos.

Tip

Auto-save is browser-local only. It does not sync across devices. If you're writing something important, save it as a Private memo first.

6.10 Demo Mode

If Memos is launched with --demo true (or MEMOS_DEMO=true), the server enters read-only demonstration mode. Write operations are disabled. This mode is intended for public-facing demos.

7. Troubleshooting

7.1 Installation and Startup Issues

Error: bind: address already in use

Cause: Another process is using the port Memos wants to bind.

Solution:

# Find what's using port 5230
lsof -i :5230
# or on Windows
netstat -ano | findstr :5230

Kill that process or start Memos on a different port:

docker run -d -p 5231:5230 ghcr.io/usememos/memos:latest

Prevention: Pick a port that isn't in use. Document your chosen port.

Error: permission denied on data directory

Cause: The Memos container runs as uid 10001 (non-root). If the bind-mounted host directory is owned by root or another user, Memos cannot write to it.

Solution:

# Fix ownership on the host directory
sudo chown -R 10001:10001 ~/.memos

Then restart the container:

docker restart memos

Prevention: Create the data directory and set ownership before running the container:

mkdir -p ~/.memos
sudo chown 10001:10001 ~/.memos

Error: database is locked

Cause: SQLite allows only one writer at a time. This error typically means multiple Memos instances are pointing at the same SQLite file, or the database file was left in a locked state.

Solution:

1. Ensure only one Memos instance is running against this data directory.
2. If you need multiple instances, use MySQL or PostgreSQL instead.
3. If the lock is stale (no Memos running), restart Memos — SQLite will clear the lock automatically.

Prevention: Use a database lock mechanism or switch to a networked database when running multiple instances.

Error: failed to connect to database

Cause: MySQL or PostgreSQL DSN is incorrect, or the database server is unreachable.

Solution:

1. Verify the DSN format matches the driver.
2. Test connectivity to the database from the Memos container:

   docker exec -it memos ping db
   

3. Verify the database and user exist with the correct permissions.

MySQL DSN format:

user:password@tcp(host:3306)/dbname?charset=utf8mb4&parseTime=True

PostgreSQL DSN format:

postgres://user:password@host:5432/dbname?sslmode=disable

Error: Container starts but web UI shows blank page

Cause: Several possibilities: frontend failed to embed, port mapping wrong, reverse proxy not configured correctly.

Solution:

1. Check container logs: docker logs memos
2. Verify port mapping: docker ps | grep memos
3. Test directly on the container's port (bypassing any proxy):

   curl http://localhost:5230
   

4. If behind a reverse proxy, check that the proxy is forwarding to the correct address and port.

Error: unix socket: no such file or directory

Cause: Using --unix-sock but the specified directory doesn't exist, or the socket file path is wrong.

Solution:

# Create the socket directory first
mkdir -p /run/memos
./memos --unix-sock /run/memos/memos.sock

If using Docker:

volumes:
  - /run/memos:/run/memos

See GitHub issue #5827 for permission edge cases with Unix sockets.

7.2 Authentication Issues

Error: invalid username or password

Cause: Wrong credentials, or the account doesn't exist.

Solution:

1. Verify you're using the correct username (not email, unless configured otherwise).
2. Use the password reset flow if available (requires email configuration by admin).
3. If you're the admin and locked out, contact your server admin to reset via the database.

Error: SSO / OAuth login fails or redirect_uri mismatch

Cause: The OAuth provider's redirect URI doesn't match the configured instance URL.

Solution:

1. In your OAuth provider (Google, GitHub, etc.), ensure the authorized redirect URI matches exactly: https://memos.example.com/auth/callback (substituting your actual domain).
2. In Memos Settings → SSO, ensure the instance URL matches what you registered.
3. In Memos startup config, set --instance-url https://memos.example.com (no trailing slash).

Prevention: Always set --instance-url when deploying Memos behind a domain.

Error: UI flash or login redirect loop before sign-in page

Cause: Known display issue (GitHub #5846) where the UI briefly renders the logged-in state before redirecting to sign-in on initial load.

Solution: This is a cosmetic issue — the redirect happens correctly. If it causes functional problems, hard-refresh the page (Ctrl+Shift+R / Cmd+Shift+R).

7.3 Memo and Content Issues

Error: Memo not appearing after save

Cause: Visibility filter is active, or a tag filter is hiding the memo.

Solution:

1. Check the right sidebar — is a tag or date filter active? Clear it with the × button.
2. Verify the memo's visibility setting matches what you expect.
3. Hard-refresh the page.

Error: Images not displaying in memos

Cause: Attachment storage is misconfigured, or the --instance-url is wrong so image URLs don't resolve.

Solution:

1. Check that the instance URL is set correctly: --instance-url https://memos.example.com.
2. If using S3 storage, verify the bucket policy allows public reads (or that signed URLs are working).
3. Check browser console for 404 or CORS errors on image requests.

Error: File upload fails silently

Cause: Storage backend misconfigured, disk full, or file size limit exceeded.

Solution:

1. Check container logs for storage errors: docker logs memos | grep -i storage
2. Check available disk space: df -h
3. Verify S3 credentials if using S3 storage.
4. Large files may time out — try a smaller test file.

Error: Markdown not rendering (shows raw text)

Cause: Renderer glitch, browser extension conflict, or very long memo causing performance issues.

Solution:

1. Hard-refresh the page.
2. Disable browser extensions temporarily (particularly ad blockers or content blockers).
3. Try in a different browser.
4. If the memo is very long, try splitting it into multiple memos.

Error: Mermaid diagram shows error instead of diagram

Cause: Syntax error in the Mermaid code block.

Solution: Use the Mermaid Live Editor to validate your diagram syntax before pasting into Memos. Common issues:

• Missing closing end or end if
• Special characters in node labels (wrap in quotes)
• Wrong diagram type keyword

Error: Math (KaTeX) not rendering

Cause: Incorrect delimiter syntax, or a conflict with other Markdown syntax.

Solution:

• Inline math: $formula$ — ensure no spaces after the opening $.
• Display math: $$formula$$ on its own line.
• If $ appears in non-math contexts, escape it: \$.

7.4 Performance Issues

Issue: Page loads slowly or timeline takes long to appear

Cause: Database query performance degraded due to large number of memos, or server resource constraints.

Solution:

1. Ensure indexes are healthy (no action needed for standard SQLite — Memos manages this).
2. For large installations (10,000+ memos), switch to PostgreSQL for better query performance.
3. Add more RAM/CPU to the server.
4. Archive old memos to reduce active dataset size.

Issue: Auto-refresh error appears repeatedly

Cause: Known issue (GitHub #5607) with SSE (Server-Sent Events) connection dropping and failing to reconnect cleanly.

Solution:

1. Hard-refresh the page to re-establish the SSE connection.
2. Check that your reverse proxy is not timing out long-running connections (SSE requires persistent connections).

For nginx, add to your proxy config:

proxy_read_timeout 3600s;
proxy_buffering off;

For Caddy:

flush_interval -1

Prevention: Configure your reverse proxy to support persistent/streaming connections.

Issue: Calendar view doesn't highlight days correctly

Cause: Known display issue (GitHub #5816) — previous-month days in the calendar view may not be colored even when they contain memos.

Solution: This is a cosmetic display bug. Click the previous-month arrow to navigate to that month directly — the days will color correctly when that month is the primary view.

Issue: Masonry layout setting not saved between sessions

Cause: Known issue (GitHub #5807) — the masonry layout preference may not persist in some versions.

Solution: Re-select the layout preference after logging in. Check for updates — this is tracked as a bug.

7.5 PWA Issues

Issue: iOS PWA shows empty feed after install

Cause: Known issue (GitHub #5823) — the installed PWA on iOS may have a cache/session initialization problem.

Solution:

1. Open Memos in Safari (not the installed PWA).
2. Log in fresh, then use "Add to Home Screen" again.
3. Alternatively, use the browser version on iOS rather than the installed PWA.

Issue: Android PWA behaves unexpectedly

Cause: Known issue (GitHub #5831) — some Android browser versions have PWA installation quirks.

Solution:

1. Try Chrome on Android for best PWA support.
2. Clear the PWA's storage: Android Settings → Apps → Memos → Storage → Clear Cache.
3. Reinstall the PWA.

7.6 AI and Voice Issues

Issue: Voice recording produces no transcript

Cause: AI transcription not configured, microphone permission denied, or wrong API key.

Solution:

1. Verify AI is configured: Settings → AI (admin access required).
2. Ensure the OpenAI or Gemini API key is valid and has sufficient quota.
3. Check browser microphone permissions: click the lock icon in the address bar.
4. Check container logs for AI API errors: docker logs memos | grep -i ai

Issue: AI transcription is inaccurate

Cause: Background noise, unclear audio, or accent/language mismatch.

Solution:

1. Record in a quiet environment.
2. Speak clearly and close to the microphone.
3. Review and edit the transcript after it's inserted.

7.7 MCP Integration Issues

Issue: AI client cannot connect to Memos MCP

Cause: Wrong endpoint URL, invalid token, or network firewall.

Solution:

1. Verify the MCP URL is https://memos.example.com/mcp (not /api/v1 or any other path).
2. Generate a fresh PAT in Settings → My Account → Access Tokens.
3. Test the endpoint directly:

   curl -H "Authorization: Bearer YOUR_TOKEN" https://memos.example.com/mcp
   

4. Check that port 443 is open and the SSL certificate is valid.

Issue: MCP returns authentication error

Cause: PAT expired, revoked, or incorrectly formatted in the client config.

Solution:

1. Generate a new PAT with no expiration.
2. Ensure the Authorization header format is exactly Bearer <token> with a space between "Bearer" and the token.

7.8 RSS Feed Issues

Issue: RSS feed returns empty or shows wrong memos

Cause: No public memos exist, or the feed URL is wrong.

Solution:

1. Ensure at least one memo has Public visibility.
2. Verify the feed URL: https://memos.example.com/rss.xml
3. For a user-specific feed: https://memos.example.com/u/{username}/rss.xml
4. Ensure --instance-url is set correctly (affects feed URLs).

8. FAQ

General

Q: Is Memos free? Memos is free and open-source under the MIT license. Running it requires only a server — no paid plans, subscriptions, or license fees.

Q: Does Memos have a mobile app? Memos does not have a dedicated native app for iOS or Android, but it works as a Progressive Web App (PWA). Install it from Safari (iOS) or Chrome (Android) via "Add to Home Screen" for an app-like experience.

Q: Can I use Memos without self-hosting? Memos is designed as a self-hosted application. There is no official cloud-hosted version. You must run it on your own server or a VPS.

Q: How is Memos different from other note-taking apps? Memos is optimized for short-form notes ("memos") rather than long documents. Key differentiators: self-hosted, privacy-first, Markdown-native, timeline-based organization (tags instead of folders), and built-in sharing with visibility controls. For long-form documents, consider a tool like Obsidian or Notion.

Q: Can I import notes from other apps? There is no built-in import wizard for other apps. For bulk import, you can use the API with a Personal Access Token to create memos programmatically. Check the community for import scripts targeting specific formats (Markdown files, Joplin, Notion exports, etc.).

Q: Does Memos sync across devices? Because Memos is a web app, any device with a browser can access the same memos through the server URL. There is no local-first sync or offline-first architecture — the server is always the source of truth.

Q: Can I use Memos offline? Basic reading may work offline via the PWA's cache, but creating or editing memos requires a connection to the server.

Q: What languages does Memos support? 30+ languages, including English, Chinese (Simplified and Traditional), German, French, Spanish, Japanese, Korean, Russian, Portuguese (Brazil and Portugal), Italian, Dutch, Polish, Turkish, Arabic, Hebrew, Thai, Vietnamese, Ukrainian, Czech, Finnish, Hungarian, Romanian, Croatian, Slovak, Slovenian, Indonesian, Malay, Catalan, Galician, and Basque.

Installation and Hosting

Q: What are the minimum server requirements? Memos is lightweight. For personal use: 512 MB RAM, 1 CPU core, and a few GB of disk (mostly for attachments). For teams: 1–2 GB RAM and more disk depending on attachment usage.

Q: Can I run Memos on a Raspberry Pi? Yes. Use the linux/arm64 or linux/arm/v7 Docker image. Performance is adequate for personal use on a Raspberry Pi 3 or newer.

Q: Can I run Memos on a shared hosting / cPanel account? Not easily. Memos is a standalone binary or Docker container — it needs persistent process execution, which shared hosting typically doesn't provide. A VPS is the simplest option.

Q: Do I need a domain name? No. You can access Memos by IP:port (e.g., http://192.168.1.100:5230). A domain is required only if you want HTTPS via Let's Encrypt or a clean URL for sharing.

Q: How do I set up HTTPS? HTTPS is not handled by Memos itself — use a reverse proxy:

• Caddy: automatically provisions Let's Encrypt certificates
• Traefik: Docker-native with automatic SSL
• nginx: manual certificate management or with certbot

See the Admin Guide for reverse proxy configuration details.

Q: Can I run multiple Memos instances on the same server? Yes. Run each on a different port with a different data directory. Use a reverse proxy to route traffic based on subdomain or path.

Q: How do I back up my Memos data? For SQLite:

cp ~/.memos/memos_prod.db ~/.memos/memos_prod.db.backup.$(date +%Y%m%d)

Or use SQLite's .backup command for a hot backup. Also back up the attachments directory if using local storage. Schedule automated backups with cron.

Q: How do I restore from a backup? Stop Memos, replace memos_prod.db with your backup copy, and restart. For attachments, restore the files directory similarly.

Q: What happens to data during an upgrade? Memos automatically runs database migrations on startup. Your data is preserved. Always back up before upgrading as a precaution.

Features

Q: Is there a character/word limit on memos? There is no hard character limit enforced by the application. Practical performance degrades for extremely long memos (thousands of lines). For long-form content, split into multiple memos.

Q: Can I organize memos into folders? Memos uses tags instead of folders. Tags are hierarchical (e.g., #work/project-alpha/meeting) and can replicate a folder structure. The tag tree in the right sidebar collapses and expands like folders.

Q: Can I set a password on a shared memo link? No. The shared link itself acts as an access token. Anyone with the link can view the memo. Revoke the share to deactivate the link.

Q: Does Memos support two-factor authentication (2FA)? Not built-in. If 2FA is important, configure SSO with an identity provider that supports 2FA (Google, GitHub with 2FA, etc.).

Q: Can I mention users who aren't members of my instance? No. @username mentions only work for users who have accounts on the same Memos instance.

Q: Does Memos support full-text search? Yes. The search bar searches the full content of your memos in real-time. Search does not currently support advanced query syntax (wildcards, boolean operators, etc.) from the UI.

Q: Can I export my memos? There is no built-in export UI. Use the API with a PAT to retrieve and export memos programmatically. The API returns memos as JSON; write a small script to convert to Markdown files or another format.

Q: Are there keyboard shortcuts?

• Ctrl+Enter / Cmd+Enter: Save memo
• Escape: Close modals or exit editor focus mode

More shortcuts may be added in future versions.

Q: Can I embed memos in other websites? Public memos can be linked to directly. There is no oEmbed or iframe embed feature built in. You can link to a specific memo using the share link.

Q: What is the Explore page? The Explore page (/explore) shows all Public memos from all users on the instance, in reverse-chronological order. It's the public-facing timeline for the instance.

Q: How do tag colors work? In Settings → Tags, you can assign a HEX color to any tag. Memos with that tag will display a color indicator. The "blur" option blurs the memo card until hovered, useful for tags marking sensitive content.

Q: Can I disable public registration? Yes — your admin can disable open registration so only invited users can create accounts. Go to Settings → Instance → Registration (admin access required).

Integrations and API

Q: What is MCP and why would I use it? MCP (Model Context Protocol) is an open standard for AI clients to interact with data sources. Memos implements an MCP server so AI assistants (Claude, Cursor, etc.) can read and write your memos using natural language. Instead of opening the browser, you can tell your AI client "create a memo about today's meeting" and it handles the rest.

Q: Can I use Memos with Zapier or Make? Yes, via Webhooks. Configure a webhook in Settings → Webhooks to POST to a Zapier/Make webhook URL when a memo is created or updated.

Q: Can I use Memos from the command line? Not directly — the memos binary only runs the server; it's not a CLI note-taking client. Use the API with a PAT and a tool like curl or httpie for scripted memo creation:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "My memo content", "visibility": "PRIVATE"}' \
  https://memos.example.com/api/v1/memos

Q: Is there an API for developers? Yes. Memos exposes a gRPC-Gateway REST API. The full API is documented in the Admin Guide and the project's proto definitions. Use Personal Access Tokens for authentication.

Q: Does Memos integrate with Obsidian? Not natively, but community plugins exist for syncing between Memos and Obsidian. Search the Obsidian community plugin directory for "memos" integrations.

Privacy and Security

Q: Who can see my Private memos? Only you. Private memos are only accessible when logged in as the owner. They do not appear in search results, the Explore page, RSS feeds, or shared links (unless you generate a specific share link).

Q: Can the server admin read my memos? The server admin has access to the database, which contains all memo content regardless of visibility. This is inherent to self-hosting. If you need memos that your admin cannot read, you would need client-side encryption (not a built-in Memos feature).

Q: Is Memos data encrypted at rest? SQLite itself does not encrypt the database by default. For encryption at rest, encrypt the filesystem or disk volume at the OS level. S3 storage backends can be configured with server-side encryption.

Q: Are shared memo links permanent? Shared links remain valid until you explicitly revoke them (⋯ → Remove share link on the memo). There is no automatic expiration.

Q: Does Memos collect any telemetry? No. Memos does not send any analytics or telemetry to external servers. All data stays on your server.

For architecture, API reference, deployment configuration, security hardening, and operational administration, see the companion Admin Guide.