memos

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Memos API Skill

Memos API 技能

This skill combines two layers:

low-level API access for exact Memos endpoints
task-oriented query helpers for common memo retrieval jobs
tag inventory helpers so the calling agent can inspect existing hashtags before deciding whether to reuse them

Scope is intentionally limited to:

attachment operations
memo operations
activity operations

It does not cover user management, auth setup beyond the local

.env

, shortcuts, identity providers, or instance settings. If the request drifts there, say the skill scope is limited instead of guessing unsupported commands.

本技能包含三层能力：

针对具体Memos端点的底层API访问能力
面向常见备忘录检索任务的任务导向查询助手
标签清单助手，可供调用的Agent在决定是否复用现有标签前进行检查

本技能的作用范围特意限定为：

附件操作
备忘录操作
活动操作

它不涵盖用户管理、本地

.env

之外的身份验证配置、快捷方式、身份提供商或实例设置。如果请求超出上述范围，请告知用户本技能的作用范围有限，不要猜测不支持的命令。

What this skill provides

本技能提供的能力

A Bun CLI at
```
scripts/memos.ts
```
Endpoint discovery and direct API calling via
```
ops
```
,
```
describe
```
, and
```
call
```
Task-oriented memo helpers via
```
latest
```
,
```
recent
```
, and
```
search
```
A
```
list-tags
```
helper that aggregates existing tags, counts, recency, and sample memo snippets
A file-to-attachment helper so agents do not have to hand-roll base64 payloads
A compact operation catalog at
```
references/api-summary.md
```
Query recipes and time-window guidance at
```
references/query-recipes.md
```

位于
```
scripts/memos.ts
```
的Bun CLI
通过
```
ops
```
、
```
describe
```
和
```
call
```
实现的端点发现和直接API调用能力
通过
```
latest
```
、
```
recent
```
和
```
search
```
实现的任务导向备忘录助手
可聚合现有标签、计数、新鲜度和备忘录示例片段的
```
list-tags
```
助手
文件转附件助手，Agent无需手动构建base64 payload
位于
```
references/api-summary.md
```
的精简操作目录
位于
```
references/query-recipes.md
```
的查询方案和时间窗口指导

Setup

配置步骤

Work from the skill directory.
Ensure
```
.env
```
contains:
- ```
MEMOS_BASE_URL
```
- ```
MEMOS_ACCESS_TOKEN
```
Verify config:

bash

bun run scripts/memos.ts config

MEMOS_BASE_URL

may be either the instance root such as

http://localhost:5230

or the API base such as

http://localhost:5230/api/v1

. The CLI normalizes both.

在技能目录下执行操作
确保
```
.env
```
文件包含以下配置：
- ```
MEMOS_BASE_URL
```
- ```
MEMOS_ACCESS_TOKEN
```
验证配置：

bash

bun run scripts/memos.ts config

MEMOS_BASE_URL

可以是实例根地址，例如

http://localhost:5230

，也可以是API根地址，例如

http://localhost:5230/api/v1

，CLI会自动对两种格式做标准化处理。

Choose the right path

选择合适的使用路径

Use the high-level commands first when the user asked for a retrieval task, not a specific endpoint.

Latest memo or latest N memos:

bash

bun run scripts/memos.ts latest --count 5

Recent memos inside a time window:

bash

bun run scripts/memos.ts recent --days 7 --window rolling --include-content

Search by text or tag:

bash

bun run scripts/memos.ts search --text agent --tag Thought --days 30

Inspect existing tags before deciding which hashtags to reuse in a new memo:

bash

bun run scripts/memos.ts list-tags --limit 100 --sample-size 2

Use

call

when the user explicitly needs one documented endpoint or a write operation.

Inspect the exact endpoint first:

bash

bun run scripts/memos.ts describe MemoService_UpdateMemo

Then call it directly:

bash

bun run scripts/memos.ts call MemoService_UpdateMemo \
  --path memo=YOUR_MEMO_ID \
  --query updateMask=content,visibility \
  --body '{"content":"Updated content","visibility":"PROTECTED"}'

当用户需要执行检索任务而非调用特定端点时，优先使用高阶命令：

最新的1条或N条备忘录：

bash

bun run scripts/memos.ts latest --count 5

指定时间窗口内的最近备忘录：

bash

bun run scripts/memos.ts recent --days 7 --window rolling --include-content

按文本或标签搜索：

bash

bun run scripts/memos.ts search --text agent --tag Thought --days 30

在新备忘录中决定复用哪些hashtag前，先查看现有标签：

bash

bun run scripts/memos.ts list-tags --limit 100 --sample-size 2

当用户明确需要调用某个已文档化的端点或执行写入操作时，使用

call

命令：

首先查看指定端点的详细信息：

bash

bun run scripts/memos.ts describe MemoService_UpdateMemo

然后直接调用该端点：

bash

bun run scripts/memos.ts call MemoService_UpdateMemo \
  --path memo=YOUR_MEMO_ID \
  --query updateMask=content,visibility \
  --body '{"content":"Updated content","visibility":"PROTECTED"}'

Known quirks

已知注意事项

call --paginate

returns

{ operationId, pageCount, pages: [...] }

, not a top-level

{ memos: [...] }

. Flatten

pages[*].memos

before post-processing.

Memo time checks should use
```
displayTime
```
first, then fall back to
```
createTime
```
.
For time-range queries, prefer
```
orderBy='display_time desc'
```
plus local filtering. Do not assume the server-side
```
filter
```
field supports stable time semantics across versions.
The task-oriented commands default
```
state=NORMAL
```
so archived or deleted content does not silently leak into user-facing summaries.
```
search --tag
```
matches the memo
```
tags
```
array exactly. It is not a full-text hashtag parser over
```
content
```
.
```
Memo.tags
```
is extracted by the server from hashtags in
```
content
```
. Treat it as output-only unless the deployed API docs explicitly say otherwise.

call --paginate

返回的格式是

{ operationId, pageCount, pages: [...] }

，而非顶层的

{ memos: [...] }

，后处理前需要先展开

pages[*].memos

备忘录时间检查优先使用
```
displayTime
```
，回退方案为
```
createTime
```
时间范围查询优先使用
```
orderBy='display_time desc'
```
加本地过滤，不要假定服务端
```
filter
```
字段在不同版本间都支持稳定的时间语义
任务导向命令默认设置
```
state=NORMAL
```
，因此已归档或已删除的内容不会静默泄露到面向用户的摘要中
```
search --tag
```
是精确匹配备忘录
```
tags
```
数组，不是对
```
content
```
做全文hashtag解析
```
Memo.tags
```
是服务端从
```
content
```
的hashtag中提取的，除非部署的API文档明确说明支持修改，否则应当作仅输出字段处理

Recommended workflow

推荐工作流

1. Retrieval tasks

1. 检索任务

When the user asks questions like:

最近一周有哪些备忘录
最新的一条 memo 是什么
带
```
Thought
```
tag 的 memo 有哪些
搜一下包含某个关键词的 memo

Use:

```
latest
```
,
```
recent
```
, or
```
search
```
Return the important fields from the JSON result
Summarize content for the user when they asked for meaning, not raw JSON

Read

references/query-recipes.md

when you need concrete examples or want to choose between

rolling

and

calendar

time windows.

当用户提出以下类型的问题时：

最近一周有哪些备忘录
最新的一条 memo 是什么
带
```
Thought
```
tag 的 memo 有哪些
搜一下包含某个关键词的 memo

请按以下步骤操作：

使用
```
latest
```
、
```
recent
```
或
```
search
```
命令
返回JSON结果中的关键字段
当用户需要了解内容含义而非原始JSON时，对内容做摘要处理

如果需要具体示例，或是要在

rolling

和

calendar

时间窗口之间做选择，请查阅

references/query-recipes.md

。

2. Tag-aware memo creation

2. 带标签感知的备忘录创建

When the user asks to create a memo with tags or hashtags:

Run
```
bun run scripts/memos.ts list-tags ...
```
first to inspect the existing tag vocabulary.
If one or more candidate tags might match, run
```
search --tag ...
```
on the likely choices to inspect prior memo context.
Let the calling agent decide which existing tags to reuse. Do not hard-code similarity logic in scripts for this decision.
Put the final tags directly into the memo
```
content
```
as hashtags, usually at the top, for example:

json

{
  "state": "NORMAL",
  "visibility": "PRIVATE",
  "content": "#memos #openclaw\n\nImplemented tag discovery before creating this memo."
}

Call
```
MemoService_CreateMemo
```
with that content body.

Prefer reusing an existing tag when it clearly expresses the same concept. If the meaning is uncertain, inspect old memo examples first instead of inventing normalization rules.

当用户要求创建带标签或hashtag的备忘录时：

首先执行
```
bun run scripts/memos.ts list-tags ...
```
查看现有标签库
如果存在一个或多个可能匹配的候选标签，对可能的选项执行
```
search --tag ...
```
查看过往备忘录上下文
由调用的Agent决定要复用哪些现有标签，不要在脚本中硬编码相似度逻辑来做这个决策
将最终的标签作为hashtag直接写入备忘录
```
content
```
中，通常放在顶部，例如：

json

{
  "state": "NORMAL",
  "visibility": "PRIVATE",
  "content": "#memos #openclaw\n\nImplemented tag discovery before creating this memo."
}

传入上述内容body调用
```
MemoService_CreateMemo
```
接口

当现有标签能明确表达相同概念时优先复用，如果含义不明确，先查看旧的备忘录示例，不要自行创建标准化规则。

3. Exact API work

3. 精确API操作

When the user asks to create, update, delete, attach files, add reactions, or inspect one exact endpoint:

Run
```
bun run scripts/memos.ts ops
```

If needed, run

bun run scripts/memos.ts describe <operationId>

Use

bun run scripts/memos.ts call <operationId> ...

This keeps the agent aligned with the documented API surface instead of inventing raw requests.

当用户要求创建、更新、删除、附加文件、添加反应，或是查看某个精确端点时：

执行
```
bun run scripts/memos.ts ops
```

如有需要，执行

bun run scripts/memos.ts describe <operationId>

使用

bun run scripts/memos.ts call <operationId> ...

执行操作

这可以保证Agent和已文档化的API表面保持一致，不会自行构造原始请求。

4. Resource naming rules

4. 资源命名规则

Path placeholders usually expect bare ids:

```
--path memo=0195c...
```
```
--path attachment=abc123
```
```
--path activity=evt_123
```

Request bodies often expect full resource names:

```
memos/0195c...
```
```
attachments/abc123
```

If you accidentally pass a full resource name into a path flag, the CLI strips the leading path and keeps the last segment.

路径占位符通常需要传入纯id：

```
--path memo=0195c...
```
```
--path attachment=abc123
```
```
--path activity=evt_123
```

请求体通常需要传入完整资源名：

```
memos/0195c...
```
```
attachments/abc123
```

如果你不小心将完整资源名传入了路径参数，CLI会自动去掉前置路径，保留最后一段。

5. Update requests

5. 更新请求

Patch endpoints such as:

```
AttachmentService_UpdateAttachment
```
```
MemoService_UpdateMemo
```

need

--query updateMask=...

Without it, many updates fail or update less than expected.

补丁端点，例如：

```
AttachmentService_UpdateAttachment
```
```
MemoService_UpdateMemo
```

需要传入

--query updateMask=...

参数。

缺少该参数的话，很多更新会失败，或是更新的内容少于预期。

6. Complex bodies and binary uploads

6. 复杂请求体和二进制上传

Prefer

@file.json

for larger bodies:

bash

bun run scripts/memos.ts call MemoService_CreateMemo --body @/tmp/memo.json

Use the helper for attachments instead of hand-building base64:

bash

bun run scripts/memos.ts attachment-body --file /path/to/file --output /tmp/body.json

Then create the attachment:

bash

bun run scripts/memos.ts call AttachmentService_CreateAttachment --body @/tmp/body.json

较大的请求体优先使用

@file.json

传入：

bash

bun run scripts/memos.ts call MemoService_CreateMemo --body @/tmp/memo.json

附件上传使用助手工具，不要手动构建base64：

bash

bun run scripts/memos.ts attachment-body --file /path/to/file --output /tmp/body.json

然后创建附件：

bash

bun run scripts/memos.ts call AttachmentService_CreateAttachment --body @/tmp/body.json

后续可选阅读

Read
```
references/query-recipes.md
```
for recent/latest/search workflows, time-window semantics, and memo post-processing examples.
Read
```
references/api-summary.md
```
for the compact endpoint catalog, body hints, and pagination details.

查阅
```
references/query-recipes.md
```
了解recent/latest/search工作流、时间窗口语义和备忘录后处理示例
查阅
```
references/api-summary.md
```
了解精简端点目录、请求体提示和分页详情

Output expectations

输出要求

When using this skill for execution:

call the real API instead of only describing it
prefer
```
latest
```
,
```
recent
```
, or
```
search
```
for retrieval tasks instead of hand-writing pagination logic each time
return the important response fields to the user
if you create or update resources, include the resource name or id in your answer
if the API returns an error, surface the status and body plainly instead of hiding it

使用本技能执行操作时：

调用真实API，不要仅做描述
检索任务优先使用
```
latest
```
、
```
recent
```
或
```
search
```
，不要每次都手动编写分页逻辑
向用户返回重要的响应字段
如果你创建或更新了资源，在回答中包含资源名称或id
如果API返回错误，清晰展示状态和响应体，不要隐藏

memos

Original

Translation

Memos API Skill

Memos API 技能

What this skill provides

本技能提供的能力

Setup

配置步骤

Choose the right path

选择合适的使用路径

Known quirks

已知注意事项

Recommended workflow

推荐工作流

1. Retrieval tasks

1. 检索任务

2. Tag-aware memo creation

2. 带标签感知的备忘录创建

3. Exact API work

3. 精确API操作

4. Resource naming rules

4. 资源命名规则

5. Update requests

5. 更新请求

6. Complex bodies and binary uploads

6. 复杂请求体和二进制上传

Read next when needed

后续可选阅读

Output expectations

输出要求