Memos API Skill

Interact with a Memos instance through its REST API.

Prerequisites

Before using this skill, ensure you have:

1. MEMOS_URL: The base URL of your Memos instance (e.g., http://localhost:5230 or https://memos.example.com)
2. MEMOS_TOKEN: A Personal Access Token for authentication

Obtaining a Personal Access Token

1. Log in to your Memos instance
2. Navigate to Settings → My Account → Access Tokens
3. Click Create Access Token
4. Provide a description (e.g., "AI Agent Token")
5. Set expiration as needed (or leave empty for no expiration)
6. Copy the generated token immediately - it is shown only once

Store the token securely. For local development, set environment variables:

export MEMOS_URL="http://localhost:5230"
export MEMOS_TOKEN="your-personal-access-token"

Quick Reference

Common Operations

Create a Memo

Request:

curl -X POST "${MEMOS_URL}/api/v1/memos" \
  -H "Authorization: Bearer ${MEMOS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# My First Memo\n\nThis is the content of my memo.",
    "visibility": "PRIVATE"
  }'

JavaScript:

const response = await fetch(`${process.env.MEMOS_URL}/api/v1/memos`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.MEMOS_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    content: '# My First Memo\n\nThis is the content of my memo.',
    visibility: 'PRIVATE'
  })
});
const memo = await response.json();

Response:

{
  "name": "memos/abc123",
  "state": "NORMAL",
  "creator": "users/1",
  "createTime": "2024-01-15T10:30:00Z",
  "content": "# My First Memo\n\nThis is the content of my memo.",
  "visibility": "PRIVATE"
}

List Memos

Request:

curl -X GET "${MEMOS_URL}/api/v1/memos?pageSize=10" \
  -H "Authorization: Bearer ${MEMOS_TOKEN}"

JavaScript:

const response = await fetch(`${process.env.MEMOS_URL}/api/v1/memos?pageSize=10`, {
  headers: { 'Authorization': `Bearer ${process.env.MEMOS_TOKEN}` }
});
const { memos } = await response.json();

Get a Single Memo

Request:

curl -X GET "${MEMOS_URL}/api/v1/memos/{memoId}" \
  -H "Authorization: Bearer ${MEMOS_TOKEN}"

Update a Memo

Request:

curl -X PATCH "${MEMOS_URL}/api/v1/memos/{memoId}?updateMask=content,visibility" \
  -H "Authorization: Bearer ${MEMOS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated content",
    "visibility": "PUBLIC"
  }'

Delete a Memo

Request:

curl -X DELETE "${MEMOS_URL}/api/v1/memos/{memoId}" \
  -H "Authorization: Bearer ${MEMOS_TOKEN}"

Visibility Values

State Values

Error Handling

All errors follow this format:

{
  "code": 3,
  "message": "Invalid argument",
  "details": []
}

See error-codes.md for common error codes and resolution strategies.

Detailed Documentation

For comprehensive API documentation:

• Full API Reference
• Memo Operations
• User Management
• Authentication
• Attachments
• Advanced Features

Helper Scripts

Executable scripts are available in the scripts/ directory:

• memos-api.sh - Bash helper functions
• memos-client.js - JavaScript client library

API Base URL

All endpoints use the base path: /api/v1

Example: http://localhost:5230/api/v1/memos

Authentication

All authenticated endpoints require the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Pagination

List endpoints support pagination:

• pageSize: Maximum items per page (default: 50, max: 1000)
• pageToken: Token from previous response for next page

Filtering

Some list endpoints support filtering via the filter parameter using Google AIP-160 syntax:

filter=row_status == "NORMAL"
filter=visibility == "PUBLIC"