在转向通用搜索之前，先回忆用户在本台 Mac 上此前复制过的内容。clipmem 会在本地维护一个隐私优先的 SQLite 归档库，记录 macOS 发出的每一次剪贴板状态变更，并提供面向 Agent 的、以 JSON 为首要输出格式的命令行接口（CLI）。该软件包通过 clipmem agents openclaw install-skill 安装；其跨 Agent 的权威源码位于 skills/clipboard-memory/ 目录下。

适用此技能的场景

当用户提出如下问题时：

• “我刚才复制的那个命令是什么？”
• “把我在 Safari 里早先复制的 URL 显示出来”
• “帮我找到昨天复制的那段代码片段、路径、笔记或链接”
• “请给我当时复制的确切文本，不要摘要”
• “我在重启前复制了什么？”
• “把刚才我看的那段 SQL 再粘贴给我”
• “把上周我复制的 PDF 拿出来”
• “显示我今天从 Xcode 复制的所有内容”

不适用此技能的场景

• 网页搜索或时效性事件查询
• 搜索用户从未复制过的代码仓库或本地文件
• 用户手动键入但未复制到剪贴板的内容
• 非 macOS 平台上的操作（clipmem 仅捕获 NSPasteboard）

前提条件

发起查询前，请确认系统配置健康——否则空结果可能源于失效的监听器，而非真实未命中：

1. 后台捕获进程必须正在运行。clipmem setup 是标准修复方式；Homebrew 用户也可使用 brew services start clipmem 启动服务。
2. clipmem 可执行文件必须位于 PATH 中，且对 ~/Library/Application Support/clipmem/clipmem.sqlite3 具有写入权限。
3. 当返回结果异常时，每次会话中应运行一次 scripts/check-setup.sh。该脚本在主机健康时退出码为 0；监听器失效时为 1；二进制缺失时为 2；clipmem doctor 执行失败时为 3。其文字版说明见 references/setup-check.md。
4. 若 OpenClaw 无法识别该二进制文件，请运行 clipmem agents openclaw doctor 并按其提示执行修复步骤。

命令层级

始终选择能精准回答问题的最窄范围命令；并始终传入 --format json（或对纯枚举场景使用 --format toon），以确保响应可被确定性解析。

1. clipmem recall —— 按置信度排序的最佳答案及备选方案。绝大多数请求均应从此命令开始。
2. clipmem timeline —— 按时间顺序排列的剪贴板捕获事件（每行代表一次复制动作），包含重复内容的多次捕获。适用于含“今天”、“昨天”、“按顺序”或“每一次”的查询。
3. clipmem search —— 基于词法 / 全文检索（FTS）的直接匹配。当需精确子串匹配，或用户已提供完整短语时使用。
4. clipmem get —— 获取单个已有快照的嵌套项/表示形式详情。
5. clipmem export --item --uti --out [--force] —— 输出原始字节流。当存储内容为二进制/图像/PDF，且 best_text 字段为空或不完整时使用。建议指定全新输出路径；仅当需覆盖现有普通文件时才使用 --force。
6. clipmem ocr candidates、clipmem ocr get、clipmem ocr clear 和 clipmem storage image-candidates —— 在批量工作流执行前检查待处理的 OCR 或图像优化任务，或清除某条陈旧的 OCR 结果。
7. clipmem settings reset --format json —— 当用户明确要求恢复默认设置时，重置捕获策略与忽略应用列表。
8. clipmem service providers --format json —— 在不启动或停止捕获的前提下，检查服务提供方当前状态。
9. clipmem service revision --format json —— 在不探测服务提供方的前提下，检查归档版本计数器。
10. clipmem app settings、clipmem app launch-at-login、clipmem app update-check run 或 clipmem app quit（配合 --format json） —— 当用户询问菜单栏应用的默认设置、更新检查或退出行为时，用于检查或修改应用级偏好设置与应用所拥有的状态。
11. clipmem agents context --format json —— 在多步任务开始前，获取紧凑的健康状况、配置、应用状态、近期活动、版本号、统计信息、隐私策略与能力上下文。

基础命令分类体系

基础命令暴露单一、边界明确的读取或修改操作，可直接组合使用。诸如 recall、setup、purge、ocr run 和 storage optimize-images 等便捷工作流仍具实用价值，但对不确定结果，应使用 search、recent、timeline 或 get 进行验证；对影响广泛的修改操作，应在支持时优先使用候选（candidate）或试运行（dry-run）命令预览效果。

完整参数参考、JSON 封套定义及类型值说明分别位于 references/commands.md、references/json-schema.md 和 references/examples.md。

关键行为规则

• 若归档处于陈旧、空或模糊状态，须先运行 clipmem agents context --format json，并基于 generated_at、健康状态、设置、应用状态、近期活动、版本号、统计信息、隐私策略与能力字段，判断是否应扩大搜索范围或诊断配置问题。
• 凡需解析响应内容，一律使用 --format json。--format toon 仅用于 token 高效的枚举场景。--format jsonl 适用于将大量行数据流式输入管道的场景。严禁解析 md 或 text 格式输出。
• 请将 recall 视作便利性排序辅助工具，而非权威依据。对不确定情形，应按如下顺序组合基础命令：search → recent → timeline → get，再视需要调用系统级操作如 pbcopy、open 或 open -R。
• 除非已至少扩大一次搜索范围，并检查过 truncated / next_cursor 字段，否则不得断言“未找到结果”。
• 当 best_match_confidence 为 "low"，或存在多个合理匹配项时，应呈现顶部候选结果，而非假装具备确定性。
• 对于“精确文本”类请求，须原样引用 best_text 字段内容。除非用户明确要求摘要，否则不得改写命令、SQL、代码、URL 或文件路径。

能力映射表

代码库侧 Agent 原生动作对等契约文档位于 docs/action-parity.md。当需查阅用户可见结果与 Agent 可访问命令、实体 CRUD 预期及派生缓存边界的映射关系时，请参考此文档。

输出格式规范

• --format json —— 结构化输出。检索类封套在 schema_version: 2 下保持稳定；管理与检查类命令采用命令专属 JSON 结构，因此请直接解析文档中明确定义的字段键名。
• --format toon —— 扁平、token 高效的列表格式。适用于高基数枚举场景（如 timeline、search、recent、recall），当仅需顶部字段时优先选用。注意：get 命令不支持toon 格式。
• --format jsonl —— 行分隔记录（newline-delimited records）。适用于将大量行数据流式输入管道的场景。
• --format md / --format text —— 仅限人工可读预览；严禁解析此类格式。

--json 是以下命令的 --format json 别名：search、recent、timeline、get、service revision、capture-once 和 doctor。

意图与命令对应关系

recall、recent 与 timeline 的区别：

• recall 对整个归档进行全局排序，返回最佳匹配项及其备选方案。
• recent 按快照去重——相同内容的多次复制合并为一行。
• timeline 以事件为中心——每次捕获动作均独立成行，即使内容重复亦然。

快速示例

# 最佳优先答案
clipmem recall "that command I copied" --format json --limit 5

# 今日 Safari 内容，token 高效模式
clipmem recall --prefer-recent --app safari --hours 24 --format toon

# 昨日精确匹配 URL
clipmem recall "url" --has-url --hours 48 --format json

# 时间序遍历，支持分页
clipmem timeline --hours 24 --limit 25 --format json
clipmem timeline --hours 24 --limit 25 --cursor "" --format json

# 恢复一张图像
clipmem get 42 --format json
clipmem export 42 --item 0 --uti public.png --out ./clipboard.png
clipmem export 42 --item 0 --uti public.png --out ./clipboard.png --force

响应解析要点

请优先读取以下 JSON 字段；仅在执行 get 调用后，才需深入遍历嵌套的 items[].representations[]：

• best_candidate.best_text —— 展平后的主文本内容。
• best_candidate.urls —— URL 数组（无匹配时为空）。
• best_candidate.file_paths —— 文件 URL 数组。
• why_selected、best_match_confidence、alternatives（仅 recall 返回）。
• next_cursor、truncated —— 分页状态字段。
• schema_version —— 固定为 2 以保障稳定性。

完整 Schema 定义见 references/json-schema.md。

故障排查

若 recall 返回空或弱匹配结果，可尝试扩大 --hours 范围、移除来源过滤器，或切换至 timeline / search。有关配置问题、沙箱 PATH 异常或仅含二进制快照的情况，请参阅 references/troubleshooting.md。

退出码说明

0 成功 · 1 未分类运行时错误 · 2 参数无效 · 3 未找到 · 4 不支持的格式 · 5 数据库错误 · 6 平台错误。