Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add agents/gmickel/flow-next/memory-scoutgit clone --depth 1 https://github.com/gmickel/flow-nextWhat it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5 | $0.00020 | $0.01259 |
| Opus 5 | $0.00010 | $0.00629 |
| Sonnet 5 | $0.00004 | $0.00252 |
| Haiku 4.5 | $0.00002 | $0.00126 |
Grade A, and why
memory-scout scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 90 lines — stays where its author put it; the contents beside it link to each section on GitHub.
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 (new schema, post fn-30):
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 astrack: "legacy").
Do not walk the filesystem directly. Use the flowctl memory CLI — it handles both schemas transparently.
Search strategy
Use these CLI shapes (shipped in fn-30.3):
flowctl memory list --json→{entries, legacy, count, status}— full index with track/category/module/tags per entry.flowctl memory search "<query>" --json→{query, matches, count}— ranked BM25-ish match across frontmatter + body.
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.
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 2d ago First seen · 90 lines · 20 tokens per session scan A a03f9066b6f2
memory-scout is an agent published in the GitHub repository gmickel/flow-next (692 stars, last pushed yesterday), licensed MIT. It adds 20 tokens to every session and 1,259 once invoked, about $0.0001 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other agents, from other repositories
docs-writer
Expert technical documentation specialist for creating comprehensive, user-friendly documentation across all project types. Use proactively for API docs, user guides, and technical documentation.
doc-writer
Technical documentation writer crystallized from studying how Stripe/Linear-quality doc practitioners think. Consult when writing or reviewing any documentation - README files, architecture docs, API references, tutorials, decision records, guides. Trigger conditions: "write docs for," "document this," "README,"…
plan-understanding-quiz
Analyzes a plan and generates multiple-choice technical comprehension questions to verify user understanding before RLCR loop. Use when validating user readiness for start-rlcr-loop command.
release-manager
The Release Manager of the aSPARK team. Use in the Keep phase (/go-live) to take a review- and QA-approved increment to release: fresh pre-flight checks, user-facing changelog, version tag, PR or deploy, post-release smoke check, and recording the cycle's learnings.
docs-writer
Prose-heavy changes — READMEs, ADRs, tutorials, API reference pages.
yak-shave-detector
Scope-creep detector - keeps tasks from going off the rails.