memo-api-x-6

原始内容

---
name: memo-api
description: >
  墨墨背单词 MaiMemo Open API skill for vocabulary learning.
  Handles: 单词 vocabulary lookup (voc_id), 释义 interpretations (CRUD),
  助记 mnemonics/notes, 云词本 notepads/word lists, 例句 phrases/example sentences,
  学习数据 study progress/review schedule/study records.
  Triggers on: 墨墨, maimemo, 背单词, 释义, 助记, 云词本, 例句, study progress,
  review schedule, words due, forgotten words, study time, export study data.
version: "1.2.0"
metadata:
  openclaw:
    requires:
      env:
        - MAIMEMO_TOKEN
      binds:
        - curl
---

# MaiMemo Open API

## Auth & Base

- **Base URL**: `https://open.maimemo.com/open/api/v1`
- **Token**: env var `$MAIMEMO_TOKEN` — obtain it from either:
  - App: 墨墨背单词 → 开放 API
  - Web: open `https://open.maimemo.com/open/api/v1/tokens/openapi`, log in to the MaiMemo account, ask the user to copy the Token and paste it back, then set it as `$MAIMEMO_TOKEN`
- **Token expiry**: Tokens from the web source are valid for 7 days. If an API call indicates the token is expired/invalid (for example auth failure), tell the user to repeat the web login/copy/paste flow and update `$MAIMEMO_TOKEN`.
- **Auth header**: `Authorization: Bearer $MAIMEMO_TOKEN`

```bash
curl -s -X ${METHOD} "${BASE}/${PATH}" \
  -H "Authorization: Bearer $MAIMEMO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '${BODY}'
```

**Rate limits**: 20/10s, 40/60s, 2000/5h

## Key Concepts

- **voc_id resolution**: Most endpoints need `voc_id`, not spelling. Resolve via `GET /vocabulary?spelling=word` or `POST /vocabulary/query` (batch up to 1000).
- **POST for updates**: Update endpoints use `POST /resource/{id}`, not PUT/PATCH.
- **Status values**: Resources use status enums (`PUBLISHED`, `UNPUBLISHED`, `DELETED`) — vary by domain.
- **Timestamps**: All times are ISO 8601. Study date filters use Beijing timezone (UTC+8).

## Domain Routing

| Task | Read reference file |
|------|-------------------|
| Look up voc_id / spelling → id | `vocabulary-api.md` |
| CRUD custom definitions | `interpretations-api.md` |
| CRUD mnemonics (联想/谐音/派生/词根/词源/固搭/语法/对比 etc.) | `notes-api.md` |
| Manage word lists / cloud notepads | `notepads-api.md` |
| CRUD example sentences | `phrases-api.md` |
| Study progress, records, schedules | `study-api.md` |

**Before calling any endpoint**, read the corresponding reference file for exact params, body schema, and curl examples.

## Study Usage Scenes

All study endpoints are **POST** and **beta** (需要打开自动同步).

### Today's Progress
**Endpoint**: `POST /study/get_study_progress` (empty body)
Returns: `finished` (done count), `total` (target count), `study_time` (ms)

| Scene | Endpoint | Key params |
|-------|----------|-----------|
| Words left today | `get_study_progress` | compute `total - finished` |
| Study time today | `get_study_progress` | `study_time` (ms → min) |

### Today's Words
**Endpoint**: `POST /study/get_today_items`

| Scene | Endpoint | Key params |
|-------|----------|-----------|
| Forgotten words today | `get_today_items` | `is_finished: true`, filter `first_response = "FORGET"` |
| New words today | `get_today_items` | `is_new: true` |
| Unfinished words | `get_today_items` | `is_finished: false` |
| Specific word history | `get_today_items` | `spellings: ["word"]` or `voc_ids: ["id"]` |

### Study Records
**Endpoint**: `POST /study/query_study_records`

| Scene | Endpoint | Key params |
|-------|----------|-----------|
| Words due in next N days | `query_study_records` | `next_study_date.end: "YYYY-MM-DDT00:00:00+08:00"`, `as_count: true` |
| Total words in plan | `query_study_records` | `as_count: true` (no filters) |
| Frequently forgotten (sticky) | `query_study_records` | iterate pages, filter `tags = "STICKING"` |
| Well-familiar words | `query_study_records` | iterate pages, filter `tags = "WELL_FAMILIAR"` |
| Export all study data | `query_study_records` | paginate via sliding `next_study_date` window, `limit: 1000` |

### Adding Words
**Endpoint**: `POST /study/add_words`

| Scene | Endpoint | Key params |
|-------|----------|-----------|
| Add words to plan | `add_words` | `words: [{"id": "voc_id"}]`, max 1000 |
| Add and advance review | `add_words` | `advance: true` (also triggers immediate review, no level limit) |

### Advance Review
**Endpoint**: `POST /study/advance_study`

| Scene | Endpoint | Key params |
|-------|----------|-----------|
| Advance words for immediate review | `advance_study` | `voc_ids: ["voc_id1", ...]`, max 1000 |
| Requires level 10+ to unlock advance review feature | | |

## Multi-domain Workflow Hints

- **Add mnemonic to word**: Vocabulary (get voc_id) → Notes (create)
- **Add example sentence**: Vocabulary (get voc_id) → Phrases (create)
- **Add custom definition**: Vocabulary (get voc_id) → Interpretations (create)
- **Build word list from study data**: Study records (query) → Notepads (create with spellings)
- **Full word info**: Vocabulary (get voc_id) → Interpretations + Notes + Phrases (list all)

name: memo-api description: > 墨墨背单词 MaiMemo Open API skill for vocabulary learning. Handles: 单词 vocabulary lookup (voc_id), 释义 interpretations (CRUD), 助记 mnemonics/notes, 云词本 notepads/word lists, 例句 phrases/example sentences, 学习数据 study progress/review schedule/study records. Triggers on: 墨墨, maimemo, 背单词, 释义, 助记, 云词本, 例句, study progress, review schedule, words due, forgotten words, study time, export study data. version: "1.2.0" metadata: openclaw: requires: env: - MAIMEMO_TOKEN binds: - curl

MaiMemo Open API

Auth & Base

Base URL: https://open.maimemo.com/open/api/v1
Token: env var $MAIMEMO_TOKEN — obtain it from either:
- App: 墨墨背单词 → 开放 API
- Web: open https://open.maimemo.com/open/api/v1/tokens/openapi, log in to the MaiMemo account, ask the user to copy the Token and paste it back, then set it as $MAIMEMO_TOKEN
Token expiry: Tokens from the web source are valid for 7 days. If an API call indicates the token is expired/invalid (for example auth failure), tell the user to repeat the web login/copy/paste flow and update $MAIMEMO_TOKEN.
Auth header: Authorization: Bearer $MAIMEMO_TOKEN

curl -s -X ${METHOD} "${BASE}/${PATH}" \
  -H "Authorization: Bearer $MAIMEMO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '${BODY}'

Rate limits: 20/10s, 40/60s, 2000/5h

Key Concepts

voc_id resolution: Most endpoints need voc_id, not spelling. Resolve via GET /vocabulary?spelling=word or POST /vocabulary/query (batch up to 1000).
POST for updates: Update endpoints use POST /resource/{id}, not PUT/PATCH.
Status values: Resources use status enums (PUBLISHED, UNPUBLISHED, DELETED) — vary by domain.
Timestamps: All times are ISO 8601. Study date filters use Beijing timezone (UTC+8).

Domain Routing

Task	Read reference file
Look up voc_id / spelling → id	`vocabulary-api.md`
CRUD custom definitions	`interpretations-api.md`
CRUD mnemonics (联想/谐音/派生/词根/词源/固搭/语法/对比 etc.)	`notes-api.md`
Manage word lists / cloud notepads	`notepads-api.md`
CRUD example sentences	`phrases-api.md`
Study progress, records, schedules	`study-api.md`

Before calling any endpoint, read the corresponding reference file for exact params, body schema, and curl examples.

Study Usage Scenes

All study endpoints are POST and beta (需要打开自动同步).

Today's Progress

Endpoint: POST /study/get_study_progress (empty body) Returns: finished (done count), total (target count), study_time (ms)

Scene	Endpoint	Key params
Words left today	`get_study_progress`	compute `total - finished`
Study time today	`get_study_progress`	`study_time` (ms → min)

Today's Words

Endpoint: POST /study/get_today_items

Scene	Endpoint	Key params
Forgotten words today	`get_today_items`	`is_finished: true`, filter `first_response = "FORGET"`
New words today	`get_today_items`	`is_new: true`
Unfinished words	`get_today_items`	`is_finished: false`
Specific word history	`get_today_items`	`spellings: ["word"]` or `voc_ids: ["id"]`

Study Records

Endpoint: POST /study/query_study_records

Scene	Endpoint	Key params
Words due in next N days	`query_study_records`	`next_study_date.end: "YYYY-MM-DDT00:00:00+08:00"`, `as_count: true`
Total words in plan	`query_study_records`	`as_count: true` (no filters)
Frequently forgotten (sticky)	`query_study_records`	iterate pages, filter `tags = "STICKING"`
Well-familiar words	`query_study_records`	iterate pages, filter `tags = "WELL_FAMILIAR"`
Export all study data	`query_study_records`	paginate via sliding `next_study_date` window, `limit: 1000`

Adding Words

Endpoint: POST /study/add_words

Scene	Endpoint	Key params
Add words to plan	`add_words`	`words: [{"id": "voc_id"}]`, max 1000
Add and advance review	`add_words`	`advance: true` (also triggers immediate review, no level limit)

Advance Review

Endpoint: POST /study/advance_study

Scene	Endpoint	Key params
Advance words for immediate review	`advance_study`	`voc_ids: ["voc_id1", ...]`, max 1000
Requires level 10+ to unlock advance review feature

Multi-domain Workflow Hints

Add mnemonic to word: Vocabulary (get voc_id) → Notes (create)
Add example sentence: Vocabulary (get voc_id) → Phrases (create)
Add custom definition: Vocabulary (get voc_id) → Interpretations (create)
Build word list from study data: Study records (query) → Notepads (create with spellings)
Full word info: Vocabulary (get voc_id) → Interpretations + Notes + Phrases (list all)