What it does

Push peepshow runs into a Zep session so downstream agents can recall what was in the clip without re-processing it. Each frame becomes a user message with ordinal, approximate timestamp, path, and byte size; the summary lands as a system message.

When to reach for it

Give a Zep-backed agent durable memory of every video it has ever watched
Rotate sessions per clip while keeping a single `ZEP_USER_ID` for cross-clip recall
Self-hosted Zep: point `ZEP_API_URL` at your instance for offline memory pipelines

Install

npm i -g peepshow

Use it

ZEP_API_KEY=... \
ZEP_SESSION_ID=clip-2026-04 \
peepshow ./cctv-night.mp4 --sink zep

Make it automatic

peepshow sinks add zep
peepshow sinks add zep --when extension=mp4,mov
peepshow sinks add zep --when path=/Volumes/Work/

Configuration

ZEP_API_KEY Zep cloud / self-hosted API key, sent as `Authorization: Api-Key …`. required
ZEP_SESSION_ID Session id to append messages to. required
ZEP_API_URL Override for self-hosted Zep. Default `https://api.getzep.com`.
ZEP_USER_ID Optional user id to associate with the session metadata.

Use with an LLM agent

Every peepshow sink reads its config from env vars and receives a single JSON payload on stdin. An LLM agent (Claude Code, Cursor, Windsurf, Gemini, Codex) can drive the Zep sink automatically when three things are true:

the env vars below are exported in the agent's shell (or a project .env it can load),
the peepshow CLI is on PATH — install with npm i -g peepshow,
a peepshow auto-sink is registered for the run (optional but recommended — makes invocation zero-argument).

1. Set the environment

# Add to ~/.zshrc, ~/.bashrc, or a project .env the agent can load
export ZEP_API_KEY="..."
export ZEP_SESSION_ID="..."

2. Register as an auto-sink

peepshow sinks add zep
peepshow sinks add zep --when extension=mp4,mov

3. Example LLM session

You → drop a .mov into Claude Code.
Claude → auto-invokes /peepshow:slides ./clip.mov. peepshow extracts frames + audio, the Zep sink forwards the run to the configured collection. Claude replies with a summary and a link to the created record.

The transcript text is a natural embedding target — index it next to the frames.

Write your own

A sink is any executable that reads the --emit json payload on stdin. Shell, Node, Python, Go — the spec's in docs/PLUGINS.md. Register persistent ones with peepshow sinks add-cmd 'your-command'.

Zep — Append every run to a Zep long-term-memory session.