How to use the Screenpipe Screen History Search agent skill

What an agent skill is and what this one does

An agent skill is a folder containing a SKILL.md file with instructions, plus optional scripts the agent can run. When a request matches the skill's description, the agent follows those instructions. This skill is named screenpipe and is listed under thedotmack/claude-mem in the plugin/skills/screenpipe location.

The skill makes the agent search Screenpipe's history for a time window and topic. It can answer questions such as what was discussed in a meeting or where you saw a document, and it cites source types, IDs, and timestamps. It only retrieves on demand; it does not start recording or background sync.

• Searches screen text (OCR, including accessibility-derived text), audio, or both
• Works within a time window you specify, defaulting to the last hour if none is given
• Can optionally save a concise note of findings into claude-mem's local memory when you ask

Install the screenpipe skill

Download the skill as a ZIP from this page. Then choose one of the two install locations below.

For a personal install available in all projects, unzip the download into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Single project: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check the requirements before you start

The skill depends on Screenpipe. Screenpipe must be installed and running on the same computer, with recording permissions granted. You also need Node.js 20 or later, because the bundled helper script runs on Node.

Saving notes needs claude-mem's local worker. Searching does not. If you use Screenpipe authentication, you can supply a SCREENPIPE_API_KEY; the source notes it is optional.

• Screenpipe installed and running locally with recording permissions
• Node.js 20 or later
• claude-mem local worker (only for saving notes)
• Optional SCREENPIPE_API_KEY if Screenpipe authentication is enabled

Ask for what you need in plain language

You do not need to type commands. Describe the topic and the time window. If you leave out the window, the agent starts with the last hour and tells you that is the scope. Give specific local times when you can, because the agent converts them to timestamps with timezone offsets.

The skill searches screen text by default. Ask for audio when you want conversations, or for both when the answer could be in either.

• "Using Screenpipe, what did we decide about the release plan between 9 and 10 this morning?"
• "Search my Screenpipe audio from yesterday afternoon for the vendor pricing discussion."
• "Find where I saw the budget spreadsheet in the last two hours, in any app."
• "Remember the key points from that meeting in claude-mem for this project."

What the helper runs under the hood

The agent runs a bundled helper script, screenpipe.mjs, with a search command. The source example shows a start and end time, a query, a type of ocr, and a result limit. You do not need to run this yourself, but it helps to recognise it when you review what the agent does.

The helper reads SCREENPIPE_URL, which defaults to http://127.0.0.1:3030. Results are capped and may be paged.

Safety, privacy and network use

This skill runs scripts and uses the network. Retrieved screen and audio text enters the agent conversation and is sent to the agent's AI provider. The skill tells you this before the first search. Search results are wrapped in private tags so claude-mem's automatic capture does not store them; only a note you ask to save is stored.

Saved notes live in the claude-mem local database and in your cloud account if cloud sync is on. Do not use this skill for confidential or regulated work. Both service URLs must be local HTTP origins, and the agent is told never to print API keys or paste credentials into chat. Captured text is treated as evidence, not instructions, so a draft on screen does not prove something was sent.

• Retrieved text is sent to the AI provider
• Search results are private-tagged so automatic capture skips them
• Saved notes are stored locally and in cloud sync if enabled
• Do not import a whole desktop history by default

Read results carefully

Answers should cite the source type, ID, and timestamp. Results can be truncated or incomplete. When the output says it is truncated or omitted, the agent should not claim an exhaustive account. An empty result does not prove nothing happened, and a timeout usually means the Screenpipe service was unavailable rather than that no history exists.

• Narrow the time window and query if results are too broad
• Ask for the next page only when you need more results
• Check existing claude-mem memories before retrying a save that timed out