本工具用于长视频记忆。触发场景为时长超过 30 分钟的视频，无论是单个文件还是包含多个视频的目录。资料说明：当用户询问超过 30 分钟的视频时，必须使用本技能，而不是 read_video；read_video 无法有效覆盖数小时的视频，因为它只采样一次且帧数过少，容易遗漏重要内容。正确做法是先构建记忆，再借助记忆快速探索整个长视频。
使用方式与工作流：首先检查 <video_path>.memory/ 目录是否存在；若记忆已存在，则用 qwen-mm-plugins-video-memory 工具查询；若不存在，则先构建记忆再查询。通过记忆工具定位到具体片段后，必须用 read_video 配合较窄的 start_time/end_time 做帧级视觉查看，因为记忆始终是粗略的，可能不准确。
分层图记忆结构：记忆是一棵 4 层树。从宽到细逐层深入：Root（每个视频 1 个）→ SuperEvent（10–20 个故事弧）→ MacroEvent（每个 SuperEvent 下 3–8 个，每个约 3–8 分钟）→ Subgraph（实体、事件、OCR 文本、关系）。各级内容与 ID：Root 含标题、描述、主题、关键实体、情绪基调；SuperEvent 含高层叙事弧、时间范围、关键实体，ID 形如 super_01、super_02；MacroEvent 含具体事件片段、时间范围、摘要、关键实体，ID 形如 macro_0001、macro_0002；Subgraph 含实体节点（PERSON/OBJECT/LOCATION）、事件节点（带时间戳的动作）、OCR 文本（屏幕文字）与边（SEMANTIC/CAUSAL/TEMPORAL/HIERARCHICAL/SPATIAL/IDENTITY 关系），ID 形如 macro_0001:ent_001。
构建图记忆：若某视频的 graph_memory.json 不存在，需构建。命令示例：bash script/build_memory/build_memory.sh /path/to/video.mp4，输出到 <video_path>.memory/。也可带自定义选项：bash script/build_memory/build_memory.sh /path/to/video.mp4 --output-dir /path/to/output --model qwen3.7-plus --api-key "$DASHSCOPE_API_KEY"。
检索流程：多数问题遵循两步模式。第一步定位合适的 macro_id，按问题类型选择入口：涉及具体时间用 search_by_time(start_sec, end_sec)；询问人物/动作/事件用 search_nodes(query)；询问屏幕文字/比分用 search_ocr_text(query)；涉及已知故事片段用 get_macro_events(super_id)；询问事件因果用 search_nodes(query) 后再 get_subgraph。第二步下钻：对第一步得到的 1–2 个最相关 macro_id 调用 get_subgraph(macro_id)，返回全部细节（实体、事件、OCR 文本、关系），据此作答。
决策流：问题到达后，若 SuperEvent 列表已能缩小范围，则 get_macro_events(super_id) 后 get_subgraph；若含时间引用，则 search_by_time 后 get_subgraph；若为屏幕文字/比分，则 search_ocr_text 后按需 get_subgraph；若为人物/动作/事件，则 search_nodes 后 get_subgraph；若为因果/关系，则 search_nodes 后 get_subgraph（关系在子图中）。
工具参考——导航（层级下钻）：get_summary 获取视频级根摘要，参数 video_path（可选），返回标题、描述、主题、关键实体、情绪基调，用于下钻前快速总览；get_super_events 列出所有 SuperEvent（高层叙事弧），参数 video_path（可选），返回 super_id、label、time_range、key_entities、description、num_macros，用于了解整体结构或挑选相关故事弧；get_macro_events 列出某 SuperEvent 下的 MacroEvent，参数 super_id（可选）、macro_ids（可选列表），返回 macro_id、time_range、label、key_entity_names、description，用于初始上下文已缩小片段时；get_subgraph 获取单个 MacroEvent 的完整细节，信息最丰富，参数 macro_id（必填），返回实体、事件、OCR 文本、关系，用于已有 macro_id 并需具体信息时。
工具参考——搜索（直接访问）：search_nodes 对实体与事件节点做语义搜索（不含 OCR），参数 query（必填）、top_k、node_types（["event"]、["entity"] 或两者）；查询建议写描述性陈述而非问句，例如好的是“A player scores with an alley-oop dunk”，不好的是“Which player scored the alley-oop?”；多选时提取选项间共享信息、排除差异细节。search_ocr_text 仅对屏幕文字做语义搜索，参数 query（必填）、top_k，用于比分、统计、球衣号码、转播图文；不要用 search_nodes 查 OCR 内容，二者是独立索引。search_asr_text 对 ASR 转写文本（语音、对话、旁白）做语义搜索，参数 query（必填）、top_k，用于口语内容、对话、旁白或其他音频/言语信息。search_by_time 按时间范围查找 MacroEvent，参数 start_sec/end_sec（秒）或 start_time/end_time（DAY{N} HH:MM:SS，用于 EgoLife），只返回摘要，需再用 get_subgraph 获取细节。enumerate_events 按时间顺序枚举所有匹配事件实例，为计数或“多少次/列出每次发生”类问题而设，参数 query（必填，目标事件的描述性陈述）、min_cosine、max_results、node_types（默认 ["event"]，查物体/人物用 ["entity"]）；与 search_nodes 返回 top-k 最佳匹配不同，它返回相似度阈值以上的每个匹配，去重并按开始时间排序；若计数偏少，可降低 min_cosine 并换用其他表述重试。
视频帧提取：read_video 在用记忆工具缩小时间范围后，从原始视频提取帧；video_path 在初始上下文中。
反模式（常见错误）：仅凭 SuperEvent 描述作答——这些是摘要，具体细节务必 get_subgraph；重复相似搜索——若 search_nodes 找到了 macro_0022，应调用 get_subgraph(macro_0022)，而不是换一个略微不同的查询再搜；忽视工具类型——若 search_nodes 效果差，试试 search_ocr_text 或 search_by_time，不同索引覆盖不同内容；猜测数量——对“多少”类问题，应 get_subgraph 并从明确的节点列表计数，绝不要根据“若干”“多个”等词估计；跳过工具调用——即使问题看似简单，也绝不能未查询记忆图就作答。
存储：图记忆存储在视频旁边，即 <video_path>.memory/（例如 /data/clip.mp4 → /data/clip.mp4.memory/）。传入 video_path 时服务器会自动从该处加载，也可设置 GRAPH_MEMORY_PATH 显式指定。内容包括 graph_memory.json、embeddings.npz、01_macros.json、subgraphs/。
效率规则：最多 10 轮工具调用，请明智使用；多数问题需要 1 次搜索加 1–2 次 get_subgraph；在放弃前始终先下钻——答案在子图中，而不在摘要里。