hermes-screenpipe
Ambient retro-recall for Hermes, from your local
Screenpipe corpus (OCR screen text + audio transcripts).
A skill can call an API — this plugin does what skills cannot: inject relevant captured context
before the model sees each turn, expose durable first-class tools, and keep a durable SQLite
cache (via plugin_db()) that survives plugin updates.
Demo flow: you're on a call, show a terminal error, close it. Later: "what was that
connection error?" — the agent answers with the exact text and timestamp, without you pasting
anything.
What it does
| Surface | What you get |
|---|---|
| pre_llm_call hook (fail-silent, ≤1.5 s network budget) | Relevant [HH:MM app] excerpt snippets injected into the current turn — only when the message is recall-ish enough, Screenpipe has a real match, and the per-session cooldown allows it. Injected text is prefixed Captured screen/audio context (untrusted, may be irrelevant): so the model treats it as data, never instructions. |
| screenpipe_search tool | Explicit search over the last N hours: {results: [{timestamp, app_name, text}]}. |
| screenpipe_around tool | Activity summary + nearest captures around a timestamp. |
| screenpipe_status tool | Liveness, current capture status, session injection counts, effective config. |
| /recall <query> slash command | The search path, formatted for humans, with screenpipe://frame/<id> deep links when available. |
Everything degrades silently: Screenpipe down/hanging → the hook returns None in under 2 s and
tools return {"error": ...} — a user's turn is never blocked.
Install
hermes plugins install vdimarco/hermes-screenpipe
hermes plugins enable screenpipe
Screenpipe setup: install the Screenpipe app and let it capture; the
plugin talks to its local REST API at http://localhost:3030. An API key is optional — set
SCREENPIPE_API_KEY (you'll be prompted at install) only if your Screenpipe requires auth; the
plugin never reads any credential store itself, it goes through Hermes' secret scope.
Configuration (Desktop → Settings → Plugins, or config.yaml)
| key | default | meaning |
|---|---|---|
| api_url | http://localhost:3030 | Screenpipe REST base URL (SCREENPIPE_API_URL env overrides) |
| injection_char_budget | 600 | Max chars of captured context injected per turn |
| history_hours | 24 | Default lookback window (72 h auto for "earlier/yesterday/last time"-style asks) |
| cooldown_seconds | 120 | Minimum seconds between injections per session |
| min_query_words | 4 | Messages shorter than this never trigger injection |
| enabled | true | Killswitch for injection (tools always stay available) |
Development
python -m pytest -q
hermes plugins doctor /path/to/hermes-screenpipe
hermes plugins validate /path/to/hermes-screenpipe --install-deps
Design spec + implementation plan: docs/superpowers/.
Roadmap (post-hackathon)
Desktop timeline pane, /export clip tool, memory-provider slot, cross-device sync queries.
README from the reviewed commit 1df1a38; it updates when the author re-pins.

vdimarco