# 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](#1-quick-start)
2. [Installation](#2-installation)
3. [Configuration](#3-configuration)
4. [Core Usage](#4-core-usage)
5. [Common Tasks](#5-common-tasks)
6. [Advanced Features](#6-advanced-features)
7. [Troubleshooting](#7-troubleshooting)
8. [FAQ](#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

```bash
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

| Step | What to do |
|---|---|
| Invite others | Settings → Members → Add member |
| Set a public URL | Settings → Instance → Instance URL |
| Enable SSO | Settings → SSO |
| Connect an AI client | See §6.5 MCP Integration |
| Change language/theme | Settings → Preferences |

---

## 2. Installation

### 2.1 Docker (Recommended)

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

#### 2.1.1 Minimal Run Command

```bash
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

```bash
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:

```bash
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:

```yaml
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:

```bash
docker compose up -d
```

Expected output:

```
[+] Running 1/1
 ✔ Container memos  Started
```

Check logs:

```bash
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](https://github.com/usememos/memos/releases).

#### Linux/macOS

```bash
# 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:

```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.

```bash
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:

| Priority | Location |
|---|---|
| `--data` flag or `MEMOS_DATA` env | Your specified path |
| `/var/opt/memos` | Used if that path exists and is writable (Docker) |
| Current working directory | Fallback for Linux/macOS |
| `%ProgramData%\memos` | Windows fallback |

The data directory contains:
- `memos_prod.db` — SQLite database (all memos, users, settings)
- Uploaded files (if using local storage)

### 2.5 Upgrading

#### Docker

```bash
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`:
> ```bash
> 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

| Flag | Environment Variable | Type | Default | Description |
|---|---|---|---|---|
| `--addr` | `MEMOS_ADDR` | string | `""` | Network address to bind (e.g., `127.0.0.1`) |
| `--port` | `MEMOS_PORT` | int | `8081` | Port to listen on (Docker default: `5230`) |
| `--unix-sock` | `MEMOS_UNIX_SOCK` | string | `""` | Unix socket path; overrides `--addr`/`--port` |
| `--data` | `MEMOS_DATA` | string | auto | Data directory path |
| `--driver` | `MEMOS_DRIVER` | string | `sqlite` | Database driver: `sqlite`, `mysql`, `postgres` |
| `--dsn` | `MEMOS_DSN` | string | `""` | Database source name / connection string |
| `--instance-url` | `MEMOS_INSTANCE_URL` | string | `""` | Public URL of this instance (used in share links, RSS) |
| `--demo` | `MEMOS_DEMO` | bool | `false` | Enable demo mode (disables write operations) |
| `--allow-private-webhooks` | `MEMOS_ALLOW_PRIVATE_WEBHOOKS` | bool | `false` | Allow webhooks to fire at private/RFC-1918 IPs |

### 3.2 Common Configuration Scenarios

#### Bind to a Specific Address (Localhost Only)

```bash
./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

```yaml
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)

```bash
./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.

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

#### MySQL

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

#### PostgreSQL

```bash
./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:

```bash
./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:

| Area | Purpose |
|---|---|
| **Top bar** | Navigation, search, user menu |
| **Memo editor** | Write new memos |
| **Memo timeline** | Your memos in reverse-chronological order |
| **Left sidebar** | Navigation: Home, Explore, Inbox, Shortcuts |
| **Right sidebar** | Tag tree, filter controls |

### 4.2 The Memo Editor

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

#### Editor Controls

| Control | Action |
|---|---|
| Toolbar buttons | Bold, italic, code, heading, list, etc. |
| `#tag` | Inline tag insertion with autocomplete |
| `/` (slash) | Opens slash command menu |
| Paperclip icon | Attach files |
| Microphone icon | Record voice and transcribe (if AI configured) |
| Map pin icon | Add location tag |
| Visibility dropdown | Public / Protected / Private |
| **Ctrl+Enter** / **Cmd+Enter** | Save memo |
| Focus Mode | Expands editor fullscreen |

#### Visibility Options

| Visibility | Who Sees It |
|---|---|
| **Public** | Anyone, including unauthenticated visitors (Explore page) |
| **Protected** | Logged-in users of this instance |
| **Private** | Only you |

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

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

#### Headings

```markdown
# H1
## H2
### H3
```

#### Lists

```markdown
- Unordered item
- Another item
  - Nested item

1. Ordered item
2. Second item
```

#### Task Lists

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

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

#### Tables

```markdown
| 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:

````markdown
```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:

```markdown
Inline: $E = mc^2$

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

#### Mermaid Diagrams

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

#### Blockquotes

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

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

#### Links and Images

```markdown
[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:

| Storage | Description |
|---|---|
| Local filesystem | Default; files saved in the data directory |
| S3-compatible | Requires admin configuration (AWS S3, MinIO, etc.) |
| Database | Stored directly in SQLite/MySQL/PostgreSQL |

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:

```bash
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**:

| Theme | Description |
|---|---|
| **Default** | Clean, minimal light theme |
| **Default Dark** | Dark version of the default |
| **Paper** | Warm, paper-like aesthetic |

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`):

```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

| Shortcut | Action |
|---|---|
| **Ctrl+Enter** / **Cmd+Enter** | Save memo |
| **/** | Focus search (when not in editor) |
| **Escape** | Close modals, exit editor |

### 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:**
```bash
# 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:

```bash
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:**
```bash
# Fix ownership on the host directory
sudo chown -R 10001:10001 ~/.memos
```

Then restart the container:

```bash
docker restart memos
```

**Prevention:** Create the data directory and set ownership before running the container:
```bash
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:
   ```bash
   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):
   ```bash
   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:**
```bash
# Create the socket directory first
mkdir -p /run/memos
./memos --unix-sock /run/memos/memos.sock
```

If using Docker:
```yaml
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](https://mermaid.live) 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:
```nginx
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:
   ```bash
   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:
```bash
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:

```bash
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.*

---

_Generated May 2026 from usememos/memos at bcbcb03. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._