yt-mem-ai — AI 어시스턴트를 위한 로컬 YouTube 메모리

Claude, Codex, Cursor 또는 모든 MCP 호스트에게 사용자를 대신해 YouTube를 시청하는 기능을 제공하세요: 비디오를 전사하고, 기억하고, 구독을 팔로우하며, 이 모든 것을 요약, 타임스탬프가 찍힌 하이라이트, Q&A, 다이제스트, 비디오 릴로 바꿔줍니다. 모든 것이 사용자 머신에서 실행됩니다 — 클라우드 서비스도, API 키도 없습니다.

예시 — "이 비디오로 프레젠테이션 만들기" (Andrej Karpathy: From Vibe Coding to Agentic Engineering, Sequoia, 30분) → 슬라이드 13장, PDF, 모든 인용문이 대본에서 타임스탬프로 연결됩니다. 요청 한 번으로 인제스트부터 덱까지.

목차

• 기능

• 설치 방법

• 시작하기

• 사용법

• 예시

• 설정

• 내부 동작

Related MCP server: YouTube MCP Server

기능

• 🎧 모든 비디오를 전사합니다 — YouTube 자막이 있으면 자막 사용(빠르고, 모든 언어), 없으면 오프라인 Whisper 사용.

• 🧠 본 것을 기억합니다 — 모든 대본이 로컬에 저장되고 인덱싱되어, 라이브러리가 영원히 검색 가능하게 유지됩니다. 어떤 것도 머신 밖으로 나가지 않습니다.

• 🔎 그 순간을 찾아줍니다 — "그 비디오에서 X에 대해 뭐라고 했지?"라고 물으면 이동할 수 있는 타임스탬프와 함께 답을 얻습니다.

• 📡 구독을 팔로우합니다 — 새 업로드를 감지하고 하루를 하나의 다이제스트로 만듭니다.

• ✍️ 어시스턴트가 글쓰기를 담당합니다 — 요약, 하이라이트, Q&A, 슬라이드 덱, 모두 비디오의 원어로, 이미 비용을 지불하고 있는 모델을 사용합니다.

• ❤️ 취향을 학습합니다 — 비디오에 좋아요 또는 싫어요를 표시하고 자신의 라이브러리에서 추천을 받습니다.

• 🎬 미디어도 만듭니다 — 클릭 가능한 하이라이트 문서, 스틸 프레임, 렌더링된 슈퍼컷 릴.

• 🔌 사용자의 도구와 함께 작동합니다 — Claude Code, Claude Desktop, Codex, Cursor, Antigravity, OpenClaw, Hermes: 스킬 또는 MCP, 선택은 사용자의 몫.

설치 방법

1. 어시스턴트 연결하기 ⭐

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

대화형 마법사가 열립니다. 원하는 것을 선택하고, 앱을 체크하고, Enter를 누르세요:

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은 어시스턴트가 일반 요청 — "이 비디오 요약해줘" — 에 따라 행동하도록 가르칩니다. MCP는 대신 도구 세트를 제공합니다. 잘 모르겠다면? Plugin으로 시작하세요; 나중에 마법사를 다시 실행해 다른 것을 설치할 수 있습니다.

필요한 모든 것을 설치하고, 이미 있는 것은 체크하며, 체크 해제한 것은 제거합니다 (계획을 보여주고 먼저 확인을 받습니다). 그런 다음 앱을 재시작하고 다음을 시도하세요: summarize 'https://youtu.be/…'.

이미 원하는 것을 알고 있나요? 질문을 건너뛰세요:

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

호스트: --claude-code --claude-desktop --codex --cursor --antigravity --openclaw --hermes, 또는 --all. 전체 플래그 목록 및 제거 방법: integrations/README.md. 에이전트가 대신 처리하게 하고 싶나요? integrations/PROMPT.md를 아무 어시스턴트에 붙여넣으세요.

2. 수동 MCP — 구성 항목 하나, 자체 설치

사전 설치 불필요: uvx가 호스트가 서버를 처음 실행할 때 패키지를 가져오고, 이후에는 캐시에 유지합니다. 호스트의 MCP 구성에 다음을 넣으세요:

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

이것이 전체 설정입니다 — 경로도, env 블록도 없습니다. 설정은 ~/.yt-mem-ai/config.env에 있으며 에이전트가 config_set 도구로 직접 작성할 수 있습니다 (또는 사용자가 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

앱을 재시작하면 도구가 나타납니다 — 각 도구가 하는 일은 사용법을 참조하세요.

아무것도 나타나지 않았거나 호스트가 타임아웃되었나요? 첫 실행은 의존성을 다운로드하므로 호스트의 시작 검사보다 오래 걸릴 수 있습니다. uvx --from 'yt-mem-ai[mcp]' yt-ai-mcp --help를 한 번 실행한 다음 앱을 다시 여세요. 호스트가 여전히 시작할 수 없다면 절대 경로를 지정하세요 — uv tool install 'yt-mem-ai[mcp]'를 실행하고 which yt-ai-mcp의 결과를 command로, "args": []를 사용하세요 (GUI 앱은 종종 PATH에서 ~/.local/bin을 인식하지 못합니다).

3. Claude Desktop — 스킬 (앱 내에서)

Desktop은 플러그인을 디스크가 아닌 Claude 계정에 저장하므로 아무것도 자동으로 설치할 수 없습니다. 앱에서 1분이면 됩니다:

Customize (왼쪽 사이드바) → Plugins → Personal plugins → + → Add marketplace → Add from a repository → https://github.com/dasein108/yt-mem-ai → Add → Install yt-mem-ai

그런 다음 물어보세요: summarize 'https://youtu.be/…'. 제거도 같은 방법으로 합니다. 동일한 플러그인은 claude.ai 및 Cowork에서도 작동합니다. 스킬보다 도구가 더 좋으신가요? 위의 MCP 설정이 Desktop에서도 작동합니다 — 그리고 그것은 스크립트로 자동화 가능합니다.

각 호스트는 사용자 범위 디렉토리에서 SKILL.md 파일을 로드합니다: Codex ~/.codex/skills/ (CLI와 IDE가 공유, v0.117.0+), Cursor ~/.cursor/skills/, Antigravity ~/.gemini/skills/, OpenClaw ~/.agents/skills/, Hermes ~/.hermes/skills/ (여기서 /yt 및 /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

Codex 추가 기능: /yt-* 프롬프트 (integrations/codex/prompts/*.md → ~/.codex/prompts/) 및 integrations/codex/AGENTS.md → ~/.codex/AGENTS.md. 전체 가이드: skills/README.md.

4. CLI 단독 사용

스킬이 이를 구동하지만, 그 자체로 훌륭한 독립 도구입니다:

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

Python 3.11+ 및 uv 필요; ffmpeg는 supercut / frame에만 필요합니다.

데스크톱 UI는 별도 저장소에 있습니다: yt-mem-ai-desktop — 이 패키지에 의존하며 자체 로컬 REST API를 실행합니다.

시작하기

설치하고 호스트를 재시작했나요? 준비 완료입니다. 어시스턴트에게 말만 하세요 — 스킬(또는 MCP 프롬프트 + analyze_video)이 인제스트를 대신 처리합니다:

"Summarize https://youtu.be/dQw4w9WgXcQ" → 비디오를 인제스트(자막 → whisper)한 다음, 비디오의 원어로 경영진 요약과 핵심 포인트를 작성합니다.

"그 비디오의 타임스탬프가 있는 하이라이트를 줘" → 의미 검색으로 앵커된 3–8개의 딥링크 순간 (watch?v=…&t=123s).

"검색 증강 생성에 대해 내가 본 것 중 뭐가 있지?" → 라이브러리의 모든 대본을 검색하고 해당 순간을 인용합니다.

"내 구독을 오늘의 다이제스트로 처리해줘" → 새 업로드를 발견하고, 인제스트하고, digests/<DATE>.md를 작성합니다.

터미널이 더 편한가요? 동일한 첫 실행:

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

모든 것이 ~/.yt-mem-ai/에 저장됩니다 (라이브러리, 로그, 다운로드).

첫 실행은 느립니다 — 정상입니다. 설치 시 ML 스택(torch, LanceDB, sentence-transformers ≈ 디스크 1 GB)을 가져오고, 첫 fetch 또는 search는 그 위에 임베딩 모델을 추가로 다운로드합니다. 비디오에 자막이 없으면 Whisper 모델(small, ≈ 460 MB)도 다운로드됩니다 — 자막 경로는 절대 필요하지 않습니다. 모두 캐시되므로 비디오마다가 아니라 한 번만 발생합니다. GUI 호스트에서는 같은 이유로 첫 MCP 실행이 앱의 시작 검사보다 오래 걸릴 수 있습니다: 터미널에서 uvx --from 'yt-mem-ai[mcp]' yt-ai-mcp --help를 한 번 실행해 캐시를 워밍업한 다음 앱을 다시 여세요.

일상 루틴

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

그런 다음 어시스턴트에게: "process subscriptions" → 비디오별 요약 및 digests/<DATE>.md, 선택적으로 yt-ai compile --out compilations/$(date +%F).md로 그날의 하이라이트를 클릭 가능한 링크로 만듭니다.

사용법

어시스턴트와 대화하기 (스킬 및 프롬프트)

플러그인에는 두 개의 스킬이 포함됩니다. MCP 호스트는 동일한 플레이북을 프롬프트로 제공받습니다 (yt_summarize, yt_highlights, yt_qa, yt_presentation, yt_digest, yt_review, yt_group), 따라서 스킬 지원이 없어도 잃는 것이 없습니다.

스킬은 데이터베이스를 직접 건드리지 않습니다 — CLI를 호출하므로 동일한 워크플로우가 모든 호스트에서 실행됩니다. 수동으로 설치하거나 붙여넣으세요: skills/README.md.

MCP 도구

yt-ai-mcp 서버는 전체 엔진을 타입이 지정된 도구로 노출합니다. analyze_video는 원스텝 진입점입니다: 인제스트하고 대본을 반환하므로 모델이 요약을 직접 작성할 수 있습니다.

서버 세부 정보, 프롬프트 목록, 원시 설정: integrations/mcp/README.md.

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)

예시

사례: 10부작 YouTube 강좌로 만든 전체 PDF 교과서. examples/defi-crypto-options.pdf — «DeFi. Бесплатный вводный курс по крипто-опционам» 시리즈(@Menaskop)에서 제작한 96페이지 러시아어 교육 서적입니다.

파이프라인: 시리즈의 10개 비디오 식별 → ru-orig 자막 가져오기(yt-dlp + 브라우저 쿠키; Whisper 불필요) → 비디오별 구조화된 요약 → 하나의 공유 스파인(용어집, 표기법, 그림 카탈로그) → 10개의 재작성된 챕터(~28.5k 단어)

• 47개의 다시 그린 벡터 그림 → Typst로 조립 및 렌더링. 요약이 아닌, 작업 예제, 다이어그램, 용어집, 그리고 각 챕터의 비디오로 돌아가는 딥링크를 갖춘 원리 기반 챕터입니다.

설정

시작에 필요한 것은 없습니다 — 기본값은 스토어, 로그, 다운로드를 ~/.yt-mem-ai/ 아래에 두고 로컬 임베딩 모델을 사용합니다. 필요할 때 조정하세요:

CLI 또는 에이전트에서 설정 — .env를 직접 편집하는 대신 yt-ai config(또는 MCP config_* 도구)를 사용하면 에이전트가 채팅에서 스스로 재구성할 수 있습니다:

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은 기본적으로 전역 설정 파일(~/.yt-mem-ai/config.env)에 기록하므로 MCP 서버가 작업 디렉터리와 무관하게 이를 읽습니다. --project는 ./.env에 기록합니다. 우선순위: 프로세스 환경 변수 > 프로젝트 .env > 전역 설정 파일이며, config list는 각 값이 어디서 왔는지 보여줍니다.

내부 동작

아래 내용은 모두 선택적 읽을거리입니다 — 내부 구조, 튜닝, 개발자 노트.

작동 방식

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

CLI가 무거운 I/O를 처리하고 스토어를 소유하며, 스킬과 MCP 도구는 얇은 호출자입니다. 비디오는 discovered → downloaded → transcribed → summarized 단계를 거칩니다. 라이브 스트림은 종료 상태인 stream 상태를 가지며 일괄 수집에서 제외됩니다(요청 시 yt-ai fetch <url>로 하나를 트랜스크립트할 수 있음). 스토리지는 임베디드 LanceDB(videos, channels, transcripts, chunks, summaries, feedback)이며, 청크별 벡터와 전체 텍스트 인덱스를 포함합니다 — 이것이 검색을 하이브리드로 만드는 이유입니다.

명령어 세부 사항

평가 및 추천 — 가져온 비디오에 좋아요/싫어요를 표시한 다음 yt-ai recommend가 트랜스크립트 임베딩을 사용하여 좋아요를 누른 항목과의 유사성(싫어요를 누른 항목 제외)을 기준으로 나머지를 순위화합니다. 좋아요를 누르기 전에는 가장 최근에 게시된 항목 순으로 폴백합니다.

discover는 증분 방식입니다 — 최신 피드 항목을 한 번의 평면 호출로 가져오고(YT_DISCOVER_FEED_LIMIT로 제한), 각 항목에 대략적인 타임스탬프를 찍은 다음, 마지막 실행의 하이워터마크에서 1시간 오버랩 (YT_DISCOVER_OVERLAP_S)을 뺀 것보다 새로운 항목만 유지하므로, 시간 단위로 반올림된 날짜가 경계 비디오를 놓치지 않습니다. 이미 처리된 비디오는 필터링됩니다. --after YYYY-MM-DD는 컷오프를 재정의합니다.

compile vs supercut — compile은 당일 하이라이트를 마크다운 딥링크(watch?v=ID&t=<start>s)로 렌더링하며, 최신 비디오 우선이고 --max-minutes(기본 20)로 제한됩니다. 즉시 실행되며 --out을 전달하지 않으면 stdout으로 출력합니다. supercut은 각 하이라이트 구간을 720p로 재다운로드하고, 라벨을 구워 넣은 다음, 모든 것을 supercuts/<date>.mp4로 연결하고 소스를 나열하는 .refs.md 사이드카(실패 후 건너뛴 클립 포함)를 생성합니다 — 훨씬 느리고 네트워크 + ffmpeg가 필요하지만 공유할 수 있습니다.

임베딩, 프록시 및 기타 튜닝

임베딩: YT_EMBEDDING_BACKEND=local|openai. 로컬은 sentence-transformers(YT_EMBEDDING_MODEL, 기본 all-MiniLM-L6-v2)를 사용합니다 — 비영어 라이브러리의 경우 paraphrase-multilingual-MiniLM-L12-v2(384차원, 50개 이상 언어)를 설정하여 의미 검색이 교차 언어로 작동하게 하세요. openai는 text-embedding-3-small|large를 사용합니다(OPENAI_API_KEY 필요). 모델을 변경한 후 yt-ai reembed를 실행하여 기존 라이브러리를 마이그레이션합니다(모든 청크를 다시 임베딩하며 재다운로드는 없음).

프록시 / VLESS: YT_USE_WEBSHARE는 기본적으로 꺼져 있습니다. 이미 시스템 수준 프록시/VPN(VLESS/Xray 등)을 실행 중이라면 꺼둔 채로 두세요 — 트래픽은 해당 터널을 통해 이동합니다. Webshare 프록시를 그 위에 쌓으면 인증된 구독 피드가 깨집니다(CONNECT 터널이 405를 반환). 다른 프록시가 없고 YouTube가 원시 IP를 속도 제한하는 경우에만 YT_USE_WEBSHARE=true를 설정하세요. Discover 튜닝: YT_DISCOVER_FEED_LIMIT(최신-N 제한, 기본 60), YT_DISCOVER_OVERLAP_S(증분 오버랩, 기본 3600), YT_DISCOVER_TIMEOUT_S.

체크아웃에서 작업 중인가요? uv sync --extra dev를 실행한 다음, 설정을 ~/.yt-mem-ai/config.env 대신 프로젝트 로컬에 두고 싶다면 cp .env.example .env를 실행하세요.

Python 패키지로 사용

yt-mem-ai는 일반 라이브러리입니다 — CLI는 직접 호출할 수 있는 run_* 코어 위의 얇은 Typer 셸입니다. 모든 것이 로컬입니다: 서버 없음, API 키 없음(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)

다른 코어도 동일한 형태입니다(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. 하위 수준 구성 요소도 가져올 수 있습니다 — 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 (LanceDB CRUD + search_chunks).

스토어는 일반 LanceDB이므로 직접 열 수도 있습니다:

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

로깅

CLI는 구조화된 JSON 이벤트를 **logs/common.jsonl**에 기록합니다(obs.log_event/blog 경유) — 한 줄에 객체 하나씩, {ts, source, level, event, msg, ...ctx} 형식입니다. 경로는 YT_LOG_FILE로 재정의할 수 있으며 gitignore 처리됩니다. jq로 확인:

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

테스트

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

릴리스 (관리자용)

버전은 git 태그에서 가져옵니다(hatch-vcs). 태그, 빌드, 게시:

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는 필요할 때 .env(gitignore 처리됨)에서 UV_PUBLISH_TOKEN을 로드하므로 매번 내보낼 필요가 없습니다 — .env에 UV_PUBLISH_TOKEN=pypi-…를 한 번 추가하세요(.env.example 참조). 동등한 방법: set -a; . ./.env; set +a; uv publish dist/*. 토큰이 노출된 적이 있다면 PyPI에서 교체하세요.