valkryhx/google_adk_agent / skills/memory_retrieval_system
memory_retrieval_system
Verified专门针对记忆归档库的 L0(广度扫描) 到 L2(精准读取) 的两级检索引擎。
SKILL.md
View on GitHub---
name: memory_retrieval_system
description: 专门针对记忆归档库的 L0(广度扫描) 到 L2(精准读取) 的两级检索引擎。
---
# 记忆检索系统 (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 格式(含有特殊标记)直接丢给用户。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |