Memory retrieval system

记忆检索系统 (Memory Retrieval System)

本技能 (Skill) 赋予你检索过往 Swarm 对话和动作黑匣子档案的能力。该系统强制采用两层检索机制，以完美对抗大模型上下文窗口限制。

核心机制：L0-L2 双轨检索策略

当你需要回忆过去的事件、用户要求查询之前的讨论、或者你需要回顾某个特定应用的历史状态时，必须且只能 遵循以下两步走策略：

第一步：L0 广度扫描 (search_memory)

使用 search_memory 工具对记忆库进行雷达扫描，寻找线索。 记忆档案是每日生成的 Markdown 文件，按月存放。

• 工作原理：底层封装了 ripgrep。为了防止 Token 爆炸，L0 返回的不再是带有上下文字符的具体内容，而是一个极其紧凑的聚合索引。它会按文件分组，仅告诉你哪些文件的哪些行命中了该关键词。
• 参数说明：
  • pattern: 非常重要。请使用最具有区分度的关键词，或者简单的正则表达式。切忌使用一整句话去搜。
  • user_id: 必填，当前用户的 ID，用于安全隔离。
  • month: 可选填。如果你明确知道要搜哪个月的 (例如 "2024-05")，填入可以极大提升速度。如果不确定，留空。
  • max_results: 默认限制 50 条，但由于现在返回的是聚合索引，通常不用担心超载。

🔥 L0 诀窍：

1. 搜专有名词、报错信息、特定 URL 或特定的任务指令。
2. 观察返回结果中的文件名 (如 2024-05-20_MyApp_session123.md) 和具体的行号数组 (如 [ 145, 148, 150 ])。L0 只能告诉你存在，不提供具体细节。必须使用 L2 读取细节。

第二步：L2 精准深读 (read_memory)

在 L0 步骤中定位到潜在文件和具体行号后，必须且只能 选取其中一个文件，使用 read_memory 带着行号区间进行定点深读。

• 工作原理：精确定位到特定文件的特定行区间，直接读取完整段落。为防止越权和雪崩溢出，单次读取内置了 300 行的强制截断保护，以及 15000 字符的强制硬截断安全机制。
• 参数说明：
  • file_path: 直接填入 L0 索引中给出的绝对路径或相对路径，系统会自动处理。
  • start_line: 起始读取行。建议比 L0 搜到的线索行号提前 10-20 行，以看清完整的上下文。
  • end_line: 结束读取行。建议比线索行号延后 30-50 行。注意：如果你请求的区间超过 300 行，系统会自动帮你修剪到最多 300 行。
  • user_id: 必填，当前用户 ID。

🔥 L2 诀窍：

1. 不要一上来就试图读取几百行，每次精读几十行（如 50-100 行），就像用放大镜看东西。
2. 如果看完这 100 行还没找到完整逻辑，遇到自动截断，再通过调整 start_line 和 end_line 往前或往后翻页。

---

最佳实践与 Few-Shot 示例

场景一：寻找曾经调用过的一个复杂 API 及其参数

目标：用户问 "上周你帮我测那个发证 API 的时候，传的 JSON 结构是什么样的来着？"

1. 执行 L0 search_memory
   • 调用：search_memory(pattern="发证 API|issue_certificate", user_id="user123")
   • 结果中发现：2024-05-15_TestApp_ses88.md:345: **[Action: Call Tool send_http_request]** 和前后行提到了发证。
2. 执行 L2 read_memory
   • 由于 JSON 可能很长，L0 的 2 行看不够。
   • 调用：read_memory(file_path="2024-05-15_TestApp_ses88.md", start_line=340, end_line=380, user_id="user123")
   • 从返回结果中完整提取当年调用的 JSON 结构。

场景二：跨节点任务溯源追踪

目标：某个持续多日的重构任务中，你需要回忆当初设定的验收标准。

1. 执行 L0 search_memory
   • 错误做法：搜 "验收标准是什么"。
   • 正确做法：搜 "任务启动"、"重构计划 YAML" 等确切的边界特征词。
   • 调用：search_memory(pattern="acceptance_criteria", user_id="user123")
2. 执行 L2 read_memory
   • 找到目标行后，放大读取前后 50 行为自己重建上下文。

场景三：跨节点协同协作追踪 (Swarm Tracing)

核心认知：主辅日志的“单向索引”关系 在 Swarm 架构中，Worker（子节点）的日志文件名与主 Agent（主节点）的日志文件名通过 Session ID 和 时间戳 关联：

• 主节点日志 (如 2026-03-10_dynamic_expert_session_{timestamp}_{random_id}.md)：记录任务的分派（hold_meeting/dispatch）和结论。
• Worker日志 (如 2026-03-10_swarm_from_8000_sub_{sub_session_id}.md)：记录具体执行步骤和原始内容。 注意：主被动文件名无直接字符串包含关系，主日志是“索引”，Worker 日志是“详情”。没有主日志中的 sub_xxx ID，很难猜出 Worker 日志归属。

追踪目标：查询曾经分配给子节点的复杂任务执行细节。

1. Step 1: 在主日志中“抓钩子”
   • 阅读主控节点日志（例如某个 dynamic_expert_session 文件）。
   • 寻找 dispatch_batch_tasks 或派发动作，搜索发现类似 session_id: sub_0d78f570。
2. Step 2: 用“钩子”钓出 Worker 日志 (进行 L0 search_memory)
   • 把找到的子会话 ID 作为唯一关键词发起新一轮搜索。
   • 调用：search_memory(pattern="sub_0d78f570", user_id="user123")
   • 系统会精准定位到 2026-03-10_swarm_from_8000_sub_0d78f570.md。
3. Step 3: 执行 L2 read_memory 深入子节点日志
   • 调用：read_memory(file_path="2026-03-10_swarm_from_8000_sub_0d78f570.md", ...) 查阅 Worker 具体做了什么。

---

限制与守则

1. 🚫 禁止越级读取：绝对禁止在没有执行 L0 搜索定位文件和行号的情况下，直接盲目调用 read_memory 试图读取整个日志文件。
2. 🚫 禁止宽泛搜索：不要搜索 "你好"、"完成" 这种高频词，这会导致 L0 返回海量无用信息，触发截断保护。
3. 🔒 严格的安全沙箱：你只能查询和读取与你当前 user_id 匹配的记忆档案。
4. 🧠 提炼而非照搬：在回答用户时，阅读完记忆后，用自己的话提炼要点，不要 直接把原生的 Markdown 格式（含有特殊标记）直接丢给用户。