Memos API

Memos (usememos.com) is an open-source, self-hosted note-taking server. Its API is generated from Protocol Buffers via grpc-gateway, so it looks like a clean AIP-style REST API on the surface - but several of its request/response conventions are non-obvious and will silently do the wrong thing if you guess at them (unwrapped request bodies, snake_case field masks against a camelCase body, oneof settings that fully replace rather than merge). This skill wraps that surface area in a tested Python client so you get correct behavior by default, plus a full reference for anything the wrapper doesn't cover.

Before you start: get server + token

Every action needs two things:

1. Server URL - e.g. https://memos.example.com, or http://localhost:5230 for a local/self-hosted instance. Ask the user for this if it's not already clear from context (don't assume usememos.com's hosted cloud).
2. A Bearer token - a Personal Access Token (looks like memos_pat_xxxxxxxx) is what you want for anything beyond a single quick call. If the user doesn't have one yet:
   • If they can sign in with a username/password, run signin --username ... --password ... to get a short-lived session token, then immediately user pat-create users/<username> --description "..." with that session token to mint a long-lived PAT. The raw token value is only shown once - capture it immediately, you cannot retrieve it again later (only re-list its metadata).
   • If this is a brand-new, freshly-deployed instance with no users yet, the very first user create --username ... --password ... call succeeds without authentication and automatically becomes the admin account - this is how you bootstrap a self-hosted instance from scratch. See references/api_reference.md gotcha #6.

Configure both once per session and every subcommand picks them up:

export MEMOS_URL=https://memos.example.com
export MEMOS_API_KEY=memos_pat_xxxxxxxx
python3 scripts/memos_client.py profile          # sanity check - no auth needed
python3 scripts/memos_client.py whoami           # confirms the token works

Or pass them per-call with --server/--token instead of environment variables - useful when juggling more than one Memos instance in the same session.

Running commands

python3 scripts/memos_client.py <resource> <action> [args...]

The script has no third-party dependencies (pure standard library), so it runs anywhere Python 3.7+ is available - no pip install needed. Run python3 scripts/memos_client.py --help or <resource> --help (e.g. memo --help) any time to see the exact flags for a subcommand; the flags mirror what's documented below and in the reference file, but --help is the fast way to double check without leaving the terminal.

Resource groups: memo, attachment, user, shortcut, idp (identity provider), instance, ai, plus top-level profile/whoami/signin/ signout/refresh-token.

Common recipes:

# Create a memo with tags (tags are just #hashtags inside the content)
python3 scripts/memos_client.py memo create --content "Grocery list #todo\n- milk\n- eggs"

# Search/list memos with a filter (CEL syntax) and pagination
python3 scripts/memos_client.py memo list --filter 'visibility == "PUBLIC"' --all

# Update just one or two fields - only what you --set changes
python3 scripts/memos_client.py memo update memos/abc123 --set pinned=true

# Upload a file and link it to a memo
python3 scripts/memos_client.py attachment create --file ./photo.png --memo memos/abc123

# Download an attachment's actual bytes
python3 scripts/memos_client.py attachment download attachments/xyz789 --output photo.png

# Anything not covered by a subcommand - call the endpoint directly
python3 scripts/memos_client.py raw GET /api/v1/memos --query pageSize=5
python3 scripts/memos_client.py raw POST /api/v1/memos:someFutureEndpoint --body '{"foo":"bar"}'

Every subcommand prints the parsed JSON response to stdout. Errors print a Memos API error: HTTP <status> (grpc code <n>): <message> line to stderr and exit non-zero - check that message first, it's usually specific enough to act on directly (e.g. permission denied, memo not found).

Things worth knowing before you improvise a request by hand

If you ever reach for raw or write a request yourself instead of using a wrapped subcommand, these are the details that actually matter (full explanations with examples in references/api_reference.md):

• Request bodies for create/update calls are "unwrapped." POST /api/v1/memos takes {"content": "..."} directly - NOT {"memo": {"content": "..."}}. Same pattern for users, attachments, shortcuts, identity providers, and settings. Wrapping the body in an extra layer doesn't error loudly; it just silently produces empty required fields.
• updateMask wants snake_case proto field names, the body wants camelCase JSON. PATCH .../users/alice?updateMask=display_name with body {"displayName": "Ada"} - mixing this up gets you invalid update path: displayName. The --set key=value flags on memo update, user update, shortcut update, idp update, and the settings-update commands handle this conversion for you automatically, including for dotted/nested keys like --set generalSetting.disallowUserRegistration=true.
• Instance and user settings currently do a full replace, not a merge, when you PATCH them - whatever sub-object you send becomes the entire new setting, and any field you omit reverts to its zero value. Always instance setting-get <KEY> (or user setting-get) first, merge your change into the full object, and send that back - don't PATCH with just the one field you care about.
• memo create --pinned and a plain POST /api/v1/memos with "pinned": true are not the same thing - the create endpoint only persists content/visibility, so pinning requires a follow-up update. The wrapped memo create --pinned already does this for you.
• Attachment bytes go in as base64 in the create request, but come back out through a different, non-/api/v1 route: GET /file/{attachment_name}/{filename}. attachment download handles this for you.

When to read the full reference

references/api_reference.md has the complete endpoint table for all eight services (Auth, Instance, Memo, Attachment, User, Shortcut, Identity Provider, AI) with exact request/response shapes - reach for it when: the task needs an endpoint that isn't wrapped as a friendly subcommand (use raw plus the reference's request shape), the user asks something about permissions/roles/visibility rules, or a raw call fails and you need to know the exact expected body shape rather than guessing again.