flomo

# flomo

Use this skill on macOS to read and write flomo content.

## Commands

- Read recent memos (remote API, recommended; auto-expands time window):

```bash
python3 scripts/flomo_tool.py read --remote --limit 20
```

- Search recent memos by keyword (remote API):

```bash
python3 scripts/flomo_tool.py read --remote --limit 100 --query "关键词"
```

- Read by tag (recommended for diary/book/etc):

```bash
python3 scripts/flomo_tool.py read --remote --limit 10 --tag "日记"
```

- List top tags (to see how many memos each tag has):

```bash
python3 scripts/flomo_tool.py read --dump-tags --limit 20
```

- Write memo (auto-resolve incoming webhook from local flomo login state):

```bash
python3 scripts/flomo_tool.py write --content "内容"
```

- Write memo via URL scheme (opens flomo app draft):

```bash
python3 scripts/flomo_tool.py write --content "内容" --url-scheme
```

- One-shot health check (read + write-url-scheme dry flow):

```bash
python3 scripts/flomo_tool.py verify --try-webhook --query "#openclaw"
```

## Behavior Rules

- Prefer webhook write; script can auto-resolve webhook when logged in on this Mac.
- Use URL scheme write only as fallback, because it requires GUI interaction to confirm/save.
- Read path uses remote API first and can auto-expand search window for sparse tags/keywords.
- For tag intent, prefer `--tag`; `--query "#标签"` is also supported.
- Never print full webhook URL in logs; only print masked form.

# OpenClaw flomo Skill (Read + Write)

[English](README.md) | [中文](README.zh-CN.md)

This folder is a shareable OpenClaw skill that can **read and write flomo memos on macOS**.

## What's New (2026-02-11)

- Improved read reliability for sparse tags/keywords:
  - `read --remote` now auto-expands the query window (`1d -> 7d -> 30d -> 180d -> 365d -> 5y`) until enough results are found.
- Added first-class tag filter:
  - `read --tag "xxx"` for exact tag intent.
  - `read --query "#xxx"` is also treated as tag query for backward compatibility.
- Added tag diagnostics:
  - `read --dump-tags --limit N` returns top tags with counts, to quickly verify how many memos are available per tag.
- Sorting and truncation behavior is stabilized:
  - Results are sorted by `updated_at` (then `created_at`) descending before applying `--limit`.
- `FLOMO_SINCE_SECONDS` behavior changed:
  - `0` (default) means auto-expand window.
  - `>0` forces a fixed query window.

## What It Does

- **Read**: fetch recent memos via flomo's API (`/api/v1/memo/updated/`) using your local flomo desktop login state.
- **Write**: create memos via flomo **incoming webhook** (`https://flomoapp.com/iwh...`).
- **Verify**: end-to-end check (remote read + webhook write + readback hit).

## Requirements

- macOS
- flomo desktop app installed and **logged in**
- `curl` available
- OpenClaw (optional, but recommended)

## Security Model (Important)

- This skill **does not include** your `access_token` or your `incoming webhook` URL.
- The script reads your local flomo app config on *your machine* (default path):
  - `~/Library/Containers/com.flomoapp.m/Data/Library/Application Support/flomo/config.json`
- The script fetches your incoming webhook path from flomo API on-demand.
- Do **not** share your local flomo `config.json` with anyone.

## Install (OpenClaw)

1. Copy this folder to the OpenClaw workspace skills directory:

```bash
mkdir -p ~/.openclaw/workspace/skills/flomo
rsync -a --delete ./openclaw-flo...