memos-api-skill

A dependency-free Python client and reference guide for the Memos REST API - works against the official cloud offering, a self-hosted Docker deployment, or a bare-metal binary behind any domain.

This repository is both:

• A standalone command-line client (scripts/memos_client.py) you can use directly, no Claude required.
• An Agent Skill for Claude - drop the folder into a Claude Code / Claude Desktop / Cowork skills directory and Claude will use it automatically whenever you ask it to do something with a Memos instance.

It was built by driving a real, locally-running Memos server through every endpoint rather than just reading the OpenAPI spec, which surfaced a few request-shape quirks the official docs don't mention (see Gotchas below).

Why this exists

The Memos API is generated from Protocol Buffers via grpc-gateway, so it looks like a clean REST API on the surface, but several of its conventions are easy to get wrong by hand:

• Request bodies for create/update calls are unwrapped ({"content": "..."}, not {"memo": {"content": "..."}}).
• The updateMask query parameter needs snake_case proto field names, while the request body itself is camelCase JSON.
• Instance and user settings are oneof-wrapped and currently do a full replace rather than a partial merge when you PATCH them.
• CreateMemo silently ignores fields like pinned - only content/visibility/timestamps persist on creation.
• Attachment bytes go in as base64 on create, but always come back empty on read - the actual file is served from a separate, non-/api/v1 route.

scripts/memos_client.py handles all of this for you. references/api_reference.md documents it in full, with a complete endpoint catalogue across all eight Memos services (Auth, Instance, Memo, Attachment, User, Shortcut, Identity Provider, AI).

Quick start

Requires only Python 3.7+ (standard library only, nothing to install).

git clone https://github.com/mathewcsims/memos-api-skill.git
cd memos-api-skill

export MEMOS_URL=https://memos.example.com      # your server, self-hosted or cloud
export MEMOS_API_KEY=memos_pat_xxxxxxxx          # a Personal Access Token

python3 scripts/memos_client.py profile          # sanity check, no auth needed
python3 scripts/memos_client.py whoami           # confirms the token works
python3 scripts/memos_client.py memo create --content "Hello from the CLI #test"
python3 scripts/memos_client.py memo list --all

Getting a Personal Access Token:

python3 scripts/memos_client.py signin --username <you> --password <password>
# copy the printed accessToken, then:
python3 scripts/memos_client.py --token <that accessToken> user pat-create users/<you> --description "cli"
# the printed token (memos_pat_...) is your MEMOS_API_KEY - it's only ever shown once

Bootstrapping a brand-new, self-hosted instance that has no users yet:

python3 scripts/memos_client.py --server https://your-instance.com --token x \
  user create --username admin --password 'a-strong-password'
# the very first user created succeeds without authentication and becomes admin automatically

What's covered

Every documented Memos v1 API service, with a friendly subcommand for the common operations plus a raw passthrough for anything else:

Resource	Subcommand group	Covers
Auth	whoami, signin, signout, refresh-token	Session login, current user
Memos	memo create/list/get/update/delete, memo set-attachments/list-attachments, memo set-relations/list-relations, memo comment-create/comment-list, memo reaction-list/reaction-add/reaction-delete, memo share-create/share-list/share-delete/get-by-share, memo link-metadata/batch-link-metadata	Full memo lifecycle, comments, reactions, sharing, relations
Attachments	attachment create/list/get/update/delete/batch-delete/download	Upload, list, rename, delete, and download file bytes
Users	user create/list/batch-get/get/update/delete, user stats/stats-all, user setting-get/setting-list/setting-update, user linked-identity-*, user pat-list/pat-create/pat-delete, user webhook-*, user notification-*	Accounts, settings, SSO links, Personal Access Tokens, webhooks, notifications
Shortcuts	shortcut list/get/create/update/delete	Saved, reusable CEL filter strings
Identity providers	idp list/get/create/update/delete	OAuth2/OIDC SSO configuration (admin only)
Instance	profile, instance setting-get/setting-batch-get/setting-update, instance test-email, instance stats	Instance profile, settings, SMTP test, storage stats
AI	ai transcribe	Audio transcription via a configured instance AI provider
Anything else	raw <METHOD> <PATH>	Direct passthrough to any endpoint, including ones added after this was written

Run python3 scripts/memos_client.py --help or <group> --help (e.g. memo --help) for the exact flags on any subcommand.

Using this as a Claude Agent Skill

Copy (or git clone) this repository into wherever your Claude environment loads skills from, so that SKILL.md sits at the top level. Claude reads the frontmatter description and will reach for this skill automatically whenever you mention Memos, usememos, or ask it to automate memo capture/search/attachments against a Memos server - it'll ask you for the server URL and a token if you haven't already provided them.

If you're packaging this for Claude Code / Claude Desktop / Cowork's skill installer, zip the folder with a .skill extension (zip -r memos-api.skill SKILL.md scripts references).

Repository layout

memos-api-skill/
├── SKILL.md                       Claude Agent Skill definition + workflow guidance
├── scripts/
│   └── memos_client.py            The CLI/library - stdlib only, no dependencies
└── references/
    └── api_reference.md           Full endpoint catalogue for all 8 Memos services

Compatibility

Verified against Memos v0.29.1 (the main-branch v1 API schema, current as of mid-2026). The API has evolved across versions, so if you're on a much older self-hosted release and something doesn't match, check references/api_reference.md against your instance's own OpenAPI spec at {server}/api/v1 first.

Disclaimer

This is an independent, community-built client. It is not affiliated with, endorsed by, or supported by the Memos project or its maintainers. "Memos" and "usememos" are referenced only to describe compatibility. All code here is original, written against Memos' public API surface - no source code from the Memos project is included or redistributed.

License

MIT