Memos Administrator & Developer Guide

This guide is the complete operational and architectural reference for administrators, DevOps engineers, and contributors deploying and maintaining Memos v0.26.2 (bcbcb03). For day-to-day usage, note creation, and user-facing features, see the companion User Guide at User Guide.

1. Architecture Overview

Note

Memos is a monolithic binary — a single compiled Go executable that simultaneously serves the REST/gRPC API, the React single-page application, and all static assets. There are no separate frontend or backend processes, no message broker, and no cache daemon. This design makes deployment trivially simple but means all components share one process and one port.

1.1 High-Level Topology

                         ┌───────────────────────────────────────────────┐
                         │              memos binary                      │
                         │                                                │
Internet ──── :8081 ───►│  Echo v5 HTTP Server                          │
  (or Unix sock)         │  ├── /healthz          HealthService           │
                         │  ├── /api/v1/*         gRPC-Gateway → gRPC     │
                         │  ├── /file/attachments  FileServer (HTTP)      │
                         │  ├── /file/users        FileServer (avatars)   │
                         │  ├── /rss/*             RSS feed generator     │
                         │  ├── /mcp               MCP server             │
                         │  └── /*                 SPA (embedded dist/)   │
                         │                                                │
                         │  Background Goroutines                         │
                         │  ├── S3 presign refresher                      │
                         │  └── Memo payload updater                      │
                         │                                                │
                         │  Store Layer                                   │
                         │  ├── In-memory cache                           │
                         │  └── DB driver (SQLite │ MySQL │ PostgreSQL)   │
                         └───────────────────────────────────────────────┘

1.2 Request Lifecycle

1. An HTTP request arrives at the Echo server.
2. The Authenticator middleware resolves the caller's identity from the Authorization header (Bearer JWT or PAT) or the memos_refresh cookie. Anonymous requests proceed with no identity.
3. The request is dispatched to the matching route:
   • /api/v1/* → gRPC-Gateway transcodes JSON↔Protobuf → gRPC service handler.
   • /file/* → Native HTTP file server with range-request and thumbnail support.
   • /mcp → MCP server with CSRF origin validation.
   • /rss/* → RSS generator.
   • Everything else → embedded index.html for SPA client-side routing.
4. gRPC handlers call the Store (cache-first, then DB driver).
5. Response returns through Echo (middleware chain is minimal — recovery only; no global rate limiter).

1.3 Component Map

1.4 Technology Stack

1.5 Startup Sequence

cmd/memos/main.go
  │
  ├─ Parse flags (Cobra + Viper)
  ├─ Build Profile (data dir, addr, port, driver, DSN)
  ├─ Validate Profile (dir writable, driver recognized)
  ├─ Init DB driver (open connection, verify connectivity)
  ├─ Run migrations (store.Migrate())
  ├─ Create Store (driver + cache wrapper)
  ├─ Create Server (server.NewServer())
  │     ├─ Create Echo instance
  │     ├─ Register recovery middleware
  │     ├─ Get/create basic instance setting (secret_key, schema_version)
  │     ├─ Register /healthz
  │     ├─ Register frontend static files (embedded)
  │     ├─ Create gRPC server + register all services
  │     ├─ Create gRPC-Gateway (HTTP/JSON bridge)
  │     ├─ Register file server routes
  │     ├─ Create + register RSS routes
  │     ├─ Register gRPC-Gateway routes (/api/v1/*)
  │     ├─ Register MCP server (/mcp)
  │     └─ Start background runners (S3 presign, memo payload)
  └─ server.Start() → listen + signal handling (SIGTERM/SIGINT)
        └─ Graceful shutdown:
              stop runners → close SSE hub → shutdown HTTP → wait runners → close DB

1.6 gRPC Services

All gRPC services are defined in proto/api/v1/ and exposed over HTTP via gRPC-Gateway at /api/v1/. The web frontend communicates using ConnectRPC (a browser-compatible gRPC transport).

2. System Requirements

2.1 Minimum Requirements

2.2 Database Requirements

Note

SQLite uses a pure Go driver (no CGO). The binary runs on any platform without external libraries. For production workloads with multiple concurrent writers, MySQL or PostgreSQL are recommended.

2.3 Network Requirements

Memos does not open any outbound ports during normal operation. Outbound connections occur only for:

• S3 storage (user-configured endpoint)
• OAuth2 identity providers (user-configured)
• SMTP email (user-configured)
• Webhook delivery (outbound to configured URLs)
• AI providers (OpenAI/Gemini endpoints)

2.4 Storage Requirements

3. Configuration Reference

Important

Memos has two configuration layers: CLI flags (and their environment variable equivalents) set server-level parameters at startup, and instance settings (stored in the database) control runtime behavior and can be changed live through the admin UI without restarting the server. CLI flags cannot be changed without a restart.

3.1 CLI Flags

All flags can be set as environment variables using the MEMOS_ prefix and upper-casing the flag name (e.g., --port → MEMOS_PORT).

Default data directory by platform:

• Linux: ~/.memos/
• macOS: ~/Library/Application Support/memos/
• Windows: %APPDATA%\memos\

DSN formats:

# MySQL
--dsn "user:password@tcp(host:3306)/memos?parseTime=true"

# PostgreSQL
--dsn "host=localhost port=5432 user=memos password=secret dbname=memos sslmode=disable"

# SQLite (explicit path)
--dsn "/data/memos.db"

3.2 Instance Settings

These settings live in the instance_setting table and are managed through Settings → Admin in the UI or via the InstanceService gRPC API. They take effect immediately without restarting the server.

3.2.1 Basic Settings

3.2.2 General Settings

3.2.3 Storage Settings

S3 configuration (only active when storage_type = S3):

3.2.4 Memo Settings

3.2.5 Tag Settings

Tags can have per-tag metadata stored in the instance settings:

3.2.6 Notification (Email) Settings

3.2.7 AI Provider Settings

Multiple AI providers can be configured simultaneously:

4. Deployment & Scaling

4.1 Docker Deployment (Recommended)

# Create data directory
mkdir -p /opt/memos

# Run with SQLite (default)
docker run -d \
  --name memos \
  -p 8081:8081 \
  -v /opt/memos:/var/opt/memos \
  -e MEMOS_DATA=/var/opt/memos \
  --restart unless-stopped \
  neosmemo/memos:0.26.2

# Run with PostgreSQL
docker run -d \
  --name memos \
  -p 8081:8081 \
  -e MEMOS_DRIVER=postgres \
  -e MEMOS_DSN="host=db port=5432 user=memos password=secret dbname=memos sslmode=disable" \
  -e MEMOS_INSTANCE_URL="https://memos.example.com" \
  --restart unless-stopped \
  neosmemo/memos:0.26.2

The Docker image runs as non-root uid 10001 for security hardening.

4.2 Docker Compose

# docker-compose.yml
services:
  memos:
    image: neosmemo/memos:0.26.2
    container_name: memos
    ports:
      - "8081:8081"
    volumes:
      - memos_data:/var/opt/memos
    environment:
      MEMOS_DATA: /var/opt/memos
      MEMOS_INSTANCE_URL: https://memos.example.com
    restart: unless-stopped

  # Optional: PostgreSQL backend
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: memos
      POSTGRES_USER: memos
      POSTGRES_PASSWORD: changeme
    volumes:
      - pg_data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  memos_data:
  pg_data:

# docker-compose.yml with PostgreSQL backend
services:
  memos:
    image: neosmemo/memos:0.26.2
    environment:
      MEMOS_DRIVER: postgres
      MEMOS_DSN: "host=db port=5432 user=memos password=changeme dbname=memos sslmode=disable"
      MEMOS_INSTANCE_URL: https://memos.example.com
    depends_on:
      - db
    ports:
      - "8081:8081"
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: memos
      POSTGRES_USER: memos
      POSTGRES_PASSWORD: changeme
    volumes:
      - pg_data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  pg_data:

4.3 Reverse Proxy (Nginx)

# /etc/nginx/sites-available/memos
server {
    listen 80;
    server_name memos.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name memos.example.com;

    ssl_certificate     /etc/letsencrypt/live/memos.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/memos.example.com/privkey.pem;

    # Increase for attachment uploads
    client_max_body_size 64m;

    location / {
        proxy_pass http://127.0.0.1:8081;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # SSE support (HealthService stream)
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 3600s;
    }
}

Important

When running behind a reverse proxy, set --instance-url to the public URL (e.g., https://memos.example.com). This URL is used in RSS feeds, email notifications, and MCP resource references. Without it, generated links will be incorrect.

4.4 Caddy Reverse Proxy

memos.example.com {
    reverse_proxy localhost:8081 {
        header_up Host {host}
    }
    # Caddy handles TLS automatically
}

4.5 Binary Deployment (Without Docker)

# Download release binary
wget https://github.com/usememos/memos/releases/download/v0.26.2/memos_linux_amd64.tar.gz
tar xf memos_linux_amd64.tar.gz

# Run
./memos \
  --data /opt/memos \
  --port 8081 \
  --instance-url https://memos.example.com

# As a systemd service
cat > /etc/systemd/system/memos.service << 'EOF'
[Unit]
Description=Memos - Self-hosted note-taking service
After=network.target

[Service]
Type=simple
User=memos
Group=memos
ExecStart=/usr/local/bin/memos \
  --data /var/opt/memos \
  --port 8081 \
  --instance-url https://memos.example.com
Restart=on-failure
RestartSec=5s
Environment=MEMOS_DATA=/var/opt/memos

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now memos

4.6 Building from Source

# Prerequisites: Go 1.26.1+, Node.js 20+

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

# Build frontend
cd web
npm install
npm run build
# Output goes to ../server/router/frontend/dist/
cd ..

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

# Cross-compile for Linux arm64
GOOS=linux GOARCH=arm64 go build -o memos-linux-arm64 ./cmd/memos/main.go

4.7 Unix Socket Deployment

For setups where the reverse proxy is on the same host, Unix socket is slightly more efficient than TCP:

memos --unix-sock /run/memos/memos.sock --data /var/opt/memos

# Nginx upstream
upstream memos {
    server unix:/run/memos/memos.sock;
}

Note

When --unix-sock is set, --addr and --port are ignored. Ensure the reverse proxy user has read/write permission on the socket file. See GitHub issue #5827 for reported permission edge cases with some configurations.

4.8 Scaling Considerations

Memos is designed as a single-instance application. Key limitations for horizontal scaling:

Recommended scaling approach: Vertical scaling (more RAM/CPU on one instance) + offload attachments to S3.

For high availability, a primary/standby setup with a shared PostgreSQL or MySQL backend and shared S3 storage is the most practical approach. Only one instance should be active at a time to avoid cache inconsistency.

5. Database Administration

5.1 Schema Overview

The row_status column on user and memo acts as a soft-delete flag: NORMAL (active) or ARCHIVED.

5.2 Migrations

Migrations run automatically at startup via store.Migrate(). There is no manual migration step.

• SQLite: store/migration/sqlite/ — plain SQL files versioned 0.2 through 0.27
• MySQL: store/migration/mysql/ — same version range, MySQL-compatible SQL
• PostgreSQL: store/migration/postgres/ — same version range, PostgreSQL-compatible SQL

The current schema version is tracked in the instance_setting table under the schema_version key. Memos will not downgrade a schema; always back up before upgrading.

5.3 SQLite Administration

# Direct SQLite access (stop memos first for safety)
sqlite3 /var/opt/memos/memos.db

# Backup
sqlite3 /var/opt/memos/memos.db ".backup '/backup/memos_$(date +%Y%m%d).db'"

# Online backup (safe while running, uses SQLite backup API)
sqlite3 /var/opt/memos/memos.db "VACUUM INTO '/backup/memos_$(date +%Y%m%d).db'"

# Check integrity
sqlite3 /var/opt/memos/memos.db "PRAGMA integrity_check;"

# Reclaim space after deletions
sqlite3 /var/opt/memos/memos.db "VACUUM;"

# WAL mode (enabled by Memos automatically)
sqlite3 /var/opt/memos/memos.db "PRAGMA journal_mode;"

SQLite is opened with WAL (Write-Ahead Logging) mode and foreign keys enabled. Do not change these pragmas externally.

5.4 PostgreSQL Administration

# Create database and user
psql -U postgres << 'SQL'
CREATE USER memos WITH PASSWORD 'strongpassword';
CREATE DATABASE memos OWNER memos;
GRANT ALL PRIVILEGES ON DATABASE memos TO memos;
SQL

# Backup
pg_dump -U memos -h localhost memos | gzip > memos_$(date +%Y%m%d).sql.gz

# Restore
gunzip -c memos_20261101.sql.gz | psql -U memos -h localhost memos

# Connection string
MEMOS_DSN="host=localhost port=5432 user=memos password=strongpassword dbname=memos sslmode=require"

5.5 MySQL Administration

# Create database and user
mysql -u root -p << 'SQL'
CREATE DATABASE memos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'memos'@'%' IDENTIFIED BY 'strongpassword';
GRANT ALL PRIVILEGES ON memos.* TO 'memos'@'%';
FLUSH PRIVILEGES;
SQL

# Backup
mysqldump -u memos -p memos | gzip > memos_$(date +%Y%m%d).sql.gz

# Connection string
MEMOS_DSN="memos:strongpassword@tcp(localhost:3306)/memos?parseTime=true&charset=utf8mb4"

5.6 Database Migration (SQLite → PostgreSQL)

There is no official automated migration tool. The recommended approach:

1. Export data via the API (using PATs or admin credentials)
2. Create a fresh PostgreSQL instance
3. Re-import via the API, or use a data-transfer script against both databases directly

For large instances, a custom Go script that reads from SQLite and writes to PostgreSQL through the Store interface is the most reliable approach.

6. Operations

Note

Memos is stateless at the process level — all persistent state lives in the database and (optionally) the filesystem/S3. Restarting the process is always safe. The main operational concern is the data directory and database file.

6.1 Health Checks

# HTTP health check (no auth required)
curl http://localhost:8081/healthz
# Expected response: 200 OK with JSON body

# Container health check (Docker)
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:8081/healthz || exit 1

6.2 Log Management

Memos logs to stdout in plain text format. Capture logs via your container runtime or systemd:

# Docker
docker logs memos --follow

# Systemd
journalctl -u memos -f

# Filter for errors
journalctl -u memos | grep -i "error\|panic\|fatal"

There is no built-in log rotation or structured JSON logging. For production, pipe stdout to a log aggregator (Loki, Datadog, CloudWatch, etc.).

6.3 Backup Strategy

#!/bin/bash
# Simple SQLite backup script
BACKUP_DIR=/backup/memos
mkdir -p "$BACKUP_DIR"

# Keep 30 days
find "$BACKUP_DIR" -name "*.db" -mtime +30 -delete

sqlite3 /var/opt/memos/memos.db "VACUUM INTO '$BACKUP_DIR/memos_$(date +%Y%m%d_%H%M%S).db'"
echo "Backup complete: $BACKUP_DIR/memos_$(date +%Y%m%d_%H%M%S).db"

6.4 Upgrade Procedure

# 1. Back up data
sqlite3 /var/opt/memos/memos.db "VACUUM INTO '/backup/memos_pre_upgrade.db'"

# 2. Pull new image (Docker)
docker pull neosmemo/memos:0.26.2

# 3. Stop old container
docker stop memos && docker rm memos

# 4. Start new container (migrations run automatically)
docker run -d \
  --name memos \
  -p 8081:8081 \
  -v /opt/memos:/var/opt/memos \
  -e MEMOS_DATA=/var/opt/memos \
  --restart unless-stopped \
  neosmemo/memos:0.26.2

# 5. Verify health
curl http://localhost:8081/healthz

Note

Schema migrations run automatically on startup. Downgrading to an older version after a migration is not supported and may corrupt data. Always back up before upgrading.

6.5 User Management via API

# Set API key from user settings → Personal Access Tokens
MEMOS_API_KEY="memos_pat_..."
BASE="https://memos.example.com"

# List users (admin only)
curl -H "Authorization: Bearer $MEMOS_API_KEY" "$BASE/api/v1/users"

# Get account info
curl -H "Authorization: Bearer $MEMOS_API_KEY" "$BASE/api/v1/auth/status"

# Update instance settings (admin only)
curl -X PATCH \
  -H "Authorization: Bearer $MEMOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"setting": {"general_setting": {"disallow_user_registration": true}}}' \
  "$BASE/api/v1/instance/setting"

6.6 Background Runners

Two background goroutines run for the lifetime of the server process:

Both runners participate in the graceful shutdown sequence. They are stopped before the HTTP server closes, and the main goroutine waits for them to finish before closing the database.

6.7 SSE (Server-Sent Events)

The sse_hub.go component maintains a registry of open SSE connections for real-time updates (new memos, changes). During graceful shutdown, all SSE connections are closed before the HTTP server shuts down to prevent client-side errors.

# SSE endpoint (authenticated)
curl -N \
  -H "Authorization: Bearer $MEMOS_API_KEY" \
  "https://memos.example.com/api/v1/events"

6.8 Thumbnail Cache

Thumbnails are generated on-demand for image attachments and cached in .thumbnail_cache/ within the data directory. Generation is semaphore-limited to 3 concurrent operations to prevent CPU spikes.

# Clear thumbnail cache (safe; regenerated on demand)
rm -rf /var/opt/memos/.thumbnail_cache/

# Thumbnail specs: max 600px on longest side, JPEG output

7. Security

Warning

Memos does not implement rate limiting or request throttling at the application level. If exposed to the public internet, configure rate limiting at the reverse proxy or firewall level to prevent brute-force attacks on the login endpoint.

7.1 Authentication System

Memos uses a dual-token JWT system:

Access token flow:

1. User signs in → server returns access token + sets memos_refresh cookie
2. Frontend uses access token in Authorization: Bearer <token> header
3. When access token expires, frontend calls the token-refresh endpoint
4. Refresh token in cookie is validated against DB → new access token issued

PAT flow:

• User generates PAT in settings → shown once, never stored in plaintext
• PAT is hashed (bcrypt) and stored in DB
• API requests include PAT as Authorization: Bearer memos_pat_...
• Server hashes incoming PAT and compares to stored hash

Password hashing: bcrypt with default cost factor.

JWT signing: HMAC-SHA256 with the secret_key instance setting (auto-generated UUID on first run).

Caution

Rotating the secret_key in instance settings immediately invalidates all existing sessions and refresh tokens. All users will be logged out. PATs are stored separately and are not affected by secret_key rotation.

7.2 Authorization (ACL)

Role-based access control is enforced at the gRPC method level via acl_config.go:

The first user registered on a fresh instance is automatically assigned the ADMIN role.

7.3 SSRF Protection

Warning

Webhook URLs are validated before delivery using SSRF protection logic in internal/webhook/. URLs resolving to reserved/private IP ranges (RFC 1918, loopback, link-local, etc.) are blocked by default. Use --allow-private-webhooks to allow webhooks to private IPs — only do this in trusted internal networks.

Blocked ranges include:

• 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 (RFC 1918)
• 127.0.0.0/8 (loopback)
• 169.254.0.0/16 (link-local)
• ::1/128, fc00::/7 (IPv6 private)

7.4 XSS Prevention

7.5 CSRF Protection

MCP endpoints (/mcp) validate the Origin header to prevent cross-site request forgery. The validation rejects requests whose origin does not match the instance URL.

7.6 Input Validation

7.7 TLS

Memos does not terminate TLS. TLS must be handled by a reverse proxy (Nginx, Caddy, Traefik). For direct TLS (no reverse proxy), wrap memos with a TLS-terminating proxy on the same host.

7.8 Docker Security

The official Docker image:

• Runs as uid 10001 (non-root)
• Does not require --privileged
• Needs write access only to the data volume mount point

# Verify the data directory is writable by uid 10001
chown -R 10001:10001 /opt/memos

7.9 Secrets Management

There is no dedicated secrets management integration (e.g., Vault, AWS Secrets Manager). All secrets are stored in the database in plaintext. Protect database access accordingly.

8. Developer Internals

8.1 Store Layer

The store layer (store/) provides the data access interface. It follows a driver interface + cache wrapper pattern:

Application code
    ↓
store.Store (interface)
    ↓
store/cache/ (in-memory cache, LRU-style)
    ↓
store/db/{sqlite,mysql,postgres}/ (SQL driver implementation)
    ↓
Database

Key design decisions:

• All DB operations use parameterized queries — no raw string interpolation
• WAL mode (SQLite) and FK enforcement are set on connection open
• The cache layer wraps the driver; cache invalidation is manual (called after writes)
• No ORM — raw SQL with database/sql

8.2 CEL Filter Engine

The filter engine in internal/filter/ implements Google's Common Expression Language (CEL) for memo queries. CEL expressions are compiled at parse time and evaluated against memo records, enabling expressive and safe server-side filtering without SQL injection risk.

This engine powers:

• The MemoService.ListMemos filter parameter
• MCP tool list_memos and search_memos
• Saved shortcuts

Example filter expressions (used internally, exposed via API):

visibility == "PUBLIC"
creator == "users/1" && tag in ["work", "project"]
content.contains("meeting notes")

8.3 Markdown Processing

The backend markdown processor (internal/markdown/) extends Goldmark with custom extensions:

• Tag parser: extracts #tag patterns into structured tag metadata stored in memo payload
• Mention parser: extracts @username mentions for inbox notifications

The frontend uses react-markdown for rendering. The two processors must remain compatible in their interpretation of Memos-specific syntax.

8.4 Webhook System

internal/webhook/ delivers outbound webhooks when memo events occur:

• Events: memo created, updated, deleted
• Payload: JSON with event type + memo data
• SSRF protection: destination URL validated before each delivery
• No retry logic — single-attempt delivery
• Timeout: standard Go HTTP client timeout

8.5 AI Integration

internal/ai/ provides a thin wrapper over external AI providers:

The AIService gRPC endpoint accepts audio or image attachments and returns transcribed text. Multiple providers can be configured; the client selects by provider ID.

8.6 MCP Server

The MCP (Model Context Protocol) server at /mcp exposes Memos as a tool-callable data source for AI assistants (Claude, etc.).

Available tools:

Resources: memo://memos/{uid} — individual memo content

Prompts: capture, review, daily_digest, organize

Authentication: MCP requests use the same PAT/JWT auth as the REST API. The MCP server enforces ACL identically to gRPC handlers.

CSRF: Origin header validated; requests from untrusted origins are rejected.

8.7 RSS Feeds

The RSS service (server/router/rss/) generates Atom/RSS feeds for public memos. The instance URL (--instance-url) must be set for feed links to be correct.

Feed URLs follow the pattern: GET /rss/{username} for per-user public memo feeds.

8.8 File Server

server/router/fileserver/ handles attachment binary serving with these features:

8.9 OAuth2 Identity Providers

internal/idp/ implements the OAuth2 authorization code flow for SSO:

1. Admin creates an IDP record via IDPService (client ID, secret, auth URL, token URL, scopes)
2. Users click "Sign in with {provider}" → redirected to OAuth2 authorization URL
3. Provider redirects back with authorization code → Memos exchanges for tokens
4. User email/identifier extracted from ID token or userinfo endpoint
5. If identifier_filter is set on the IDP, only matching identifiers can sign in
6. Existing user matched by email; new user created if registration is allowed

8.10 Scheduler and Cron

internal/scheduler/ provides a generic job scheduler with middleware support (logging, error recovery). internal/cron/ is a lightweight cron expression parser. These are used for the background runners but can be extended for future scheduled operations.

8.11 gRPC-Gateway and ConnectRPC

Memos uses two HTTP-to-gRPC bridges:

• gRPC-Gateway: generates RESTful JSON endpoints at /api/v1/* from protobuf service definitions. Used by third-party API clients and curl-based integrations.
• ConnectRPC: browser-compatible gRPC transport used by the React frontend. More efficient than gRPC-Gateway for browser clients (avoids base64 encoding overhead).

Both bridges talk to the same Go gRPC service handlers — the logic is written once in gRPC and exposed via both transports.

8.12 Version Management

internal/version/ provides version parsing and comparison utilities. The application version is embedded at build time. Migration files are compared against the stored schema_version to determine which migrations need to run.

9. Integration Points

9.1 REST API Reference

All endpoints are served at https://{instance}/api/v1/. Authentication via Authorization: Bearer {token} (access token or PAT).

Note

The canonical API definition is the protobuf files in proto/api/v1/. The gRPC-Gateway generates HTTP/JSON bindings from them. When in doubt, the proto definition is authoritative.

9.2 Personal Access Tokens

PATs are the recommended authentication method for automation and integrations:

# Generate via UI: Settings → Personal Access Tokens → Create

# Use in API calls
curl -H "Authorization: Bearer memos_pat_..." \
  https://memos.example.com/api/v1/memos

# Use with MCP clients (e.g., Claude Desktop)
# In claude_desktop_config.json:
{
  "mcpServers": {
    "memos": {
      "command": "curl",
      "args": ["-N", "https://memos.example.com/mcp"],
      "headers": {
        "Authorization": "Bearer memos_pat_..."
      }
    }
  }
}

9.3 MCP Integration

Configure Memos as an MCP data source for AI assistants:

// Claude Desktop MCP configuration
{
  "mcpServers": {
    "memos": {
      "type": "http",
      "url": "https://memos.example.com/mcp",
      "headers": {
        "Authorization": "Bearer memos_pat_your_token_here"
      }
    }
  }
}

9.4 Webhooks

Configure webhooks in user settings to receive event notifications:

// Webhook payload shape (memo created)
{
  "event": "memo.created",
  "memo": {
    "name": "memos/abc123",
    "content": "Note content...",
    "visibility": "PRIVATE",
    "createTime": "2026-05-07T10:00:00Z"
  }
}

Warning

Webhooks are single-attempt with no retry. If the destination is unreliable, implement idempotent handling and use a queuing layer on the receiving end. Private IP destinations are blocked by default (SSRF protection).

9.5 RSS Feeds

# Per-user public memo feed
GET /rss/{username}

# Example
https://memos.example.com/rss/alice

Feeds contain all PUBLIC memos for the specified user. The instance URL must be configured (--instance-url) for feed links to resolve correctly.

9.6 S3-Compatible Storage Integration

# MinIO example
# Instance settings (via admin UI or API):
{
  "storage_type": "S3",
  "s3_config": {
    "endpoint": "https://minio.example.com",
    "region": "us-east-1",
    "bucket": "memos-attachments",
    "access_key_id": "minioadmin",
    "access_key_secret": "minioadmin",
    "use_path_style": true
  }
}

# Cloudflare R2 example
{
  "storage_type": "S3",
  "s3_config": {
    "endpoint": "https://<account>.r2.cloudflarestorage.com",
    "region": "auto",
    "bucket": "memos",
    "access_key_id": "<R2 access key>",
    "access_key_secret": "<R2 secret>",
    "use_path_style": false
  }
}

9.7 OAuth2 SSO Configuration

# Create IDP via API (admin)
curl -X POST \
  -H "Authorization: Bearer $ADMIN_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "identityProvider": {
      "name": "Google SSO",
      "type": "OAUTH2",
      "config": {
        "client_id": "xxx.apps.googleusercontent.com",
        "client_secret": "xxx",
        "auth_url": "https://accounts.google.com/o/oauth2/auth",
        "token_url": "https://oauth2.googleapis.com/token",
        "scopes": ["openid", "email", "profile"],
        "field_mapping": {
          "identifier": "email",
          "display_name": "name"
        }
      }
    }
  }' \
  https://memos.example.com/api/v1/identityProviders

10. Troubleshooting

Tip

Before investigating application-level issues, verify the health endpoint responds: curl http://localhost:8081/healthz. A non-200 response or connection refused means the process is not running or not bound to the expected address.

10.1 Common Issues

Tip

When troubleshooting attachment issues, always check the storage_type setting first. A mismatch between stored storage_type on individual attachment records and the current instance-level setting is the most common cause of broken attachment links.

10.2 Database Diagnostics

# SQLite: check for corruption
sqlite3 /var/opt/memos/memos.db "PRAGMA integrity_check;"

# SQLite: check WAL status
sqlite3 /var/opt/memos/memos.db "PRAGMA journal_mode; PRAGMA wal_checkpoint;"

# Check schema version
sqlite3 /var/opt/memos/memos.db \
  "SELECT value FROM instance_setting WHERE name = 'schema_version';"

# List all users
sqlite3 /var/opt/memos/memos.db \
  "SELECT id, username, role, row_status FROM user;"

# Count memos by visibility
sqlite3 /var/opt/memos/memos.db \
  "SELECT visibility, COUNT(*) FROM memo GROUP BY visibility;"

10.3 Authentication Diagnostics

# Decode JWT (for debugging — do not use in production)
# JWT is base64-encoded; inspect payload
echo "eyJ..." | cut -d. -f2 | base64 -d | jq .

# Check refresh token in cookie
# Browser DevTools → Application → Cookies → memos_refresh

# Revoke all sessions for a user (admin — delete refresh tokens from DB)
sqlite3 /var/opt/memos/memos.db \
  "DELETE FROM user_setting WHERE user_id = <uid> AND key = 'refresh_token';"

10.4 Performance Diagnostics

# Check memo count
sqlite3 /var/opt/memos/memos.db "SELECT COUNT(*) FROM memo WHERE row_status = 'NORMAL';"

# Check attachment storage usage
sqlite3 /var/opt/memos/memos.db "SELECT storage_type, COUNT(*), SUM(size)/1024/1024 AS total_mb FROM attachment GROUP BY storage_type;"

# Check thumbnail cache size
du -sh /var/opt/memos/.thumbnail_cache/

# Docker resource usage
docker stats memos --no-stream

11. Module Reference

11.1 cmd/memos/main.go

Entry point. Registers the root Cobra command with all CLI flags. Initializes the profile from flags/env, calls store.Migrate(), constructs the Store, constructs the Server, and calls server.Start(). Signal handling (SIGTERM/SIGINT) triggers graceful shutdown.

11.2 server/server.go

Creates and configures the Echo HTTP server. Responsibilities: middleware registration (recovery), health endpoint, static file embedding, gRPC server setup, gRPC-Gateway bridge, file server routes, RSS routes, MCP registration, background runner startup, graceful shutdown coordination.

11.3 server/auth/

Implements the Authenticator middleware. Extracts credentials from Authorization: Bearer header (both PATs and JWTs) and the memos_refresh HttpOnly cookie. Validates JWTs against the secret_key. For PATs: bcrypt hash comparison against DB. Populates the Echo context with the resolved user identity for downstream handlers.

11.4 server/router/api/v1/

Contains all gRPC service handler implementations. One Go file per service (e.g., memo_service.go, user_service.go). acl_config.go defines which gRPC methods require which roles. sse_hub.go manages the in-memory SSE connection registry.

11.5 server/router/fileserver/

Native HTTP handler for GET /file/attachments/{uid}/{filename} and GET /file/users/{identifier}/avatar. Implements:

• Content-type detection with SVG/HTML override to application/octet-stream
• Range request parsing and response for video/audio streaming
• On-demand thumbnail generation with .thumbnail_cache/ persistence
• Cache-Control: public, max-age=3600 header
• S3 presigned URL redirect for S3-stored attachments

11.6 server/router/frontend/

Serves the embedded React SPA. The frontend build output (web/dist/) is embedded into the binary at compile time via Go's embed package. All routes not matched by other handlers return index.html, enabling client-side routing.

11.7 server/router/mcp/

Implements the MCP server using the mcp-go library. Registers all tools, resources, and prompts. Enforces CSRF via Origin header validation. All tool calls go through the same Store layer as gRPC handlers.

11.8 server/router/rss/

Generates RSS/Atom XML feeds for public memos. Reads PUBLIC memos from the Store, formats them as feed items, and returns the feed document.

11.9 store/

The data access interface (Store) is defined here. Implementations in store/db/{sqlite,mysql,postgres}/ provide driver-specific SQL. The cache wrapper in store/cache/ intercepts reads (returning cached values) and writes (invalidating cache entries). Migrations in store/migration/ are plain SQL files, one per schema version.

11.10 internal/filter/

CEL (Common Expression Language) filter engine. Takes a filter string, compiles it to a CEL program, and evaluates it against memo records. Used by MemoService.ListMemos and MCP tools to implement server-side memo filtering without ad-hoc SQL construction.

11.11 internal/markdown/

Goldmark-based markdown processor. Custom extensions:

• Tag extractor: parses #tag tokens, extracts tag names, stores in memo payload JSON
• Mention extractor: parses @username tokens, creates inbox notifications

11.12 internal/webhook/

Outbound webhook delivery. Before making the HTTP request, validates the destination URL against reserved CIDR blocks (SSRF protection). Single-attempt delivery with standard HTTP timeout. No retry queue.

11.13 internal/ai/

Thin client wrappers for OpenAI and Google Gemini APIs. Used by AIService for audio transcription and image-to-text. Provider selection is by configured provider ID. API keys are stored in instance settings.

11.14 internal/email/

SMTP email client. Supports STARTTLS and implicit SSL/TLS. Used for account notifications. Configuration in instance settings (email_config.*). No email queuing — delivery is synchronous.

11.15 internal/idp/

OAuth2 identity provider client. Implements the authorization code flow: generates auth URL, exchanges code for tokens, fetches user info, applies identifier_filter. Supports any standard OAuth2 provider.

11.16 internal/profile/

Defines the Profile struct that holds the resolved runtime configuration (data dir, addr, port, driver, DSN, instance URL, etc.). Populated from CLI flags at startup and passed to all major components.

11.17 internal/storage/s3/

S3 client wrapper using the AWS SDK. Handles upload, download (presigned URL generation), and deletion. Used by both the file server (for serving) and the S3 presign runner (for URL refresh).

11.18 web/

React 18 SPA built with Vite and TypeScript. Key libraries: Tailwind CSS 4 (styling), Radix UI (headless components), TanStack React Query (server state), react-markdown (markdown rendering), ConnectRPC (gRPC transport). The build output is embedded into the Go binary at compile time.