yt-mem

yt — the yt-mem-ai entry point

Single entry point for driving the yt-mem-ai YouTube pipeline CLI. Every data operation goes through the CLI — never touch the LanceDB store directly.

Prereqs

• Always invoke the CLI as uvx yt-mem-ai — zero-install, cached, always latest. Nothing is installed on PATH: the native plugins ship skills only, so do NOT go hunting for a yt-ai binary, a wrapper script, or a venv. (Only inside a source checkout of this repo may you use uv run yt-ai .)
• Always single-quote a video/channel URL — YouTube URLs contain ? and &, which the shell treats as glob and job-control metacharacters, so a bare URL fails (zsh: no matches found). Write uvx yt-mem-ai fetch 'https://www.youtube.com/watch?v=ID', never bare. Same for transcript and channel-list.
• Settings live in a global config file, not a .env you hand-edit: inspect and change anything with uvx yt-mem-ai config list / uvx yt-mem-ai config set KEY VALUE (see Configure & maintain). Prefer config set over exporting env vars — each uvx run is a fresh process, so an env var only applies to the one command you prefixed it to.
• Video lifecycle status: discovered → transcribed → summarized (live streams get a terminal stream and skip transcription).

uvx yt-mem-ai  [args]

Decide what the user wants, then run

Ingest one video

uvx yt-mem-ai fetch ''        # download audio + transcribe + embed + store
uvx yt-mem-ai transcript ''   # same pipeline (alias intent)

Discover + batch ingest (subscriptions)

uvx yt-mem-ai discover [--after ] [--deep] [--min-duration ] [--json]
uvx yt-mem-ai fetch-pending [--since ] [--limit ]   # ingest 'discovered' videos

Enumerate a channel (does not ingest)

uvx yt-mem-ai channel-list '' [--limit ] [--from ] [--to ] [--json]
# newest uploads for a channel URL/@handle; feed the URLs to `fetch` to ingest a group.

Read / query the library

uvx yt-mem-ai list [--status ] [--since ] [--json]
uvx yt-mem-ai show  [--json]     # metadata + full transcript
uvx yt-mem-ai status                        # counts by status
uvx yt-mem-ai search "" [--hybrid|--fts|--vector] [-k ]

Summaries (skills generate the analysis; CLI persists it)

uvx yt-mem-ai save-summary  "" \
  --highlights '' --qa ''

Do not write summaries free-hand here. For the model-generated analysis (summary + timestamped highlights + Q&A + presentation, a subscription digest, or a cross-video review), hand off to [[yt-agent]].

[[yt-agent]] produces the analysis with this agent (Claude Code) reading the stored transcript — no API key, no OpenRouter, no external LLM call. (The desktop app has a separate OpenRouter-based summarize path; it is not used here.)

Taste / recommendations

uvx yt-mem-ai like       # feedback table (latest signal per video wins)
uvx yt-mem-ai dislike 
uvx yt-mem-ai recommend [--limit ] [--json]   # rank unrated fetched videos by taste

Configure & maintain

uvx yt-mem-ai config list                     # every setting, value, and source
uvx yt-mem-ai config set KEY VALUE            # e.g. WEBSHARE_PROXY_USERNAME, YT_EMBEDDING_MODEL
uvx yt-mem-ai config get KEY [--reveal]       # secrets masked unless --reveal
uvx yt-mem-ai config unset KEY                # remove from the config file

Use this to reconfigure the engine on request — set Webshare proxy creds, switch the embedding model/backend, point at a cookies browser, change caption languages — without hand-editing .env. set writes the global config (~/.yt-mem-ai/config.env) by default; add --project for ./.env. Only known .env keys are accepted. After changing the embedding model/backend, migrate the existing library:

uvx yt-mem-ai reembed                          # re-embed all chunks with the current YT_EMBEDDING_* config

Compile / video output

uvx yt-mem-ai compile [--since ] [--max-minutes ] [--out ] [--json]
# Deep-linked highlights doc from summarized videos. Fast, no download. Prints the
# markdown to stdout by default; pass --out compilations/.md to save a file.

uvx yt-mem-ai supercut [--since ] [--max-minutes ] [--out ] [--keep-clips]
# → actual video reel supercuts/.mp4 + .refs.md sidecar.
# Slow: re-downloads each clip (720p) + ffmpeg concat. Needs network + local ffmpeg.

uvx yt-mem-ai frame  --at  [--out ]
# Grab one still frame from an ingested video (needs yt-dlp + ffmpeg).
# → frames/_s.png by default.

The REST API / serve command moved to the yt-mem-ai-desktop repo (yt-ai-desktop-serve); it is not part of this engine CLI.

When YouTube blocks a fetch

Two different blocks with two different fixes — read the message, don't guess.

Set these with config set, not KEY=value uvx …: the config file persists across runs, an env var only covers the single command you prefixed. On macOS the first Chrome-cookie read may raise a Keychain prompt — if a command hangs, tell the user to approve it.

Pipelines

Daily routine (subscriptions → digest → clickable highlights):

uvx yt-mem-ai discover          # new uploads → 'discovered'
uvx yt-mem-ai fetch-pending     # download+transcribe+embed today's batch (skips failures)

then invoke [[yt-agent]] (process subscriptions → per-video summaries + digests/.md), then:

uvx yt-mem-ai compile           # deep-linked highlights doc for the day
# optionally: uvx yt-mem-ai supercut   # shareable video reel

Single video on demand:

uvx yt-mem-ai fetch ''

then invoke [[yt-agent]] (single-video summary / highlights / Q&A / presentation).

Conventions

• Skills-primary summarization: the CLI stores data; skills read via show --json / search and write via save-summary. Never invent highlight timestamps — anchor them with uvx yt-mem-ai search "" --vector -k 3.
• Dates are YYYY-MM-DD strings; string comparison is date comparison.
• is_seen is status-based (transcribed/summarized), so ingest is retry-safe; re-running fetch/fetch-pending is safe.
• Always report what ran + the resulting file paths (digests/compilations/supercuts) in chat.

Notes

• If show prints not found, the video isn't ingested — run fetch '' first.
• If fetch-pending/list finds nothing for a day, run discover first.
• supercut continues past a clip whose download/render fails (logged in the .refs.md sidecar's skipped list) rather than aborting.
• Related: [[yt-agent]] (analysis scenarios: single video, subscription digest, cross-video review).