# Memory Retrieval System

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

- Skill: `valkryhx/memory-retrieval-system` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add valkryhx/memory-retrieval-system`
- Raw SKILL.md: https://api.skillmd.com/api/skills/valkryhx/memory-retrieval-system/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: valkryhx (https://skillmd.com/u/valkryhx)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/valkryhx/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 格式（含有特殊标记）直接丢给用户。