Memos API 客户端（memos-node）

通过 Memos 官方 REST API（/api/v1）操作自托管 Memos 实例，已打包为单文件，无需 npm install。

覆盖对象：memo（增删改查/归档/置顶/评论/表情/标签）、attachment（上传下载）、user、instance。

快速开始

# 配置实例与令牌（写入本目录 .env，或直接 export）
export MEMOS_URL=https://memos.example.com
export MEMOS_TOKEN=your-access-token

# 写一条 memo
node skill.js memo create "今天读了 #Rust 所有权章节"

# 列最近的 memo
node skill.js memo list --limit 10

# 按标签 + 关键字搜索
node skill.js memo list --tag Rust --search 所有权 --since 30d

命令总表

命令别名：list/ls、get/show、create/new/add、update/edit、delete/rm、upload/put、download/dl。

通用选项

认证与配置

在 Memos 网页端「设置 → 访问令牌」创建个人访问令牌，请求以 Authorization: Bearer <token> 发送。

也可复制 .env.example 为同目录 .env 填写；已存在的环境变量优先于 .env。

过滤与排序

memo list 的快捷选项会拼成 Memos 的 CEL 过滤表达式（--filter 传入原生表达式时以 && 组合）：

--since 支持 30m / 24h / 7d / 2w，或 ISO 时间戳（如 2026-01-01T00:00:00Z）。

可用 CEL 字段：content、creator、created_ts、updated_ts、pinned、visibility、tags、has_link、has_task_list、has_code、has_incomplete_tasks。

--orderby 默认 create_time desc，支持 pinned desc, create_time desc（字段：pinned、create_time、update_time、name）。注意排序用 create_time，过滤用 created_ts。

--archived 等价于 state=ARCHIVED；不加时只返回正常 memo。

输出格式

默认 JSON 到 stdout；错误输出 {error, message, status, hint} JSON 到 stderr，退出码 1（参数错误为 2）。

--format yaml 比 JSON 省约 40% token，适合 LLM 阅读；--format table 适合人眼快速浏览列表。

常见问题

Q: 报 401 或提示未认证？ 检查 MEMOS_TOKEN 是否为有效的个人访问令牌（在 Memos 网页端「设置 → 访问令牌」创建），且未过期。注意 token 与 --url 必须属于同一实例。

Q: 列表返回空，但网页上能看到 memo？ Memos 的列表接口按调用者权限过滤。token 对应的账号只能看到自己创建或有权访问的 memo；PRIVATE memo 仅作者可见。确认 token 属于正确的账号。

Q: 按标签搜索没有结果？ 标签过滤使用 "标签名" in tags，标签名不带 #。子标签（如 #work/project）需写完整路径。

Q: memo update 报缺少字段？ updateMask 由工具按实际传入的选项自动生成；至少要提供 --content / --visibility / --pinned 之一。

Q: 上传大文件失败？ attachment upload 走单次 base64 上传，适合数 MB 以内的文件。更大文件请用 Memos 网页端或客户端分片上传接口（/api/v1/attachments:upload）。

Q: 自签名证书报证书错误？ 加 --insecure，或设 MEMOS_INSECURE=true。该选项进程级关闭 TLS 校验，仅建议内网使用。

Q: 不同 Memos 版本接口有差异？ 本工具面向 0.2x/0.31 的 /api/v1 路径。Memos 新版将 REST 路径迁到 /api（如 /api/memos），届时需相应调整 lib/api.js 中的路径。

开发

pnpm install && pnpm run build   # run.js -> skill.js
node skill.js --help             # 验证