yt-mem-ai — 为你的 AI 助手提供本地 YouTube 记忆

让 Claude、Codex、Cursor 或任何 MCP 主机具备替你观看 YouTube 的能力：转录视频、记住它们、关注你的订阅，并将这一切转化为摘要、带时间戳的高光片段、问答、每日摘要和视频混剪。一切都在你的机器上运行——无需云服务，无需 API 密钥。

示例 — "根据这个视频制作一份演示文稿" (Andrej Karpathy: From Vibe Coding to Agentic Engineering, Sequoia, 30 分钟) → 13 页幻灯片，PDF， 每一句引用都带有来自转录文本的时间戳。从摄入到幻灯片只需一次请求。

目录

• 功能特性

• 如何安装

• 快速上手

• 使用方法

• 示例

• 配置

• 底层原理

Related MCP server: YouTube MCP Server

功能特性

• 🎧 转录任何视频 — 有 YouTube 字幕时使用字幕（快速，支持任何语言），没有时使用离线 Whisper。

• 🧠 记住你看过的内容 — 每份转录文本都会在本地存储并建立索引，让你的资料库永远可搜索。没有任何数据离开你的机器。

• 🔎 找到那个瞬间 — 问"那个视频关于 X 说了什么"，就能得到带时间戳的答案，你可以直接跳转过去。

• 📡 关注你的订阅 — 捕捉新上传的视频，把一天的内容变成一份摘要。

• ✍️ 你的助手负责写作 — 摘要、高光、问答、幻灯片，全部使用视频本身的语言，使用你已经付费的模型。

• ❤️ 学习你的品味 — 喜欢或不喜欢视频，从你自己的资料库获得推荐。

• 🎬 还能制作媒体 — 可点击的高光文档、静态帧和渲染好的超剪视频。

• 🔌 与你的工具配合 — Claude Code、Claude Desktop、Codex、Cursor、Antigravity、OpenClaw、Hermes：skills 或 MCP，任你选择。

如何安装

1. 连接你的助手 ⭐

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

一个交互式向导会打开。选择你想要的，勾选你的应用，按回车：

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 应用通常看不到 ~/.local/bin 在它们的 PATH 中）。

3. Claude Desktop — skills（在应用内）

Desktop 将插件存储在你的 Claude 账户中，而不是磁盘上，所以没有任何东西能替你安装它们。在应用内花一分钟即可：

自定义（左侧边栏）→ 插件 → 个人插件 → + → 添加市场 → 从仓库添加 → https://github.com/dasein108/yt-mem-ai → 添加 → 安装 yt-mem-ai

然后问：summarize 'https://youtu.be/…'。用同样的方式卸载。同一个插件也适用于 claude.ai 和 Cowork。更喜欢工具而不是 skills？上面的 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

skills 驱动它，但它本身也是一个非常好用的独立工具：

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。

快速上手

已安装并重启主机？你准备好了。直接和你的助手对话——skills（或 MCP 提示词 + analyze_video）会替你完成摄入：

"Summarize https://youtu.be/dQw4w9WgXcQ" → 摄入视频（字幕 → whisper），然后用视频本身的语言写一份执行摘要 加上要点。

"Give me the highlights of that video with timestamps" → 3–8 个深链时刻（watch?v=…&t=123s），由语义搜索锚定。

"What did I watch about retrieval-augmented generation?" → 搜索你资料库中的每份转录文本并引用那些时刻。

"Process my subscriptions into today's digest" → 发现新上传，摄入它们，写入 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 将当天的高光生成为 可点击的链接。

使用方法

与你的助手对话（skills 和提示词）

插件附带两个 skills。MCP 主机获得相同的剧本作为提示词 （yt_summarize、yt_highlights、yt_qa、yt_presentation、yt_digest、 yt_review、yt_group），所以没有 skill 支持也不会丢失任何功能。

Skills 从不直接接触数据库——它们调用 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 — 一本 96 页的俄语教育书籍，由系列课程 «DeFi. Бесплатный вводный курс по крипто-опционам»（@Menaskop）构建而成。

流程：识别 10 个系列视频 → 拉取 ru-orig 字幕（yt-dlp + 浏览器 cookies；无需 Whisper）→ 生成结构化的逐视频摘要 → 一个共享 主干（术语表、符号说明、图表目录）→ 10 个重写的章节（约 2.85 万字）

• 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 负责繁重的 IO 并拥有存储；skills 和 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 与 supercut 对比 — compile 将当天的高亮片段渲染为 markdown 深度链接（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。发现调优：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（gitignored）加载 UV_PUBLISH_TOKEN， 因此你无需每次都导出它 — 在 .env 中一次性添加 UV_PUBLISH_TOKEN=pypi-… （参见 .env.example）。等价地：set -a; . ./.env; set +a; uv publish dist/*。 如果令牌曾经暴露，请在 PyPI 上轮换它。