{"id":"5312b4ff-0fe6-4b03-9f78-004db9f80b78","entityType":"agent","slug":"clawhub-tristanmanchester-clipboard-memory","name":"clipboard-memory","canonicalUrl":"https://www.xpersona.co/agent/clawhub-tristanmanchester-clipboard-memory","canonicalPath":"/agent/clawhub-tristanmanchester-clipboard-memory","generatedAt":"2026-10-10T06:44:32.148Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T01:35:21.186Z","emptyReason":null},"description":"Recall what the user copied on this Mac via the local clipmem archive — text, commands, URLs, file paths, HTML, images, PDFs. Triggers on requests like \"what was that command I copied?\", \"the URL I copied from Safari\", \"find that snippet before I restarted\", or any paraphrase involving copy, paste, or clipboard. Offers ranked recall, chronological timeline, lexical / FTS search, raw-byte export for binary content, cursor pagination, and filters by app, kind, time window, and content shape. Use before reaching for generic web or repo search whenever the user is trying to recover something they previously had on the clipboard.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.8K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s17c3xv8wvvzzbj84z9vcj498n83gnkp:clipboard-memory","sourceUrl":"https://clawhub.ai/tristanmanchester/clipboard-memory","homepage":"https://clawhub.ai/tristanmanchester/skills/clipboard-memory","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/tristanmanchester/clipboard-memory","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/tristanmanchester/skills/clipboard-memory","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":65,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"clipboard-memory technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T01:35:21.186Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T01:35:21.186Z","emptyReason":null},"stars":null,"forks":null,"downloads":1803,"packageName":null,"latestVersion":"1.3.9","tractionLabel":"1.8K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T01:35:21.186Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T01:35:21.186Z","lastCrawledAt":"2026-10-10T01:35:21.186Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T01:35:21.186Z","lastVerifiedAt":null,"highlights":[{"version":"1.3.9","createdAt":"2026-09-13T11:22:40.819Z","changelog":"Skill replacement and uninstall now reject unrecognized directories and symlinked paths. Uninstall removes only packaged files, preserving unrelated user files ClawHub skill publication accepts the current version's release notes after Unreleased entries are promoted for a release LaunchAgent configuration stores absolute archive and log paths. Skill discovery expands home-relative paths and respects custom OpenClaw state and Hermes home directories Refresh compatible Rust dependencies, GitHub Actions, ClawHub CLI (0.23.3), and cargo-dist (0.33.0); retain Rust 1.88 compatibility and add latest-stable CI coverage. Use Servo's HTML5 entity table for rich-text projection Package clipboard-memory skill 1.3.9 with updated health checks and service instructions Updated the ClawHub `clipboard-memory` skill package to 1.3.9 so setup guidance no longer promises an implicit clipboard capture and directs explicit current-clipboard capture through `clipmem capture-once`","fileCount":9,"zipByteSize":25328},{"version":"1.3.8","createdAt":"2026-07-11T20:47:19.291Z","changelog":"Updated the ClawHub `clipboard-memory` skill package to 1.3.8 so setup guidance no longer promises an implicit clipboard capture and directs explicit current-clipboard capture through `clipmem capture-once`","fileCount":9,"zipByteSize":25152},{"version":"1.3.7","createdAt":"2026-05-30T18:47:20.733Z","changelog":"Updated the packaged `clipboard-memory` skill to 1.3.7 so ClawHub publishes the current package contents after the 0.5.2 release","fileCount":9,"zipByteSize":24842},{"version":"1.3.6","createdAt":"2026-05-27T06:33:02.656Z","changelog":"Fixed Hermes skill metadata validation so `platforms` and `tags` require exact YAML list items instead of accepting substring matches Updated the packaged `clipboard-memory` skill to 1.3.6 to document that `forget` and `purge` also remove orphaned OCR result rows via an explicit cleanup step rather than only via foreign-key cascades Updated the packaged `clipboard-memory` skill to 1.3.5 for the refreshed command reference and settings JSON output documentation","fileCount":9,"zipByteSize":25000},{"version":"1.3.5","createdAt":"2026-05-05T12:38:02.875Z","changelog":"Updated the packaged `clipboard-memory` skill to 1.3.5 for the refreshed command reference and settings JSON output documentation","fileCount":8,"zipByteSize":23547},{"version":"1.3.4","createdAt":"2026-04-29T14:39:02.561Z","changelog":"Added an agent-native action parity contract that maps user-visible clipboard outcomes to CLI and skill surfaces, and linked it from the CLI help, packaged skills, and architecture docs Strengthened packaged agent skill policy around context preflights, primitive command composition, low-confidence handling, exact-text quoting, and OS follow-through actions Added menu bar Diagnostics discovery actions for copying agent context and skill install commands, and documented the agent context path in getting started and menu bar app docs Added richer menu bar Diagnostics agent discovery actions for OpenClaw and Hermes doctor commands, packaged skill inspection, and the maintained capability map Updated the ClawHub `clipboard-memory` skill package to 1.3.4 for the agent-native command and JSON contract updates","fileCount":8,"zipByteSize":23529},{"version":"1.3.3","createdAt":"2026-04-26T06:25:24.158Z","changelog":"Updated the ClawHub clipboard-memory skill package to 1.3.3 so the revised command and setup-check references can publish cleanly Improved OpenClaw and Hermes skill validation by deduplicating referenced Markdown files with borrowed-path tracking instead of allocating a path for every repeated link. In a 25,000-reference agent skill benchmark, median reference extraction time dropped from 5.483 ms to 3.875 ms","fileCount":8,"zipByteSize":20670},{"version":"1.3.2","createdAt":"2026-04-25T15:16:25.176Z","changelog":"Updated the ClawHub clipboard-memory skill package to 1.3.2 so the revised command and setup-check references can publish cleanly","fileCount":8,"zipByteSize":20596}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17c3xv8wvvzzbj84z9vcj498n83gnkp:clipboard-memory","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17c3xv8wvvzzbj84z9vcj498n83gnkp:clipboard-memory` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/tristanmanchester/clipboard-memory before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tristanmanchester-clipboard-memory/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tristanmanchester-clipboard-memory/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tristanmanchester-clipboard-memory/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-tristanmanchester-clipboard-memory/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-tristanmanchester-clipboard-memory/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-tristanmanchester-clipboard-memory/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T06:44:32.144Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tristanmanchester-clipboard-memory/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tristanmanchester-clipboard-memory/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tristanmanchester-clipboard-memory/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tristanmanchester-clipboard-memory/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T01:35:21.186Z","emptyReason":null},"readme":"Skill: clipboard-memory\n\nOwner: tristanmanchester\n\nSummary: Recall what the user copied on this Mac via the local clipmem archive — text, commands, URLs, file paths, HTML, images, PDFs. Triggers on requests like \"what was that command I copied?\", \"the URL I copied from Safari\", \"find that snippet before I restarted\", or any paraphrase involving copy, paste, or clipboard. Offers ranked recall, chronological timeline, lexical / FTS search, raw-byte export for binary content, cursor pagination, and filters by app, kind, time window, and content shape. Use before reaching for generic web or repo search whenever the user is trying to recover something they previously had on the clipboard.\n\nTags: latest:1.3.9\n\nVersion history:\n\nv1.3.9 | 2026-09-13T11:22:40.819Z | user\n\nSkill replacement and uninstall now reject unrecognized directories and symlinked paths. Uninstall removes only packaged files, preserving unrelated user files ClawHub skill publication accepts the current version's release notes after Unreleased entries are promoted for a release LaunchAgent configuration stores absolute archive and log paths. Skill discovery expands home-relative paths and respects custom OpenClaw state and Hermes home directories Refresh compatible Rust dependencies, GitHub Actions, ClawHub CLI (0.23.3), and cargo-dist (0.33.0); retain Rust 1.88 compatibility and add latest-stable CI coverage. Use Servo's HTML5 entity table for rich-text projection Package clipboard-memory skill 1.3.9 with updated health checks and service instructions Updated the ClawHub `clipboard-memory` skill package to 1.3.9 so setup guidance no longer promises an implicit clipboard capture and directs explicit current-clipboard capture through `clipmem capture-once`\n\nv1.3.8 | 2026-07-11T20:47:19.291Z | user\n\nUpdated the ClawHub `clipboard-memory` skill package to 1.3.8 so setup guidance no longer promises an implicit clipboard capture and directs explicit current-clipboard capture through `clipmem capture-once`\n\nv1.3.7 | 2026-05-30T18:47:20.733Z | user\n\nUpdated the packaged `clipboard-memory` skill to 1.3.7 so ClawHub publishes the current package contents after the 0.5.2 release\n\nv1.3.6 | 2026-05-27T06:33:02.656Z | user\n\nFixed Hermes skill metadata validation so `platforms` and `tags` require exact YAML list items instead of accepting substring matches Updated the packaged `clipboard-memory` skill to 1.3.6 to document that `forget` and `purge` also remove orphaned OCR result rows via an explicit cleanup step rather than only via foreign-key cascades Updated the packaged `clipboard-memory` skill to 1.3.5 for the refreshed command reference and settings JSON output documentation\n\nv1.3.5 | 2026-05-05T12:38:02.875Z | user\n\nUpdated the packaged `clipboard-memory` skill to 1.3.5 for the refreshed command reference and settings JSON output documentation\n\nv1.3.4 | 2026-04-29T14:39:02.561Z | user\n\nAdded an agent-native action parity contract that maps user-visible clipboard outcomes to CLI and skill surfaces, and linked it from the CLI help, packaged skills, and architecture docs Strengthened packaged agent skill policy around context preflights, primitive command composition, low-confidence handling, exact-text quoting, and OS follow-through actions Added menu bar Diagnostics discovery actions for copying agent context and skill install commands, and documented the agent context path in getting started and menu bar app docs Added richer menu bar Diagnostics agent discovery actions for OpenClaw and Hermes doctor commands, packaged skill inspection, and the maintained capability map Updated the ClawHub `clipboard-memory` skill package to 1.3.4 for the agent-native command and JSON contract updates\n\nv1.3.3 | 2026-04-26T06:25:24.158Z | user\n\nUpdated the ClawHub clipboard-memory skill package to 1.3.3 so the revised command and setup-check references can publish cleanly Improved OpenClaw and Hermes skill validation by deduplicating referenced Markdown files with borrowed-path tracking instead of allocating a path for every repeated link. In a 25,000-reference agent skill benchmark, median reference extraction time dropped from 5.483 ms to 3.875 ms\n\nv1.3.2 | 2026-04-25T15:16:25.176Z | user\n\nUpdated the ClawHub clipboard-memory skill package to 1.3.2 so the revised command and setup-check references can publish cleanly\n\nv1.3.1 | 2026-04-21T09:27:05.308Z | user\n\nRepublish the current skill package with schema_version 2 guidance, recent command coverage, export --force guidance, and OpenClaw metadata version 1.3.1.\n\nv1.3.0 | 2026-04-19T18:57:17.130Z | user\n\nAdd opt-in local OCR retrieval fields, OCR commands, and JSON schema_version 2 guidance.\n\nv1.2.1 | 2026-04-17T17:14:13.680Z | user\n\nBump skill version to match newer package content already present in the repo.\n\nv1.2.0 | 2026-04-17T12:50:32.687Z | user\n\nAdds first-class `clipmem setup` and `clipmem service` onboarding, Homebrew-aware service checks, and updated troubleshooting/setup guidance for Cargo and Homebrew installs.\n\nv1.1.1 | 2026-04-17T11:28:35.465Z | user\n\nNormalize the skill identity around clipboard-memory, add a canonical repo-root package for skills.sh discovery, and align OpenClaw packaging, docs, and install paths.\n\nv1.1.0 | 2026-04-17T10:53:55.898Z | user\n\nInitial public release of the clipmem-powered clipboard recovery skill, including setup checks, examples, JSON schema docs, and stricter OpenClaw doctor guidance.\n\nArchive index:\n\nArchive v1.3.9: 9 files, 25328 bytes\n\nFiles: references/commands.md (20467b), references/examples.md (4889b), references/json-schema.md (5907b), references/setup-check.md (2409b), references/troubleshooting.md (5272b), scripts/check-setup.sh (9231b), skill-card.md (2885b), SKILL.md (10251b), _meta.json (135b)\n\nFile v1.3.9:SKILL.md\n\n---\nname: clipboard-memory\ndescription: Recall what the user copied on this Mac via the local clipmem archive — text, commands, URLs, file paths, HTML, images, PDFs. Triggers on requests like \"what was that command I copied?\", \"the URL I copied from Safari\", \"find that snippet before I restarted\", or any paraphrase involving copy, paste, or clipboard. Offers ranked recall, chronological timeline, lexical / FTS search, raw-byte export for binary content, cursor pagination, and filters by app, kind, time window, and content shape. Use before reaching for generic web or repo search whenever the user is trying to recover something they previously had on the clipboard.\nlicense: MIT\nmetadata: {\"openclaw\":{\"emoji\":\"📋\",\"os\":[\"darwin\"],\"requires\":{\"bins\":[\"clipmem\"]},\"install\":[{\"id\":\"brew\",\"kind\":\"brew\",\"label\":\"Install clipmem (brew)\",\"bins\":[\"clipmem\"],\"formula\":\"clipmem\",\"tap\":\"tristanmanchester/tap\"},{\"id\":\"cargo\",\"kind\":\"cargo\",\"label\":\"Install clipmem (cargo)\",\"bins\":[\"clipmem\"],\"package\":\"clipmem\"}],\"version\":\"1.3.9\"}}\n---\n\nRecall what the user copied on this Mac before reaching for generic search. `clipmem` maintains a local, privacy-preserving SQLite archive of every clipboard state macOS emits, and exposes a JSON-first CLI built for agents. This package is installed by `clipmem agents openclaw install-skill`; the canonical cross-agent source lives under `skills/clipboard-memory/`.\n\n## Use this skill when\n\nThe user asks things like:\n\n- \"what was that command I copied?\"\n- \"show me the URL I copied from Safari earlier\"\n- \"find that snippet, path, note, or link I copied yesterday\"\n- \"give me the exact text I copied, not a summary\"\n- \"what did I copy before I restarted?\"\n- \"paste me back that SQL I was looking at\"\n- \"get the PDF I copied last week\"\n- \"show me everything I copied from Xcode today\"\n\n## Do not use this skill for\n\n- web search or current-events lookups\n- searching the repository or local files the user never copied\n- content the user typed but never copied to the clipboard\n- anything on a non-macOS machine (`clipmem` captures `NSPasteboard` only)\n\n## Prerequisites\n\nBefore querying, confirm the setup is healthy — otherwise empty results may be a stale watcher, not a true miss:\n\n1. Background capture must be running. `clipmem setup` is the canonical fix; Homebrew users can also use `clipmem service start`.\n2. The binary `clipmem` must be on PATH with write access to `~/Library/Application Support/clipmem/clipmem.sqlite3`.\n3. Run [`scripts/check-setup.sh`](scripts/check-setup.sh) once per session when results look wrong. It exits `0` on a healthy host, `1` if the watcher is stale, `2` if the binary is missing, `3` if `clipmem doctor` fails. The prose equivalent is in [references/setup-check.md](references/setup-check.md).\n4. If OpenClaw cannot see the binary, run `clipmem agents openclaw doctor` and follow its remediation lines.\n\n## Command ladder\n\nAlways pick the narrowest command that answers the question, and always pass `--format json` (or `--format toon` for plain enumeration) so you can parse the response deterministically.\n\n1. **`clipmem recall`** — best-first ranked answer with alternatives. Start here for almost every request.\n2. **`clipmem timeline`** — chronological capture events (one row per copy), including repeated copies of the same content. Use for \"today\", \"yesterday\", \"in order\", or \"every time\".\n3. **`clipmem search`** — direct lexical / FTS matching. Use when you need precise substring hits or the user gave you an exact phrase.\n4. **`clipmem get <snapshot_id>`** — nested item/representation detail for a single snapshot already in hand.\n5. **`clipmem export <snapshot_id> --item <n> --uti <uti> --out <path> [--force]`** — raw bytes. Use when the stored content is binary/image/PDF and `best_text` is empty or partial. Prefer a fresh output path; use `--force` only to replace an existing regular file.\n6. **`clipmem ocr candidates`, `clipmem ocr get`, `clipmem ocr clear`, and `clipmem storage image-candidates`** — inspect queued OCR or image optimization work before running batch workflows, or clear one stale OCR result.\n7. **`clipmem settings reset --format json`** — reset capture policy and ignored apps when the user explicitly asks to restore defaults.\n8. **`clipmem service providers --format json`** — inspect service provider state without starting or stopping capture.\n9. **`clipmem service revision --format json`** — inspect archive revision counters without probing service providers.\n10. **`clipmem app settings`, `clipmem app launch-at-login`, `clipmem app update-check run`, or `clipmem app quit` with `--format json`** — inspect or change menu bar app preferences and app-owned state when the user asks about app defaults, update checks, or quitting the app.\n11. **`clipmem agents context --format json`** — compact health, settings, app state, recent activity, revision, stats, privacy, and capability context before multi-step work.\n\n## Primitive command taxonomy\n\nPrimitive commands expose one bounded read or mutation that can be composed\ndirectly. Convenience workflows such as `recall`, `setup`, `purge`, `ocr run`, and\n`storage optimize-images` remain useful, but verify uncertain results with\n`search`, `recent`, `timeline`, or `get`, and preview broad mutations with\ncandidate or dry-run commands when available.\n\nThe full flag reference, JSON envelope, and kind values live in [references/commands.md](references/commands.md), [references/json-schema.md](references/json-schema.md), and [references/examples.md](references/examples.md).\n\n## Critical behaviour rules\n\n- Before answering from a stale, empty, or ambiguous archive, run `clipmem agents context --format json` and use `generated_at`, health, settings, app state, recent activity, revision, stats, privacy, and capability fields to decide whether to broaden search or diagnose setup.\n- Always use `--format json` when you will parse the response. `--format toon` is for token-efficient enumeration only. `--format jsonl` is for streaming many rows into a pipeline. Never parse `md` or `text`.\n- Treat `recall` as a convenience ranking helper, not an authority. For uncertain cases, compose primitive commands in this order: `search`, `recent`, `timeline`, `get`, then OS follow-through such as `pbcopy`, `open`, or `open -R`.\n- Never claim \"nothing found\" until you have broadened the search once and checked `truncated` / `next_cursor`.\n- When `best_match_confidence` is `\"low\"` or there are several plausible hits, present the top candidates instead of pretending certainty.\n- For exact-text requests, quote `best_text` verbatim. Do not paraphrase commands, SQL, code, URLs, or file paths unless the user asked for a summary.\n\n## Capability map\n\nThe repo-side agent-native action parity contract lives in `docs/action-parity.md`. Use it when you need the maintained map from user-visible outcomes to agent-accessible commands, entity CRUD expectations, and derived-cache boundaries.\n\n## Output format rule\n\n- `--format json` — structured output. Retrieval envelopes are stable within `schema_version: 2`; management and inspection commands use command-specific JSON shapes, so parse documented keys directly.\n- `--format toon` — flat, token-efficient list. Prefer for high-cardinality enumeration (`timeline`, `search`, `recent`, `recall`) when you only need the top fields. Note: `get` does **not** support `toon`.\n- `--format jsonl` — newline-delimited records. Use when streaming many rows into a pipeline.\n- `--format md` / `--format text` — human-readable previews only; never parse these.\n\n`--json` is an alias for `--format json` on `search`, `recent`, `timeline`, `get`, `service revision`, `capture-once`, and `doctor`.\n\n## Which command for which intent\n\n| User intent | First command |\n|---|---|\n| \"what was that thing I copied\" (no time cue) | `recall \"<query>\" --format json` |\n| \"what did I copy today / yesterday / in order\" | `timeline --hours <N> --format json` |\n| \"recent unique things I copied\" | `recent --hours <N> --format json` |\n| exact substring or punctuation-heavy query | `search --mode literal \"<query>\" --format json` |\n| already have a snapshot id | `get <id> --format json` |\n| need raw image / PDF bytes | `get <id>` then `export <id> --item <n> --uti <uti> --out <path>` |\n\n`recall` vs `recent` vs `timeline`:\n\n- `recall` ranks across the archive and returns a best candidate plus alternatives.\n- `recent` deduplicates by snapshot — identical copies collapse into one row.\n- `timeline` is event-centric — every capture event is its own row, even if the content repeats.\n\n## Quick examples\n\n```bash\n# best-first answer\nclipmem recall \"that command I copied\" --format json --limit 5\n\n# Safari today, token-efficient\nclipmem recall --prefer-recent --app safari --hours 24 --format toon\n\n# exact URL yesterday\nclipmem recall \"url\" --has-url --hours 48 --format json\n\n# chronological sweep, paginated\nclipmem timeline --hours 24 --limit 25 --format json\nclipmem timeline --hours 24 --limit 25 --cursor \"<next_cursor>\" --format json\n\n# recover an image\nclipmem get 42 --format json\nclipmem export 42 --item 0 --uti public.png --out ./clipboard.png\nclipmem export 42 --item 0 --uti public.png --out ./clipboard.png --force\n```\n\n## Reading the response\n\nRead these JSON fields first; walk nested `items[].representations[]` only after a `get` call:\n\n- `best_candidate.best_text` — the flattened primary text.\n- `best_candidate.urls` — URL array (empty when none).\n- `best_candidate.file_paths` — file-URL array.\n- `why_selected`, `best_match_confidence`, `alternatives` (only on `recall`).\n- `next_cursor`, `truncated` — pagination state.\n- `schema_version` — pin to `2` for stability.\n\nFull schema in [references/json-schema.md](references/json-schema.md).\n\n## Troubleshooting\n\nIf `recall` looks empty or weak, widen `--hours`, drop source filters, or switch to `timeline` / `search`. For setup issues, sandbox PATH problems, or binary-only snapshots, see [references/troubleshooting.md](references/troubleshooting.md).\n\n## Exit codes\n\n`0` success · `1` uncategorized runtime · `2` invalid args · `3` not found · `4` unsupported format · `5` database error · `6` platform error.\n\nFile v1.3.9:_meta.json\n\n{\n  \"ownerId\": \"kn762fvz617r91c4h7qr9bdbp97zar1g\",\n  \"slug\": \"clipboard-memory\",\n  \"version\": \"1.3.9\",\n  \"publishedAt\": 1789298560819\n}\n\nFile v1.3.9:references/commands.md\n\n# Clipboard Memory — Commands Reference\n\nFull flag and subcommand reference for `clipmem`. This file is kept byte-identical across the OpenClaw-native and portable skill packages.\n\n---\n\n## Decision ladder\n\nPick the narrowest command that answers the question. Always pass `--format json` (or `--format toon` for plain enumeration) when parsing programmatically.\n\n1. `clipmem recall \"<query>\" --format json` — best-first ranked answer with alternatives. **Start here.**\n2. `clipmem timeline --hours <N> --format json` — chronological capture events. Use when the user says \"today\", \"yesterday\", \"in order\", or \"every time\".\n3. `clipmem recent --hours <N> --format json` — deduplicated recent snapshots. Use for \"recent unique things\".\n4. `clipmem search \"<query>\" --format json` — direct lexical / FTS match. Use when you need precise substring hits.\n5. `clipmem get <snapshot_id> --format json` — nested item/representation detail for a snapshot you already have.\n6. `clipmem restore <snapshot_id>` — restore the full stored representation set for a snapshot back onto the macOS clipboard.\n7. `clipmem export <snapshot_id> --item <n> --uti <uti> --out <path> [--force]` — raw bytes for binary/image/PDF payloads.\n8. `clipmem forget <snapshot_id>` — hard-delete one snapshot and its capture history.\n9. `clipmem purge --older-than <duration> [--dry-run]` — prune by `last_observed_at`.\n10. `clipmem storage compact [--dry-run] --format json` — reclaim SQLite/WAL disk space without changing content.\n11. `clipmem storage image-candidates --format json` — inspect image rows eligible for optimization without rewriting bytes.\n12. `clipmem storage optimize-images [--dry-run] [--no-compact] [--limit N] [--format json|--progress jsonl]` — convert eligible stored images to lossless WebP and compact by default.\n13. `clipmem service providers --format json` — inspect service provider availability without starting or stopping capture.\n14. `clipmem service revision --format json` — read archive revision counters without probing service providers.\n15. `clipmem settings show --format json` — inspect persistent capture policy.\n16. `clipmem app settings show --format json` — inspect menu bar app preferences.\n17. `clipmem app settings set KEY VALUE --format json` / `clear KEY --format json` — change app-local preferences and bump app preference revision.\n18. `clipmem app launch-at-login show|set|clear --format json` — inspect or change the app-owned launch-at-login preference bridge.\n19. `clipmem app update-check show|run|clear --format json` — inspect, run, or clear app update-check state.\n20. `clipmem app quit --format json` — request the menu bar app to quit.\n21. `clipmem agents context --format json` — one-call agent context: generated_at, service health, settings, app state, recent activity metadata, revision, stats, privacy guidance, and capability summary.\n22. `clipmem ocr status --format json` — inspect local OCR queue and result counts.\n23. `clipmem ocr candidates --format json` — inspect pending OCR candidates without running OCR.\n24. `clipmem ocr get <raw-sha256> --format json` / `clear <raw-sha256> --format json` — inspect or clear one OCR result.\n25. `clipmem ocr run [--limit N] [--snapshot ID]` — backfill OCR for image snapshots.\n\nPrimitive commands are the direct read/list/get/set/delete/start/stop surfaces\nabove. Convenience workflows are still supported but should be classified\nhonestly: `recall` ranks likely answers, `setup` composes initialization plus\nservice startup, `ocr run` processes a bounded OCR batch, and\n`storage optimize-images` scans and rewrites eligible image rows. Use\ncandidate, dry-run, or detail commands before broad workflow mutations when the\nuser has not explicitly asked to proceed.\n\n---\n\n## Subcommand matrix\n\n| Subcommand | Default `--format` | Supports `toon`? | Purpose |\n|---|---|---|---|\n| `recall [QUERY]` | `md` | yes | Ranked best-first answer with alternatives |\n| `search <QUERY>` | `text` | yes | Lexical / FTS match over the archive |\n| `recent` | `text` | yes | Recent unique snapshots (deduplicated) |\n| `timeline` | `text` | yes | Chronological capture events (not deduped) |\n| `get <SNAPSHOT_ID>` | `text` | **no** | Nested detail for one snapshot |\n| `restore <SNAPSHOT_ID>` | text | — | Restore a stored snapshot back onto the clipboard |\n| `export <SNAPSHOT_ID>` | — (raw bytes) | — | Write one representation to disk |\n| `forget <SNAPSHOT_ID>` | text | — | Hard-delete one snapshot and its capture history |\n| `purge` | text | — | Delete old snapshots by `last_observed_at` |\n| `storage compact` | text (`json` supported) | — | Reclaim SQLite/WAL disk space |\n| `storage image-candidates` | text (`json` supported) | — | List image rows eligible for optimization without mutation |\n| `storage optimize-images` | text (`json` supported, progress JSONL available) | — | Convert eligible images to lossless WebP |\n| `settings show` | `text` | **no** | Show persistent pause / retention / ignore-list policy |\n| `settings pause` | text | — | Persistently pause or resume capture; supports `json` and `human` |\n| `settings api-key-filter` | text | — | Enable or disable API key filtering; supports `json` and `human` |\n| `settings ocr` | text | — | Enable or disable local OCR for new image captures; supports `json` and `human` |\n| `settings retention` | text | — | Set retention to a duration or `forever`; supports `json` and `human` |\n| `settings reset` | text (`json` supported) | — | Reset capture policy and ignored apps to defaults |\n| `settings ignore add/remove/list` | text | **no** | Manage ignored bundle identifiers; supports `json` and `human` |\n| `app settings show` | text (`json` supported) | — | Show menu bar app preferences |\n| `app settings set` | text (`json` supported) | — | Set one menu bar app preference |\n| `app settings clear` | text (`json` supported) | — | Clear one menu bar app preference |\n| `app launch-at-login show/set/clear` | text (`json` supported) | — | Manage the app-owned launch-at-login preference bridge |\n| `app update-check show/run/clear` | text (`json` supported) | — | Show, run, or clear app update-check state |\n| `app quit` | text (`json` supported) | — | Request the menu bar app to quit |\n| `agents context` | text (`json` supported) | — | Agent context bundle: generated_at, health, settings, app state, recent activity, revision, stats, privacy, capabilities |\n| `ocr status` | text (`json` supported) | — | Local OCR queue and result counts |\n| `ocr candidates` | text (`json` supported) | — | Pending OCR candidate hashes without processing |\n| `ocr get` | text (`json` supported) | — | One OCR result by raw representation hash |\n| `ocr clear` | text (`json` supported) | — | Delete one OCR result and rebuild affected OCR cache |\n| `ocr run` | text (`json` supported) | — | Backfill OCR for stored image snapshots |\n| `capture-once` | — | — | Explicitly capture the current clipboard once |\n| `watch` | — | — | Background daemon; usually a LaunchAgent |\n| `setup` | — | — | Initialize the database and start background capture |\n| `service status` | text (or `--json`) | — | Background provider state + capture freshness |\n| `service providers` | text (`json` supported) | — | Service provider availability without mutation |\n| `service revision` | text (`json` supported) | — | Archive revision counters without provider probes |\n| `service start` / `stop` / `uninstall` | — | — | Manage the background watcher service |\n| `doctor` | text (or `--json`) | — | SQLite / FTS5 diagnostics |\n| `agents openclaw doctor` | text | — | Integration health: PATH, workspace, sandbox |\n| `agents openclaw install-skill` | — | — | Write packaged skill files to disk |\n| `agents openclaw print-skill` | — | — | Print embedded `SKILL.md` to stdout |\n| `agents openclaw uninstall-skill` | — | — | Remove installed skill directory |\n| `agents hermes doctor` | text | — | Hermes integration health: PATH, skill discovery |\n| `agents hermes install-skill` | — | — | Write packaged Hermes skill to disk |\n| `agents hermes print-skill` | — | — | Print embedded Hermes `SKILL.md` to stdout |\n| `agents hermes uninstall-skill` | — | — | Remove installed Hermes skill directory |\n\n`--json` is a compatibility alias for `--format json` on `search`, `recent`, `timeline`, `get`, `agents context`, `storage compact`, `storage optimize-images`, `ocr status`, `ocr run`, `capture-once`, and `doctor`.\n\n---\n\n## Output formats\n\nAll retrieval commands share the same `--format` set except `get`, which omits `toon`:\n\n- `text` — human-oriented terminal output. Default for `search`, `recent`, `timeline`, `get`. **Do not parse.**\n- `md` — compact markdown. Default for `recall`. Human-oriented. **Do not parse.**\n- `json` — single structured object with a stable envelope. Parse this.\n- `jsonl` — newline-delimited rows. Prefer when streaming many results through a pipe.\n- `toon` — flat token-efficient list. Prefer for `timeline`, `search`, `recent`, and `recall` when you only need the top fields. Unsupported on `get`.\n\n---\n\n## Shared retrieval filters\n\n`search`, `recent`, `timeline`, and `recall` accept the same filter set. `get` and `export` accept them as guards against the explicitly targeted snapshot.\n\n**Time window:**\n\n- `--since <RFC3339>` — captures at or after this timestamp (e.g. `2026-04-16T09:00:00Z`).\n- `--until <RFC3339>` — captures at or before this timestamp.\n- `--hours <N>` — last N hours. `--since` wins if both are provided.\n\n**Source:**\n\n- `--app <name>` — case-insensitive substring match on the recorded frontmost app name.\n- `--bundle-id <id>` — case-insensitive exact match on bundle identifier (e.g. `com.apple.Safari`).\n\n**Content shape:**\n\n- `--kind text|html|rtf|url|file|image|pdf|binary|other`. One value per invocation.\n- `--has-text`, `--has-url`, `--has-file-url`, `--has-image`, `--has-pdf` — additive presence flags (AND semantics).\n\n**Size:**\n\n- `--min-bytes <N>` / `--max-bytes <N>` — applied to the total snapshot byte count.\n\n### `--kind` values\n\n| Value | Matches |\n|---|---|\n| `text` | plain text representations |\n| `html` | HTML clipboard payloads |\n| `rtf` | rich-text format |\n| `url` | web URLs |\n| `file` | **file URLs (Finder paths)** — not regular files on disk |\n| `image` | image blobs (PNG, JPEG, TIFF, etc.) |\n| `pdf` | PDF documents |\n| `binary` | opaque binary that has no safe text projection |\n| `other` | mixed or empty snapshots |\n\n`--kind file` is a common pitfall: it matches clipboard-as-file-URL payloads (things dragged from Finder), not arbitrary files the user happened to reference.\n\n---\n\n## Pagination\n\nList commands (`search`, `recent`, `timeline`) accept `--limit` and `--cursor`:\n\n- `--limit <N>` — 1–250, default 10.\n- `--cursor <opaque>` — resume from a `next_cursor` returned by a prior response.\n\nCursors are tied to the active query, mode, and filters. Changing any of those while paginating will reject the cursor. When a response includes `\"truncated\": true` and a non-null `next_cursor`, there are more rows.\n\n```bash\nclipmem search \"git status\" --format json --limit 25\nclipmem search \"git status\" --format json --limit 25 --cursor \"<next_cursor>\"\n```\n\n---\n\n## Search modes (`search`, `recall`)\n\n`--mode auto|fts|literal`, default `auto`.\n\n- `auto` — picks FTS or literal per query. Prefers literal for URLs, paths, bundle ids, dotted identifiers, and shell fragments (`--flag=value`, pipes, subshells). Plain prose queries try FTS first.\n- `fts` — strict SQLite FTS5. Use when you want to compose boolean queries: `\"launchctl\" AND bootstrap`.\n- `literal` — exact substring match. Use for punctuation-heavy strings like `50%`, `Co-Authored-By:`, or URL fragments.\n\nRules of thumb:\n\n- Query contains `\"`, `AND`, `OR`, `NOT` → `--mode fts`.\n- Query contains `/`, `.`, `:`, `%`, or shell metacharacters → `--mode literal`.\n- Short natural-language query → let `--mode auto` pick.\n\n---\n\n## `recall` extras\n\nOn top of the shared filters:\n\n- `--format md|json|toon` (default `md`).\n- `--limit <N>` — ranked candidates to consider (default 5).\n- `--full` — expand the best candidate text instead of the compact form.\n- `--quote` — force quoted best-text output.\n- `--min-score <0.0-1.0>` — threshold below which a query alone is not trusted; falls back to recency / filters.\n- `--prefer-recent` — bias ranking toward recency.\n- `--prefer-app <name>` — bias toward matching app or bundle id.\n- `--hours <N>` — window for the recent-fallback when a query is weak.\n\nIf the user has no query but said \"the thing I just copied\":\n\n```bash\nclipmem recall --prefer-recent --hours 24 --format json --limit 5\n```\n\n---\n\n## `get`, `restore`, and `export`\n\n```bash\nclipmem get <snapshot_id> --format json        # nested representation detail\nclipmem get <snapshot_id> --events <N>         # include last N capture events (default 10)\nclipmem restore <snapshot_id>                  # restore the whole snapshot to the clipboard\nclipmem export <snapshot_id> --item <index> --uti <uti> --out <path> [--force]\n```\n\n`get --format json` flattens the common text fields on the root snapshot so agents don't have to walk the representation tree. `get` does **not** support `--format toon`.\n\n`restore` is macOS-only and writes the full stored item/UTI/raw-byte set back onto the general pasteboard. This is a whole-snapshot restore, not a text-only approximation.\n\n`export` writes raw bytes to `--out` and supports `--format json` for structured confirmation. By default it creates a new file and refuses to replace an existing destination; pass `--force` only to replace an existing regular file. Symlink destinations are rejected. Required arguments: `--item` (0-based), `--uti` (e.g. `public.png`, `public.utf8-plain-text`, `com.adobe.pdf`), `--out`. Inspect `items[].representations[].uti` and `size_bytes` in a prior `get --format json` to choose the right combination.\n\n---\n\n## `forget`, `purge`, `storage`, and `settings`\n\n```bash\nclipmem forget <snapshot_id>\nclipmem purge --older-than 30d [--dry-run]\nclipmem storage compact [--dry-run] [--format json]\nclipmem storage image-candidates [--limit N] [--format json]\nclipmem storage optimize-images [--dry-run] [--no-compact] [--limit N] [--format json|--progress jsonl]\nclipmem settings show [--format json]\nclipmem settings pause on|off [--format json]\nclipmem settings api-key-filter on|off [--format json]\nclipmem settings ocr on|off [--format json]\nclipmem settings retention <duration|forever> [--format json]\nclipmem settings reset [--format json]\nclipmem settings ignore add <bundle_id> [--format json]\nclipmem settings ignore remove <bundle_id> [--format json]\nclipmem settings ignore list [--format json]\nclipmem app settings show [--format json]\nclipmem app settings set binary-path-override <path> [--format json]\nclipmem app settings set database-path-override <path> [--format json]\nclipmem app settings set default-recent-hours <hours> [--format json]\nclipmem app settings set default-query-mode recall|search|recent|timeline|diagnostics [--format json]\nclipmem app settings set hotkey-enabled true|false [--format json]\nclipmem app settings clear <key> [--format json]\nclipmem app launch-at-login show [--format json]\nclipmem app launch-at-login set on|off [--format json]\nclipmem app launch-at-login clear [--format json]\nclipmem app update-check show [--format json]\nclipmem app update-check run [--format json]\nclipmem app update-check clear [--format json]\nclipmem app quit [--format json]\nclipmem service revision [--format json]\nclipmem ocr status [--format json]\nclipmem ocr candidates [--limit N] [--snapshot ID] [--format json]\nclipmem ocr get <raw-sha256> [--format json]\nclipmem ocr clear <raw-sha256> [--format json]\nclipmem ocr run [--limit N] [--snapshot ID] [--retry-failed] [--format json]\n```\n\n`forget` is a hard delete. It removes the snapshot row, all child items/representations, and all capture events for that snapshot id via foreign-key cascades. OCR results with no remaining representation referencing their image hash are also removed.\n\n`purge` computes age from `snapshot_stats.last_observed_at`, not `snapshots.created_at`. Duration grammar is a single integer plus one unit: `Nd`, `Nh`, or `Nm`.\n\n`storage compact` checkpoints WAL state and vacuums SQLite pages back to the filesystem. It never changes clipboard content. `storage image-candidates` lists eligible image rows without rewriting bytes or marking rows (defaults to 25, while `optimize-images` scans all candidates when `--limit` is omitted). `storage optimize-images` rewrites eligible image representations to lossless WebP only when doing so saves meaningful space, then compacts SQLite storage by default; already compressed or skipped rows are not retried by normal runs. Use `--progress jsonl` for streamed `started`, `scanning`, `compacting`, and `complete` progress events. Use `--no-compact` only when batching optimization runs and compacting once at the end.\n\n`ocr candidates` lists pending OCR hashes and affected snapshot counts without invoking Apple Vision. Use it before `ocr run` when an agent needs to inspect queue work.\n\n`settings` is the persistent capture-policy entrypoint. Ignore matching is exact, case-insensitive bundle-id matching only. OCR is opt-in, runs locally through Apple Vision on macOS, and stores text/status separately from raw image bytes.\n\n`app settings`, `app launch-at-login`, and `app update-check` are menu bar app state bridges. They read and write app-local preferences without changing archive capture policy. Mutating commands bump `app_preferences_revision` so an open app can observe external agent changes. Launch-at-login writes the desired app-owned preference; the menu bar app applies it through `SMAppService`. `app update-check run` performs the live latest-stable-release lookup and updates the same cache the app reads. `app quit` requests the menu bar app to terminate through the app bundle identifier.\n\n`clipmem agents context --format json` is safe as a first call in agent sessions. It includes `generated_at`, service health, capture policy, archive revision, bounded recent activity, menu bar app state, capability discovery, and privacy guidance. It excludes raw clipboard content and representation bytes, but includes operational metadata such as app names, timestamps, counts, paths, and app preference state.\n\n`clipmem service revision --format json` is the lightweight polling path for change detection. It reads the same archive revision counters surfaced in service status and agent context without checking Homebrew, LaunchAgent, or other service providers.\n\n---\n\n## Global flags\n\n- `--db <path>` — override the SQLite database path. Default: `~/Library/Application Support/clipmem/clipmem.sqlite3` on macOS. Use this only when pointing at an alternate archive (tests, backups).\n\n## Environment\n\n- `CLIPMEM_OPENCLAW_WORKSPACE` — overrides the OpenClaw workspace root used by `agents openclaw install-skill` and `agents openclaw doctor`. Falls back to `openclaw config get agents.defaults.workspace`, then `~/.openclaw/workspace`.\n- `HOME` — resolves `~/` in default paths.\n\n---\n\n## Exit codes\n\n- `0` — success\n- `1` — uncategorized runtime failure\n- `2` — invalid args\n- `3` — not found (e.g. snapshot id, representation)\n- `4` — unsupported format for this subcommand (e.g. `--format toon` on `get`)\n- `5` — database error\n- `6` — platform error (macOS API / filesystem)\n\nScripts can rely on these to distinguish \"no such snapshot\" (retriable with a different id) from \"database locked\" (retry with backoff) from \"wrong format\" (agent bug).\n\n---\n\n## Script-friendly guarantees\n\n- stdout contains only the requested command output.\n- stderr contains diagnostics only.\n- No interactive prompts anywhere in the CLI.\n- List commands use bounded `--limit` defaults and opaque cursor pagination.\n- Retrieval JSON envelopes (`search`, `recent`, `timeline`, `get`, `recall`, and mutation confirmations that include `schema_version`) are stable within `schema_version: 2`. Management and inspection commands such as `agents context`, `app`, `service`, `ocr`, and `storage image-candidates` have command-specific JSON shapes; parse their documented keys directly and do not require `schema_version: 2` unless the command emits it.\n\nFile v1.3.9:references/examples.md\n\n# Clipboard Memory — Worked Examples\n\nConcrete input → output walkthroughs. Byte-identical across skill packages.\n\nEach example shows the user's question, the command to run, the shape of the response, and the next step.\n\n---\n\n## Example 1 — \"What was that URL I copied from Safari yesterday?\"\n\nThe user gave a time cue (yesterday) and a source (Safari). Use `recall` with a `--prefer-recent` bias, an `--app` filter, and a generous `--hours` window.\n\n```bash\nclipmem recall \"url\" --prefer-recent --app safari --has-url --hours 48 --format json --limit 5\n```\n\nResponse (trimmed):\n\n```json\n{\n  \"schema_version\": 2,\n  \"command\": \"recall\",\n  \"best_candidate\": {\n    \"snapshot_id\": 812,\n    \"best_text\": \"https://developer.apple.com/documentation/appkit/nspasteboard\",\n    \"urls\": [\"https://developer.apple.com/documentation/appkit/nspasteboard\"],\n    \"app_name\": \"Safari\",\n    \"observed_at\": \"2026-04-16T17:45:00Z\",\n    \"why_matched\": \"url filter + recency bias\"\n  },\n  \"best_match_confidence\": \"high\",\n  \"alternatives\": [ /* ... */ ],\n  \"next_cursor\": null\n}\n```\n\nReport `best_candidate.urls[0]`. If `best_match_confidence` were `\"low\"`, enumerate `alternatives` instead.\n\n---\n\n## Example 2 — \"Show me everything I copied today, in order\"\n\nThe user wants chronological events, not deduplicated recent snapshots. Use `timeline` and `toon` for efficient enumeration.\n\n```bash\nclipmem timeline --hours 24 --format toon --sort asc --limit 50\n```\n\nTOON output (one row per line, tab-separated scalar fields):\n\n```\nsnapshot_id\tobserved_at\tapp_name\tkind\tbest_text\n812\t2026-04-17T08:02:11Z\tSafari\turl\thttps://developer.apple.com/…\n813\t2026-04-17T08:04:03Z\tTerminal\ttext\tgit status\n813\t2026-04-17T08:11:59Z\tTerminal\ttext\tgit status\n...\n```\n\nNotice snapshot `813` appears twice — `timeline` shows each capture event, not each unique snapshot. If `truncated` shows more rows exist, re-run with the last row's time as `--until` or request `--format json` and page via `--cursor`.\n\n---\n\n## Example 3 — \"Pull the image I copied from that screenshot tool\"\n\nImages have no text projection. Use `recall` to find the snapshot, then `get` to discover the representation `uti` and byte size, then `export` to write raw bytes.\n\n```bash\n# 1. find the snapshot\nclipmem recall \"screenshot\" --kind image --hours 72 --format json --limit 3\n```\n\n```json\n{\n  \"best_candidate\": {\n    \"snapshot_id\": 901,\n    \"kind\": \"image\",\n    \"best_text\": null,\n    \"total_bytes\": 138402,\n    \"app_name\": \"CleanShot X\"\n  }\n}\n```\n\n```bash\n# 2. inspect representations to pick a uti\nclipmem get 901 --format json\n```\n\n```json\n{\n  \"snapshot\": {\n    \"items\": [\n      {\n        \"item_index\": 0,\n        \"representations\": [\n          { \"uti\": \"public.png\", \"size_bytes\": 138402, \"is_indexed\": false },\n          { \"uti\": \"public.tiff\", \"size_bytes\": 412004, \"is_indexed\": false }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```bash\n# 3. export raw bytes\nclipmem export 901 --item 0 --uti public.png --out ./clipboard.png\nclipmem export 901 --item 0 --uti public.png --out ./clipboard.png --force\n```\n\n`export` writes binary content to `--out` and exits 0 on success. It creates a new file by default; pass `--force` only to replace an existing regular file. There is no `--format` on `export`.\n\n---\n\n## Example 4 — Paginating a large search\n\nThe user asks for everything matching a phrase. `search` returns bounded pages; use the cursor to keep going.\n\n```bash\nclipmem search \"launchctl bootstrap\" --mode literal --format json --limit 25\n```\n\n```json\n{\n  \"schema_version\": 2,\n  \"command\": \"search\",\n  \"results\": [ /* 25 rows */ ],\n  \"truncated\": true,\n  \"next_cursor\": \"eyJvZmZzZXQiOjI1LCJxdWVyeSI6Imxhdw...\"\n}\n```\n\n```bash\nclipmem search \"launchctl bootstrap\" --mode literal --format json --limit 25 \\\n  --cursor \"eyJvZmZzZXQiOjI1LCJxdWVyeSI6Imxhdw...\"\n```\n\nStop paginating when `truncated` is `false` or `next_cursor` is `null`.\n\nCursors are tied to the active query, mode, and filters. Changing any of those mid-pagination invalidates the cursor — start over.\n\n---\n\n## Example 5 — \"Give me the exact text, not a summary\"\n\nBy default `recall` returns a compact form. Force quoted, full text:\n\n```bash\nclipmem recall \"the SQL migration\" --quote --full --format json\n```\n\n`best_candidate.best_text` now holds the complete stored text. If it's still truncated (very large clipboards), use `get --format json` and concatenate `text_fragments[].text`.\n\n---\n\n## Example 6 — \"Nothing is copied from today\" — diagnose first\n\nDon't assume the archive is wrong; the watcher may have stopped.\n\n```bash\n./scripts/check-setup.sh\n# or, inline\nclipmem doctor --json\nclipmem service status --json\n```\n\nIf `clipmem service status --json` reports `stale: true`, the watcher is not running. Tell the user to run `clipmem setup` or `clipmem service start` before retrying.\n\nSee [troubleshooting.md](troubleshooting.md) for remediation steps.\n\nFile v1.3.9:references/json-schema.md\n\n# Clipboard Memory — JSON Schema\n\nStable response shapes for `--format json`. Current `schema_version` is `2`. This file is kept byte-identical across skill packages.\n\nBreaking changes to these fields will bump `schema_version`. Additive changes (new optional keys) are allowed within the same version.\n\n---\n\n## Shared envelope (`recall`, `search`, `recent`, `timeline`)\n\n```json\n{\n  \"schema_version\": 2,\n  \"command\": \"recall\",\n  \"generated_at\": \"2026-04-17T12:34:56Z\",\n  \"applied_filters\": { \"hours\": 24, \"app\": \"safari\" },\n  \"truncated\": false,\n  \"next_cursor\": null,\n  \"results\": [ /* rows, see below */ ]\n}\n```\n\n- `schema_version` — integer. Pin to `2` for stability checks.\n- `command` — echoes the subcommand.\n- `generated_at` — RFC3339 timestamp when the response was produced.\n- `applied_filters` — echoes the filters actually applied after argument parsing.\n- `truncated` — `true` when more rows exist beyond `--limit`.\n- `next_cursor` — opaque string to pass back as `--cursor` when `truncated` is `true`. `null` when there are no more rows.\n- `results` — list of flattened snapshot rows.\n\n`recall` adds three extras at the top level:\n\n- `best_candidate` — the top-ranked row (also appears as `results[0]`).\n- `why_selected` — short string explaining why `best_candidate` was picked.\n- `best_match_confidence` — `\"high\" | \"medium\" | \"low\"`.\n- `best_match_score` — float in `[0.0, 1.0]`.\n- `quoted_text` — present only when `--quote` is set and usable text exists.\n\n---\n\n## Flattened snapshot row (in `results[]` and `best_candidate`)\n\nRead these first; walk nested `items[].representations[]` only after `get`.\n\n```json\n{\n  \"snapshot_id\": 42,\n  \"event_id\": 1000,\n  \"sha256\": \"<hex>\",\n  \"kind\": \"text\",\n  \"observed_at\": \"2026-04-17T12:00:00Z\",\n  \"first_seen_at\": \"2026-04-17T11:00:00Z\",\n  \"last_seen_at\":  \"2026-04-17T12:00:00Z\",\n  \"app_name\": \"Terminal\",\n  \"app_bundle_id\": \"com.apple.Terminal\",\n\n  \"best_text\": \"git status\",\n  \"best_text_uti\": \"public.utf8-plain-text\",\n  \"text_fragments\": [{ \"representation\": \"public.utf8-plain-text\", \"text\": \"git status\" }],\n  \"urls\": [],\n  \"file_paths\": [],\n  \"html_text\": null,\n  \"rtf_text\": null,\n  \"ocr_text\": null,\n  \"ocr_status\": null,\n  \"text_summary\": \"git status\",\n  \"preview_text\": \"git status\",\n\n  \"item_count\": 1,\n  \"total_bytes\": 10,\n  \"capture_count\": 3,\n  \"score\": 0.95,\n  \"why_matched\": \"full phrase match\",\n  \"matched_fields\": [\"search_text\"],\n  \"snippet\": \"git status\"\n}\n```\n\nFields to read first for common questions:\n\n| Intent | Read |\n|---|---|\n| \"what was the text\" | `best_text` (fall back to `text_summary`, `preview_text`) |\n| \"what URL\" | `urls` (array) |\n| \"what file / path\" | `file_paths` (array) |\n| \"which app\" | `app_name` / `app_bundle_id` |\n| \"when\" | `observed_at`, `first_seen_at`, `last_seen_at` |\n| \"is this binary / image / pdf\" | `kind`, presence of `best_text`, `total_bytes` |\n| \"why did recall pick this\" | `why_matched`, `matched_fields`, `score` |\n\n`best_text` can come from OCR for image-only snapshots. In that case, `best_text_uti` is `\"com.clipmem.ocr.text\"` and `ocr_status` is `\"ready\"`. If binary-only snapshots have no OCR text, fall through to `clipmem export` with a `uti` drawn from `clipmem get`.\n\n---\n\n## `clipmem get --format json`\n\n```json\n{\n  \"schema_version\": 2,\n  \"command\": \"get\",\n  \"generated_at\": \"2026-04-17T12:34:56Z\",\n  \"applied_filters\": { },\n  \"snapshot\": {\n    \"snapshot_id\": 42,\n    \"sha256\": \"<hex>\",\n    \"kind\": \"text\",\n    \"best_text\": \"git status\",\n    \"best_text_uti\": \"public.utf8-plain-text\",\n    \"text_fragments\": [ /* ... */ ],\n    \"urls\": [],\n    \"file_paths\": [],\n    \"html_text\": null,\n    \"rtf_text\": null,\n    \"ocr_text\": null,\n    \"ocr_status\": null,\n    \"text_summary\": \"git status\",\n    \"preview_text\": \"git status\",\n    \"search_text\": \"git status\",\n    \"item_count\": 1,\n    \"total_bytes\": 10,\n    \"created_at\": \"2026-04-17T11:00:00Z\",\n    \"capture_count\": 3,\n    \"first_observed_at\": \"2026-04-17T11:00:00Z\",\n    \"last_observed_at\":  \"2026-04-17T12:00:00Z\",\n    \"last_frontmost_app_name\": \"Terminal\",\n    \"last_frontmost_app_bundle_id\": \"com.apple.Terminal\",\n    \"recent_events\": [\n      { \"event_id\": 1000, \"observed_at\": \"2026-04-17T12:00:00Z\", \"change_count\": 123 }\n    ],\n    \"items\": [\n      {\n        \"item_index\": 0,\n        \"representations\": [\n          {\n            \"uti\": \"public.utf8-plain-text\",\n            \"size_bytes\": 10,\n            \"is_indexed\": true\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\nRaw bytes are **not** included in `get --format json`. The `items[].representations[]` tree gives you the `uti` and `size_bytes` needed to call `clipmem export`. `get` does not accept `--format toon`.\n\n---\n\n## `clipmem capture-once --json`\n\nReturns a single snapshot envelope similar to `get`, describing what was just captured.\n\n---\n\n## `clipmem doctor --json`\n\n```json\n{\n  \"db_path\": \"/Users/you/Library/Application Support/clipmem/clipmem.sqlite3\",\n  \"sqlite_version\": \"3.45.1\",\n  \"journal_mode\": \"wal\",\n  \"fts5_compile_option_present\": true,\n  \"fts5_create_virtual_table_ok\": true,\n  \"compile_options\": [\"ENABLE_FTS5\", \"ENABLE_RTREE\", \"…\"]\n}\n```\n\n`clipmem doctor` communicates failure via **exit code** (non-zero means the SQLite archive is corrupt, missing, or unreadable), not via a JSON `errors` field. `fts5_create_virtual_table_ok: false` means `--mode fts` will fail; use `--mode literal` instead. `fts5_compile_option_present` is the weaker \"SQLite was built with FTS5 support\" signal and is not sufficient on its own.\n\n---\n\n## Top-level keys an agent should always check\n\nBefore trusting a response:\n\n1. `schema_version == 2`.\n2. For envelopes: `truncated` and `next_cursor` before concluding \"there is nothing else\".\n3. For rows: `best_text` nullability before claiming \"I found the exact text\".\n4. For `recall`: `best_match_confidence` before committing to `best_candidate`. On `\"low\"`, surface alternatives.\n\nFile v1.3.9:references/setup-check.md\n\n# Clipboard Memory — Setup Check\n\nProse mirror of `scripts/check-setup.sh`. Use this when your runtime can't execute shell scripts directly. Byte-identical across skill packages.\n\nRun these commands in order. Stop at the first failure and repair before querying.\n\n## 1. Binary present\n\n```bash\nclipmem --version\n```\n\nExpect a version line on stdout, exit code 0. If not, `clipmem` is missing from PATH. Install via `brew install tristanmanchester/tap/clipmem` or `cargo install clipmem`.\n\n## 2. Database healthy\n\n```bash\nclipmem doctor --json\n```\n\nExpect exit 0 and `\"fts5_create_virtual_table_ok\": true` in the JSON payload. Non-zero exit means the SQLite archive is corrupt or inaccessible (failure is signalled via exit code, not a JSON `errors` field). `fts5_create_virtual_table_ok: false` means FTS queries will fail — either use `--mode literal` or rebuild the database.\n\n## 3. Service and watcher freshness\n\n```bash\nclipmem service status --json\n```\n\nExpect `stale: false`. The report also tells you whether the Homebrew service (`homebrew.mxcl.clipmem`) or the direct LaunchAgent (`io.openclaw.clipmem.watch`) is loaded and running.\n\nIf the report says no background service is loaded, start one of these:\n\n```bash\nclipmem setup\n# or\nclipmem service start\n```\n\n## 4. Agent integration (optional)\n\nIf the agent is OpenClaw, also check:\n\n```bash\nclipmem agents openclaw doctor\n```\n\nIf the agent is Hermes Agent, also check:\n\n```bash\nclipmem agents hermes doctor\n```\n\nExpect every check to report `[OK]`. `[FAIL]` lines include remediation steps.\n\n## Interpretation\n\n| Symptom | Likely cause |\n|---|---|\n| `clipmem` not found | binary not installed or not on PATH |\n| `doctor` exits non-zero | database lock, corruption, or permission issue |\n| `service status --json` reports `stale: true` | no recent captures and no background watcher running |\n| FTS query errors | `fts5_create_virtual_table_ok: false` — switch to `--mode literal` |\n| Sandboxed agent can't see the archive | PATH or file-access scope; rerun `openclaw sandbox explain` |\n\nSee `scripts/check-setup.sh` for the executable version with categorised exit codes (0 healthy, 1 watcher stale, 2 binary missing, 3 doctor failed).\n\nCapture paused is reported with exit code 4 and `paused: true`; an unknown pause state reports exit code 3. Resume deliberately using `clipmem settings pause off`. The check never resumes capture itself.\n\nFile v1.3.9:references/troubleshooting.md\n\n# Clipboard Memory — Troubleshooting\n\nDiagnose before reinterpreting. Most \"nothing found\" outcomes are a stale watcher or a mismatched filter, not a true miss.\n\nStart by running `scripts/check-setup.sh` (installed alongside this skill) or the prose in [setup-check.md](setup-check.md).\n\n---\n\n## Empty or weak `recall` result\n\nDo these in order, stopping when the result improves:\n\n1. **Widen the time window.** `--hours 72`, or drop `--hours` entirely.\n2. **Remove source filters.** The user's memory of which app doesn't always match what `clipmem` recorded as the frontmost process.\n3. **Switch to `timeline`.** If the user said \"today\" or \"yesterday\", chronological order + filters often finds things `recall`'s ranker misses.\n4. **Switch to `search`.** For exact phrases or punctuation-heavy strings, try `--mode literal`.\n5. **Loosen content shape.** Drop `--kind`, `--has-url`, `--has-text` flags — they may be excluding the right snapshot.\n\n```bash\nclipmem recall \"<query>\" --hours 72 --format json\nclipmem timeline --hours 72 --format json --limit 25\nclipmem search \"<query>\" --mode literal --format json\n```\n\n---\n\n## Watcher not running\n\nSymptom: `clipmem timeline --hours 1` returns zero rows despite the user having copied recently.\n\n```bash\nclipmem service status --json\n```\n\nIf `stale: true` or neither the Homebrew service nor the direct LaunchAgent is running:\n\n```bash\nclipmem setup\n# or, for Homebrew-native management:\nclipmem service start\n```\n\n---\n\n## FTS mode failures\n\n`clipmem search \"...\" --mode fts` errors with `fts5: syntax error` or similar:\n\n- Punctuation in the query confuses FTS5. Switch to `--mode literal`.\n- Check `clipmem doctor --json` for `\"fts5_create_virtual_table_ok\": true`. If false, the SQLite build lacks usable FTS5 — every `--mode fts` call will fail.\n- Mix of quotes and operators (`\"foo\" AND bar`) should parse in FTS5. Unbalanced quotes do not.\n\n---\n\n## Binary-only snapshots (images, PDFs, opaque blobs)\n\nSymptom: `best_text` is `null` or empty, yet `total_bytes > 0` and `kind` is `image`, `pdf`, or `binary`.\n\nThis is expected — those clipboards have no safe text projection. To recover the content:\n\n1. Call `clipmem get <snapshot_id> --format json`.\n2. Inspect `items[].representations[]` for a useful `uti` (e.g. `public.png`, `com.adobe.pdf`).\n3. Call `clipmem export <snapshot_id> --item <index> --uti <uti> --out <path>`.\n\nWhen no usable `best_text` exists, report the metadata honestly:\n\n> \"I found the clipboard item (snapshot 901, PNG from CleanShot X at 10:12 today). It has no stored text — I'd need to export the raw image to recover the content.\"\n\nDo **not** invent exact text that was never captured as text.\n\n---\n\n## OpenClaw sandbox / PATH issues\n\nSymptom: OpenClaw cannot execute `clipmem` even though it runs fine in the user's shell.\n\n```bash\nclipmem agents openclaw doctor\n```\n\nInterpret the output:\n\n- `[OK] clipmem on PATH` — binary visible to OpenClaw.\n- `[FAIL] clipmem on PATH` — the binary exists on the user's shell PATH but not the sandbox's. Add the install directory (usually `~/.local/bin` or `/opt/homebrew/bin`) to the sandbox PATH.\n- `[OK] workspace resolved` — `CLIPMEM_OPENCLAW_WORKSPACE` or `openclaw config get agents.defaults.workspace` is set.\n- `[FAIL] skill files present` — the skill was never installed. Run `clipmem agents openclaw install-skill`.\n\nAlso useful:\n\n```bash\nopenclaw sandbox explain   # when available; prints visible PATH and file-access scope\n```\n\nIf the binary was installed **after** the sandbox was created, recreate the sandbox image and retry.\n\n---\n\n## Locked or corrupt database\n\nSymptom: `clipmem doctor --json` includes errors, or retrieval commands exit with code `5`.\n\n```bash\nclipmem doctor --json\n```\n\n- `database is locked` — another writer is holding the lock. Usually the watcher under heavy load; try again in a few seconds.\n- `incompatible prerelease schema` — an older archive format is being mistaken for the current DB. Move the file aside, then run `clipmem setup`.\n- `malformed` or `corrupt` — SQLite detected structural damage. Back up `~/Library/Application Support/clipmem/clipmem.sqlite3`, then delete and let `clipmem capture-once` rebuild. You will lose history.\n- `permission denied` — the database file is not writable by the current user. Check `0600` on the file and `0700` on the containing directory (`~/Library/Application Support/clipmem/`).\n\n---\n\n## Exit code reference\n\n| Code | Meaning | Typical response |\n|---|---|---|\n| `0` | success | continue |\n| `1` | uncategorized runtime failure | inspect stderr; try again |\n| `2` | invalid args | agent bug — check flags and re-invoke |\n| `3` | not found | snapshot id, representation, or query returned no hits |\n| `4` | unsupported format | wrong `--format` for this subcommand (e.g. `toon` on `get`) |\n| `5` | database error | see \"Locked or corrupt database\" above |\n| `6` | platform error | macOS API / filesystem issue; user action likely needed |\n\n---\n\n## When to give up gracefully\n\nIf after all of the above the archive genuinely has no match:\n\n- Say so plainly. Don't hallucinate.\n- Quote the nearest metadata hits: `app_name`, `observed_at`, `kind`.\n- Suggest the user copy the item again and retry — `clipmem` captures in real time.\n\nFile v1.3.9:skill-card.md\n\n## Description:\n\nClipboard Memory helps agents recover text, commands, URLs, file paths, images, PDFs, and other items previously copied on a Mac from the local clipmem archive.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[tristanmanchester](https://clawhub.ai/user/tristanmanchester)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and end users on macOS use this skill when they need an agent to recover or inspect clipboard history from the local clipmem archive. It supports exact text recall, URL and file-path recovery, chronological timelines, targeted search, binary export, and setup diagnosis.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can expose sensitive clipboard data stored in a persistent local archive.\n\nMitigation: Install only from a trusted publisher, prefer narrow read-only recall/search/timeline/get workflows, and avoid broad searches when clipboard history may include passwords, tokens, private documents, or other sensitive data.\n\nRisk: The skill documents export, restore, delete, purge, setup, service, settings, launch-at-login, update-check, and install/uninstall commands that can change local state.\n\nMitigation: Require explicit user confirmation before state-changing commands and use candidate, detail, or dry-run commands where available before broad mutations.\n\nRisk: Stale capture services or inaccessible archives can cause misleading empty or weak recall results.\n\nMitigation: Run the setup check, doctor, service status, or agent context workflow before concluding that requested clipboard content is unavailable.\n\n## Reference(s):\n\n- [Clipboard Memory Skill Page](https://clawhub.ai/tristanmanchester/skills/clipboard-memory)\n- [Clipboard Memory Commands Reference](artifact/references/commands.md)\n- [Clipboard Memory JSON Schema](artifact/references/json-schema.md)\n- [Clipboard Memory Worked Examples](artifact/references/examples.md)\n- [Clipboard Memory Setup Check](artifact/references/setup-check.md)\n- [Clipboard Memory Troubleshooting](artifact/references/troubleshooting.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with JSON-oriented command examples and shell commands]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Guidance emphasizes JSON or toon output parsing, pagination checks, setup checks, and explicit confirmation for state-changing clipmem commands.]\n\n## Skill Version(s):\n\n1.3.9 (source: server release metadata and openclaw metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.3.8: 9 files, 25152 bytes\n\nFiles: references/commands.md (20467b), references/examples.md (4895b), references/json-schema.md (5907b), references/setup-check.md (2210b), references/troubleshooting.md (5278b), scripts/check-setup.sh (8587b), skill-card.md (3141b), SKILL.md (10257b), _meta.json (135b)\n\nFile v1.3.8:SKILL.md\n\n---\nname: clipboard-memory\ndescription: Recall what the user copied on this Mac via the local clipmem archive — text, commands, URLs, file paths, HTML, images, PDFs. Triggers on requests like \"what was that command I copied?\", \"the URL I copied from Safari\", \"find that snippet before I restarted\", or any paraphrase involving copy, paste, or clipboard. Offers ranked recall, chronological timeline, lexical / FTS search, raw-byte export for binary content, cursor pagination, and filters by app, kind, time window, and content shape. Use before reaching for generic web or repo search whenever the user is trying to recover something they previously had on the clipboard.\nlicense: MIT\nmetadata: {\"openclaw\":{\"emoji\":\"📋\",\"os\":[\"darwin\"],\"requires\":{\"bins\":[\"clipmem\"]},\"install\":[{\"id\":\"brew\",\"kind\":\"brew\",\"label\":\"Install clipmem (brew)\",\"bins\":[\"clipmem\"],\"formula\":\"clipmem\",\"tap\":\"tristanmanchester/tap\"},{\"id\":\"cargo\",\"kind\":\"cargo\",\"label\":\"Install clipmem (cargo)\",\"bins\":[\"clipmem\"],\"package\":\"clipmem\"}],\"version\":\"1.3.8\"}}\n---\n\nRecall what the user copied on this Mac before reaching for generic search. `clipmem` maintains a local, privacy-preserving SQLite archive of every clipboard state macOS emits, and exposes a JSON-first CLI built for agents. This package is installed by `clipmem agents openclaw install-skill`; the canonical cross-agent source lives under `skills/clipboard-memory/`.\n\n## Use this skill when\n\nThe user asks things like:\n\n- \"what was that command I copied?\"\n- \"show me the URL I copied from Safari earlier\"\n- \"find that snippet, path, note, or link I copied yesterday\"\n- \"give me the exact text I copied, not a summary\"\n- \"what did I copy before I restarted?\"\n- \"paste me back that SQL I was looking at\"\n- \"get the PDF I copied last week\"\n- \"show me everything I copied from Xcode today\"\n\n## Do not use this skill for\n\n- web search or current-events lookups\n- searching the repository or local files the user never copied\n- content the user typed but never copied to the clipboard\n- anything on a non-macOS machine (`clipmem` captures `NSPasteboard` only)\n\n## Prerequisites\n\nBefore querying, confirm the setup is healthy — otherwise empty results may be a stale watcher, not a true miss:\n\n1. Background capture must be running. `clipmem setup` is the canonical fix; Homebrew users can also use `brew services start clipmem`.\n2. The binary `clipmem` must be on PATH with write access to `~/Library/Application Support/clipmem/clipmem.sqlite3`.\n3. Run [`scripts/check-setup.sh`](scripts/check-setup.sh) once per session when results look wrong. It exits `0` on a healthy host, `1` if the watcher is stale, `2` if the binary is missing, `3` if `clipmem doctor` fails. The prose equivalent is in [references/setup-check.md](references/setup-check.md).\n4. If OpenClaw cannot see the binary, run `clipmem agents openclaw doctor` and follow its remediation lines.\n\n## Command ladder\n\nAlways pick the narrowest command that answers the question, and always pass `--format json` (or `--format toon` for plain enumeration) so you can parse the response deterministically.\n\n1. **`clipmem recall`** — best-first ranked answer with alternatives. Start here for almost every request.\n2. **`clipmem timeline`** — chronological capture events (one row per copy), including repeated copies of the same content. Use for \"today\", \"yesterday\", \"in order\", or \"every time\".\n3. **`clipmem search`** — direct lexical / FTS matching. Use when you need precise substring hits or the user gave you an exact phrase.\n4. **`clipmem get <snapshot_id>`** — nested item/representation detail for a single snapshot already in hand.\n5. **`clipmem export <snapshot_id> --item <n> --uti <uti> --out <path> [--force]`** — raw bytes. Use when the stored content is binary/image/PDF and `best_text` is empty or partial. Prefer a fresh output path; use `--force` only to replace an existing regular file.\n6. **`clipmem ocr candidates`, `clipmem ocr get`, `clipmem ocr clear`, and `clipmem storage image-candidates`** — inspect queued OCR or image optimization work before running batch workflows, or clear one stale OCR result.\n7. **`clipmem settings reset --format json`** — reset capture policy and ignored apps when the user explicitly asks to restore defaults.\n8. **`clipmem service providers --format json`** — inspect service provider state without starting or stopping capture.\n9. **`clipmem service revision --format json`** — inspect archive revision counters without probing service providers.\n10. **`clipmem app settings`, `clipmem app launch-at-login`, `clipmem app update-check run`, or `clipmem app quit` with `--format json`** — inspect or change menu bar app preferences and app-owned state when the user asks about app defaults, update checks, or quitting the app.\n11. **`clipmem agents context --format json`** — compact health, settings, app state, recent activity, revision, stats, privacy, and capability context before multi-step work.\n\n## Primitive command taxonomy\n\nPrimitive commands expose one bounded read or mutation that can be composed\ndirectly. Convenience workflows such as `recall`, `setup`, `purge`, `ocr run`, and\n`storage optimize-images` remain useful, but verify uncertain results with\n`search`, `recent`, `timeline`, or `get`, and preview broad mutations with\ncandidate or dry-run commands when available.\n\nThe full flag reference, JSON envelope, and kind values live in [references/commands.md](references/commands.md), [references/json-schema.md](references/json-schema.md), and [references/examples.md](references/examples.md).\n\n## Critical behaviour rules\n\n- Before answering from a stale, empty, or ambiguous archive, run `clipmem agents context --format json` and use `generated_at`, health, settings, app state, recent activity, revision, stats, privacy, and capability fields to decide whether to broaden search or diagnose setup.\n- Always use `--format json` when you will parse the response. `--format toon` is for token-efficient enumeration only. `--format jsonl` is for streaming many rows into a pipeline. Never parse `md` or `text`.\n- Treat `recall` as a convenience ranking helper, not an authority. For uncertain cases, compose primitive commands in this order: `search`, `recent`, `timeline`, `get`, then OS follow-through such as `pbcopy`, `open`, or `open -R`.\n- Never claim \"nothing found\" until you have broadened the search once and checked `truncated` / `next_cursor`.\n- When `best_match_confidence` is `\"low\"` or there are several plausible hits, present the top candidates instead of pretending certainty.\n- For exact-text requests, quote `best_text` verbatim. Do not paraphrase commands, SQL, code, URLs, or file paths unless the user asked for a summary.\n\n## Capability map\n\nThe repo-side agent-native action parity contract lives in `docs/action-parity.md`. Use it when you need the maintained map from user-visible outcomes to agent-accessible commands, entity CRUD expectations, and derived-cache boundaries.\n\n## Output format rule\n\n- `--format json` — structured output. Retrieval envelopes are stable within `schema_version: 2`; management and inspection commands use command-specific JSON shapes, so parse documented keys directly.\n- `--format toon` — flat, token-efficient list. Prefer for high-cardinality enumeration (`timeline`, `search`, `recent`, `recall`) when you only need the top fields. Note: `get` does **not** support `toon`.\n- `--format jsonl` — newline-delimited records. Use when streaming many rows into a pipeline.\n- `--format md` / `--format text` — human-readable previews only; never parse these.\n\n`--json` is an alias for `--format json` on `search`, `recent`, `timeline`, `get`, `service revision`, `capture-once`, and `doctor`.\n\n## Which command for which intent\n\n| User intent | First command |\n|---|---|\n| \"what was that thing I copied\" (no time cue) | `recall \"<query>\" --format json` |\n| \"what did I copy today / yesterday / in order\" | `timeline --hours <N> --format json` |\n| \"recent unique things I copied\" | `recent --hours <N> --format json` |\n| exact substring or punctuation-heavy query | `search --mode literal \"<query>\" --format json` |\n| already have a snapshot id | `get <id> --format json` |\n| need raw image / PDF bytes | `get <id>` then `export <id> --item <n> --uti <uti> --out <path>` |\n\n`recall` vs `recent` vs `timeline`:\n\n- `recall` ranks across the archive and returns a best candidate plus alternatives.\n- `recent` deduplicates by snapshot — identical copies collapse into one row.\n- `timeline` is event-centric — every capture event is its own row, even if the content repeats.\n\n## Quick examples\n\n```bash\n# best-first answer\nclipmem recall \"that command I copied\" --format json --limit 5\n\n# Safari today, token-efficient\nclipmem recall --prefer-recent --app safari --hours 24 --format toon\n\n# exact URL yesterday\nclipmem recall \"url\" --has-url --hours 48 --format json\n\n# chronological sweep, paginated\nclipmem timeline --hours 24 --limit 25 --format json\nclipmem timeline --hours 24 --limit 25 --cursor \"<next_cursor>\" --format json\n\n# recover an image\nclipmem get 42 --format json\nclipmem export 42 --item 0 --uti public.png --out ./clipboard.png\nclipmem export 42 --item 0 --uti public.png --out ./clipboard.png --force\n```\n\n## Reading the response\n\nRead these JSON fields first; walk nested `items[].representations[]` only after a `get` call:\n\n- `best_candidate.best_text` — the flattened primary text.\n- `best_candidate.urls` — URL array (empty when none).\n- `best_candidate.file_paths` — file-URL array.\n- `why_selected`, `best_match_confidence`, `alternatives` (only on `recall`).\n- `next_cursor`, `truncated` — pagination state.\n- `schema_version` — pin to `2` for stability.\n\nFull schema in [references/json-schema.md](references/json-schema.md).\n\n## Troubleshooting\n\nIf `recall` looks empty or weak, widen `--hours`, drop source filters, or switch to `timeline` / `search`. For setup issues, sandbox PATH problems, or binary-only snapshots, see [references/troubleshooting.md](references/troubleshooting.md).\n\n## Exit codes\n\n`0` success · `1` uncategorized runtime · `2` invalid args · `3` not found · `4` unsupported format · `5` database error · `6` platform error.\n\nFile v1.3.8:_meta.json\n\n{\n  \"ownerId\": \"kn762fvz617r91c4h7qr9bdbp97zar1g\",\n  \"slug\": \"clipboard-memory\",\n  \"version\": \"1.3.8\",\n  \"publishedAt\": 1783802839291\n}\n\nFile v1.3.8:references/commands.md\n\n# Clipboard Memory — Commands Reference\n\nFull flag and subcommand reference for `clipmem`. This file is kept byte-identical across the OpenClaw-native and portable skill packages.\n\n---\n\n## Decision ladder\n\nPick the narrowest command that answers the question. Always pass `--format json` (or `--format toon` for plain enumeration) when parsing programmatically.\n\n1. `clipmem recall \"<query>\" --format json` — best-first ranked answer with alternatives. **Start here.**\n2. `clipmem timeline --hours <N> --format json` — chronological capture events. Use when the user says \"today\", \"yesterday\", \"in order\", or \"every time\".\n3. `clipmem recent --hours <N> --format json` — deduplicated recent snapshots. Use for \"recent unique things\".\n4. `clipmem search \"<query>\" --format json` — direct lexical / FTS match. Use when you need precise substring hits.\n5. `clipmem get <snapshot_id> --format json` — nested item/representation detail for a snapshot you already have.\n6. `clipmem restore <snapshot_id>` — restore the full stored representation set for a snapshot back onto the macOS clipboard.\n7. `clipmem export <snapshot_id> --item <n> --uti <uti> --out <path> [--force]` — raw bytes for binary/image/PDF payloads.\n8. `clipmem forget <snapshot_id>` — hard-delete one snapshot and its capture history.\n9. `clipmem purge --older-than <duration> [--dry-run]` — prune by `last_observed_at`.\n10. `clipmem storage compact [--dry-run] --format json` — reclaim SQLite/WAL disk space without changing content.\n11. `clipmem storage image-candidates --format json` — inspect image rows eligible for optimization without rewriting bytes.\n12. `clipmem storage optimize-images [--dry-run] [--no-compact] [--limit N] [--format json|--progress jsonl]` — convert eligible stored images to lossless WebP and compact by default.\n13. `clipmem service providers --format json` — inspect service provider availability without starting or stopping capture.\n14. `clipmem service revision --format json` — read archive revision counters without probing service providers.\n15. `clipmem settings show --format json` — inspect persistent capture policy.\n16. `clipmem app settings show --format json` — inspect menu bar app preferences.\n17. `clipmem app settings set KEY VALUE --format json` / `clear KEY --format json` — change app-local preferences and bump app preference revision.\n18. `clipmem app launch-at-login show|set|clear --format json` — inspect or change the app-owned launch-at-login preference bridge.\n19. `clipmem app update-check show|run|clear --format json` — inspect, run, or clear app update-check state.\n20. `clipmem app quit --format json` — request the menu bar app to quit.\n21. `clipmem agents context --format json` — one-call agent context: generated_at, service health, settings, app state, recent activity metadata, revision, stats, privacy guidance, and capability summary.\n22. `clipmem ocr status --format json` — inspect local OCR queue and result counts.\n23. `clipmem ocr candidates --format json` — inspect pending OCR candidates without running OCR.\n24. `clipmem ocr get <raw-sha256> --format json` / `clear <raw-sha256> --format json` — inspect or clear one OCR result.\n25. `clipmem ocr run [--limit N] [--snapshot ID]` — backfill OCR for image snapshots.\n\nPrimitive commands are the direct read/list/get/set/delete/start/stop surfaces\nabove. Convenience workflows are still supported but should be classified\nhonestly: `recall` ranks likely answers, `setup` composes initialization plus\nservice startup, `ocr run` processes a bounded OCR batch, and\n`storage optimize-images` scans and rewrites eligible image rows. Use\ncandidate, dry-run, or detail commands before broad workflow mutations when the\nuser has not explicitly asked to proceed.\n\n---\n\n## Subcommand matrix\n\n| Subcommand | Default `--format` | Supports `toon`? | Purpose |\n|---|---|---|---|\n| `recall [QUERY]` | `md` | yes | Ranked best-first answer with alternatives |\n| `search <QUERY>` | `text` | yes | Lexical / FTS match over the archive |\n| `recent` | `text` | yes | Recent unique snapshots (deduplicated) |\n| `timeline` | `text` | yes | Chronological capture events (not deduped) |\n| `get <SNAPSHOT_ID>` | `text` | **no** | Nested detail for one snapshot |\n| `restore <SNAPSHOT_ID>` | text | — | Restore a stored snapshot back onto the clipboard |\n| `export <SNAPSHOT_ID>` | — (raw bytes) | — | Write one representation to disk |\n| `forget <SNAPSHOT_ID>` | text | — | Hard-delete one snapshot and its capture history |\n| `purge` | text | — | Delete old snapshots by `last_observed_at` |\n| `storage compact` | text (`json` supported) | — | Reclaim SQLite/WAL disk space |\n| `storage image-candidates` | text (`json` supported) | — | List image rows eligible for optimization without mutation |\n| `storage optimize-images` | text (`json` supported, progress JSONL available) | — | Convert eligible images to lossless WebP |\n| `settings show` | `text` | **no** | Show persistent pause / retention / ignore-list policy |\n| `settings pause` | text | — | Persistently pause or resume capture; supports `json` and `human` |\n| `settings api-key-filter` | text | — | Enable or disable API key filtering; supports `json` and `human` |\n| `settings ocr` | text | — | Enable or disable local OCR for new image captures; supports `json` and `human` |\n| `settings retention` | text | — | Set retention to a duration or `forever`; supports `json` and `human` |\n| `settings reset` | text (`json` supported) | — | Reset capture policy and ignored apps to defaults |\n| `settings ignore add/remove/list` | text | **no** | Manage ignored bundle identifiers; supports `json` and `human` |\n| `app settings show` | text (`json` supported) | — | Show menu bar app preferences |\n| `app settings set` | text (`json` supported) | — | Set one menu bar app preference |\n| `app settings clear` | text (`json` supported) | — | Clear one menu bar app preference |\n| `app launch-at-login show/set/clear` | text (`json` supported) | — | Manage the app-owned launch-at-login preference bridge |\n| `app update-check show/run/clear` | text (`json` supported) | — | Show, run, or clear app update-check state |\n| `app quit` | text (`json` supported) | — | Request the menu bar app to quit |\n| `agents context` | text (`json` supported) | — | Agent context bundle: generated_at, health, settings, app state, recent activity, revision, stats, privacy, capabilities |\n| `ocr status` | text (`json` supported) | — | Local OCR queue and result counts |\n| `ocr candidates` | text (`json` supported) | — | Pending OCR candidate hashes without processing |\n| `ocr get` | text (`json` supported) | — | One OCR result by raw representation hash |\n| `ocr clear` | text (`json` supported) | — | Delete one OCR result and rebuild affected OCR cache |\n| `ocr run` | text (`json` supported) | — | Backfill OCR for stored image snapshots |\n| `capture-once` | — | — | Explicitly capture the current clipboard once |\n| `watch` | — | — | Background daemon; usually a LaunchAgent |\n| `setup` | — | — | Initialize the database and start background capture |\n| `service status` | text (or `--json`) | — | Background provider state + capture freshness |\n| `service providers` | text (`json` supported) | — | Service provider availability without mutation |\n| `service revision` | text (`json` supported) | — | Archive revision counters without provider probes |\n| `service start` / `stop` / `uninstall` | — | — | Manage the background watcher service |\n| `doctor` | text (or `--json`) | — | SQLite / FTS5 diagnostics |\n| `agents openclaw doctor` | text | — | Integration health: PATH, workspace, sandbox |\n| `agents openclaw install-skill` | — | — | Write packaged skill files to disk |\n| `agents openclaw print-skill` | — | — | Print embedded `SKILL.md` to stdout |\n| `agents openclaw uninstall-skill` | — | — | Remove installed skill directory |\n| `agents hermes doctor` | text | — | Hermes integration health: PATH, skill discovery |\n| `agents hermes install-skill` | — | — | Write packaged Hermes skill to disk |\n| `agents hermes print-skill` | — | — | Print embedded Hermes `SKILL.md` to stdout |\n| `agents hermes uninstall-skill` | — | — | Remove installed Hermes skill directory |\n\n`--json` is a compatibility alias for `--format json` on `search`, `recent`, `timeline`, `get`, `agents context`, `storage compact`, `storage optimize-images`, `ocr status`, `ocr run`, `capture-once`, and `doctor`.\n\n---\n\n## Output formats\n\nAll retrieval commands share the same `--format` set except `get`, which omits `toon`:\n\n- `text` — human-oriented terminal output. Default for `search`, `recent`, `timeline`, `get`. **Do not parse.**\n- `md` — compact markdown. Default for `recall`. Human-oriented. **Do not parse.**\n- `json` — single structured object with a stable envelope. Parse this.\n- `jsonl` — newline-delimited rows. Prefer when streaming many results through a pipe.\n- `toon` — flat token-efficient list. Prefer for `timeline`, `search`, `recent`, and `recall` when you only need the top fields. Unsupported on `get`.\n\n---\n\n## Shared retrieval filters\n\n`search`, `recent`, `timeline`, and `recall` accept the same filter set. `get` and `export` accept them as guards against the explicitly targeted snapshot.\n\n**Time window:**\n\n- `--since <RFC3339>` — captures at or after this timestamp (e.g. `2026-04-16T09:00:00Z`).\n- `--until <RFC3339>` — captures at or before this timestamp.\n- `--hours <N>` — last N hours. `--since` wins if both are provided.\n\n**Source:**\n\n- `--app <name>` — case-insensitive substring match on the recorded frontmost app name.\n- `--bundle-id <id>` — case-insensitive exact match on bundle identifier (e.g. `com.apple.Safari`).\n\n**Content shape:**\n\n- `--kind text|html|rtf|url|file|image|pdf|binary|other`. One value per invocation.\n- `--has-text`, `--has-url`, `--has-file-url`, `--has-image`, `--has-pdf` — additive presence flags (AND semantics).\n\n**Size:**\n\n- `--min-bytes <N>` / `--max-bytes <N>` — applied to the total snapshot byte count.\n\n### `--kind` values\n\n| Value | Matches |\n|---|---|\n| `text` | plain text representations |\n| `html` | HTML clipboard payloads |\n| `rtf` | rich-text format |\n| `url` | web URLs |\n| `file` | **file URLs (Finder paths)** — not regular files on disk |\n| `image` | image blobs (PNG, JPEG, TIFF, etc.) |\n| `pdf` | PDF documents |\n| `binary` | opaque binary that has no safe text projection |\n| `other` | mixed or empty snapshots |\n\n`--kind file` is a common pitfall: it matches clipboard-as-file-URL payloads (things dragged from Finder), not arbitrary files the user happened to reference.\n\n---\n\n## Pagination\n\nList commands (`search`, `recent`, `timeline`) accept `--limit` and `--cursor`:\n\n- `--limit <N>` — 1–250, default 10.\n- `--cursor <opaque>` — resume from a `next_cursor` returned by a prior response.\n\nCursors are tied to the active query, mode, and filters. Changing any of those while paginating will reject the cursor. When a response includes `\"truncated\": true` and a non-null `next_cursor`, there are more rows.\n\n```bash\nclipmem search \"git status\" --format json --limit 25\nclipmem search \"git status\" --format json --limit 25 --cursor \"<next_cursor>\"\n```\n\n---\n\n## Search modes (`search`, `recall`)\n\n`--mode auto|fts|literal`, default `auto`.\n\n- `auto` — picks FTS or literal per query. Prefers literal for URLs, paths, bundle ids, dotted identifiers, and shell fragments (`--flag=value`, pipes, subshells). Plain prose queries try FTS first.\n- `fts` — strict SQLite FTS5. Use when you want to compose boolean queries: `\"launchctl\" AND bootstrap`.\n- `literal` — exact substring match. Use for punctuation-heavy strings like `50%`, `Co-Authored-By:`, or URL fragments.\n\nRules of thumb:\n\n- Query contains `\"`, `AND`, `OR`, `NOT` → `--mode fts`.\n- Query contains `/`, `.`, `:`, `%`, or shell metacharacters → `--mode literal`.\n- Short natural-language query → let `--mode auto` pick.\n\n---\n\n## `recall` extras\n\nOn top of the shared filters:\n\n- `--format md|json|toon` (default `md`).\n- `--limit <N>` — ranked candidates to consider (default 5).\n- `--full` — expand the best candidate text instead of the compact form.\n- `--quote` — force quoted best-text output.\n- `--min-score <0.0-1.0>` — threshold below which a query alone is not trusted; falls back to recency / filters.\n- `--prefer-recent` — bias ranking toward recency.\n- `--prefer-app <name>` — bias toward matching app or bundle id.\n- `--hours <N>` — window for the recent-fallback when a query is weak.\n\nIf the user has no query but said \"the thing I just copied\":\n\n```bash\nclipmem recall --prefer-recent --hours 24 --format json --limit 5\n```\n\n---\n\n## `get`, `restore`, and `export`\n\n```bash\nclipmem get <snapshot_id> --format json        # nested representation detail\nclipmem get <snapshot_id> --events <N>         # include last N capture events (default 10)\nclipmem restore <snapshot_id>                  # restore the whole snapshot to the clipboard\nclipmem export <snapshot_id> --item <index> --uti <uti> --out <path> [--force]\n```\n\n`get --format json` flattens the common text fields on the root snapshot so agents don't have to walk the representation tree. `get` does **not** support `--format toon`.\n\n`restore` is macOS-only and writes the full stored item/UTI/raw-byte set back onto the general pasteboard. This is a whole-snapshot restore, not a text-only approximation.\n\n`export` writes raw bytes to `--out` and supports `--format json` for structured confirmation. By default it creates a new file and refuses to replace an existing destination; pass `--force` only to replace an existing regular file. Symlink destinations are rejected. Required arguments: `--item` (0-based), `--uti` (e.g. `public.png`, `public.utf8-plain-text`, `com.adobe.pdf`), `--out`. Inspect `items[].representations[].uti` and `size_bytes` in a prior `get --format json` to choose the right combination.\n\n---\n\n## `forget`, `purge`, `storage`, and `settings`\n\n```bash\nclipmem forget <snapshot_id>\nclipmem purge --older-than 30d [--dry-run]\nclipmem storage compact [--dry-run] [--format json]\nclipmem storage image-candidates [--limit N] [--format json]\nclipmem storage optimize-images [--dry-run] [--no-compact] [--limit N] [--format json|--progress jsonl]\nclipmem settings show [--format json]\nclipmem settings pause on|off [--format json]\nclipmem settings api-key-filter on|off [--format json]\nclipmem settings ocr on|off [--format json]\nclipmem settings retention <duration|forever> [--format json]\nclipmem settings reset [--format json]\nclipmem settings ignore add <bundle_id> [--format json]\nclipmem settings ignore remove <bundle_id> [--format json]\nclipmem settings ignore list [--format json]\nclipmem app settings show [--format json]\nclipmem app settings set binary-path-override <path> [--format json]\nclipmem app settings set database-path-override <path> [--format json]\nclipmem app settings set default-recent-hours <hours> [--format json]\nclipmem app settings set default-query-mode recall|search|recent|timeline|diagnostics [--format json]\nclipmem app settings set hotkey-enabled true|false [--format json]\nclipmem app settings clear <key> [--format json]\nclipmem app launch-at-login show [--format json]\nclipmem app launch-at-login set on|off [--format json]\nclipmem app launch-at-login clear [--format json]\nclipmem app update-check show [--format json]\nclipmem app update-check run [--format json]\nclipmem app update-check clear [--format json]\nclipmem app quit [--format json]\nclipmem service revision [--format json]\nclipmem ocr status [--format json]\nclipmem ocr candidates [--limit N] [--snapshot ID] [--format json]\nclipmem ocr get <raw-sha256> [--format json]\nclipmem ocr clear <raw-sha256> [--format json]\nclipmem ocr run [--limit N] [--snapshot ID] [--retry-failed] [--format json]\n```\n\n`forget` is a hard delete. It removes the snapshot row, all child items/representations, and all capture events for that snapshot id via foreign-key cascades. OCR results with no remaining representation referencing their image hash are also removed.\n\n`purge` computes age from `snapshot_stats.last_observed_at`, not `snapshots.created_at`. Duration grammar is a single integer plus one unit: `Nd`, `Nh`, or `Nm`.\n\n`storage compact` checkpoints WAL state and vacuums SQLite pages back to the filesystem. It never changes clipboard content. `storage image-candidates` lists eligible image rows without rewriting bytes or marking rows (defaults to 25, while `optimize-images` scans all candidates when `--limit` is omitted). `storage optimize-images` rewrites eligible image representations to lossless WebP only when doing so saves meaningful space, then compacts SQLite storage by default; already compressed or skipped rows are not retried by normal runs. Use `--progress jsonl` for streamed `started`, `scanning`, `compacting`, and `complete` progress events. Use `--no-compact` only when batching optimization runs and compacting once at the end.\n\n`ocr candidates` lists pending OCR hashes and affected snapshot counts without invoking Apple Vision. Use it before `ocr run` when an agent needs to inspect queue work.\n\n`settings` is the persistent capture-policy entrypoint. Ignore matching is exact, case-insensitive bundle-id matching only. OCR is opt-in, runs locally through Apple Vision on macOS, and stores text/status separately from raw image bytes.\n\n`app settings`, `app launch-at-login`, and `app update-check` are menu bar app state bridges. They read and write app-local preferences without changing archive capture policy. Mutating commands bump `app_preferences_revision` so an open app can observe external agent changes. Launch-at-login writes the desired app-owned preference; the menu bar app applies it through `SMAppService`. `app update-check run` performs the live latest-stable-release lookup and updates the same cache the app reads. `app quit` requests the menu bar app to terminate through the app bundle identifier.\n\n`clipmem agents context --format json` is safe as a first call in agent sessions. It includes `generated_at`, service health, capture policy, archive revision, bounded recent activity, menu bar app state, capability discovery, and privacy guidance. It excludes raw clipboard content and representation bytes, but includes operational metadata such as app names, timestamps, counts, paths, and app preference state.\n\n`clipmem service revision --format json` is the lightweight polling path for change detection. It reads the same archive revision counters surfaced in service status and agent context without checking Homebrew, LaunchAgent, or other service providers.\n\n---\n\n## Global flags\n\n- `--db <path>` — override the SQLite database path. Default: `~/Library/Application Support/clipmem/clipmem.sqlite3` on macOS. Use this only when pointing at an alternate archive (tests, backups).\n\n## Environment\n\n- `CLIPMEM_OPENCLAW_WORKSPACE` — overrides the OpenClaw workspace root used by `agents openclaw install-skill` and `agents openclaw doctor`. Falls back to `openclaw config get agents.defaults.workspace`, then `~/.openclaw/workspace`.\n- `HOME` — resolves `~/` in default paths.\n\n---\n\n## Exit codes\n\n- `0` — success\n- `1` — uncategorized runtime failure\n- `2` — invalid args\n- `3` — not found (e.g. snapshot id, representation)\n- `4` — unsupported format for this subcommand (e.g. `--format toon` on `get`)\n- `5` — database error\n- `6` — platform error (macOS API / filesystem)\n\nScripts can rely on these to distinguish \"no such snapshot\" (retriable with a different id) from \"database locked\" (retry with backoff) from \"wrong format\" (agent bug).\n\n---\n\n## Script-friendly guarantees\n\n- stdout contains only the requested command output.\n- stderr contains diagnostics only.\n- No interactive prompts anywhere in the CLI.\n- List commands use bounded `--limit` defaults and opaque cursor pagination.\n- Retrieval JSON envelopes (`search`, `recent`, `timeline`, `get`, `recall`, and mutation confirmations that include `schema_version`) are stable within `schema_version: 2`. Management and inspection commands such as `agents context`, `app`, `service`, `ocr`, and `storage image-candidates` have command-specific JSON shapes; parse their documented keys directly and do not require `schema_version: 2` unless the command emits it.\n\nFile v1.3.8:references/examples.md\n\n# Clipboard Memory — Worked Examples\n\nConcrete input → output walkthroughs. Byte-identical across skill packages.\n\nEach example shows the user's question, the command to run, the shape of the response, and the next step.\n\n---\n\n## Example 1 — \"What was that URL I copied from Safari yesterday?\"\n\nThe user gave a time cue (yesterday) and a source (Safari). Use `recall` with a `--prefer-recent` bias, an `--app` filter, and a generous `--hours` window.\n\n```bash\nclipmem recall \"url\" --prefer-recent --app safari --has-url --hours 48 --format json --limit 5\n```\n\nResponse (trimmed):\n\n```json\n{\n  \"schema_version\": 2,\n  \"command\": \"recall\",\n  \"best_candidate\": {\n    \"snapshot_id\": 812,\n    \"best_text\": \"https://developer.apple.com/documentation/appkit/nspasteboard\",\n    \"urls\": [\"https://developer.apple.com/documentation/appkit/nspasteboard\"],\n    \"app_name\": \"Safari\",\n    \"observed_at\": \"2026-04-16T17:45:00Z\",\n    \"why_matched\": \"url filter + recency bias\"\n  },\n  \"best_match_confidence\": \"high\",\n  \"alternatives\": [ /* ... */ ],\n  \"next_cursor\": null\n}\n```\n\nReport `best_candidate.urls[0]`. If `best_match_confidence` were `\"low\"`, enumerate `alternatives` instead.\n\n---\n\n## Example 2 — \"Show me everything I copied today, in order\"\n\nThe user wants chronological events, not deduplicated recent snapshots. Use `timeline` and `toon` for efficient enumeration.\n\n```bash\nclipmem timeline --hours 24 --format toon --sort asc --limit 50\n```\n\nTOON output (one row per line, tab-separated scalar fields):\n\n```\nsnapshot_id\tobserved_at\tapp_name\tkind\tbest_text\n812\t2026-04-17T08:02:11Z\tSafari\turl\thttps://developer.apple.com/…\n813\t2026-04-17T08:04:03Z\tTerminal\ttext\tgit status\n813\t2026-04-17T08:11:59Z\tTerminal\ttext\tgit status\n...\n```\n\nNotice snapshot `813` appears twice — `timeline` shows each capture event, not each unique snapshot. If `truncated` shows more rows exist, re-run with the last row's time as `--until` or request `--format json` and page via `--cursor`.\n\n---\n\n## Example 3 — \"Pull the image I copied from that screenshot tool\"\n\nImages have no text projection. Use `recall` to find the snapshot, then `get` to discover the representation `uti` and byte size, then `export` to write raw bytes.\n\n```bash\n# 1. find the snapshot\nclipmem recall \"screenshot\" --kind image --hours 72 --format json --limit 3\n```\n\n```json\n{\n  \"best_candidate\": {\n    \"snapshot_id\": 901,\n    \"kind\": \"image\",\n    \"best_text\": null,\n    \"total_bytes\": 138402,\n    \"app_name\": \"CleanShot X\"\n  }\n}\n```\n\n```bash\n# 2. inspect representations to pick a uti\nclipmem get 901 --format json\n```\n\n```json\n{\n  \"snapshot\": {\n    \"items\": [\n      {\n        \"item_index\": 0,\n        \"representations\": [\n          { \"uti\": \"public.png\", \"size_bytes\": 138402, \"is_indexed\": false },\n          { \"uti\": \"public.tiff\", \"size_bytes\": 412004, \"is_indexed\": false }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```bash\n# 3. export raw bytes\nclipmem export 901 --item 0 --uti public.png --out ./clipboard.png\nclipmem export 901 --item 0 --uti public.png --out ./clipboard.png --force\n```\n\n`export` writes binary content to `--out` and exits 0 on success. It creates a new file by default; pass `--force` only to replace an existing regular file. There is no `--format` on `export`.\n\n---\n\n## Example 4 — Paginating a large search\n\nThe user asks for everything matching a phrase. `search` returns bounded pages; use the cursor to keep going.\n\n```bash\nclipmem search \"launchctl bootstrap\" --mode literal --format json --limit 25\n```\n\n```json\n{\n  \"schema_version\": 2,\n  \"command\": \"search\",\n  \"results\": [ /* 25 rows */ ],\n  \"truncated\": true,\n  \"next_cursor\": \"eyJvZmZzZXQiOjI1LCJxdWVyeSI6Imxhdw...\"\n}\n```\n\n```bash\nclipmem search \"launchctl bootstrap\" --mode literal --format json --limit 25 \\\n  --cursor \"eyJvZmZzZXQiOjI1LCJxdWVyeSI6Imxhdw...\"\n```\n\nStop paginating when `truncated` is `false` or `next_cursor` is `null`.\n\nCursors are tied to the active query, mode, and filters. Changing any of those mid-pagination invalidates the cursor — start over.\n\n---\n\n## Example 5 — \"Give me the exact text, not a summary\"\n\nBy default `recall` returns a compact form. Force quoted, full text:\n\n```bash\nclipmem recall \"the SQL migration\" --quote --full --format json\n```\n\n`best_candidate.best_text` now holds the complete stored text. If it's still truncated (very large clipboards), use `get --format json` and concatenate `text_fragments[].text`.\n\n---\n\n## Example 6 — \"Nothing is copied from today\" — diagnose first\n\nDon't assume the archive is wrong; the watcher may have stopped.\n\n```bash\n./scripts/check-setup.sh\n# or, inline\nclipmem doctor --json\nclipmem service status --json\n```\n\nIf `clipmem service status --json` reports `stale: true`, the watcher is not running. Tell the user to run `clipmem setup` or `brew services start clipmem` before retrying.\n\nSee [troubleshooting.md](troubleshooting.md) for remediation steps.\n\nFile v1.3.8:references/json-schema.md\n\n# Clipboard Memory — JSON Schema\n\nStable response shapes for `--format json`. Current `schema_version` is `2`. This file is kept byte-identical across skill packages.\n\nBreaking changes to these fields will bump `schema_version`. Additive changes (new optional keys) are allowed within the same version.\n\n---\n\n## Shared envelope (`recall`, `search`, `recent`, `timeline`)\n\n```json\n{\n  \"schema_version\": 2,\n  \"command\": \"recall\",\n  \"generated_at\": \"2026-04-17T12:34:56Z\",\n  \"applied_filters\": { \"hours\": 24, \"app\": \"safari\" },\n  \"truncated\": false,\n  \"next_cursor\": null,\n  \"results\": [ /* rows, see below */ ]\n}\n```\n\n- `schema_version` — integer. Pin to `2` for stability checks.\n- `command` — echoes the subcommand.\n- `generated_at` — RFC3339 timestamp when the response was produced.\n- `applied_filters` — echoes the filters actually applied after argument parsing.\n- `truncated` — `true` when more rows exist beyond `--limit`.\n- `next_cursor` — opaque string to pass back as `--cursor` when `truncated` is `true`. `null` when there are no more rows.\n- `results` — list of flattened snapshot rows.\n\n`recall` adds three extras at the top level:\n\n- `best_candidate` — the top-ranked row (also appears as `results[0]`).\n- `why_selected` — short string explaining why `best_candidate` was picked.\n- `best_match_confidence` — `\"high\" | \"medium\" | \"low\"`.\n- `best_match_score` — float in `[0.0, 1.0]`.\n- `quoted_text` — present only when `--quote` is set and usable text exists.\n\n---\n\n## Flattened snapshot row (in `results[]` and `best_candidate`)\n\nRead these first; walk nested `items[].representations[]` only after `get`.\n\n```json\n{\n  \"snapshot_id\": 42,\n  \"event_id\": 1000,\n  \"sha256\": \"<hex>\",\n  \"kind\": \"text\",\n  \"observed_at\": \"2026-04-17T12:00:00Z\",\n  \"first_seen_at\": \"2026-04-17T11:00:00Z\",\n  \"last_seen_at\":  \"2026-04-17T12:00:00Z\",\n  \"app_name\": \"Terminal\",\n  \"app_bundle_id\": \"com.apple.Terminal\",\n\n  \"best_text\": \"git status\",\n  \"best_text_uti\": \"public.utf8-plain-text\",\n  \"text_fragments\": [{ \"representation\": \"public.utf8-plain-text\", \"text\": \"git status\" }],\n  \"urls\": [],\n  \"file_paths\": [],\n  \"html_text\": null,\n  \"rtf_text\": null,\n  \"ocr_text\": null,\n  \"ocr_status\": null,\n  \"text_summary\": \"git status\",\n  \"preview_text\": \"git status\",\n\n  \"item_count\": 1,\n  \"total_bytes\": 10,\n  \"capture_count\": 3,\n  \"score\": 0.95,\n  \"why_matched\": \"full phrase match\",\n  \"matched_fields\": [\"search_text\"],\n  \"snippet\": \"git status\"\n}\n```\n\nFields to read first for common questions:\n\n| Intent | Read |\n|---|---|\n| \"what was the text\" | `best_text` (fall back to `text_summary`, `preview_text`) |\n| \"what URL\" | `urls` (array) |\n| \"what file / path\" | `file_paths` (array) |\n| \"which app\" | `app_name` / `app_bundle_id` |\n| \"when\" | `observed_at`, `first_seen_at`, `last_seen_at` |\n| \"is this binary / image / pdf\" | `kind`, presence of `best_text`, `total_bytes` |\n| \"why did recall pick this\" | `why_matched`, `matched_fields`, `score` |\n\n`best_text` can come from OCR for image-only snapshots. In that case, `best_text_uti` is `\"com.clipmem.ocr.text\"` and `ocr_status` is `\"ready\"`. If binary-only snapshots have no OCR text, fall through to `clipmem export` with a `uti` drawn from `clipmem get`.\n\n---\n\n## `clipmem get --format json`\n\n```json\n{\n  \"schema_version\": 2,\n  \"command\": \"get\",\n  \"generated_at\": \"2026-04-17T12:34:56Z\",\n  \"applied_filters\": { },\n  \"snapshot\": {\n    \"snapshot_id\": 42,\n    \"sha256\": \"<hex>\",\n    \"kind\": \"text\",\n    \"best_text\": \"git status\",\n    \"best_text_uti\": \"public.utf8-plain-text\",\n    \"text_fragments\": [ /* ... */ ],\n    \"urls\": [],\n    \"file_paths\": [],\n    \"html_text\": null,\n    \"rtf_text\": null,\n    \"ocr_text\": null,\n    \"ocr_status\": null,\n    \"text_summary\": \"git status\",\n    \"preview_text\": \"git status\",\n    \"search_text\": \"git status\",\n    \"item_count\": 1,\n    \"total_bytes\": 10,\n    \"created_at\": \"2026-04-17T11:00:00Z\",\n    \"capture_count\": 3,\n    \"first_observed_at\": \"2026-04-17T11:00:00Z\",\n    \"last_observed_at\":  \"2026-04-17T12:00:00Z\",\n    \"last_frontmost_app_name\": \"Terminal\",\n    \"last_frontmost_app_bundle_id\": \"com.apple.Terminal\",\n    \"recent_events\": [\n      { \"event_id\": 1000, \"observed_at\": \"2026-04-17T12:00:00Z\", \"change_count\": 123 }\n    ],\n    \"items\": [\n      {\n        \"item_index\": 0,\n        \"representations\": [\n          {\n            \"uti\": \"public.utf8-plain-text\",\n            \"size_bytes\": 10,\n            \"is_indexed\": true\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\nRaw bytes are **not** included in `get --format json`. The `items[].representations[]` tree gives you the `uti` and `size_bytes` needed to call `clipmem export`. `get` does not accept `--format toon`.\n\n---\n\n## `clipmem capture-once --json`\n\nReturns a single snapshot envelope similar to `get`, describing what was just captured.\n\n---\n\n## `clipmem doctor --json`\n\n```json\n{\n  \"db_path\": \"/Users/you/Library/Application Support/clipmem/clipmem.sqlite3\",\n  \"sqlite_version\": \"3.45.1\",\n  \"journal_mode\": \"wal\",\n  \"fts5_compile_option_present\": true,\n  \"fts5_create_virtual_table_ok\": true,\n  \"compile_options\": [\"ENABLE_FTS5\", \"ENABLE_RTREE\", \"…\"]\n}\n```\n\n`clipmem doctor` communicates failure via **exit code** (non-zero means the SQLite archive is corrupt, missing, or unreadable), not via a JSON `errors` field. `fts5_create_virtual_table_ok: false` means `--mode fts` will fail; use `--mode literal` instead. `fts5_compile_option_present` is the weaker \"SQLite was built with FTS5 support\" signal and is not sufficient on its own.\n\n---\n\n## Top-level keys an agent should always check\n\nBefore trusting a response:\n\n1. `schema_version == 2`.\n2. For envelopes: `truncated` and `next_cursor` before concluding \"there is nothing else\".\n3. For rows: `best_text` nullability before claiming \"I found the exact text\".\n4. For `recall`: `best_match_confidence` before committing to `best_candidate`. On `\"low\"`, surface alternatives.\n\nFile v1.3.8:references/setup-check.md\n\n# Clipboard Memory — Setup Check\n\nProse mirror of `scripts/check-setup.sh`. Use this when your runtime can't execute shell scripts directly. Byte-identical across skill packages.\n\nRun these commands in order. Stop at the first failure and repair before querying.\n\n## 1. Binary present\n\n```bash\nclipmem --version\n```\n\nExpect a version line on stdout, exit code 0. If not, `clipmem` is missing from PATH. Install via `brew install tristanmanchester/tap/clipmem` or `cargo install clipmem`.\n\n## 2. Database healthy\n\n```bash\nclipmem doctor --json\n```\n\nExpect exit 0 and `\"fts5_create_virtual_table_ok\": true` in the JSON payload. Non-zero exit means the SQLite archive is corrupt or inaccessible (failure is signalled via exit code, not a JSON `errors` field). `fts5_create_virtual_table_ok: false` means FTS queries will fail — either use `--mode literal` or rebuild the database.\n\n## 3. Service and watcher freshness\n\n```bash\nclipmem service status --json\n```\n\nExpect `stale: false`. The report also tells you whether the Homebrew service (`homebrew.mxcl.clipmem`) or the direct LaunchAgent (`io.openclaw.clipmem.watch`) is loaded and running.\n\nIf the report says no background service is loaded, start one of these:\n\n```bash\nclipmem setup\n# or\nbrew services start clipmem\n```\n\n## 4. Agent integration (optional)\n\nIf the agent is OpenClaw, also check:\n\n```bash\nclipmem agents openclaw doctor\n```\n\nIf the agent is Hermes Agent, also check:\n\n```bash\nclipmem agents hermes doctor\n```\n\nExpect every check to report `[OK]`. `[FAIL]` lines include remediation steps.\n\n## Interpretation\n\n| Symptom | Likely cause |\n|---|---|\n| `clipmem` not found | binary not installed or not on PATH |\n| `doctor` exits non-zero | database lock, corruption, or permission issue |\n| `service status --json` reports `stale: true` | no recent captures and no background watcher running |\n| FTS query errors | `fts5_create_virtual_table_ok: false` — switch to `--mode literal` |\n| Sandboxed agent can't see the archive | PATH or file-access scope; rerun `openclaw sandbox explain` |\n\nSee `scripts/check-setup.sh` for the executable version with categorised exit codes (0 healthy, 1 watcher stale, 2 binary missing, 3 doctor failed).\n\nFile v1.3.8:references/troubleshooting.md\n\n# Clipboard Memory — Troubleshooting\n\nDiagnose before reinterpreting. Most \"nothing found\" outcomes are a stale watcher or a mismatched filter, not a true miss.\n\nStart by running `scripts/check-setup.sh` (installed alongside this skill) or the prose in [setup-check.md](setup-check.md).\n\n---\n\n## Empty or weak `recall` result\n\nDo these in order, stopping when the result improves:\n\n1. **Widen the time window.** `--hours 72`, or drop `--hours` entirely.\n2. **Remove source filters.** The user's memory of which app doesn't always match what `clipmem` recorded as the frontmost process.\n3. **Switch to `timeline`.** If the user said \"today\" or \"yesterday\", chronological order + filters often finds things `recall`'s ranker misses.\n4. **Switch to `search`.** For exact phrases or punctuation-heavy strings, try `--mode literal`.\n5. **Loosen content shape.** Drop `--kind`, `--has-url`, `--has-text` flags — they may be excluding the right snapshot.\n\n```bash\nclipmem recall \"<query>\" --hours 72 --format json\nclipmem timeline --hours 72 --format json --limit 25\nclipmem search \"<query>\" --mode literal --format json\n```\n\n---\n\n## Watcher not running\n\nSymptom: `clipmem timeline --hours 1` returns zero rows despite the user having copied recently.\n\n```bash\nclipmem service status --json\n```\n\nIf `stale: true` or neither the Homebrew service nor the direct LaunchAgent is running:\n\n```bash\nclipmem setup\n# or, for Homebrew-native management:\nbrew services start clipmem\n```\n\n---\n\n## FTS mode failures\n\n`clipmem search \"...\" --mode fts` errors with `fts5: syntax error` or similar:\n\n- Punctuation in the query confuses FTS5. Switch to `--mode literal`.\n- Check `clipmem doctor --json` for `\"fts5_create_virtual_table_ok\": true`. If false, the SQLite build lacks usable FTS5 — every `--mode fts` call will fail.\n- Mix of quotes and operators (`\"foo\" AND bar`) should parse in FTS5. Unbalanced quotes do not.\n\n---\n\n## Binary-only snapshots (images, PDFs, opaque blobs)\n\nSymptom: `best_text` is `null` or empty, yet `total_bytes > 0` and `kind` is `image`, `pdf`, or `binary`.\n\nThis is expected — those clipboards have no safe text projection. To recover the content:\n\n1. Call `clipmem get <snapshot_id> --format json`.\n2. Inspect `items[].representations[]` for a useful `uti` (e.g. `public.png`, `com.adobe.pdf`).\n3. Call `clipmem export <snapshot_id> --item <index> --uti <uti> --out <path>`.\n\nWhen no usable `best_text` exists, report the metadata honestly:\n\n> \"I found the clipboard item (snapshot 901, PNG from CleanShot X at 10:12 today). It has no stored text — I'd need to export the raw image to recover the content.\"\n\nDo **not** invent exact text that was never captured as text.\n\n---\n\n## OpenClaw sandbox / PATH issues\n\nSymptom: OpenClaw cannot execute `clipmem` even though it runs fine in the user's shell.\n\n```bash\nclipmem agents openclaw doctor\n```\n\nInterpret the output:\n\n- `[OK] clipmem on PATH` — binary visible to OpenClaw.\n- `[FAIL] clipmem on PATH` — the binary exists on the user's shell PATH but not the sandbox's. Add the install directory (usually `~/.local/bin` or `/opt/homebrew/bin`) to the sandbox PATH.\n- `[OK] workspace resolved` — `CLIPMEM_OPENCLAW_WORKSPACE` or `openclaw config get agents.defaults.workspace` is set.\n- `[FAIL] skill files present` — the skill was never installed. Run `clipmem agents openclaw install-skill`.\n\nAlso useful:\n\n```bash\nopenclaw sandbox explain   # when available; prints visible PATH and file-access scope\n```\n\nIf the binary was installed **after** the sandbox was created, recreate the sandbox image and retry.\n\n---\n\n## Locked or corrupt database\n\nSymptom: `clipmem doctor --json` includes errors, or retrieval commands exit with code `5`.\n\n```bash\nclipmem doctor --json\n```\n\n- `database is locked` — another writer is holding the lock. Usually the watcher under heavy load; try again in a few seconds.\n- `incompatible prerelease schema` — an older archive format is being mistaken for the current DB. Move the file aside, then run `clipmem setup`.\n- `malformed` or `corrupt` — SQLite detected structural damage. Back up `~/Library/Application Support/clipmem/clipmem.sqlite3`, then delete and let `clipmem capture-once` rebuild. You will lose history.\n- `permission denied` — the database file is not writable by the current user. Check `0600` on the file and `0700` on the containing directory (`~/Library/Application Support/clipmem/`).\n\n---\n\n## Exit code reference\n\n| Code | Meaning | Typical response |\n|---|---|---|\n| `0` | success | continue |\n| `1` | uncategorized runtime failure | inspect stderr; try again |\n| `2` | invalid args | agent bug — check flags and re-invoke |\n| `3` | not found | snapshot id, representation, or query returned no hits |\n| `4` | unsupported format | wrong `--format` for this subcommand (e.g. `toon` on `get`) |\n| `5` | database error | see \"Locked or corrupt database\" above |\n| `6` | platform error | macOS API / filesystem issue; user action likely needed |\n\n---\n\n## When to give up gracefully\n\nIf after all of the above the archive genuinely has no match:\n\n- Say so plainly. Don't hallucinate.\n- Quote the nearest metadata hits: `app_name`, `observed_at`, `kind`.\n- Suggest the user copy the item again and retry — `clipmem` captures in real time.\n\nFile v1.3.8:skill-card.md\n\n## Description: <br>\nClipboard Memory helps an agent recall and recover clipboard history on macOS from the local clipmem archive, including text, commands, URLs, file paths, HTML, images, PDFs, and binary exports. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[tristanmanchester](https://clawhub.ai/user/tristanmanchester) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and agent users on macOS use this skill when they need to find, inspect, restore, or export something previously copied to the local clipboard. It is intended for narrow clipboard-history recall before using broader web, repository, or filesystem search. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Clipboard history can contain passwords, tokens, private messages, documents, images, and file paths. <br>\nMitigation: Use narrow queries and filters, surface only the minimum matching content needed, and avoid broad exports or summaries of unrelated clipboard entries. <br>\nRisk: Commands such as export, restore, forget, purge, settings, service, launch-at-login, and update-check can disclose, overwrite, delete, or change local clipboard and app state. <br>\nMitigation: Treat these as explicit user-intent operations; inspect candidates or use dry-run/detail commands where available before making broad mutations. <br>\nRisk: Empty or weak results may reflect a stale watcher, inaccessible database, or overly narrow filters rather than absence of copied content. <br>\nMitigation: Check setup health and pagination or broaden the query before concluding that no matching clipboard item exists. <br>\n\n\n## Reference(s): <br>\n- [ClawHub skill page](https://clawhub.ai/tristanmanchester/skills/clipboard-memory) <br>\n- [Publisher profile](https://clawhub.ai/user/tristanmanchester) <br>\n- [Clipboard Memory Commands Reference](references/commands.md) <br>\n- [Clipboard Memory JSON Schema](references/json-schema.md) <br>\n- [Clipboard Memory Worked Examples](references/examples.md) <br>\n- [Clipboard Memory Setup Check](references/setup-check.md) <br>\n- [Clipboard Memory Troubleshooting](references/troubleshooting.md) <br>\n- [Apple NSPasteboard documentation](https://developer.apple.com/documentation/appkit/nspasteboard) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance] <br>\n**Output Format:** [Markdown guidance with inline shell commands and JSON field references] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Uses local macOS clipmem results; retrieval commands should prefer --format json or toon and check pagination, confidence, and setup health before answering.] <br>\n\n## Skill Version(s): <br>\n1.3.8 (source: server release metadata and openclaw metadata) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nArchive v1.3.7: 9 files, 24842 bytes\n\nFiles: references/commands.md (20419b), references/examples.md (4895b), references/json-schema.md (5907b), references/setup-check.md (2210b), references/troubleshooting.md (5278b), scripts/check-setup.sh (8587b), skill-card.md (2320b), SKILL.md (10257b), _meta.json (135b)\n\nFile v1.3.7:SKILL.md\n\n---\nname: clipboard-memory\ndescription: Recall what the user copied on this Mac via the local clipmem archive — text, commands, URLs, file paths, HTML, images, PDFs. Triggers on requests like \"what was that command I copied?\", \"the URL I copied from Safari\", \"find that snippet before I restarted\", or any paraphrase involving copy, paste, or clipboard. Offers ranked recall, chronological timeline, lexical / FTS search, raw-byte export for binary content, cursor pagination, and filters by app, kind, time window, and content shape. Use before reaching for generic web or repo search whenever the user is trying to recover something they previously had on the clipboard.\nlicense: MIT\nmetadata: {\"openclaw\":{\"emoji\":\"📋\",\"os\":[\"darwin\"],\"requires\":{\"bins\":[\"clipmem\"]},\"install\":[{\"id\":\"brew\",\"kind\":\"brew\",\"label\":\"Install clipmem (brew)\",\"bins\":[\"clipmem\"],\"formula\":\"clipmem\",\"tap\":\"tristanmanchester/tap\"},{\"id\":\"cargo\",\"kind\":\"cargo\",\"label\":\"Install clipmem (cargo)\",\"bins\":[\"clipmem\"],\"package\":\"clipmem\"}],\"version\":\"1.3.7\"}}\n---\n\nRecall what the user copied on this Mac before reaching for generic search. `clipmem` maintains a local, privacy-preserving SQLite archive of every clipboard state macOS emits, and exposes a JSON-first CLI built for agents. This package is installed by `clipmem agents openclaw install-skill`; the canonical cross-agent source lives under `skills/clipboard-memory/`.\n\n## Use this skill when\n\nThe user asks things like:\n\n- \"what was that command I copied?\"\n- \"show me the URL I copied from Safari earlier\"\n- \"find that snippet, path, note, or link I copied yesterday\"\n- \"give me the exact text I copied, not a summary\"\n- \"what did I copy before I restarted?\"\n- \"paste me back that SQL I was looking at\"\n- \"get the PDF I copied last week\"\n- \"show me everything I copied from Xcode today\"\n\n## Do not use this skill for\n\n- web search or current-events lookups\n- searching the repository or local files the user never copied\n- content the user typed but never copied to the clipboard\n- anything on a non-macOS machine (`clipmem` captures `NSPasteboard` only)\n\n## Prerequisites\n\nBefore querying, confirm the setup is healthy — otherwise empty results may be a stale watcher, not a true miss:\n\n1. Background capture must be running. `clipmem setup` is the canonical fix; Homebrew users can also use `brew services start clipmem`.\n2. The binary `clipmem` must be on PATH with write access to `~/Library/Application Support/clipmem/clipmem.sqlite3`.\n3. Run [`scripts/check-setup.sh`](scripts/check-setup.sh) once per session when results look wrong. It exits `0` on a healthy host, `1` if the watcher is stale, `2` if the binary is missing, `3` if `clipmem doctor` fails. The prose equivalent is in [references/setup-check.md](references/setup-check.md).\n4. If OpenClaw cannot see the binary, run `clipmem agents openclaw doctor` and follow its remediation lines.\n\n## Command ladder\n\nAlways pick the narrowest command that answers the question, and always pass `--format json` (or `--format toon` for plain enumeration) so you can parse the response deterministically.\n\n1. **`clipmem recall`** — best-first ranked answer with alternatives. Start here for almost every request.\n2. **`clipmem timeline`** — chronological capture events (one row per copy), including repeated copies of the same content. Use for \"today\", \"yesterday\", \"in order\", or \"every time\".\n3. **`clipmem search`** — direct lexical / FTS matching. Use when you need precise substring hits or the user gave you an exact phrase.\n4. **`clipmem get <snapshot_id>`** — nested item/representation detail for a single snapshot already in hand.\n5. **`clipmem export <snapshot_id> --item <n> --uti <uti> --out <path> [--force]`** — raw bytes. Use when the stored content is binary/image/PDF and `best_text` is empty or partial. Prefer a fresh output path; use `--force` only to replace an existing regular file.\n6. **`clipmem ocr candidates`, `clipmem ocr get`, `clipmem ocr clear`, and `clipmem storage image-candidates`** — inspect queued OCR or image optimization work before running batch workflows, or clear one stale OCR result.\n7. **`clipmem settings reset --format json`** — reset capture policy and ignored apps when the user explicitly asks to restore defaults.\n8. **`clipmem service providers --format json`** — inspect service provider state without starting or stopping capture.\n9. **`clipmem service revision --format json`** — inspect archive revision counters without probing service providers.\n10. **`clipmem app settings`, `clipmem app launch-at-login`, `clipmem app update-check run`, or `clipmem app quit` with `--format json`** — inspect or change menu bar app preferences and app-owned state when the user asks about app defaults, update checks, or quitting the app.\n11. **`clipmem agents context --format json`** — compact health, settings, app state, recent activity, revision, stats, privacy, and capability context before multi-step work.\n\n## Primitive command taxonomy\n\nPrimitive commands expose one bounded read or mutation that can be composed\ndirectly. Convenience workflows such as `recall`, `setup`, `purge`, `ocr run`, and\n`storage optimize-images` remain useful, but verify uncertain results with\n`search`, `recent`, `timeline`, or `get`, and preview broad mutations with\ncandidate or dry-run commands when available.\n\nThe full flag reference, JSON envelope, and kind values live in [references/commands.md](references/commands.md), [references/json-schema.md](references/json-schema.md), and [references/examples.md](references/examples.md).\n\n## Critical behaviour rules\n\n- Before answering from a stale, empty, or ambiguous archive, run `clipmem agents context --format json` and use `generated_at`, health, settings, app state, recent activity, revision, stats, privacy, and capability fields to decide whether to broaden search or diagnose setup.\n- Always use `--format json` when you will parse the response. `--format toon` is for token-efficient enumeration only. `--format jsonl` is for streaming many rows into a pipeline. Never parse `md` or `text`.\n- Treat `recall` as a convenience ranking helper, not an authority. For uncertain cases, compose primitive commands in this order: `search`, `recent`, `timeline`, `get`, then OS follow-through such as `pbcopy`, `open`, or `open -R`.\n- Never claim \"nothing found\" until you have broadened the search once and checked `truncated` / `next_cursor`.\n- When `best_match_confidence` is `\"low\"` or there are several plausible hits, present the top candidates instead of pretending certainty.\n- For exact-text requests, quote `best_text` verbatim. Do not paraphrase commands, SQL, code, URLs, or file paths unless the user asked for a summary.\n\n## Capability map\n\nThe repo-side agent-native action parity contract lives in `docs/action-parity.md`. Use it when you need the maintained map from user-visible outcomes to agent-accessible commands, entity CRUD expectations, and derived-cache boundaries.\n\n## Output format rule\n\n- `--format json` — structured output. Retrieval envelopes are stable within `schema_version: 2`; management and inspection commands use command-specific JSON shapes, so parse documented keys directly.\n- `--format toon` — flat, token-efficient list. Prefer for high-cardinality enumeration (`timeline`, `search`, `recent`, `recall`) when you only need the top fields. Note: `get` does **not** support `toon`.\n- `--format jsonl` — newline-delimited records. Use when streaming many rows into a pipeline.\n- `--format md` / `--format text` — human-readable previews only; never parse these.\n\n`--json` is an alias for `--format json` on `search`, `recent`, `timeline`, `get`, `service revision`, `capture-once`, and `doctor`.\n\n## Which command for which intent\n\n| User intent | First command |\n|---|---|\n| \"what was that thing I copied\" (no time cue) | `recall \"<query>\" --format json` |\n| \"what did I copy today / yesterday / in order\" | `timeline --hours <N> --format json` |\n| \"recent unique things I copied\" | `recent --hours <N> --format json` |\n| exact substring or punctuation-heavy query | `search --mode literal \"<query>\" --format json` |\n| already have a snapshot id | `get <id> --format json` |\n| need raw image / PDF bytes | `get <id>` then `export <id> --item <n> --uti <uti> --out <path>` |\n\n`recall` vs `recent` vs `timeline`:\n\n- `recall` ranks across the archive and returns a best candidate plus alternatives.\n- `recent` deduplicates by snapshot — identical copies collapse into one row.\n- `timeline` is event-centric — every capture event is its own row, even if the content repeats.\n\n## Quick examples\n\n```bash\n# best-first answer\nclipmem recall \"that command I copied\" --format json --limit 5\n\n# Safari today, token-efficient\nclipmem recall --prefer-recent --app safari --hours 24 --format toon\n\n# exact URL yesterday\nclipmem recall \"url\" --has-url --hours 48 --format json\n\n# chronological sweep, paginated\nclipmem timeline --hours 24 --limit 25 --format json\nclipmem timeline --hours 24 --limit 25 --cursor \"<next_cursor>\" --format json\n\n# recover an image\nclipmem get 42 --format json\nclipmem export 42 --item 0 --uti public.png --out ./clipboard.png\nclipmem export 42 --item 0 --uti public.png --out ./clipboard.png --force\n```\n\n## Reading the response\n\nRead these JSON fields first; walk nested `items[].representations[]` only after a `get` call:\n\n- `best_candidate.best_text` — the flattened primary text.\n- `best_candidate.urls` — URL array (empty when none).\n- `best_candidate.file_paths` — file-URL array.\n- `why_selected`, `best_match_confidence`, `alternatives` (only on `recall`).\n- `next_cursor`, `truncated` — pagination state.\n- `schema_version` — pin to `2` for stability.\n\nFull schema in [references/json-schema.md](references/json-schema.md).\n\n## Troubleshooting\n\nIf `recall` looks empty or weak, widen `--hours`, drop source filters, or switch to `timeline` / `search`. For setup issues, sandbox PATH problems, or binary-only snapshots, see [references/troubleshooting.md](references/troubleshooting.md).\n\n## Exit codes\n\n`0` success · `1` uncategorized runtime · `2` invalid args · `3` not found · `4` unsupported format · `5` database error · `6` platform error.\n\nFile v1.3.7:_meta.json\n\n{\n  \"ownerId\": \"kn762fvz617r91c4h7qr9bdbp97zar1g\",\n  \"slug\": \"clipboard-memory\",\n  \"version\": \"1.3.7\",\n  \"publishedAt\": 1780166840733\n}\n\nFile v1.3.7:references/commands.md\n\n# Clipboard Memory — Commands Reference\n\nFull flag and subcommand reference for `clipmem`. This file is kept byte-identical across the OpenClaw-native and portable skill packages.\n\n---\n\n## Decision ladder\n\nPick the narrowest command that answers the question. Always pass `--format json` (or `--format toon` for plain enumeration) when parsing programmatically.\n\n1. `clipmem recall \"<query>\" --format json` — best-first ranked answer with alternatives. **Start here.**\n2. `clipmem timeline --hours <N> --format json` — chronological capture events. Use when the user says \"today\", \"yesterday\", \"in order\", or \"every time\".\n3. `clipmem recent --hours <N> --format json` — deduplicated recent snapshots. Use for \"recent unique things\".\n4. `clipmem search \"<query>\" --format json` — direct lexical / FTS match. Use when you need precise substring hits.\n5. `clipmem get <snapshot_id> --format json` — nested item/representation detail for a snapshot you already have.\n6. `clipmem restore <snapshot_id>` — restore the full stored representation set for a snapshot back onto the macOS clipboard.\n7. `clipmem export <snapshot_id> --item <n> --uti <uti> --out <path> [--force]` — raw bytes for binary/image/PDF payloads.\n8. `clipmem forget <snapshot_id>` — hard-delete one snapshot and its capture history.\n9. `clipmem purge --older-than <duration> [--dry-run]` — prune by `last_observed_at`.\n10. `clipmem storage compact [--dry-run] --format json` — reclaim SQLite/WAL disk space without changing content.\n11. `clipmem storage image-candidates --format json` — inspect image rows eligible for optimization without rewriting bytes.\n12. `clipmem storage optimize-images [--dry-run] [--no-compact] [--limit N] [--format json|--progress jsonl]` — convert eligible stored images to lossless WebP and compact by default.\n13. `clipmem service providers --format json` — inspect service provider availability without starting or stopping capture.\n14. `clipmem service revision --format json` — read archive revision counters without probing service providers.\n15. `clipmem settings show --format json` — inspect persistent capture policy.\n16. `clipmem app settings show --format json` — inspect menu bar app preferences.\n17. `clipmem app settings set KEY VALUE --format json` / `clear KEY --format json` — change app-local preferences and bump app preference revision.\n18. `clipmem app launch-at-login show|set|clear --format json` — inspect or change the app-owned launch-at-login preference bridge.\n19. `clipmem app update-check show|run|clear --format json` — inspect, run, or clear app update-check state.\n20. `clipmem app quit --format json` — request the menu bar app to quit.\n21. `clipmem agents context --format json` — one-call agent context: generated_at, service health, settings, app state, recent activity metadata, revision, stats, privacy guidance, and capability summary.\n22. `clipmem ocr status --format json` — inspect local OCR queue and result counts.\n23. `clipmem ocr candidates --format json` — inspect pending OCR candidates without running OCR.\n24. `clipmem ocr get <raw-sha256> --format json` / `clear <raw-sha256> --format json` — inspect or clear one OCR result.\n25. `clipmem ocr run [--limit N] [--snapshot ID]` — backfill OCR for image snapshots.\n\nPrimitive commands are the direct read/list/get/set/delete/start/stop surfaces\nabove. Convenience workflows are still supported but should be classified\nhonestly: `recall` ranks likely answers, `setup` composes initialization plus\nservice startup, `ocr run` processes a bounded OCR batch, and\n`storage optimize-images` scans and rewrites eligible image rows. Use\ncandidate, dry-run, or detail commands before broad workflow mutations when the\nuser has not explicitly asked to proceed.\n\n---\n\n## Subcommand matrix\n\n| Subcommand | Default `--format` | Supports `toon`? | Purpose |\n|---|---|---|---|\n| `recall [QUERY]` | `md` | yes | Ranked best-first answer with alternatives |\n| `search <QUERY>` | `text` | yes | Lexical / FTS match over the archive |\n| `recent` | `text` | yes | Recent unique snapshots (deduplicated) |\n| `timeline` | `text` | yes | Chronological capture events (not deduped) |\n| `get <SNAPSHOT_ID>` | `text` | **no** | Nested detail for one snapshot |\n| `restore <SNAPSHOT_ID>` | text | — | Restore a stored snapshot back onto the clipboard |\n| `export <SNAPSHOT_ID>` | — (raw bytes) | — | Write one representation to disk |\n| `forget <SNAPSHOT_ID>` | text | — | Hard-delete one snapshot and its capture history |\n| `purge` | text | — | Delete old snapshots by `last_observed_at` |\n| `storage compact` | text (`json` supported) | — | Reclaim SQLite/WAL disk space |\n| `storage image-candidates` | text (`json` supported) | — | List image rows eligible for optimization without mutation |\n| `storage optimize-images` | text (`json` supported, progress JSONL available) | — | Convert eligible images to lossless WebP |\n| `settings show` | `text` | **no** | Show persistent pause / retention / ignore-list policy |\n| `settings pause` | text | — | Persistently pause or resume capture; supports `json` and `human` |\n| `settings api-key-filter` | text | — | Enable or disable API key filtering; supports `json` and `human` |\n| `settings ocr` | text | — | Enable or disable local OCR for new image captures; supports `json` and `human` |\n| `settings retention` | text | — | Set retention to a duration or `forever`; supports `json` and `human` |\n| `settings reset` | text (`json` supported) | — | Reset capture policy and ignored apps to defaults |\n| `settings ignore add/remove/list` | text | **no** | Manage ignored bundle identifiers; supports `json` and `human` |\n| `app settings show` | text (`json` supported) | — | Show menu bar app preferences |\n| `app settings set` | text (`json` supported) | — | Set one menu bar app preference |\n| `app settings clear` | text (`json` supported) | — | Clear one menu bar app preference |\n| `app launch-at-login show/set/clear` | text (`json` supported) | — | Manage the app-owned launch-at-login preference bridge |\n| `app update-check show/run/clear` | text (`json` supported) | — | Show, run, or clear app update-check state |\n| `app quit` | text (`json` supported) | — | Request the menu bar app to quit |\n| `agents context` | text (`json` supported) | — | Agent context bundle: generated_at, health, settings, app state, recent activity, revision, stats, privacy, capabilities |\n| `ocr status` | text (`json` supported) | — | Local OCR queue and result counts |\n| `ocr candidates` | text (`json` supported) | — | Pending OCR candidate hashes without processing |\n| `ocr get` | text (`json` supported) | — | One OCR result by raw representation hash |\n| `ocr clear` | text (`json` supported) | — | Delete one OCR result and rebuild affected OCR cache |\n| `ocr run` | text (`json` supported) | — | Backfill OCR for stored image snapshots |\n| `capture-once` | — | — | Single clipboard capture (setup / ad-hoc) |\n| `watch` | — | — | Background daemon; usually a LaunchAgent |\n| `setup` | — | — | Seed one capture and start background capture |\n| `service status` | text (or `--json`) | — | Background provider state + capture freshness |\n| `service providers` | text (`json` supported) | — | Service provider availability without mutation |\n| `service revision` | text (`json` supported) | — | Archive revision counters without provider probes |\n| `service start` / `stop` / `uninstall` | — | — | Manage the background watcher service |\n| `doctor` | text (or `--json`) | — | SQLite / FTS5 diagnostics |\n| `agents openclaw doctor` | text | — | Integration health: PATH, workspace, sandbox |\n| `agents openclaw install-skill` | — | — | Write packaged skill files to disk |\n| `agents openclaw print-skill` | — | — | Print embedded `SKILL.md` to stdout |\n| `agents openclaw uninstall-skill` | — | — | Remove installed skill directory |\n| `agents hermes doctor` | text | — | Hermes integration health: PATH, skill discovery |\n| `agents hermes install-skill` | — | — | Write packaged Hermes skill to disk |\n| `agents hermes print-skill` | — | — | Print embedded Hermes `SKILL.md` to stdout |\n| `agents hermes uninstall-skill` | — | — | Remove installed Hermes skill directory |\n\n`--json` is a compatibility alias for `--format json` on `search`, `recent`, `timeline`, `get`, `agents context`, `storage compact`, `storage optimize-images`, `ocr status`, `ocr run`, `capture-once`, and `doctor`.\n\n---\n\n## Output formats\n\nAll retrieval commands share the same `--format` set except `get`, which omits `toon`:\n\n- `text` — human-oriented terminal output. Default for `search`, `recent`, `timeline`, `get`. **Do not parse.**\n- `md` — compact markdown. Default for `recall`. Human-oriented. **Do not parse.**\n- `json` — single structured object with a stable envelope. Parse this.\n- `jsonl` — newline-delimited rows. Prefer when streaming many results through a pipe.\n- `toon` — flat token-efficient list. Prefer for `timeline`, `search`, `recent`, and `recall` when you only need the top fields. Unsupported on `get`.\n\n---\n\n## Shared retrieval filters\n\n`search`, `recent`, `timeline`, and `recall` accept the same filter set. `get` and `export` accept them as guards against the explicitly targeted snapshot.\n\n**Time window:**\n\n- `--since <RFC3339>` — captures at or after this timestamp (e.g. `2026-04-16T09:00:00Z`).\n- `--until <RFC3339>` — captures at or before this timestamp.\n- `--hours <N>` — last N hours. `--since` wins if both are provided.\n\n**Source:**\n\n- `--app <name>` — case-insensitive substring match on the recorded frontmost app name.\n- `--bundle-id <id>` — case-insensitive exact match on bundle identifier (e.g. `com.apple.Safari`).\n\n**Content shape:**\n\n- `--kind text|html|rtf|url|file|image|pdf|binary|other`. One value per invocation.\n- `--has-text`, `--has-url`, `--has-file-url`, `--has-image`, `--has-pdf` — additive presence flags (AND semantics).\n\n**Size:**\n\n- `--min-bytes <N>` / `--max-bytes <N>` — applied to the total snapshot byte count.\n\n### `--kind` values\n\n| Value | Matches |\n|---|---|\n| `text` | plain text representations |\n| `html` | HTML clipboard payloads |\n| `rtf` | rich-text format |\n| `url` | web URLs |\n| `file` | **file URLs (Finder paths)** — not regular files on disk |\n| `image` | image blobs (PNG, JPEG, TIFF, etc.) |\n| `pdf` | PDF documents |\n| `binary` | opaque binary that has no safe text projection |\n| `other` | mixed or empty snapshots |\n\n`--kind file` is a common pitfall: it matches clipboard-as-file-URL payloads (things dragged from Finder), not arbitrary files the user happened to reference.\n\n---\n\n## Pagination\n\nList commands (`search`, `recent`, `timeline`) accept `--limit` and `--cursor`:\n\n- `--limit <N>` — 1–250, default 10.\n- `--cursor <opaque>` — resume from a `next_cursor` returned by a prior response.\n\nCursors are tied to the active query, mode, and filters. Changing any of those while paginating will reject the cursor. When a response includes `\"truncated\": true` and a non-null `next_cursor`, there are more rows.\n\n```bash\nclipmem search \"git status\" --format json --limit 25\nclipmem search \"git status\" --format json --limit 25 --cursor \"<next_cursor>\"\n```\n\n---\n\n## Search modes (`search`, `recall`)\n\n`--mode auto|fts|literal`, default `auto`.\n\n- `auto` — picks FTS or literal per query. Prefers literal for URLs, paths, bundle ids, dotted identifiers, and shell fragments (`--flag=value`, pipes, subshells). Plain prose queries try FTS first.\n- `fts` — strict SQLite FTS5. Use when you want to compose boolean queries: `\"launchctl\" AND bootstrap`.\n- `literal` — exact substring match. Use for punctuation-heavy strings like `50%`, `Co-Authored-By:`, or URL fragments.\n\nRules of thumb:\n\n- Query contains `\"`, `AND`, `OR`, `NOT` → `--mode fts`.\n- Query contains `/`, `.`, `:`, `%`, or shell metacharacters → `--mode literal`.\n- Short natural-language query → let `--mode auto` pick.\n\n---\n\n## `recall` extras\n\nOn top of the shared filters:\n\n- `--format md|json|toon` (default `md`).\n- `--limit <N>` — ranked candidates to consider (default 5).\n- `--full` — expand the best candidate text instead of the compact form.\n- `--quote` — force quoted best-text output.\n- `--min-score <0.0-1.0>` — threshold below which a query alone is not trusted; falls back to recency / filters.\n- `--prefer-recent` — bias ranking toward recency.\n- `--prefer-app <name>` — bias toward matching app or bundle id.\n- `--hours <N>` — window for the recent-fallback when a query is weak.\n\nIf the user has no query but said \"the thing I just copied\":\n\n```bash\nclipmem recall --prefer-recent --hours 24 --format json --limit 5\n```\n\n---\n\n## `get`, `restore`, and `export`\n\n```bash\nclipmem get <snapshot_id> --format json        # nested representation detail\nclipmem get <snapshot_id> --events <N>         # include last N capture events (default 10)\nclipmem restore <snapshot_id>                  # restore the whole snapshot to the clipboard\nclipmem export <snapshot_id> --item <index> --uti <uti> --out <path> [--force]\n```\n\n`get --format json` flattens the common text fields on the root snapshot so agents don't have to walk the representation tree. `get` does **not** support `--format toon`.\n\n`restore` is macOS-only and writes the full stored item/UTI/raw-byte set back onto the general pasteboard. This is a whole-snapshot restore, not a text-only approximation.\n\n`export` writes raw bytes to `--out` and supports `--format json` for structured confirmation. By default it creates a new file and refuses to replace an existing destination; pass `--force` only to replace an existing regular file. Symlink destinations are rejected. Required arguments: `--item` (0-based), `--uti` (e.g. `public.png`, `public.utf8-plain-text`, `com.adobe.pdf`), `--out`. Inspect `items[].representations[].uti` and `size_bytes` in a prior `get --format json` to choose the right combination.\n\n---\n\n## `forget`, `purge`, `storage`, and `settings`\n\n```bash\nclipmem forget <snapshot_id>\nclipmem purge --older-than 30d [--dry-run]\nclipmem storage compact [--dry-run] [--format json]\nclipmem storage image-candidates [--limit N] [--format json]\nclipmem storage optimize-images [--dry-run] [--no-compact] [--limit N] [--format json|--progress jsonl]\nclipmem settings show [--format json]\nclipmem settings pause on|off [--format json]\nclipmem settings api-key-filter on|off [--format json]\nclipmem settings ocr on|off [--format json]\nclipmem settings retention <duration|forever> [--format json]\nclipmem settings reset [--format json]\nclipmem settings ignore add <bundle_id> [--format json]\nclipmem settings ignore remove <bundle_id> [--format json]\nclipmem settings ignore list [--format json]\nclipmem app settings show [--format json]\nclipmem app settings set binary-path-override <path> [--format json]\nclipmem app settings set database-path-override <path> [--format json]\nclipmem app settings set default-recent-hours <hours> [--format json]\nclipmem app settings set default-query-mode recall|search|recent|timeline|diagnostics [--format json]\nclipmem app settings set hotkey-enabled true|false [--format json]\nclipmem app settings clear <key> [--format json]\nclipmem app launch-at-login show [--format json]\nclipmem app launch-at-login set on|off [--format json]\nclipmem app launch-at-login clear [--format json]\nclipmem app update-check show [--format json]\nclipmem app update-check run [--format json]\nclipmem app update-check clear [--format json]\nclipmem app quit [--format json]\nclipmem service revision [--format json]\nclipmem ocr status [--format json]\nclipmem ocr candidates [--limit N] [--snapshot ID] [--format json]\nclipmem ocr get <raw-sha256> [--format json]\nclipmem ocr clear <raw-sha256> [--format json]\nclipmem ocr run [--limit N] [--snapshot ID] [--retry-failed] [--format json]\n```\n\n`forget` is a hard delete. It removes the snapshot row, all child items/representations, and all capture events for that snapshot id via foreign-key cascades. OCR results with no remaining representation referencing their image hash are also removed.\n\n`purge` computes age from `snapshot_stats.last_observed_at`, not `snapshots.created_at`. Duration grammar is a single integer plus one unit: `Nd`, `Nh`, or `Nm`.\n\n`storage compact` checkpoints WAL state and vacuums SQLite pages back to the filesystem. It never changes clipboard content. `storage image-candidates` lists the same eligible image rows that `storage optimize-images` would scan, without rewriting bytes or marking rows. `storage optimize-images` rewrites eligible image representations to lossless WebP only when doing so saves meaningful space, then compacts SQLite storage by default; already compressed or skipped rows are not retried by normal runs. Use `--progress jsonl` for streamed `started`, `scanning`, `compacting`, and `complete` progress events. Use `--no-compact` only when batching optimization runs and compacting once at the end.\n\n`ocr candidates` lists pending OCR hashes and affected snapshot counts without invoking Apple Vision. Use it before `ocr run` when an agent needs to inspect queue work.\n\n`settings` is the persistent capture-policy entrypoint. Ignore matching is exact, case-insensitive bundle-id matching only. OCR is opt-in, runs locally through Apple Vision on macOS, and stores text/status separately from raw image bytes.\n\n`app settings`, `app launch-at-login`, and `app update-check` are menu bar app state bridges. They read and write app-local preferences without changing archive capture policy. Mutating commands bump `app_preferences_revision` so an open app can observe external agent changes. Launch-at-login writes the desired app-owned preference; the menu bar app applies it through `SMAppService`. `app update-check run` performs the live latest-stable-release lookup and updates the same cache the app reads. `app quit` requests the menu bar app to terminate through the app bundle identifier.\n\n`clipmem agents context --format json` is safe as a first call in agent sessions. It includes `generated_at`, service health, capture policy, archive revision, bounded recent activity, menu bar app state, capability discovery, and privacy guidance. It excludes raw clipboard content and representation bytes, but includes operational metadata such as app names, timestamps, counts, paths, and app preference state.\n\n`clipmem service revision --format json` is the lightweight polling path for change detection. It reads the same archive revision counters surfaced in service status and agent context without checking Homebrew, LaunchAgent, or other service providers.\n\n---\n\n## Global flags\n\n- `--db <path>` — override the SQLite database path. Default: `~/Library/Application Support/clipmem/clipmem.sqlite3` on macOS. Use this only when pointing at an alternate archive (tests, backups).\n\n## Environment\n\n- `CLIPMEM_OPENCLAW_WORKSPACE` — overrides the OpenClaw workspace root used by `agents openclaw install-skill` and `agents openclaw doctor`. Falls back to `openclaw config get agents.defaults.workspace`, then `~/.openclaw/workspace`.\n- `HOME` — resolves `~/` in default paths.\n\n---\n\n## Exit codes\n\n- `0` — success\n- `1` — uncategorized runtime failure\n- `2` — invalid args\n- `3` — not found (e.g. snapshot id, representation)\n- `4` — unsupported format for this subcommand (e.g. `--format toon` on `get`)\n- `5` — database error\n- `6` — platform error (macOS API / filesystem)\n\nScripts can rely on these to distinguish \"no such snapshot\" (retriable with a different id) from \"database locked\" (retry with backoff) from \"wrong format\" (agent bug).\n\n---\n\n## Script-friendly guarantees\n\n- stdout contains only the requested command output.\n- stderr contains diagnostics only.\n- No interactive prompts anywhere in the CLI.\n- List commands use bounded `--limit` defaults and opaque cursor pagination.\n- Retrieval JSON envelopes (`search`, `recent`, `timeline`, `get`, `recall`, and mutation confirmations that include `schema_version`) are stable within `schema_version: 2`. Management and inspection commands such as `agents context`, `app`, `service`, `ocr`, and `storage image-candidates` have command-specific JSON shapes; parse their documented keys directly and do not require `schema_version: 2` unless the command emits it.\n\nFile v1.3.7:references/examples.md\n\n# Clipboard Memory — Worked Examples\n\nConcrete input → output walkthroughs. Byte-identical across skill packages.\n\nEach example shows the user's question, the command to run, the shape of the response, and the next step.\n\n---\n\n## Example 1 — \"What was that URL I copied from Safari yesterday?\"\n\nThe user gave a time cue (yesterday) and a source (Safari). Use `recall` with a `--prefer-recent` bias, an `--app` filter, and a generous `--hours` window.\n\n```bash\nclipmem recall \"url\" --prefer-recent --app safari --has-url --hours 48 --format json --limit 5\n```\n\nResponse (trimmed):\n\n```json\n{\n  \"schema_version\": 2,\n  \"command\": \"recall\",\n  \"best_candidate\": {\n    \"snapshot_id\": 812,\n    \"best_text\": \"https://developer.apple.com/documentation/appkit/nspasteboard\",\n    \"urls\": [\"https://developer.apple.com/documentation/appkit/nspasteboard\"],\n    \"app_name\": \"Safari\",\n    \"observed_at\": \"2026-04-16T17:45:00Z\",\n    \"why_matched\": \"url filter + recency bias\"\n  },\n  \"best_match_confidence\": \"high\",\n  \"alternatives\": [ /* ... */ ],\n  \"next_cursor\": null\n}\n```\n\nReport `best_candidate.urls[0]`. If `best_match_confidence` were `\"low\"`, enumerate `alternatives` instead.\n\n---\n\n## Example 2 — \"Show me everything I copied today, in order\"\n\nThe user wants chronological events, not deduplicated recent snapshots. Use `timeline` and `toon` for efficient enumeration.\n\n```bash\nclipmem timeline --hours 24 --format toon --sort asc --limit 50\n```\n\nTOON output (one row per line, tab-separated scalar fields):\n\n```\nsnapshot_id\tobserved_at\tapp_name\tkind\tbest_text\n812\t2026-04-17T08:02:11Z\tSafari\turl\thttps://developer.apple.com/…\n813\t2026-04-17T08:04:03Z\tTerminal\ttext\tgit status\n813\t2026-04-17T08:11:59Z\tTerminal\ttext\tgit status\n...\n```\n\nNotice snapshot `813` appears twice — `timeline` shows each capture event, not each unique snapshot. If `truncated` shows more rows exist, re-run with the last row's time as `--until` or request `--format json` and page via `--cursor`.\n\n---\n\n## Example 3 — \"Pull the image I copied from that screenshot tool\"\n\nImages have no text projection. Use `recall` to find the snapshot, then `get` to discover the representation `uti` and byte size, then `export` to write raw bytes.\n\n```bash\n# 1. find the snapshot\nclipmem recall \"screenshot\" --kind image --hours 72 --format json --limit 3\n```\n\n```json\n{\n  \"best_candidate\": {\n    \"snapshot_id\": 901,\n    \"kind\": \"image\",\n    \"best_text\": null,\n    \"total_bytes\": 138402,\n    \"app_name\": \"CleanShot X\"\n  }\n}\n```\n\n```bash\n# 2. inspect representations to pick a uti\nclipmem get 901 --format json\n```\n\n```json\n{\n  \"snapshot\": {\n    \"items\": [\n      {\n        \"item_index\": 0,\n        \"representations\": [\n          { \"uti\": \"public.png\", \"size_bytes\": 138402, \"is_indexed\": false },\n          { \"uti\": \"public.tiff\", \"size_bytes\": 412004, \"is_indexed\": false }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```bash\n# 3. export raw bytes\nclipmem export 901 --item 0 --uti public.png --out ./clipboard.png\nclipmem export 901 --item 0 --uti public.png --out ./clipboard.png --force\n```\n\n`export` writes binary content to `--out` and exits 0 on success. It creates a new file by default; pass `--force` only to replace an existing regular file. There is no `--format` on `export`.\n\n---\n\n## Example 4 — Paginating a large search\n\nThe user asks for everything matching a phrase. `search` returns bounded pages; use the cursor to keep going.\n\n```bash\nclipmem search \"launchctl bootstrap\" --mode literal --format json --limit 25\n```\n\n```json\n{\n  \"schema_version\": 2,\n  \"command\": \"search\",\n  \"results\": [ /* 25 rows */ ],\n  \"truncated\": true,\n  \"next_cursor\": \"eyJvZmZzZXQiOjI1LCJxdWVyeSI6Imxhdw...\"\n}\n```\n\n```bash\nclipmem search \"launchctl bootstrap\" --mode literal --format json --limit 25 \\\n  --cursor \"eyJvZmZzZXQiOjI1LCJxdWVyeSI6Imxhdw...\"\n```\n\nStop paginating when `truncated` is `false` or `next_cursor` is `null`.\n\nCursors are tied to the active query, mode, and filters. Changing any of those mid-pagination invalidates the cursor — start over.\n\n---\n\n## Example 5 — \"Give me the exact text, not a summary\"\n\nBy default `recall` returns a compact form. Force quoted, full text:\n\n```bash\nclipmem recall \"the SQL migration\" --quote --full --format json\n```\n\n`best_candidate.best_text` now holds the complete stored text. If it's still truncated (very large clipboards), use `get --format json` and concatenate `text_fragments[].text`.\n\n---\n\n## Example 6 — \"Nothing is copied from today\" — diagnose first\n\nDon't assume the archive is wrong; the watcher may have stopped.\n\n```bash\n./scripts/check-setup.sh\n# or, inline\nclipmem doctor --json\nclipmem service status --json\n```\n\nIf `clipmem service status --json` reports `stale: true`, the watcher is not running. Tell the user to run `clipmem setup` or `brew services start clipmem` before retrying.\n\nSee [troubleshooting.md](troubleshooting.md) for remediation steps.\n\nFile v1.3.7:references/json-schema.md\n\n# Clipboard Memory — JSON Schema\n\nStable response shapes for `--format json`. Current `schema_version` is `2`. This file is kept byte-identical across skill packages.\n\nBreaking changes to these fields will bump `schema_version`. Additive changes (new optional keys) are allowed within the same version.\n\n---\n\n## Shared envelope (`recall`, `search`, `recent`, `timeline`)\n\n```json\n{\n  \"schema_version\": 2,\n  \"command\": \"recall\",\n  \"generated_at\": \"2026-04-17T12:34:56Z\",\n  \"applied_filters\": { \"hours\": 24, \"app\": \"safari\" },\n  \"truncated\": false,\n  \"next_cursor\": null,\n  \"results\": [ /* rows, see below */ ]\n}\n```\n\n- `schema_version` — integer. Pin to `2` for stability checks.\n- `command` — echoes the subcommand.\n- `generated_at` — RFC3339 timestamp when the response was produced.\n- `applied_filters` — echoes the filters actually applied after argument parsing.\n- `\n\nArchive v1.3.6: 9 files, 25000 bytes\n\nFiles: references/commands.md (20419b), references/examples.md (4895b), references/json-schema.md (5907b), references/setup-check.md (2210b), references/troubleshooting.md (5278b), scripts/check-setup.sh (8587b), skill-card.md (2741b), SKILL.md (10257b), _meta.json (135b)\n\nArchive v1.3.5: 8 files, 23547 bytes\n\nFiles: references/commands.md (20327b), references/examples.md (4895b), references/json-schema.md (5907b), references/setup-check.md (2210b), references/troubleshooting.md (5278b), scripts/check-setup.sh (8587b), SKILL.md (10257b), _meta.json (135b)\n\nArchive v1.3.4: 8 files, 23529 bytes\n\nFiles: references/commands.md (20116b), references/examples.md (4895b), references/json-schema.md (5907b), references/setup-check.md (2210b), references/troubleshooting.md (5278b), scripts/check-setup.sh (8587b), SKILL.md (10257b), _meta.json (135b)\n\nArchive v1.3.3: 8 files, 20670 bytes\n\nFiles: references/commands.md (13690b), references/examples.md (4895b), references/json-schema.md (5907b), references/setup-check.md (2210b), references/troubleshooting.md (5278b), scripts/check-setup.sh (8587b), SKILL.md (7297b), _meta.json (135b)\n\nArchive v1.3.2: 8 files, 20596 bytes\n\nFiles: references/commands.md (13523b), references/examples.md (4895b), references/json-schema.md (5907b), references/setup-check.md (2210b), references/troubleshooting.md (5278b), scripts/check-setup.sh (8587b), SKILL.md (7297b), _meta.json (135b)\n\nArchive v1.3.1: 8 files, 20521 bytes\n\nFiles: references/commands.md (13169b), references/examples.md (4895b), references/json-schema.md (5907b), references/setup-check.md (2128b), references/troubleshooting.md (5278b), scripts/check-setup.sh (8587b), SKILL.md (7297b), _meta.json (135b)\n\nArchive v1.3.0: 8 files, 18012 bytes\n\nFiles: _meta.json (135b), references/commands.md (8922b), references/examples.md (4729b), references/json-schema.md (5739b), references/setup-check.md (2128b), references/troubleshooting.md (5278b), scripts/check-setup.sh (5251b), SKILL.md (7129b)","readmeExcerpt":"Skill: clipboard-memory Owner: tristanmanchester Summary: Recall what the user copied on this Mac via the local clipmem archive — text, commands, URLs, file paths, HTML, images, PDFs. Triggers on requests like \"what was that command I copied?\", \"the URL I copied from Safari\", \"find that snippet before I restarted\", or any paraphrase involving copy, paste, or clipboard. Offers ranked recall, chronological timeline, le","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# best-first answer\nclipmem recall \"that command I copied\" --format json --limit 5\n\n# Safari today, token-efficient\nclipmem recall --prefer-recent --app safari --hours 24 --format toon\n\n# exact URL yesterday\nclipmem recall \"url\" --has-url --hours 48 --format json\n\n# chronological sweep, paginated\nclipmem timeline --hours 24 --limit 25 --format json\nclipmem timeline --hours 24 --limit 25 --cursor \"<next_cursor>\" --format json\n\n# recover an image\nclipmem get 42 --format json\nclipmem export 42 --item 0 --uti public.png --out ./clipboard.png\nclipmem export 42 --item 0 --uti public.png --out ./clipboard.png --force"},{"language":"bash","snippet":"clipmem search \"git status\" --format json --limit 25\nclipmem search \"git status\" --format json --limit 25 --cursor \"<next_cursor>\""},{"language":"bash","snippet":"clipmem recall --prefer-recent --hours 24 --format json --limit 5"},{"language":"bash","snippet":"clipmem get <snapshot_id> --format json        # nested representation detail\nclipmem get <snapshot_id> --events <N>         # include last N capture events (default 10)\nclipmem restore <snapshot_id>                  # restore the whole snapshot to the clipboard\nclipmem export <snapshot_id> --item <index> --uti <uti> --out <path> [--force]"},{"language":"bash","snippet":"clipmem forget <snapshot_id>\nclipmem purge --older-than 30d [--dry-run]\nclipmem storage compact [--dry-run] [--format json]\nclipmem storage image-candidates [--limit N] [--format json]\nclipmem storage optimize-images [--dry-run] [--no-compact] [--limit N] [--format json|--progress jsonl]\nclipmem settings show [--format json]\nclipmem settings pause on|off [--format json]\nclipmem settings api-key-filter on|off [--format json]\nclipmem settings ocr on|off [--format json]\nclipmem settings retention <duration|forever> [--format json]\nclipmem settings reset [--format json]\nclipmem settings ignore add <bundle_id> [--format json]\nclipmem settings ignore remove <bundle_id> [--format json]\nclipmem settings ignore list [--format json]\nclipmem app settings show [--format json]\nclipmem app settings set binary-path-override <path> [--format json]\nclipmem app settings set database-path-override <path> [--format json]\nclipmem app settings set default-recent-hours <hours> [--format json]\nclipmem app settings set default-query-mode recall|search|recent|timeline|diagnostics [--format json]\nclipmem app settings set hotkey-enabled true|false [--format json]\nclipmem app settings clear <key> [--format json]\nclipmem app launch-at-login show [--format json]\nclipmem app launch-at-login set on|off [--format json]\nclipmem app launch-at-login clear [--format json]\nclipmem app update-check show [--format json]\nclipmem app update-check run [--format json]\nclipmem app update-check clear [--format json]\nclipmem app quit [--format json]\nclipmem service revision [--format json]\nclipmem ocr status [--format json]\nclipmem ocr candidates [--limit N] [--snapshot ID] [--format json]\nclipmem ocr get <raw-sha256> [--format json]\nclipmem ocr clear <raw-sha256> [--format json]\nclipmem ocr run [--limit N] [--snapshot ID] [--retry-failed] [--format json]"},{"language":"bash","snippet":"clipmem recall \"url\" --prefer-recent --app safari --has-url --hours 48 --format json --limit 5"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: clipboard-memory\ndescription: Recall what the user copied on this Mac via the local clipmem archive — text, commands, URLs, file paths, HTML, images, PDFs. Triggers on requests like \"what was that command I copied?\", \"the URL I copied from Safari\", \"find that snippet before I restarted\", or any paraphrase involving copy, paste, or clipboard. Offers ranked recall, chronological timeline, lexical / FTS search, raw-byte export for binary content, cursor pagination, and filters by app, kind, time window, and content shape. Use before reaching for generic web or repo search whenever the user is trying to recover something they previously had on the clipboard.\nlicense: MIT\nmetadata: {\"openclaw\":{\"emoji\":\"📋\",\"os\":[\"darwin\"],\"requires\":{\"bins\":[\"clipmem\"]},\"install\":[{\"id\":\"brew\",\"kind\":\"brew\",\"label\":\"Install clipmem (brew)\",\"bins\":[\"clipmem\"],\"formula\":\"clipmem\",\"tap\":\"tristanmanchester/tap\"},{\"id\":\"cargo\",\"kind\":\"cargo\",\"label\":\"Install clipmem (cargo)\",\"bins\":[\"clipmem\"],\"package\":\"clipmem\"}],\"version\":\"1.3.9\"}}\n---\n\nRecall what the user copied on this Mac before reaching for generic search. `clipmem` maintains a local, privacy-preserving SQLite archive of every clipboard state macOS emits, and exposes a JSON-first CLI built for agents. This package is installed by `clipmem agents openclaw install-skill`; the canonical cross-agent source lives under `skills/clipboard-memory/`.\n\n## Use this skill when\n\nThe user asks things like:\n\n- \"what was that command I copied?\"\n- \"show me the URL I copied from Safari earlier\"\n- \"find that snippet, path, note, or link I copied yesterday\"\n- \"give me the exact text I copied, not a summary\"\n- \"what did I copy before I restarted?\"\n- \"paste me back that SQL I was looking at\"\n- \"get the PDF I copied last week\"\n- \"show me everything I copied from Xcode today\"\n\n## Do not use this skill for\n\n- web search or current-events lookups\n- searching the repository or local files the user never copied\n- content the user typed but never copied to the clipboard\n- anything on a non-macOS machine (`clipmem` captures `NSPasteboard` only)\n\n## Prerequisites\n\nBefore querying, confirm the setup is healthy — otherwise empty results may be a stale watcher, not a true miss:\n\n1. Background capture must be running. `clipmem setup` is the canonical fix; Homebrew users can also use `clipmem service start`.\n2. The binary `clipmem` must be on PATH with write access to `~/Library/Application Support/clipmem/clipmem.sqlite3`.\n3. Run [`scripts/check-setup.sh`](scripts/check-setup.sh) once per session when results look wrong. It exits `0` on a healthy host, `1` if the watcher is stale, `2` if the binary is missing, `3` if `clipmem doctor` fails. The prose equivalent is in [references/setup-check.md](references/setup-check.md).\n4. If OpenClaw cannot see the binary, run `clipmem agents openclaw doctor` and follow its remediation lines.\n\n## Command ladder\n\nAlways pick the narrowest command that answers the question, and always pass `--format json"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn762fvz617r91c4h7qr9bdbp97zar1g\",\n  \"slug\": \"clipboard-memory\",\n  \"version\": \"1.3.9\",\n  \"publishedAt\": 1789298560819\n}"},{"path":"references/commands.md","content":"# Clipboard Memory — Commands Reference\n\nFull flag and subcommand reference for `clipmem`. This file is kept byte-identical across the OpenClaw-native and portable skill packages.\n\n---\n\n## Decision ladder\n\nPick the narrowest command that answers the question. Always pass `--format json` (or `--format toon` for plain enumeration) when parsing programmatically.\n\n1. `clipmem recall \"<query>\" --format json` — best-first ranked answer with alternatives. **Start here.**\n2. `clipmem timeline --hours <N> --format json` — chronological capture events. Use when the user says \"today\", \"yesterday\", \"in order\", or \"every time\".\n3. `clipmem recent --hours <N> --format json` — deduplicated recent snapshots. Use for \"recent unique things\".\n4. `clipmem search \"<query>\" --format json` — direct lexical / FTS match. Use when you need precise substring hits.\n5. `clipmem get <snapshot_id> --format json` — nested item/representation detail for a snapshot you already have.\n6. `clipmem restore <snapshot_id>` — restore the full stored representation set for a snapshot back onto the macOS clipboard.\n7. `clipmem export <snapshot_id> --item <n> --uti <uti> --out <path> [--force]` — raw bytes for binary/image/PDF payloads.\n8. `clipmem forget <snapshot_id>` — hard-delete one snapshot and its capture history.\n9. `clipmem purge --older-than <duration> [--dry-run]` — prune by `last_observed_at`.\n10. `clipmem storage compact [--dry-run] --format json` — reclaim SQLite/WAL disk space without changing content.\n11. `clipmem storage image-candidates --format json` — inspect image rows eligible for optimization without rewriting bytes.\n12. `clipmem storage optimize-images [--dry-run] [--no-compact] [--limit N] [--format json|--progress jsonl]` — convert eligible stored images to lossless WebP and compact by default.\n13. `clipmem service providers --format json` — inspect service provider availability without starting or stopping capture.\n14. `clipmem service revision --format json` — read archive revision counters without probing service providers.\n15. `clipmem settings show --format json` — inspect persistent capture policy.\n16. `clipmem app settings show --format json` — inspect menu bar app preferences.\n17. `clipmem app settings set KEY VALUE --format json` / `clear KEY --format json` — change app-local preferences and bump app preference revision.\n18. `clipmem app launch-at-login show|set|clear --format json` — inspect or change the app-owned launch-at-login preference bridge.\n19. `clipmem app update-check show|run|clear --format json` — inspect, run, or clear app update-check state.\n20. `clipmem app quit --format json` — request the menu bar app to quit.\n21. `clipmem agents context --format json` — one-call agent context: generated_at, service health, settings, app state, recent activity metadata, revision, stats, privacy guidance, and capability summary.\n22. `clipmem ocr status --format json` — inspect local OCR queue and result counts.\n23. `clipmem ocr candidates --format json` "},{"path":"references/examples.md","content":"# Clipboard Memory — Worked Examples\n\nConcrete input → output walkthroughs. Byte-identical across skill packages.\n\nEach example shows the user's question, the command to run, the shape of the response, and the next step.\n\n---\n\n## Example 1 — \"What was that URL I copied from Safari yesterday?\"\n\nThe user gave a time cue (yesterday) and a source (Safari). Use `recall` with a `--prefer-recent` bias, an `--app` filter, and a generous `--hours` window.\n\n```bash\nclipmem recall \"url\" --prefer-recent --app safari --has-url --hours 48 --format json --limit 5\n```\n\nResponse (trimmed):\n\n```json\n{\n  \"schema_version\": 2,\n  \"command\": \"recall\",\n  \"best_candidate\": {\n    \"snapshot_id\": 812,\n    \"best_text\": \"https://developer.apple.com/documentation/appkit/nspasteboard\",\n    \"urls\": [\"https://developer.apple.com/documentation/appkit/nspasteboard\"],\n    \"app_name\": \"Safari\",\n    \"observed_at\": \"2026-04-16T17:45:00Z\",\n    \"why_matched\": \"url filter + recency bias\"\n  },\n  \"best_match_confidence\": \"high\",\n  \"alternatives\": [ /* ... */ ],\n  \"next_cursor\": null\n}\n```\n\nReport `best_candidate.urls[0]`. If `best_match_confidence` were `\"low\"`, enumerate `alternatives` instead.\n\n---\n\n## Example 2 — \"Show me everything I copied today, in order\"\n\nThe user wants chronological events, not deduplicated recent snapshots. Use `timeline` and `toon` for efficient enumeration.\n\n```bash\nclipmem timeline --hours 24 --format toon --sort asc --limit 50\n```\n\nTOON output (one row per line, tab-separated scalar fields):\n\n```\nsnapshot_id\tobserved_at\tapp_name\tkind\tbest_text\n812\t2026-04-17T08:02:11Z\tSafari\turl\thttps://developer.apple.com/…\n813\t2026-04-17T08:04:03Z\tTerminal\ttext\tgit status\n813\t2026-04-17T08:11:59Z\tTerminal\ttext\tgit status\n...\n```\n\nNotice snapshot `813` appears twice — `timeline` shows each capture event, not each unique snapshot. If `truncated` shows more rows exist, re-run with the last row's time as `--until` or request `--format json` and page via `--cursor`.\n\n---\n\n## Example 3 — \"Pull the image I copied from that screenshot tool\"\n\nImages have no text projection. Use `recall` to find the snapshot, then `get` to discover the representation `uti` and byte size, then `export` to write raw bytes.\n\n```bash\n# 1. find the snapshot\nclipmem recall \"screenshot\" --kind image --hours 72 --format json --limit 3\n```\n\n```json\n{\n  \"best_candidate\": {\n    \"snapshot_id\": 901,\n    \"kind\": \"image\",\n    \"best_text\": null,\n    \"total_bytes\": 138402,\n    \"app_name\": \"CleanShot X\"\n  }\n}\n```\n\n```bash\n# 2. inspect representations to pick a uti\nclipmem get 901 --format json\n```\n\n```json\n{\n  \"snapshot\": {\n    \"items\": [\n      {\n        \"item_index\": 0,\n        \"representations\": [\n          { \"uti\": \"public.png\", \"size_bytes\": 138402, \"is_indexed\": false },\n          { \"uti\": \"public.tiff\", \"size_bytes\": 412004, \"is_indexed\": false }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```bash\n# 3. export raw bytes\nclipmem export 901 --item 0 --uti public.png --out ./clipboard.png\nclipmem export 901 --item 0 --uti publ"},{"path":"references/json-schema.md","content":"# Clipboard Memory — JSON Schema\n\nStable response shapes for `--format json`. Current `schema_version` is `2`. This file is kept byte-identical across skill packages.\n\nBreaking changes to these fields will bump `schema_version`. Additive changes (new optional keys) are allowed within the same version.\n\n---\n\n## Shared envelope (`recall`, `search`, `recent`, `timeline`)\n\n```json\n{\n  \"schema_version\": 2,\n  \"command\": \"recall\",\n  \"generated_at\": \"2026-04-17T12:34:56Z\",\n  \"applied_filters\": { \"hours\": 24, \"app\": \"safari\" },\n  \"truncated\": false,\n  \"next_cursor\": null,\n  \"results\": [ /* rows, see below */ ]\n}\n```\n\n- `schema_version` — integer. Pin to `2` for stability checks.\n- `command` — echoes the subcommand.\n- `generated_at` — RFC3339 timestamp when the response was produced.\n- `applied_filters` — echoes the filters actually applied after argument parsing.\n- `truncated` — `true` when more rows exist beyond `--limit`.\n- `next_cursor` — opaque string to pass back as `--cursor` when `truncated` is `true`. `null` when there are no more rows.\n- `results` — list of flattened snapshot rows.\n\n`recall` adds three extras at the top level:\n\n- `best_candidate` — the top-ranked row (also appears as `results[0]`).\n- `why_selected` — short string explaining why `best_candidate` was picked.\n- `best_match_confidence` — `\"high\" | \"medium\" | \"low\"`.\n- `best_match_score` — float in `[0.0, 1.0]`.\n- `quoted_text` — present only when `--quote` is set and usable text exists.\n\n---\n\n## Flattened snapshot row (in `results[]` and `best_candidate`)\n\nRead these first; walk nested `items[].representations[]` only after `get`.\n\n```json\n{\n  \"snapshot_id\": 42,\n  \"event_id\": 1000,\n  \"sha256\": \"<hex>\",\n  \"kind\": \"text\",\n  \"observed_at\": \"2026-04-17T12:00:00Z\",\n  \"first_seen_at\": \"2026-04-17T11:00:00Z\",\n  \"last_seen_at\":  \"2026-04-17T12:00:00Z\",\n  \"app_name\": \"Terminal\",\n  \"app_bundle_id\": \"com.apple.Terminal\",\n\n  \"best_text\": \"git status\",\n  \"best_text_uti\": \"public.utf8-plain-text\",\n  \"text_fragments\": [{ \"representation\": \"public.utf8-plain-text\", \"text\": \"git status\" }],\n  \"urls\": [],\n  \"file_paths\": [],\n  \"html_text\": null,\n  \"rtf_text\": null,\n  \"ocr_text\": null,\n  \"ocr_status\": null,\n  \"text_summary\": \"git status\",\n  \"preview_text\": \"git status\",\n\n  \"item_count\": 1,\n  \"total_bytes\": 10,\n  \"capture_count\": 3,\n  \"score\": 0.95,\n  \"why_matched\": \"full phrase match\",\n  \"matched_fields\": [\"search_text\"],\n  \"snippet\": \"git status\"\n}\n```\n\nFields to read first for common questions:\n\n| Intent | Read |\n|---|---|\n| \"what was the text\" | `best_text` (fall back to `text_summary`, `preview_text`) |\n| \"what URL\" | `urls` (array) |\n| \"what file / path\" | `file_paths` (array) |\n| \"which app\" | `app_name` / `app_bundle_id` |\n| \"when\" | `observed_at`, `first_seen_at`, `last_seen_at` |\n| \"is this binary / image / pdf\" | `kind`, presence of `best_text`, `total_bytes` |\n| \"why did recall pick this\" | `why_matched`, `matched_fields`, `score` |\n\n`best_text` can come from OCR for image-only snapshots. In"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":2173,"uniquenessScore":40,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T01:35:21.186Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T01:35:21.186Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T06:44:32.148Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}