Skip to content

valkryhx/google_adk_agent / skills/memory_retrieval_system

memory_retrieval_system

Verified

专门针对记忆归档库的 L0(广度扫描) 到 L2(精准读取) 的两级检索引擎。

FileKindSize
SKILL.mdskill md6.4 KB
tools.pyscript7.1 KB
---
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 格式(含有特殊标记)直接丢给用户。
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall