Memos

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

| Service | Description | Key Operations | |---------|-------------|----------------| | Memo | Notes and content | Create, List, Get, Update, Delete, Comments, Reactions | | User | User management | Create, Get, List, Update, Delete, Personal Access Tokens | | Auth | Authentication | Sign in, Sign out, Refresh token, Current user | | Attachment | Files and media | Create, Get, List, Update, Delete | | Shortcut | Saved filters | Create, Get, List, Update, Delete | | Instance | Server settings | Get profile, Get/Update settings |

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

| Value | Description | |-------|-------------| | PRIVATE | Only visible to the creator | | PROTECTED | Visible to logged-in users | | PUBLIC | Visible to everyone |

State Values

| Value | Description | |-------|-------------| | NORMAL | Active memo | | ARCHIVED | Archived memo |

Error Handling

All errors follow this format:

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

See [error-codes.md](assets/error-codes.md) for common error codes and resolution strategies.

Detailed Documentation

For comprehensive API documentation:

• [Full API Reference](references/REFERENCE.md)
• [Memo Operations](references/examples/memo-operations.md)
• [User Management](references/examples/user-management.md)
• [Authentication](references/examples/authentication.md)
• [Attachments](references/examples/attachments.md)
• [Advanced Features](references/examples/advanced-features.md)

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"

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jrodriguezruibal
• Source: jrodriguezruibal/memos-skill
• License: MIT

Install and usage instructions live in the source repository linked above.