project.mdvideo-use 给 Agent 的轻量记忆为什么比向量库更香【免费下载链接】video-useEdit videos with coding agents项目地址: https://gitcode.com/GitHub_Trending/vid/video-use当 Agent 要记住上一周的剪辑进度时主流方案的第一反应往往是上向量数据库把历史切成块、灌进 embedding、部署检索服务、调 top-k 和相似度阈值。而开源项目 video-use用 coding agent 对话式剪视频、已在 GitHub 收获上万 star社区有大量实测文章给出的答案是一段几 KB 的 markdown追加式写入名叫project.md。这个选择看似反直觉背后却是一整套关于Agent 到底需要什么记忆的判断。本文直接翻开 SKILL.md 与 helpers 源码讲清楚这套轻量记忆的工作原理以及它在真实剪辑场景中为什么比向量库更香。长记忆的常规解法与它的隐性成本先把向量库方案的账算明白。标准的 RAG 式长期记忆长这样文档切块 → embedding 模型编码 → 写入向量存储 → 用户提问时对查询向量做相似度检索 → 把命中的片段拼回上下文。每个环节都有隐性成本基础设施成本要维护一套向量数据库索引构建、存储、备份、升级或者为 embedding API 持续付费。对个人项目、单机 Agent 来说这是一份不轻的运维负担。检索质量调参成本chunk 大小、重叠、top-k、相似度阈值、重排策略——任何一个参数失配记忆召回的质量就飘忽不定。而调好只能靠一轮轮实验很难有确定性的验收标准。语义近似与精确性冲突向量检索的本质是模糊召回适合回答历史上有没有聊过类似的东西但剪辑决策恰恰需要精确引用——C0103 第 2.42 秒到 6.85 秒是 HOOK 段因为那是唯一没有口误的 take。这种精确引用是 embedding 的相似度排名给不了的。换句话说向量库是为海量、异构、语义模糊的语料设计的重武器。而个人 Agent 的跨会话记忆规模通常只有几十 KB、结构高度稳定、内容需要精确续接——用重武器打这种场景属于明显的过度设计。video-use 的 README.md 里有一句话点明了设计取向Persists session memory inproject.mdso next weeks session picks up where you left off——记忆的目的不是检索历史而是下周无缝续接。project.md一段几 KB 的 markdown 就是长期记忆先看它在项目里的位置。SKILL.md 的目录布局规定所有会话产物都落在素材目录下的edit/里videos_dir/ ├── source files, untouched └── edit/ ├── project.md ← memory; appended every session ├── takes_packed.md ← phrase-level transcripts, the LLMs primary reading view ├── edl.json ← cut decisions ├── transcripts/name.json ← cached raw Scribe JSON └── ...记忆机制的用法极其朴素每个会话在project.md追加一节格式在 SKILL.md 的 Memory —project.md 章节中原样给出## Session N — YYYY-MM-DD **Strategy:** one paragraph describing the approach **Decisions:** take choices, cuts, grades, animations why **Reasoning log:** one-line rationale for non-obvious decisions **Outstanding:** deferred items配套的启动协议只有一句话读project.md用一句话总结上个会话然后问用户是否继续。整个记忆系统到此为止——没有 embedding、没有向量索引、没有检索服务。为什么这样够用三个原因第一格式与 LLM 的原生能力对齐。LLM 最强的能力之一就是理解自然语言和半结构化文本。Strategy/Decisions/Reasoning log/Outstanding四个字段恰好是 Agent 能直接读进去的上下文而不是需要解码的向量。把 markdown 塞进上下文窗口比经过embedding-检索-拼装三跳拿回一堆碎片更可靠。第二记忆体量小到无需检索。一个会话的记录通常只有几 KB。几十个会话累计也就是几十 KB直接放进上下文即可检索带来的收益为负——检索本身的延迟、排序误差、上下文截断反而会损失信息。第三它是追加式append-only而不是覆盖式。每次会话都在文件尾部追加一节天然形成一条不可篡改的决策时间线。下次启动时Agent 既可以精读最近一节也可以回看历史各节的演进——这比向量库里几条孤立的相似片段更有上下文连续性。剪辑场景里的实际收益为什么轻在这里就是准视频剪辑是一个极其特殊的 Agent 场景它的记忆需求天然排斥向量库素材是不变的重转录是昂贵的。转录走 ElevenLabs Scribe真金白银helpers/transcribe.py 里明确写了缓存逻辑——输出文件已存在就跳过上传。而 SKILL.md 的 Hard Rule 9 更是把除非源文件本身变化否则永不重转录定为铁律。这意味着剪辑决策所依赖的底层事实每句话的精确时间戳、说话人、静音间隙一旦计算就固定了。Agent 需要的不是再次检索这些事实而是记住上次基于这些事实做了哪些判断、为什么。project.md的Reasoning log字段记录的正是后者——一行话解释非常规决策的理由这是向量检索永远给不出的东西。跨周会话的续接靠的是复盘而非召回。社区对 video-use 的实测文章普遍提到它的工作流是Ask → Confirm → Execute → Self-Eval → PersistAgent 先读转录稿提出剪辑策略等用户确认才动刀出片前自检最后把决策写回project.md。这套循环跑完留下的不是一堆待检索的语料而是一份这本片子剪到哪了、为什么这么剪、还剩什么没做的工程状态。下一周打开同一个素材目录Agent 读一眼project.md就能以一句话总结恢复全部上下文——这正是 README 里next weeks session picks up where you left off的字面实现。记忆与主阅读视图配对形成两级轻量信息结构。project.md记录的是决策与理由而它的姊妹文件takes_packed.md由 helpers/pack_transcripts.py 生成把所有 take 的词级转录打包成约 12KB 的纯文本——LLM 的主阅读视图## C0103 (duration: 43.0s, 8 phrases) [002.52-005.36] S0 Ninety percent of what a web agent does is completely wasted. [006.08-006.74] S0 We fixed this.这套设计的精髓在 README.md 的成本对比里写得非常直白Naive approach: 30,000 frames × 1,500 tokens 45M tokens of noise. Video Use:12KB text a handful of PNGs.LLM 从不看视频它通过转录文本 按需生成的视觉复合图如 static/timeline-view.svg 展示的胶片条 说话人轨道 波形 词标签 静音间隙剪辑候选来读视频。project.md正是这一哲学在时间维度上的延伸帧是噪音文本是界面历史检索是噪音追加式复盘是界面。更进一步SKILL.md 的 Anti-patterns 直接否定了重索引路线它明确反对带可用性标签 / 语气标签 / 镜头分层的层级预计算格式理由是过度工程——这些元数据该在决策时从转录里现推而不是提前索引好它也反对手写 moment-scoring 启发式函数理由是LLM 比任何你手写的启发式都选得好。这等于把整个向量库式预计算索引的思路在剪辑场景里判了死刑与其在外部堆检索设施不如让 LLM 在上下文里直接推理。对个人 Agent 系统设计的启示跳出剪辑project.md这套设计给所有个人化、单项目Agent 系统提供了四条可迁移的判断标准启示一记忆分两层——可续接的状态与可重算的产物要分开存。project.md存的是状态决策、理由、未竟事项而takes_packed.md、edl.json、transcripts/*.json都是可重算或已缓存的产物。前者必须追加保留后者按需重建、绝不重复计算。很多系统的错误在于把两者混进同一个检索池白白浪费存储和检索成本。启示二写为什么而不是是什么。向量库记录的是内容的相似性project.md记录的是决策的因果。对 Agent 而言为什么是下一次推理最省 token 的上下文——它直接把上次的思考结论注入本次的推理起点而不是让模型重新从碎片里猜。启示三为 LLM 定制格式而不是为数据库定制格式。markdown 半结构化文本是人机双读的用户能看懂复盘、Agent 能直接消费。相比之下把记忆塞进向量库等于把唯一一份人可读的工程日志降级成了不可读的浮点数组——可审计性、可调试性全部丢失。对个人 Agent可读 可控。启示四向量库的门槛应该画在规模上。什么情况下才真的需要向量库语料大到上下文窗口装不下海量文档、跨项目知识库、查询是语义模糊的开放问答、内容高度异构且持续增长。而单个项目的跨会话续接这种场景——体量 KB 级、内容精确、结构稳定——markdown 追加文件就是最优解。选型不是比谁的方案更高级而是比谁的方案在给定体量下开销最小、精度最高。回到开头的问题为什么project.md比向量库更香因为它回答的根本不是同一个问题。向量库回答从海量语料里模糊召回什么project.md回答上次干到哪了、为什么这么干、接下来干什么。前者是搜索后者是续接。对一个要用 coding agent 长期维护一部片子、一个项目、一套配置的个人 Agent 来说一段几 KB 的追加式 markdown加上一条启动时先读它的协议就是性价比最高的长期记忆——轻到没有运维成本准到可以精确引用每一次剪辑决策而这恰恰是向量库最不擅长、也最昂贵的那部分能力。【免费下载链接】video-useEdit videos with coding agents项目地址: https://gitcode.com/GitHub_Trending/vid/video-use创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考