让 Agent 看懂视频，下次还能找回来。
Turn videos into searchable memory for your AI agent.
Video2Memory 是一个开源的本地视频分析与记忆插件。把视频文件或可访问的视频链接交给 Agent，它就能读取字幕或语音转写、查看指定时刻的画面，生成带时间戳和原文出处的分析，并把结果保存在本地，供之后的会话继续检索。
视频处理和资料库运行在本机；理解、翻译和写作使用宿主 Agent 已配置的模型。当前发行针对 Windows x64，已完成 Codex 实际工具调用验收。
第一次，把视频交给 Agent：
分析这个视频，提炼主要观点。保留关键原文和时间戳，用中文整理，并保存分析包。
之后，在使用同一资料库的新会话里继续问：
找一下之前那段讲虚拟团队的视频。它和传统团队有什么共同点？引用原片出处。
Agent 通过工具查找已保存的分析和原始证据。分析包保留交付语言、引用片段和时间范围；需要看画面时，工具返回实际解码的图片供宿主模型查看。
这里的“记忆”是可检索的持久资料库。它不会训练模型，也不会把整个视频库自动放进每次对话；Agent 需要调用检索工具。当前搜索为文字匹配，不是语义向量检索。
- 导入视频：本地文件、用户提供的字幕，以及可公开访问且允许处理的视频 URL。
- 读取原文：优先使用字幕；无字幕时使用本地多语言 Whisper ASR，保留时间信息。
- 查看画面：按需抽取指定时间点或短时间窗的源画面，返回真实图片块。
- 整理分析：由宿主模型撰写摘要、翻译和问答，保存带证据引用的语言版本。
- 跨会话找回：按视频、文字、语言查询资料库，继续展开原始证据。
- 带走结果：按需导出 Markdown，可放入用户选择的 Obsidian vault。
源语言和交付语言独立，例如读取印尼语原文、输出中文或英文。画面结论需要宿主具备读图能力；语音识别和模型分析仍可能出错。
三个 ZIP 都提供 SHA256 校验信息。体积为近似值，最终以 Release 附件为准。
| 安装包 | 约大小 | 内容与用途 |
|---|---|---|
video2memory-0.4.2-windows-x64-lite.zip |
166 MB | 首次安装推荐；包含 Python、固定依赖、FFmpeg，模型可复用或按需准备 |
video2memory-0.4.2-windows-x64-reuse.zip |
2.2 MB | 不含运行时和模型；需要已有兼容的完整 VideoAnalyst / Video2Memory 运行环境 |
video2memory-0.4.2-windows-x64-offline.zip |
612 MB | 完整运行时及固定版本模型，可离线准备 |
setup 会先检查组件版本、原生模块和真实音视频编解码能力，再决定能否复用。已有模型必须通过固定文件的 SHA256 校验；复用时只保存路径引用，不复制模型，也不修改共享缓存。不会随意替换成系统 Python 或不同版本的模型。
下载并解压到稳定目录，例如 D:\Tools\video2memory。在该目录打开 PowerShell，先检查环境，再完成设置：
powershell -NoProfile -ExecutionPolicy Bypass -File .\setup.ps1 -DiscoverOnly
powershell -NoProfile -ExecutionPolicy Bypass -File .\setup.ps1轻量版没有找到可复用模型时，字幕和画面工作流仍可使用。需要语音转写时，再显式准备约 486 MB 的模型文件：
powershell -NoProfile -ExecutionPolicy Bypass -File .\setup.ps1 -PrepareModel已有模型可指定 -ModelDirectory "D:\Models\whisper-small"。使用复用包时，可指定 -RuntimeDirectory "D:\Tools\existing-videoanalyst"；已登记的兼容运行时也可自动发现。被引用的目录需要一直保留。
检查状态，并为实际使用的项目配置 Codex：
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\launch.ps1 doctor
$runtime = (Get-Content .\runtime-selection.json -Raw | ConvertFrom-Json).directory
& (Join-Path $runtime 'python\python.exe') .\scripts\configure_host.py codex --project 'D:\Projects\my-project'将示例项目路径换成自己的路径。在宿主中信任/启用该项目的 MCP 配置并重新打开项目，然后交给 Agent 一个视频进行分析。项目配置方式是本轮实际验收的安装入口。若已配置旧版，请按脚本提示更新已有入口，避免同时启动两个相同工具服务。
配置脚本也支持 claude 和 opencode。这两款宿主已提供适配入口，模型调用验收尚未完成。Codex 原生插件 UI 安装/更新和干净 Windows 虚拟机安装也仍待验证。
上述 ExecutionPolicy Bypass 只用于当前 PowerShell 进程，不修改机器策略。
视频副本、字幕、转写、分析包和 SQLite 索引保存在本地。向 Agent 请求分析时，工具返回的证据会进入宿主模型上下文，并受该宿主和模型服务的隐私规则约束。因此“本地处理”不等于“所有证据都不会发送给模型服务”。
URL 导入需要访问来源网站；首次在线准备模型需要访问固定权重下载地址。发行包不包含通用 LLM/VLM，宿主的模型使用可能产生费用。
为兼容已交付的旧版本，当前默认数据目录仍为 %LOCALAPPDATA%\VideoAnalyst，MCP 配置键仍为 videoanalyst。可使用 VIDEOANALYST_DATA_DIR 或 setup 的 -DataDirectory 指定数据目录；配置宿主时也应传入同一个 --data-dir。品牌更新不会移动或删除已有资料库。卸载程序也不会自动清除持久数据。
- 0.4.1 已通过 58 项本地测试，以及模型缓存零复制、旧运行时复用、真实 ASR 和抽帧验证。
- Codex 已实际完成证据读取、多语言交付、分析包保存和读回，见 验收文档。
- 0.4.2 更新品牌、README 和发行包结构，见 0.4.2 发行说明。
- 本地发行不依赖网站、数据库服务器或独立后台服务。
- 视频来源可能要求登录、触发验证或限制地区；遇到这些情况会报告原因，可改用用户合法提供的本地文件。
- 当前未提供 OCR、实时视频理解、全平台下载保证或任意语义检索。
本仓库包含本地插件、必要的复用模块、固定依赖清单、打包脚本和测试。内部 Python 模块和插件源码目录暂保留 videoanalyst 标识，以保持旧版兼容。
backend/videoanalyst_local/ MCP 核心、资料库、媒体处理和模型发现
backend/app/ 复用的字幕解析、权重校验和错误定义
plugins/videoanalyst/ 宿主清单、skills、setup 和启动脚本
packaging/ 固定依赖、来源、哈希及 Windows 构建脚本
tests/local/ 本地回归测试
scripts/ 构建及实际宿主验收工具
docs/ 使用说明和可审查的验收记录
维护者使用 Windows x64 / Python 3.12 构建。构建脚本下载并校验锁定的上游依赖，不使用当前系统已安装的包代替发行依赖：
python packaging/build_windows.py --cache .tmp/release-cache --output .tmp/dist/lite/video2memory
python packaging/build_reuse.py --from-bundle .tmp/dist/lite/video2memory --output .tmp/dist/reuse/video2memory
python packaging/build_windows.py --with-model --cache .tmp/release-cache --output .tmp/dist/offline/video2memory缓存完整时可加 --offline 禁止构建联网。该选项与 --with-model 是否包含模型独立。每次构建必须使用新的输出目录，成品包含逐文件 SHA256SUMS.json。
开发测试：
python -m venv .venv
& .\.venv\Scripts\python.exe -m pip install -r packaging/requirements.in pytest
$env:PYTHONPATH = "$PWD\backend"
& .\.venv\Scripts\python.exe -m pytest tests/local -q提交问题时，请附操作系统、发行版本、经过脱敏的 doctor 输出、期望和实际行为。不要在 Issue 中上传密钥、私人视频或完整私人资料库。
项目源码遵循 MIT License，保留原贡献者版权说明。第三方 Python、FFmpeg、PyAV 及模型各自保留许可证，见发行包的 THIRD-PARTY.json 和 licenses/。项目的 MIT 许可不覆盖这些第三方组件。
当前版本按 预发布候选 提供。已列出依赖版本、下载来源、校验和和许可信息；FFmpeg、PyAV 内含 FFmpeg 及链接库的完整对应源码归档和许可证复核仍待完成，详见验收记录。不要把本仓库的应用源码误认为所有第三方二进制的完整对应源码。