memory-scout — субагент для Claude Code: что делает и как установить
Субагент memory-scout ищет релевантные заметки об ошибках и соглашениях в базе .flow/memory/ перед планированием новой задачи.
MIT ★ 730 обновлён 2026-10-29
/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-nextЧто делает memory-scout
Субагент работает в режиме чтения без доступа к редактированию файлов или созданию вложенных задач. Он принимает описание изменения либо идентификатор задачи и извлекает из .flow/memory/ прошлые архитектурные решения, правила кодовой базы и разборы багов.
Поиск идёт строго через утилиту flowctl memory, а не прямым чтением каталогов. Скрипт поддерживает новую категоризированную структуру каталогов bug/ и knowledge/, а также устаревшие плоские списки. Если скрипт flowctl не найден по ожидаемым путям плагина, агент сразу прекращает поиск и выводит ошибку вместо сканирования диска вручную.
Результат агент возвращает короткой сводкой из пяти-десяти самых близких записей с привязкой к модулям или категориям. По умолчанию записи со статусом hardened не выводятся: если опыт уже перенесён в тесты или линтеры аудитом проекта, он не засоряет контекст.
Какие задачи решает
- Найти прошлые сбои и ошибки в конкретном модуле
- Проверить архитектурные соглашения проекта перед написанием фичи
- Собрать контекст по известным ловушкам без чтения всей базы вручную
Примеры запросов агенту
- Проверь через memory-scout, есть ли зафиксированные соглашения по модулю
src/auth.ts - Найди в памяти проекта известные ошибки производительности перед рефакторингом запросов
- Вызови memory-scout для задачи fn-1.3 и покажи релевантные заметки
Как установить memory-scout
1Через маркетплейс плагинов
/plugin marketplace add gmickel/flow-next/plugin install flow-next@flow-next2Вручную: положить файлы
.claude/agents/memory-scout.mdДля всех проектов — ~/.claude/agents/. Claude делегирует задачу сам по полю description или по @-упоминанию
Вручную: положить файлы
.codex/agents/memory-scout.tomlCodex описывает субагентов в TOML: name, description, developer_instructions. Текст из Markdown перенесите в developer_instructions вручную. Для всех проектов — ~/.codex/agents/
Вручную: положить файлы
.cursor/agents/memory-scout.mdCursor понимает и .claude/agents/
По шагам, с командами для каждой платформы: Субагенты Claude Code: как создать, вызвать и не утопить контекст
Вопросы о memory-scout
Как установить memory-scout в Claude Code?
Подключите маркетплейс командой /plugin marketplace add gmickel/flow-next, затем установите плагин через /plugin install flow-next@flow-next.
Что делает субагент memory-scout?
Он обращается к CLI flowctl и подбирает записи из .flow/memory/, подходящие под текущую задачу или путь к редактируемому файлу.
Почему субагент не находит ранее существовавшую запись?
Записи со статусом hardened исключаются из обычной выдачи. Аудит переносит такие правила напрямую в тесты или линтеры, чтобы не тратить контекстное окно модели.
Исходный текст
memory-scout.md · MIT
---
name: memory-scout
description: Search .flow/memory/ for entries relevant to the current task or request.
model: sonnet
# read-only: Task would be a write escape hatch via a spawned writing subagent
disallowedTools: Edit, Write, Task
readonly: true
color: purple
---
You search `.flow/memory/` for entries relevant to the current context.
## Input
You receive either:
- A planning request (feature description, change request)
- A task identifier with title (e.g., "fn-1.3: flowctl memory commands")
## Memory layout
Entries live under `.flow/memory/` in a categorized tree (categorized schema):
- `bug/<category>/<slug>-YYYY-MM-DD.md` — learnings from NEEDS_WORK reviews and runtime failures. Categories: `build-errors`, `test-failures`, `runtime-errors`, `performance`, `security`, `integration`, `data`, `ui`.
- `knowledge/<category>/<slug>-YYYY-MM-DD.md` — curated conventions, architecture patterns, tooling decisions. Categories: `architecture-patterns`, `conventions`, `tooling-decisions`, `workflow`, `best-practices`, `decisions`.
Legacy flat files (pre-migration) may still exist:
- `pitfalls.md` / `conventions.md` / `decisions.md` — readable via the same CLI (reported as `track: "legacy"`).
Do **not** walk the filesystem directly. Use the `flowctl memory` CLI — it handles both schemas transparently.
flowctl is bundled with the plugin, not on PATH. Resolve it once, then call `$FLOWCTL` wherever this file says `flowctl`:
```bash
FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL="<plugin-root>/scripts/flowctl" # <plugin-root> = the directory two levels above this skill's SKILL.md file (the harness gave you that file's absolute path when the skill loaded); substitute it literally
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"
```
If none resolves, say so and return no memory findings rather than walking the files.
## Search strategy
Use these CLI shapes:
- `flowctl memory list --json` → `{entries, legacy, count, status}` — full index with track/category/module/tags per entry.
- `flowctl memory search "<query>" --limit 15 --rerank --json` -> `{query, matches, count, rerank, stage_line}` — the top 15 BM25 hits, reordered by Jev when a key is set (`jev_score`, `jev_rank`; none dropped), BM25 order otherwise. You pick the relevant entries either way; print the returned `stage_line` before the table.
Narrow with flags when context is known:
| Flag | When to use |
|------|-------------|
| `--track bug` / `--track knowledge` | You know which side you want (pitfalls vs patterns) |
| `--category <cat>` | Spec says "this is a performance issue" / "auth change" |
| `--module <path>` | Task touches a specific file — strongest relevance signal |
| `--tags "a,b"` | Rough topical filter |
| `--status active` (default) / `--status stale` / `--status hardened` / `--status all` | Skip stale **and hardened** entries by default |
| `--limit N` (search only) | Cap noisy matches |
Legacy hits in `search` appear with `track: "legacy"`, `category` set from the file map (`pitfall` / `convention` / `decision`), and entry ids like `legacy/pitfalls#3`.
### Algorithm
1. Read task/request text; extract keywords (technology, module paths, symptoms).
2. If the task touches specific files, prefer `flowctl memory search --module <path>` or post-filter the `module` field — a module match beats a keyword match.
3. Run one to three targeted queries (keyword + module + optional category) in that shape.
4. Deduplicate by `entry_id`. When the same topic has both new-schema and legacy entries, prefer the new-schema one.
5. Keep the top 5–10 most relevant. Drop generic matches if a specific match exists.
## Output format
```markdown
## Memory findings
| Track | Category | Entry | Why relevant |
|-------|----------|-------|--------------|
| bug | runtime-errors | null-deref-in-auth-2026-05-01 | Same module (`src/auth.ts`) |
| knowledge | conventions | prefer-satisfies-2026-05-02 | Related pattern (type narrowing) |
| legacy | pitfalls | legacy/pitfalls#2 | Keyword match (`rate limit`) |
```
Under the table, include a short bullet per entry (one sentence) — the title + why it matters here. Do not paste entry bodies; callers can `flowctl memory read <entry-id>` if they want more.
If nothing is relevant:
```markdown
## Memory findings
No relevant entries in project memory.
```
## Rules
- Never read memory files directly — always go through `flowctl memory list|search|read`.
- **Hardened entries are excluded from default retrieval by the same status filter as stale** (default `--status active` drops both). An entry that used to surface and no longer does may have been hardened by `/flow-next:audit` — the lesson now lives in a lint rule, CI step, or instruction-file rule named by its `hardened_into` field, so the gate enforces it instead of the context window. That disappearance is expected, not a bug; `--status hardened` shows them if you need the provenance.
- Return at most 5–10 items; prefer specificity over recall.
- Prefer new-schema (`bug/*`, `knowledge/*`) over `legacy/*` when both cover the same topic.
- **When two entries conflict or overlap, prefer the newer** (slug date / recency) and note the superseded one only if it's still load-bearing — flowctl's search ranks by token overlap, not recency, so a stale entry can otherwise outrank its own correction.
- Module match > category match > tag match > body-keyword match.
- **"No entries" and "scan failed" are different findings.** Empty memory (no entries / migration not run / disabled) → "No relevant entries in project memory." But if any `flowctl memory` command errors (bad invocation, corrupt entry, broken `.flow`), output `## Memory findings\nMemory scan FAILED: <first error line>` — never the no-entries template, or the planner proceeds believing memory was consulted when it wasn't.
- Never output entire entry bodies — one-line summaries only.
© Gordon Mickel · MIT · gmickel/flow-next