clipmem

A private clipboard memory for your Mac.

clipmem watches the macOS clipboard, saves every observed state in a local SQLite archive, and lets you search, recall, inspect, restore, and export what you copied later. It works as a terminal tool, a native menu bar app, and an agent-friendly memory layer for OpenClaw, Hermes Agent, and other local automation.

Use it when you want to:

• recover the command, URL, snippet, file path, or message you copied earlier
• ask a coding agent "what did I copy?" without dumping your whole clipboard archive into the prompt
• restore an older clipboard item exactly, including rich clipboard formats
• filter history by time, app, content type, size, URL, image, PDF, or file URL
• make copied screenshots searchable with opt-in Apple Vision OCR, fully on-device

Requirements

• macOS — clipboard capture uses NSPasteboard via objc2
• Apple Silicon for the prebuilt Homebrew package
• Rust 1.88+ for building from source

Install

Choose one path:

CLI only (Apple Silicon):

brew install tristanmanchester/tap/clipmem
clipmem setup

CLI + native menu bar app (Apple Silicon):

brew install --cask tristanmanchester/tap/clipmem-app
open -a ClipmemMenuBar

If Homebrew says tristanmanchester/tap is not trusted, trust only the clipmem install surfaces and rerun the install command:

brew trust --formula tristanmanchester/tap/clipmem
brew trust --cask tristanmanchester/tap/clipmem-app

The cask installs the CLI, runs clipmem setup, and enables launch at login. See docs/installation.md for Cargo, source builds, upgrades, and Intel Mac support.

Start using it

clipmem setup
clipmem service status

Copy something new, then ask for it:

printf "clipmem can find this copied sentence later" | pbcopy
sleep 1
clipmem recall "copied sentence"
clipmem recent --hours 1 --human

Use the snapshot id from recent to inspect or restore a previous clipboard state:

clipmem get 42 --human
clipmem restore 42

See docs/getting-started.md for a full walkthrough.

Everyday commands

For screenshots and image-only clipboard items:

clipmem settings ocr on
clipmem ocr run --limit 25
clipmem recall "text from that screenshot"

Privacy model

• Clipboard data stays on this Mac in ~/Library/Application Support/clipmem/clipmem.sqlite3.
• OCR uses Apple Vision locally; image data is not sent to a hosted service.
• The database directory is created with 0700 permissions and the database file with 0600 permissions.
• The archive is not encrypted by clipmem; use FileVault or equivalent disk encryption for at-rest protection.
• Use clipmem forget, clipmem purge, clipmem settings pause, and ignored app rules to control what is retained.

Documentation

• Installation — all install methods, requirements, and upgrades
• Getting started — setup, background capture, and first queries
• Searching and filtering — recall, search, timeline, OCR text, filters, and pagination
• Output formats — JSON envelope, TOON, exit codes, and script-friendly guarantees
• Managing your archive — restore, delete, export, and capture policy
• Command reference — exhaustive flag-level reference for every command
• Agent integration — OpenClaw, Hermes Agent, and portable skill usage
• Menu bar app — native SwiftUI menu bar frontend
• Privacy and security — local-only guarantees, file permissions, and uninstall
• Architecture — capture model, deduplication, search strategy, and limitations
• Troubleshooting — diagnose empty results, watcher issues, and database problems
• Contributing — project layout, build, test, and release workflow

License

clipmem is released under the MIT License. See LICENSE.