yt-mem-ai — una memoria local de YouTube para tu asistente de IA

Dale a Claude, Codex, Cursor o cualquier host MCP la capacidad de ver YouTube por ti: transcribir vídeos, recordarlos, seguir tus suscripciones y convertirlo todo en resúmenes, momentos destacados con marca de tiempo, preguntas y respuestas, resúmenes diarios y vídeos recopilatorios. Todo se ejecuta en tu máquina: sin servicio en la nube, sin clave de API.

Ejemplo — "haz una presentación a partir de este vídeo" (Andrej Karpathy: From Vibe Coding to Agentic Engineering, Sequoia, 30 min) → 13 diapositivas, PDF, cada cita con su marca de tiempo extraída de la transcripción. De la ingesta a la presentación en una sola petición.

Tabla de contenidos

• Características

• Cómo instalar

• Primeros pasos

• Uso

• Ejemplos

• Configuración

• Por dentro

Related MCP server: YouTube MCP Server

Características

• 🎧 Transcribe cualquier vídeo — subtítulos de YouTube cuando existen (rápido, en cualquier idioma), Whisper sin conexión cuando no los hay.

• 🧠 Recuerda lo que has visto — cada transcripción se almacena e indexa localmente, para que tu biblioteca siga siendo buscable para siempre. Nada sale de tu máquina.

• 🔎 Encuentra el momento — pregunta "¿qué decía ese vídeo sobre X" y obtén la respuesta con una marca de tiempo a la que puedes saltar.

• 📡 Sigue tus suscripciones — detecta nuevos vídeos y convierte el día en un único resumen.

• ✍️ Tu asistente hace la escritura — resúmenes, momentos destacados, preguntas y respuestas, presentaciones de diapositivas, todo en el idioma del propio vídeo, usando el modelo que ya pagas.

• ❤️ Aprende tus gustos — dale "me gusta" o "no me gusta" a los vídeos y recibe recomendaciones de tu propia biblioteca.

• 🎬 También crea contenido multimedia — documentos de momentos destacados en los que se puede hacer clic, fotogramas fijos y vídeos recopilatorios renderizados.

• 🔌 Funciona con tus herramientas — Claude Code, Claude Desktop, Codex, Cursor, Antigravity, OpenClaw, Hermes: habilidades o MCP, tú eliges.

Cómo instalar

1. Conecta tu asistente ⭐

curl -LsSf https://raw.githubusercontent.com/dasein108/yt-mem-ai/main/install.sh | sh

Se abre un asistente interactivo. Elige lo que quieras, marca tus aplicaciones, pulsa intro:

step 1/2 — what (pick one)     step 2/2 — where (tick any)
> Plugin  skills + CLI         [x] Claude Code    [ ] Claude Desktop
  MCP     typed tools          [x] Codex          [ ] Cursor
                               [ ] Antigravity    [ ] OpenClaw   [ ] Hermes

Plugin enseña a tu asistente a actuar ante peticiones sencillas — "resume este vídeo". MCP le da un conjunto de herramientas en su lugar. ¿No lo tienes claro? Empieza con Plugin; puedes volver a ejecutar el asistente para la otra opción.

Instala todo lo que necesita, marca lo que ya tienes y elimina lo que desmarques (muestra un plan y pregunta primero). Luego reinicia la aplicación y prueba: resume 'https://youtu.be/…'.

¿Ya sabes lo que quieres? Sáltate las preguntas:

curl -LsSf https://raw.githubusercontent.com/dasein108/yt-mem-ai/main/install.sh \
  | sh -s -- --plugin --claude-code --codex
curl -LsSf https://raw.githubusercontent.com/dasein108/yt-mem-ai/main/install.sh \
  | sh -s -- --mcp --claude-desktop --cursor

Hosts: --claude-code --claude-desktop --codex --cursor --antigravity --openclaw --hermes, o --all. Lista completa de opciones y notas de desinstalación: integrations/README.md. ¿Prefieres que lo haga un agente? Pega integrations/PROMPT.md en cualquier asistente.

2. MCP a mano — una entrada de configuración, autoinstalable

No se necesita instalación previa: uvx descarga el paquete la primera vez que el host inicia el servidor y lo mantiene en caché después. Añade esto a la configuración MCP de tu host:

{
  "mcpServers": {
    "yt-mem-ai": {
      "command": "uvx",
      "args": ["--from", "yt-mem-ai[mcp]", "yt-ai-mcp"]
    }
  }
}

Eso es toda la configuración: sin rutas, sin bloque env. Los ajustes viven en ~/.yt-mem-ai/config.env y el agente puede escribirlos él mismo con la herramienta config_set (o tú con yt-ai config set).

# ~/.codex/config.toml
[mcp_servers.yt-mem-ai]
command = "uvx"
args = ["--from", "yt-mem-ai[mcp]", "yt-ai-mcp"]

# ~/.hermes/config.yaml
mcp_servers:
  yt-mem-ai:
    command: "uvx"
    args: ["--from", "yt-mem-ai[mcp]", "yt-ai-mcp"]
    enabled: true

Reinicia la aplicación y las herramientas aparecerán — consulta Uso para saber qué hacen.

¿No ha aparecido nada, o el host agotó el tiempo? El primer arranque descarga dependencias y puede superar el tiempo de comprobación de inicio del host. Ejecuta uvx --from 'yt-mem-ai[mcp]' yt-ai-mcp --help una vez y vuelve a abrir la aplicación. Si el host aún no puede iniciarlo, dale rutas absolutas: uv tool install 'yt-mem-ai[mcp]' y usa which yt-ai-mcp como command con "args": [] (las aplicaciones GUI a menudo no ven ~/.local/bin en su PATH).

3. Claude Desktop — habilidades (en la aplicación)

Desktop guarda los plugins en tu cuenta de Claude, no en el disco, así que nada puede instalarlos por ti. Lleva un minuto en la aplicación:

Personalizar (barra lateral izquierda) → Plugins → Plugins personales → + → Añadir marketplace → Añadir desde un repositorio → https://github.com/dasein108/yt-mem-ai → Añadir → Instalar yt-mem-ai

Luego pregunta: resume 'https://youtu.be/…'. Desinstala de la misma manera. El mismo plugin también funciona en claude.ai y Cowork. ¿Prefieres herramientas a habilidades? La configuración MCP de arriba también funciona para Desktop — y esa sí se puede automatizar.

Cada host carga archivos SKILL.md desde un directorio de ámbito de usuario: Codex ~/.codex/skills/ (CLI e IDE lo comparten, v0.117.0+), Cursor ~/.cursor/skills/, Antigravity ~/.gemini/skills/, OpenClaw ~/.agents/skills/, Hermes ~/.hermes/skills/ (donde se convierten en /yt y /yt-agent).

# from a checkout
cp -R skills/yt skills/yt-agent ~/.codex/skills/

# without a checkout
for s in yt yt-agent; do
  mkdir -p ~/.codex/skills/$s
  curl -LsSf "https://raw.githubusercontent.com/dasein108/yt-mem-ai/main/skills/$s/SKILL.md" \
    -o ~/.codex/skills/$s/SKILL.md
done

Extras de Codex: los prompts /yt-* (integrations/codex/prompts/*.md → ~/.codex/prompts/) y integrations/codex/AGENTS.md → ~/.codex/AGENTS.md. Guía completa: skills/README.md.

4. La CLI por sí sola

Las habilidades la manejan, pero es una herramienta independiente perfectamente válida:

uvx yt-mem-ai --help          # zero-install run
uv tool install yt-mem-ai     # or install the persistent `yt-ai` command

Necesita Python 3.11+ y uv; ffmpeg solo para supercut / frame.

La interfaz de escritorio vive en un repositorio aparte: yt-mem-ai-desktop — depende de este paquete y ejecuta su propia API REST local.

Primeros pasos

¿Instalado y host reiniciado? Estás listo. Solo habla con tu asistente — las habilidades (o los prompts MCP + analyze_video) hacen la ingesta por ti:

"Resume https://youtu.be/dQw4w9WgXcQ" → ingiere el vídeo (subtítulos → whisper), luego escribe un resumen ejecutivo más puntos clave, en el idioma del propio vídeo.

"Dame los momentos destacados de ese vídeo con marcas de tiempo" → 3–8 momentos con enlace profundo (watch?v=…&t=123s) anclados por búsqueda semántica.

"¿Qué vi sobre generación aumentada por recuperación?" → busca en todas las transcripciones de tu biblioteca y cita los momentos.

"Procesa mis suscripciones en el resumen de hoy" → descubre nuevos vídeos, los ingiere, escribe digests/<DATE>.md.

¿Prefieres la terminal? La misma primera ejecución:

yt-ai fetch 'https://www.youtube.com/watch?v=VIDEO_ID'   # ingest one video
yt-ai search "what was said about embeddings"            # search your library
yt-ai status                                             # what's in the store

Todo termina en ~/.yt-mem-ai/ (biblioteca, registros, descargas).

La primera ejecución es lenta — es lo esperado. La instalación trae el stack de ML (torch, LanceDB, sentence-transformers ≈ 1 GB en disco), y tu primer fetch o search descarga el modelo de incrustación además de eso. Si un vídeo no tiene subtítulos, el modelo Whisper (small, ≈ 460 MB) también se descarga — la ruta de subtítulos nunca lo necesita. Todo queda en caché, así que ocurre una vez, no por vídeo. En un host con GUI, el primer arranque de MCP puede superar el tiempo de comprobación de inicio de la aplicación por la misma razón: ejecuta uvx --from 'yt-mem-ai[mcp]' yt-ai-mcp --help una vez en una terminal para calentar la caché, y luego vuelve a abrir la aplicación.

Rutina diaria

yt-ai discover               # what's new in your subscriptions
yt-ai fetch-pending          # transcribe today's batch

luego en tu asistente: "procesar suscripciones" → resúmenes por vídeo y digests/<DATE>.md, y opcionalmente yt-ai compile --out compilations/$(date +%F).md para los momentos destacados del día como enlaces en los que se puede hacer clic.

Uso

Hablando con tu asistente (habilidades y prompts)

Dos habilidades vienen con el plugin. Los hosts MCP reciben los mismos guiones como prompts (yt_summarize, yt_highlights, yt_qa, yt_presentation, yt_digest, yt_review, yt_group), así que no se pierde nada sin soporte de habilidades.

Las habilidades nunca tocan la base de datos directamente — llaman a la CLI, así que el mismo flujo de trabajo funciona en cualquier host. Instálalas o pégalas a mano: skills/README.md.

Herramientas MCP

El servidor yt-ai-mcp expone todo el motor como herramientas tipadas. analyze_video es el punto de entrada de un solo paso: ingiere y devuelve la transcripción para que el modelo pueda escribir el resumen él mismo.

Detalles del servidor, lista de prompts y configuración sin procesar: integrations/mcp/README.md.

Comandos CLI

yt-ai fetch <url>            # download + transcribe + embed + store one video
yt-ai fetch <url> --captions-only  # captions only: no audio download / no whisper (fails if none)
yt-ai transcript <url>       # same pipeline
yt-ai discover               # new subscription uploads (--after/--deep/--min-duration/--json); incremental by default
yt-ai fetch-pending          # batch-fetch pending 'discovered' videos (since --since, default today; --limit)
yt-ai list                   # list stored videos (--status/--since/--json)
yt-ai show <video_id>        # metadata + transcript (--json)
yt-ai status                 # counts by status
yt-ai search "<query>"       # semantic search (--hybrid/--fts/--vector, -k N)
yt-ai save-summary <id> "<summary>" --highlights '<json>' --qa '<json>'  # persist a summary (used by skills)
yt-ai like <video_id>        # mark liked (feeds recommendations)
yt-ai dislike <video_id>     # mark disliked
yt-ai recommend              # rank your unrated fetched videos by taste (--limit/--json)
yt-ai compile                # deep-linked highlights doc, budget-bounded (--since/--max-minutes/--json/--out)
yt-ai supercut               # video reel of highlights, re-downloaded + labeled (--since/--max-minutes/--out/--keep-clips)
yt-ai frame <video_id> --at <ts>  # still frame at a timestamp (seconds or H:M:S) → frames/<id>_<s>s.png
yt-ai reembed                # re-embed all chunks with the current YT_EMBEDDING_* config
yt-ai channel-list <url>     # list a channel's recent uploads (--limit/--from/--to/--json); enumerate only
yt-ai config list            # get/set any .env setting: config get/set/unset/path (reconfigure from CLI or chat)

Ejemplos

Caso: un libro de texto PDF completo a partir de un curso de YouTube de 10 partes. examples/defi-crypto-options.pdf — un libro educativo ruso de 96 páginas construido a partir de la serie «DeFi. Бесплатный вводный курс по крипто-опционам» (@Menaskop).

Proceso: identificar los 10 vídeos de la serie → extraer los subtítulos ru-orig (yt-dlp + cookies del navegador; no se necesita Whisper) → resúmenes estructurados por vídeo → un esquema compartido (glosario, notación, catálogo de figuras) → 10 capítulos reescritos (~28.5k palabras)

• 47 figuras vectoriales redibujadas → ensambladas y renderizadas con Typst. No es un resumen: capítulos desde primeros principios con ejemplos resueltos, diagramas, glosario y enlaces profundos por capítulo de vuelta a cada vídeo.

Configuración

No se necesita nada para empezar: los valores predeterminados colocan el almacén, los registros y las descargas en ~/.yt-mem-ai/ y usan un modelo de incrustación local. Ajústalo cuando lo necesites:

Configura desde la CLI o un agente — en lugar de editar .env a mano, usa yt-ai config (o las herramientas MCP config_*, para que un agente pueda reconfigurarse desde el chat):

yt-ai config list                  # every setting, value, and source
yt-ai config set WEBSHARE_PROXY_USERNAME <user>
yt-ai config set WEBSHARE_PROXY_PASSWORD <pass>
yt-ai config set YT_EMBEDDING_MODEL paraphrase-multilingual-MiniLM-L12-v2
yt-ai config get OPENAI_API_KEY    # secrets masked (--reveal to show)

set escribe el archivo de configuración global (~/.yt-mem-ai/config.env) por defecto para que el servidor MCP lo recoja independientemente de su directorio de trabajo; --project escribe ./.env. Precedencia: env del proceso > .env del proyecto > archivo de configuración global, y config list muestra de dónde proviene cada valor.

Entresijos

Todo lo siguiente es lectura opcional: detalles internos, ajustes y notas para desarrolladores.

Cómo funciona

yt-dlp → captions (or Whisper) → chunks → embeddings → LanceDB
                                                          ↓
                     your assistant reads + writes summaries back

La CLI realiza la E/S pesada y es propietaria del almacén; las skills y las herramientas MCP son llamadores ligeros. Un vídeo avanza por discovered → downloaded → transcribed → summarized; las transmisiones en vivo reciben un estado terminal stream y se omiten en la ingesta por lotes (transcribe una bajo demanda con yt-ai fetch <url>). El almacenamiento es un LanceDB incrustado (videos, channels, transcripts, chunks, summaries, feedback), con vectores por fragmento más un índice de texto completo — eso es lo que hace híbrida la búsqueda.

Detalles de los comandos

Puntuar y recomendar — marca como "me gusta"/"no me gusta" los vídeos que hayas obtenido, y luego yt-ai recommend clasifica el resto por similitud con lo que te gustó (menos lo que te disgustó), usando sus incrustaciones de transcripción. Antes de que te guste algo, recurre a los publicados más recientemente.

discover es incremental — extrae las entradas más recientes del feed en una sola llamada plana (limitada por YT_DISCOVER_FEED_LIMIT), sella cada una con una marca de tiempo aproximada y conserva solo las más recientes que la marca de agua alta de la última ejecución menos una superposición de 1 h (YT_DISCOVER_OVERLAP_S), de modo que las fechas redondeadas a la hora nunca pierdan un vídeo límite. Los vídeos ya procesados se filtran. --after YYYY-MM-DD anula el límite.

compile vs supercut — compile renderiza los destacados del día como enlaces profundos en markdown (watch?v=ID&t=<start>s), primero los vídeos más recientes y limitado por --max-minutes (predeterminado 20); es instantáneo e imprime en stdout a menos que pases --out. supercut vuelve a descargar la sección de cada destacado a 720p, quema una etiqueta en ella y concatena todo en supercuts/<date>.mp4 más un archivo lateral .refs.md que enumera las fuentes (y cualquier clip omitido tras un fallo) — mucho más lento, necesita red + ffmpeg, pero se puede compartir.

Incrustaciones, proxy y otros ajustes

Incrustaciones: YT_EMBEDDING_BACKEND=local|openai. Local usa sentence-transformers (YT_EMBEDDING_MODEL, predeterminado all-MiniLM-L6-v2) — para bibliotecas no inglesas establece paraphrase-multilingual-MiniLM-L12-v2 (384-d, más de 50 idiomas) para que la búsqueda semántica funcione entre idiomas. openai usa text-embedding-3-small|large (necesita OPENAI_API_KEY). Después de cambiar el modelo, ejecuta yt-ai reembed para migrar la biblioteca existente (re-incrusta todos los fragmentos; sin volver a obtener).

Proxy / VLESS: YT_USE_WEBSHARE está desactivado por defecto. Si ya ejecutas un proxy/VPN a nivel de sistema (VLESS/Xray, etc.), déjalo desactivado: el tráfico viaja por ese túnel. Apilar el proxy Webshare encima rompe el feed de suscripciones autenticado (su túnel CONNECT devuelve 405). Solo establece YT_USE_WEBSHARE=true si no tienes otro proxy y YouTube limita la tasa de tu IP sin procesar. Ajustes de discover: YT_DISCOVER_FEED_LIMIT (límite de los N más recientes, predeterminado 60), YT_DISCOVER_OVERLAP_S (superposición incremental, predeterminado 3600), YT_DISCOVER_TIMEOUT_S.

¿Trabajando desde un checkout? uv sync --extra dev, y luego cp .env.example .env si prefieres mantener los ajustes locales al proyecto en lugar de en ~/.yt-mem-ai/config.env.

Uso como paquete de Python

yt-mem-ai es una biblioteca normal: la CLI es una capa fina de Typer sobre los núcleos run_* que puedes llamar directamente. Todo es local: sin servidor, sin clave de API (a menos que elijas el backend de incrustación openai).

pip install yt-mem-ai     # or: uv add yt-mem-ai

from dataclasses import replace
from pathlib import Path

from yt_mem_ai.config import load_config
from yt_mem_ai.cli import open_store, run_fetch, run_search, run_list, run_save_summary
from yt_mem_ai.store import db as store

# Config comes from ~/.yt-mem-ai/config.env < ./.env < process env.
# Override any field in code (Config is a frozen dataclass):
cfg = replace(load_config(), store_path=Path("~/.yt-mem-ai/lance").expanduser())

db = open_store(cfg)          # opens LanceDB + creates tables/indexes once
                              # pass db=... to every run_* call to reuse it

# 1. Ingest: download → transcribe (captions → whisper) → chunk → embed → store
video_id = run_fetch("https://www.youtube.com/watch?v=dQw4w9WgXcQ", cfg, db=db)
# captions only (no audio download, no whisper):
# video_id = run_fetch(url, cfg, db=db, captions_only=True)

# 2. Read what was stored
video = store.get_video(db, video_id)
text = store.get_transcript_text(db, video_id)
print(video.title, video.channel, video.duration_s, len(text or ""))

for c in store.list_chunks(db, video_id)[:3]:
    print(f"[{c['start_s']:.0f}s] {c['text'][:80]}")

# 3. Semantic search across the whole library (hybrid | vector | fts)
for hit in run_search(cfg, "retrieval augmented generation", mode="hybrid", k=5, db=db):
    print(hit["video_id"], hit["start_s"], hit["text"][:100])

# 4. Bring your own LLM: summarize the transcript however you like, then persist
summary_md = my_llm(text)                       # any model / provider
run_save_summary(
    cfg, video_id, summary_md,
    highlights_json='[{"t": 42, "text": "key moment"}]',
    qa_json='[{"q": "What is it about?", "a": "..."}]',
    db=db,
)
print(store.get_summary(db, video_id))

# 5. Library queries
for v in run_list(cfg, status="transcribed", since="2026-01-01", db=db):
    print(v.video_id, v.published_at, v.title)

Otros núcleos, con la misma forma (run_x(cfg, ..., db=db)): run_discover, run_fetch_pending, run_channel_list, run_recommend, run_feedback, run_compile, run_supercut, run_frame, run_reembed. Las piezas de nivel inferior también son importables: yt_mem_ai.download.download, yt_mem_ai.transcript.get_transcript, yt_mem_ai.store.embeddings.build_embedder / chunk_segments, yt_mem_ai.store.db (CRUD de LanceDB + search_chunks).

El almacén es LanceDB puro, así que también puedes abrirlo directamente:

import lancedb
from pathlib import Path
tbl = lancedb.connect(Path("~/.yt-mem-ai/lance").expanduser()).open_table("chunks")
df = tbl.to_pandas()      # video_id, start_s, end_s, text, vector

Registro

La CLI escribe eventos JSON estructurados en logs/common.jsonl (a través de obs.log_event/blog) — un objeto por línea, {ts, source, level, event, msg, ...ctx}. Anula la ruta con YT_LOG_FILE; está en gitignore. Inspecciónalo con jq:

jq -c 'select(.level=="error")' logs/common.jsonl   # every error
tail -f logs/common.jsonl | jq -c '{ts,event,msg}'  # live tail, compact

Pruebas

uv run pytest -q                       # offline unit tests (fake embedder)
YT_RUN_INTEGRATION=1 uv run pytest -q  # + real sentence-transformers integration

Publicación (mantenedores)

La versión proviene de la etiqueta git (hatch-vcs). Etiqueta, compila y publica:

git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z
uv build                                # → dist/ (sdist + wheel)
sh scripts/publish.sh dist/yt_mem_ai-X.Y.Z*   # uploads to PyPI

scripts/publish.sh carga UV_PUBLISH_TOKEN desde .env (gitignored) bajo demanda, para que no tengas que exportarlo cada vez — añade UV_PUBLISH_TOKEN=pypi-… a .env una vez (consulta .env.example). De forma equivalente: set -a; . ./.env; set +a; uv publish dist/*. Rota el token en PyPI si alguna vez se expone.