flomo-local-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Flomo Local API

Overview

概述

Use this skill for fast flomo access when local desktop auth is available.

This is the default recommendation for

mac

users. If local desktop auth is missing or broken, fall back to

flomo-web-crud

instead of trying to fake the API path.

When the user wants to create or revise a memo:

Tag reuse is required: Prefer the user's existing flomo tag system over inventing new tags. Aim for existing-tag reuse in at least 95% of memo-writing cases.
Plain text only: flomo does not support Markdown rendering. Never use
```
**bold**
```
,
```
- [ ]
```
checkboxes,
```
# headers
```
, or other markdown syntax in memo content. Use plain text formatting instead.

This skill supports direct text edits to existing memos through the same local auth flow, including when the user provides a flomo memo URL like

https://v.flomoapp.com/mine/?memo_id=...

当可使用本地桌面认证时，可通过该技能快速访问flomo。

这是

mac

用户的默认推荐方案。如果缺少本地桌面认证或认证失效，请改用

flomo-web-crud

，不要尝试伪造API路径。

当用户需要创建或修改备忘录时：

必须复用标签：优先使用用户现有flomo标签体系，不要创建新标签。在至少95%的备忘录编写场景中都要做到复用现有标签。
仅支持纯文本：flomo不支持Markdown渲染，绝对不要在备忘录内容中使用
```
**加粗**
```
、
```
- [ ]
```
复选框、
```
# 标题
```
或其他Markdown语法，请改用纯文本格式。

该技能支持通过相同的本地认证流程直接编辑现有备忘录的文本，即使用户提供的是类似

https://v.flomoapp.com/mine/?memo_id=...

的flomo备忘录URL也可支持。

Preconditions

前置条件

```
flomo.app
```
has been logged in on this Mac before
Local flomo storage exists under
```
~/Library/Containers/com.flomoapp.m/...
```
The request can be handled with local auth and API access

该Mac设备上曾登录过
```
flomo.app
```
本地存在flomo存储文件，路径为
```
~/Library/Containers/com.flomoapp.m/...
```
需求可通过本地认证和API访问完成

Use This Skill When

适用场景

The user asks to search flomo memos by keyword, tag, or time range
The user asks what they have been thinking about recently
The user wants monthly markdown export or tag statistics
The user wants to create a simple memo without Chrome UI automation
The user wants to edit an existing text memo by slug or by flomo memo URL without opening the Web UI
The user wants faster querying than Chrome UI automation
The user wants a draft memo that fits their existing flomo tag taxonomy before creating it

用户需要按关键词、标签或时间范围搜索flomo备忘录
用户询问自己最近在思考什么内容
用户需要月度markdown导出或标签统计
用户希望无需Chrome UI自动化即可创建简单备忘录
用户希望通过slug或flomo备忘录URL编辑现有文本备忘录，无需打开Web UI
用户需要比Chrome UI自动化更快的查询速度
用户希望在创建备忘录前得到符合其现有flomo标签体系的草稿

Do Not Use This Skill When

不适用场景

The user wants to delete a memo
The user wants to operate through the live Web UI
The local desktop login state is missing or broken and the request cannot be completed from local auth

用户需要删除备忘录
用户需要通过实时Web UI操作
缺少本地桌面登录状态或登录状态失效，无法通过本地认证完成需求

Default Workflow

默认工作流

Use
```
scripts/flomo_local_api.py
```
.
Prefer
```
query
```
for direct lookup.
Prefer
```
summarize
```
for reflective prompts such as "最近在想什么".
Prefer
```
export-monthly
```
when the user wants markdown output.
Before creating or editing a memo with tags, inspect the user's existing tag taxonomy with
```
tags
```
.
Draft memo body first, then choose 1-4 tags by reusing existing tags that are already in the system.
Prefer
```
create
```
for lightweight memo creation without attachments.
Prefer
```
edit
```
for updating the text content of an existing memo by slug or
```
memo_id
```
URL.
Treat delete as out of scope unless the skill is expanded again later.

使用
```
scripts/flomo_local_api.py
```
直接查找优先使用
```
query
```
命令
针对「最近在想什么」这类反思类需求优先使用
```
summarize
```
命令
用户需要markdown输出时优先使用
```
export-monthly
```
命令
在创建或编辑带标签的备忘录前，使用
```
tags
```
命令查看用户现有标签体系
先撰写备忘录正文草稿，再从系统现有标签中选择1-4个复用
无附件的轻量备忘录创建优先使用
```
create
```
命令
通过slug或
```
memo_id
```
URL更新现有备忘录文本内容优先使用
```
edit
```
命令
删除操作不在能力范围内，除非后续技能再次扩展

Commands

命令说明

Command Template

命令模板

Set the script path from the current environment instead of a hardcoded user directory:

bash

SKILL_ROOT="${CODEX_HOME:-$HOME/.codex}/skills/flomo-local-api"
SCRIPT="$SKILL_ROOT/scripts/flomo_local_api.py"

从当前环境获取脚本路径，不要硬编码用户目录：

bash

SKILL_ROOT="${CODEX_HOME:-$HOME/.codex}/skills/flomo-local-api"
SCRIPT="$SKILL_ROOT/scripts/flomo_local_api.py"

Query

Use for direct search by keyword, tag, date range, or recent window.

bash

python3 "$SCRIPT" query --keyword "openclaw" --limit 10
python3 "$SCRIPT" query --tag "Proj/mf" --days 30
python3 "$SCRIPT" query --start-date 2026-03-01 --end-date 2026-03-11 --format markdown

query

results include both

slug

and the corresponding flomo memo URL so later edit steps can reuse them directly.

用于按关键词、标签、日期范围或最近时间窗口直接搜索。

bash

python3 "$SCRIPT" query --keyword "openclaw" --limit 10
python3 "$SCRIPT" query --tag "Proj/mf" --days 30
python3 "$SCRIPT" query --start-date 2026-03-01 --end-date 2026-03-11 --format markdown

query

结果同时包含

slug

和对应的flomo备忘录URL，后续编辑步骤可直接复用。

Summarize

Use for "我最近在关注什么 / 最近状态如何" style requests.

bash

python3 "$SCRIPT" summarize --days 30
python3 "$SCRIPT" summarize --days 90 --limit 80

用于「我最近在关注什么 / 最近状态如何」这类需求。

bash

python3 "$SCRIPT" summarize --days 30
python3 "$SCRIPT" summarize --days 90 --limit 80

Export Monthly

Use when the user wants a monthly markdown dump plus

tag-stats.md

bash

python3 "$SCRIPT" export-monthly
python3 "$SCRIPT" export-monthly --output-dir ~/download/flomo-markdown-export-monthly

用于用户需要月度markdown导出和

tag-stats.md

的场景。

bash

python3 "$SCRIPT" export-monthly
python3 "$SCRIPT" export-monthly --output-dir ~/download/flomo-markdown-export-monthly

Tags

Use when the user wants to create or edit a memo and you need to reuse the existing tag system instead of inventing new tags.

bash

python3 "$SCRIPT" tags --roots-only --limit 20
python3 "$SCRIPT" tags --query "agent" --limit 20 --min-total-count 2
python3 "$SCRIPT" tags --prefix "area/ai/agent" --limit 20 --format markdown --min-total-count 2
python3 "$SCRIPT" tags --query "设计" --days 365 --limit 20 --min-total-count 2

Recommended pattern for memo writing:

Draft the memo body without tags first.
Extract 2-5 likely concepts from the memo.
Start with one cheap scan:
```
tags --roots-only --limit 12
```
.
Then make at most 2 focused lookups, usually one concrete entity query and one abstract theme query. If the memo names a specific project, person, product, or proper noun, spend the first focused lookup on that exact entity string before abstract theme queries. Prefer
```
--min-total-count 2
```
.
If a root is obvious, prefer one
```
--prefix
```
lookup inside that subtree over spraying many synonym queries.
Reuse 1-4 existing tags, preferring mature path tags with repeated usage.
Stop once you have 2 strong tags and at most 1-2 optional supporting tags. Do not keep searching just to exhaust every possible synonym.
If the best hit is a singleton leaf under an unfamiliar root, widen once and prefer a broader, better-established parent or nearby mature sibling.
If the memo clearly centers on a named project, person, or product and an existing
```
Proj/*
```
,
```
p/*
```
, or product tag exists, include that concrete taxonomy tag before adding more generic thematic tags.
When an exact or near-exact named-entity tag is found, treat it as required evidence, not optional flavor. Do not drop it in favor of only abstract theme tags.
Only create a new tag when there is no close existing tag. If you do, tell the user briefly why reuse was not possible.

Search budget:

Default budget is 3 tag lookups total:
- 1 roots-only scan
- 1 focused entity/theme lookup
- 1 optional disambiguation lookup
Going beyond 3 lookups needs a clear reason, such as no mature match after the first pass.
Avoid synonym fan-out like querying
```
prompt
```
,
```
eval
```
,
```
policy
```
,
```
rules
```
,
```
safety
```
,
```
design
```
,
```
comment
```
one by one unless earlier results were genuinely inconclusive.

用于用户需要创建或编辑备忘录时，复用现有标签体系避免创建新标签的场景。

bash

python3 "$SCRIPT" tags --roots-only --limit 20
python3 "$SCRIPT" tags --query "agent" --limit 20 --min-total-count 2
python3 "$SCRIPT" tags --prefix "area/ai/agent" --limit 20 --format markdown --min-total-count 2
python3 "$SCRIPT" tags --query "设计" --days 365 --limit 20 --min-total-count 2

备忘录编写推荐流程：

先撰写不带标签的备忘录正文草稿
从备忘录中提取2-5个可能的概念
先进行一次低成本扫描：
```
tags --roots-only --limit 12
```
最多进行2次针对性查找，通常是1次具体实体查询和1次抽象主题查询。如果备忘录提到了特定项目、人物、产品或专有名词，先针对该 exact 实体字符串进行第一次针对性查找，再进行抽象主题查询。优先使用
```
--min-total-count 2
```
参数
如果明显属于某个根标签下的内容，优先在该子树内进行1次
```
--prefix
```
查找，不要大量发送同义词查询
复用1-4个现有标签，优先选择使用次数多的成熟路径标签
当获得2个强相关标签和最多1-2个可选辅助标签后即可停止，不要为了穷尽所有可能的同义词继续搜索
如果最优匹配是陌生根标签下的单个叶子标签，扩大一次搜索范围，优先选择更宽泛、更成熟的父标签或相邻的成熟同级标签
如果备忘录明确围绕某个已命名的项目、人物或产品展开，且存在对应的
```
Proj/*
```
、
```
p/*
```
或产品标签，先添加该具体分类标签，再添加更通用的主题标签
当找到完全匹配或接近匹配的命名实体标签时，将其作为必填项，不要仅保留抽象主题标签而舍弃它
仅在没有近似现有标签时才创建新标签，如果确实创建了新标签，需要简要告知用户无法复用现有标签的原因

搜索次数限制：

默认最多总共进行3次标签查找：
- 1次根标签扫描
- 1次针对性实体/主题查找
- 1次可选的消歧查找
超过3次查找需要有明确理由，比如首次查找后没有找到成熟匹配项
避免逐个查询
```
prompt
```
、
```
eval
```
、
```
policy
```
、
```
rules
```
、
```
safety
```
、
```
design
```
、
```
comment
```
这类同义词，除非之前的查询结果确实无法得出结论

Create

Use when the user wants to quickly create a text memo from local auth.

Text Formatting Note: flomo does not render Markdown syntax. Use plain text formatting instead:

For emphasis: use
```
「」
```
quotes or ALL CAPS instead of
```
**bold**
```
For lists: use simple bullets like
```
•
```
or
```
1.
```
instead of markdown list syntax
Do NOT use checkboxes or todo lists in flomo memos
Keep paragraphs separated by blank lines for readability

bash

python3 "$SCRIPT" create --content "测试 memo #codex/demo"
printf '第一行\n\n第二段 #codex/demo\n' | python3 "$SCRIPT" create --stdin

用于用户希望通过本地认证快速创建文本备忘录的场景。

文本格式注意事项：flomo不会渲染Markdown语法，请改用纯文本格式：

强调内容：使用
```
「」
```
引号或全大写代替
```
**加粗**
```
列表：使用
```
•
```
或
```
1.
```
这类简单项目符号代替Markdown列表语法
不要在flomo备忘录中使用复选框或待办列表
段落之间用空行分隔提升可读性

bash

python3 "$SCRIPT" create --content "测试 memo #codex/demo"
printf '第一行\n\n第二段 #codex/demo\n' | python3 "$SCRIPT" create --stdin

Edit

Use when the user wants to update the text of an existing memo and already has either the memo

slug

or a flomo memo URL.

Text Formatting Note: Same as

create

— flomo does not render Markdown. Use plain text formatting.

bash

python3 "$SCRIPT" edit --slug "MTIzMDgzNzgz" --content "更新后的 memo 内容 #codex/demo"
python3 "$SCRIPT" edit --url "https://v.flomoapp.com/mine/?memo_id=MTIzMDgzNzgz" --content "更新后的 memo 内容 #codex/demo"
printf '第一行修改后\n\n第二段也更新\n' | python3 "$SCRIPT" edit --slug "MTIzMDgzNzgz" --stdin

用于用户需要更新现有备忘录文本，且已获取备忘录

slug

或flomo备忘录URL的场景。

文本格式注意事项：和

create

命令一致——flomo不会渲染Markdown，请使用纯文本格式。

bash

python3 "$SCRIPT" edit --slug "MTIzMDgzNzgz" --content "更新后的 memo 内容 #codex/demo"
python3 "$SCRIPT" edit --url "https://v.flomoapp.com/mine/?memo_id=MTIzMDgzNzgz" --content "更新后的 memo 内容 #codex/demo"
printf '第一行修改后\n\n第二段也更新\n' | python3 "$SCRIPT" edit --slug "MTIzMDgzNzgz" --stdin

Output Conventions

输出规范

```
query --format json
```
returns structured memo hits
```
query --format markdown
```
returns a readable markdown list
```
summarize
```
returns memo counts, top tags, and supporting memos
```
export-monthly
```
writes one markdown file per month plus
```
tag-stats.md
```

tags

returns existing tag rows with

tag

depth

parent

direct_count

total_count

```
create
```
returns the created memo payload with parsed markdown and tags
```
edit
```
returns the updated memo payload with parsed markdown and tags

```
query --format json
```
返回结构化的备忘录匹配结果
```
query --format markdown
```
返回易读的markdown列表
```
summarize
```
返回备忘录数量、热门标签和相关备忘录
```
export-monthly
```
按月份生成markdown文件，同时输出
```
tag-stats.md
```
```
tags
```
返回现有标签行，包含
```
tag
```
、
```
depth
```
、
```
parent
```
、
```
direct_count
```
、
```
total_count
```
字段
```
create
```
返回创建的备忘录 payload，包含解析后的markdown和标签
```
edit
```
返回更新后的备忘录 payload，包含解析后的markdown和标签

Safety Rules

安全规则

Only use
```
create
```
when the user explicitly asks for a new memo
Only use
```
edit
```
when the user explicitly asks to modify an existing memo
Do not invent new tags casually; check existing tags first with
```
tags
```
Do not delete flomo memos from this skill
Do not persist extra raw dumps unless the user explicitly asks
Treat summaries as patterns from memo evidence, not diagnoses
Never use Markdown syntax in memo content
Never create task lists or checkboxes in flomo memos

仅当用户明确要求创建新备忘录时使用
```
create
```
命令
仅当用户明确要求修改现有备忘录时使用
```
edit
```
命令
不要随意创建新标签，先使用
```
tags
```
命令检查现有标签
不要通过该技能删除flomo备忘录
除非用户明确要求，不要额外存储原始导出内容
总结内容是备忘录证据呈现的规律，而非诊断结论
绝对不要在备忘录内容中使用Markdown语法
绝对不要在flomo备忘录中创建任务列表或复选框

Resources

资源

scripts/

```
scripts/flomo_local_api.py
```
: CLI for flomo query, summarize, export, lightweight create, and text edit

```
scripts/flomo_local_api.py
```
: 支持flomo查询、总结、导出、轻量创建和文本编辑的CLI工具