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=...

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

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

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

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.

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"

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.

Summarize

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

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

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.

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

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

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

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

Resources

scripts/

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

flomo-local-api

NPX Install

Tags

SKILL.md Content

Flomo Local API

Overview

Preconditions

Use This Skill When

Do Not Use This Skill When

Default Workflow

Commands

Command Template

Query

Summarize

Export Monthly

Tags

Create

Edit

Output Conventions

Safety Rules

Resources

scripts/