企业官网建设流程全解析

project.md：video-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 week's 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 LLM's 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 → Persist"：Agent 先读转录稿提出剪辑策略，等用户确认才动刀，出片前自检，最后把决策写回project.md。这套循环跑完，留下的不是一堆待检索的语料，而是一份"这本片子剪到哪了、为什么这么剪、还剩什么没做"的工程状态。下一周打开同一个素材目录，Agent 读一眼project.md就能以一句话总结恢复全部上下文——这正是 README 里"next week's 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