Manual-trigger skill. disable-model-invocation: true keeps the model from
running memory audits automatically mid-task. When installed from this plugin,
invoke it deliberately as /agent-docs:remember when you want to clean
up. Do not add hooks, background tasks, auto-trigger behavior, runtime storage,
vector databases, MCP integration, or external memory systems.
Choose the explicit scope below and produce a structured Memory Health Report using the workflow.
What this does
This is the complement to /agent-docs:learn:
/agent-docs:learn proposes verified knowledge additions to AGENTS.md or
docs/ from the current session./agent-docs:remember audits existing AGENTS.md memory surfaces for staleness,
duplication, misplacement, and low-signal content.- It may also accept one explicitly named docs entry as a candidate for
promotion into the nearest
AGENTS.md.
Read and apply the shared
Knowledge Admission Policy. Do not
invoke learn; both workflows independently apply the same policy in opposite
directions.
Step 1: Choose scope and gather memory layers
Use exactly one mode:
- Full memory audit: when the user asks to audit or reorganize project
memory, read all project
AGENTS.md files.
- Targeted promotion: when the user explicitly names a rule in docs or a
codemap for possible promotion, read that entry and the nearest candidate
AGENTS.md only. Do not turn it into a full memory audit.
Resolve "nearest" from the source path affected by the rule, not from whichever
AGENTS.md the runtime loaded first:
- Extract the primary affected source path or paths from the named entry.
- For one path, walk from its containing directory toward the repository root
and select the deepest existing project
AGENTS.md. For multiple paths,
use the deepest AGENTS.md at their common scope.
- If the entry does not identify an affected path and the target cannot be
verified, report
Needs user input instead of defaulting to root.
Locating candidate filenames along that ancestor chain is allowed; do not open
or audit non-target AGENTS.md files. A root AGENTS.md already present in
the runtime context is not evidence that it is the nearest target.
Typical project memory layers include:
AGENTS.md
internal/<package>/AGENTS.md
<other-package>/AGENTS.md
Exclude personal preference files such as ~/.claude/CLAUDE.md or
~/.config/opencode/AGENTS.md, every CLAUDE.md, and any non-project
AGENTS.md. In targeted-promotion mode, do not enumerate or audit the rest of
docs/; the named entry is input evidence, not a docs curation license.
Step 2: Audit memory surfaces
Audit every relevant AGENTS.md memory surface, not only ## Hidden Knowledge.
| Surface |
Checks |
Quick Reference |
Commands/workflows exist, placeholders are removed, commands are current or explicitly marked as examples |
Architecture |
Gives agents a clear entry map, key directories, and module relationships without becoming a copied source-code encyclopedia |
Key Patterns |
Captures project-specific patterns that are still true and valuable enough for prompt space, whether non-derivable or expensive to rediscover |
Golden Rules |
Still hard rules, not duplicated from docs/rules/, not better represented as links |
Hidden Knowledge |
Non-derivable gotchas, quirks, critical ordering, or misleading failures; verified, not stale, not duplicated, correctly placed |
Sub-package AGENTS.md |
Still justified by complexity, cross-module constraints, state machines, or special verification needs |
Step 3: Classify issues by quality dimension
Use these dimensions to explain every finding. Do not produce an overall score
for an AGENTS.md file. Use the shared candidate value score only when deciding
whether a specific entry earns prompt space.
| Dimension |
Meaning |
Commands/Workflows |
Essential build, test, lint, verify, install, or project workflows are present, current, and have enough context to run safely |
Architecture Clarity |
AGENTS.md maps the codebase, entry points, and relationships well enough for a future agent to start in the right place |
Non-Obvious Patterns |
Gotchas, quirks, critical ordering, and "why this is different" knowledge are captured without restating visible code |
Conciseness |
Each line earns prompt space; remove filler, template residue, obvious advice, and long explanations better suited for docs |
Currency |
Paths, commands, symbols, and described behavior are still true |
Actionability |
A future agent can follow the instruction directly with concrete commands, paths, or decision rules |
Signal |
The content is worth prompt space and helps future agents act better |
Placement |
The content lives at the right AGENTS.md level and section, or in the owning code artifact's doc comment when the knowledge is scoped to a single symbol |
Non-Derivability |
Hidden knowledge cannot now be inferred from code, git, or existing docs; this is an automatic-admission signal, not a universal requirement for every surface |
Knowledge Value |
Derivable content still earns prompt space when impact, recurrence, discovery cost, actionability, durability, and scope justify it |
Duplication |
The same guidance is not repeated across layers or docs |
Map any additional memory-quality criterion to a dimension above before
reporting rather than changing the audit target.
Step 4: Verify findings
Before proposing a cleanup, verify it:
| Finding type |
Verification |
| Missing or stale file path |
Check the path exists |
| Missing function, type, command, or symbol |
Search for the referenced name |
| Stale command |
Run the safest relevant command, or explain why execution is unsafe |
| Contradicted behavior |
Inspect source or run the smallest relevant check |
| Duplicate content |
Cite both locations |
| Now-derivable hidden knowledge |
Cite the code, docs, git history, or AGENTS.md main-body section that now covers it, then assess whether it remains valuable in another surface |
| Entry better placed as a code comment |
Confirm the owning symbol or file exists, the knowledge is scoped to it, and its existing doc comments do not already cover it |
| Potentially low-value derivable entry |
Show the shared-policy score and the lower-cost source or document that would replace it |
| Memory assertion backed by a linked doc |
Open that one linked doc and confirm it still supports the assertion |
| Explicit docs promotion candidate |
Cite the named entry, verify it changes recurring agent behavior, score its prompt value, and confirm it is absent from the nearest AGENTS.md |
If a finding cannot be verified, label it Needs user input instead of treating
it as fact.
Scope guard — linked docs are a verification method, not an audit target.
Open only the specific doc a memory assertion links to, confirm it still supports
that assertion, and stop. Do not enumerate docs/, score doc quality, or
traverse cross-links; doc-level quality (including redundancy) is owned by a
separate audit, not /agent-docs:remember. The economics differ — AGENTS.md
is prompt-resident and uses the highest value threshold, while docs/ is
pull-based and may legitimately be longer or more detailed. The only question
here is whether the linked doc still backs the memory claim that cites it.
Step 5: Classify actions
| Action |
Use when |
Promotions |
Lower-level guidance affects multiple packages, belongs in a higher-level AGENTS.md, or an explicitly named docs rule earns prompt space in the nearest AGENTS.md |
Deletions |
Content fails a hard gate, or derivable content scores too low for prompt-resident memory; derivability alone is insufficient, and valid non-derivable content must be retained or rerouted |
Relocations to code |
A prompt-resident entry is scoped to a single code artifact and fits a concise doc comment or module doc on it; scope and conciseness trigger this, never derivability alone. Keep a one-line pointer in AGENTS.md only when agents must know before opening the file |
Rewrites |
Content is true but unclear, too verbose, misplaced within the same file, or missing verification context |
Duplicates |
Exact or overlapping guidance appears in multiple places |
Conflicts |
Two files or sections contradict each other and need user judgment |
No Action Needed |
Content is valid, placed correctly, and useful |
Relocation scope guard. Verifying a relocation opens exactly the one
source file that owns the symbol — a verification method, not a license to
audit or rewrite source. Do not enumerate the source tree or propose
unrelated code changes from /agent-docs:remember.
Rewrite heuristic — prefer stable references over line numbers. When memory
points at source, prefer stable references (symbol name, package path, heading
anchor, or file) over line numbers. Line numbers drift on every unrelated edit,
so a stale file.go:42 is a recurring false signal. If a cited line number no
longer points at the named symbol, propose a Rewrite to the symbol/package form
(e.g. the Run method in deploy_v3.go) rather than just bumping the number —
bumping only fixes it until the next edit.
Step 6: Present the report
Output a structured report:
## Memory Health Report
### Summary
- Files reviewed: <count and paths>
- Surfaces reviewed: <Quick Reference / Architecture / Key Patterns / Golden Rules / Hidden Knowledge / sub-package AGENTS.md>
- Changes proposed: <count>
- Items needing user input: <count>
### Promotions
1. `<source file>`: "<entry>" -> move to `<target file>` because <dimension + verification evidence>
### Deletions
1. `<file>`: "<entry>" -> delete because <dimension + verification evidence>
### Rewrites
1. `<file>`: "<entry>" -> rewrite as "<new wording>" because <dimension + verification evidence>
### Relocations
1. `<file>`: "<entry>" -> move into a doc comment on `<symbol or file>` because <scope evidence + conciseness>; keep a one-line pointer only if agents must know before opening the file
### Duplicates
1. "<entry>" appears in `<file A>` and `<file B>` -> keep `<file A>`, remove `<file B>` because <reason>
### Conflicts
1. `<file A>` says "X" but `<file B>` says "Y" -> needs user input: <question>
### No Action Needed
<brief note on entries that are valid and well-placed>
If no AGENTS.md memory surfaces exist beyond placeholders, say so and suggest
running /agent-docs:learn after a future session discovers valuable knowledge.
Step 7: User approval
- Stop after presenting the report. Modify only proposals the user explicitly
approves; they may approve any subset, reject all, or request revisions.
- Never auto-delete or auto-merge conflicts. Ask which version is correct before
editing.
- After applying approved changes, report applied changes, rejected proposals,
unresolved conflicts, and residual risks.
1---2name: remember3description: Audit and reorganize project AGENTS.md memory, or evaluate an explicitly named rule for promotion into the nearest AGENTS.md. Use for explicit memory-audit or rule-promotion requests; not to capture new session insights.4---56> **Manual-trigger skill.** `disable-model-invocation: true` keeps the model from7> running memory audits automatically mid-task. When installed from this plugin,8> invoke it deliberately as `/agent-docs:remember` when you want to clean9> up. Do not add hooks, background tasks, auto-trigger behavior, runtime storage,10> vector databases, MCP integration, or external memory systems.1112Choose the explicit scope below and produce a structured `Memory Health13Report` using the workflow.1415## What this does1617This is the complement to `/agent-docs:learn`:1819- `/agent-docs:learn` proposes verified knowledge additions to `AGENTS.md` or20 `docs/` from the current session.21- `/agent-docs:remember` audits existing `AGENTS.md` memory surfaces for staleness,22 duplication, misplacement, and low-signal content.23- It may also accept one explicitly named docs entry as a candidate for24 promotion into the nearest `AGENTS.md`.2526Read and apply the shared27[Knowledge Admission Policy](references/knowledge-admission.md). Do not28invoke `learn`; both workflows independently apply the same policy in opposite29directions.3031## Step 1: Choose scope and gather memory layers3233Use exactly one mode:3435- **Full memory audit:** when the user asks to audit or reorganize project36 memory, read all project `AGENTS.md` files.37- **Targeted promotion:** when the user explicitly names a rule in docs or a38 codemap for possible promotion, read that entry and the nearest candidate39 `AGENTS.md` only. Do not turn it into a full memory audit.4041Resolve "nearest" from the source path affected by the rule, not from whichever42`AGENTS.md` the runtime loaded first:43441. Extract the primary affected source path or paths from the named entry.452. For one path, walk from its containing directory toward the repository root46 and select the deepest existing project `AGENTS.md`. For multiple paths,47 use the deepest `AGENTS.md` at their common scope.483. If the entry does not identify an affected path and the target cannot be49 verified, report `Needs user input` instead of defaulting to root.5051Locating candidate filenames along that ancestor chain is allowed; do not open52or audit non-target `AGENTS.md` files. A root `AGENTS.md` already present in53the runtime context is not evidence that it is the nearest target.5455Typical project memory layers include:5657```text58AGENTS.md59internal/<package>/AGENTS.md60<other-package>/AGENTS.md61```6263Exclude personal preference files such as `~/.claude/CLAUDE.md` or64`~/.config/opencode/AGENTS.md`, every `CLAUDE.md`, and any non-project65`AGENTS.md`. In targeted-promotion mode, do not enumerate or audit the rest of66`docs/`; the named entry is input evidence, not a docs curation license.6768## Step 2: Audit memory surfaces6970Audit every relevant `AGENTS.md` memory surface, not only `## Hidden Knowledge`.7172| Surface | Checks |73|---------|--------|74| `Quick Reference` | Commands/workflows exist, placeholders are removed, commands are current or explicitly marked as examples |75| `Architecture` | Gives agents a clear entry map, key directories, and module relationships without becoming a copied source-code encyclopedia |76| `Key Patterns` | Captures project-specific patterns that are still true and valuable enough for prompt space, whether non-derivable or expensive to rediscover |77| `Golden Rules` | Still hard rules, not duplicated from `docs/rules/`, not better represented as links |78| `Hidden Knowledge` | Non-derivable gotchas, quirks, critical ordering, or misleading failures; verified, not stale, not duplicated, correctly placed |79| Sub-package `AGENTS.md` | Still justified by complexity, cross-module constraints, state machines, or special verification needs |8081## Step 3: Classify issues by quality dimension8283Use these dimensions to explain every finding. Do not produce an overall score84for an `AGENTS.md` file. Use the shared candidate value score only when deciding85whether a specific entry earns prompt space.8687| Dimension | Meaning |88|-----------|---------|89| `Commands/Workflows` | Essential build, test, lint, verify, install, or project workflows are present, current, and have enough context to run safely |90| `Architecture Clarity` | `AGENTS.md` maps the codebase, entry points, and relationships well enough for a future agent to start in the right place |91| `Non-Obvious Patterns` | Gotchas, quirks, critical ordering, and "why this is different" knowledge are captured without restating visible code |92| `Conciseness` | Each line earns prompt space; remove filler, template residue, obvious advice, and long explanations better suited for docs |93| `Currency` | Paths, commands, symbols, and described behavior are still true |94| `Actionability` | A future agent can follow the instruction directly with concrete commands, paths, or decision rules |95| `Signal` | The content is worth prompt space and helps future agents act better |96| `Placement` | The content lives at the right `AGENTS.md` level and section, or in the owning code artifact's doc comment when the knowledge is scoped to a single symbol |97| `Non-Derivability` | Hidden knowledge cannot now be inferred from code, git, or existing docs; this is an automatic-admission signal, not a universal requirement for every surface |98| `Knowledge Value` | Derivable content still earns prompt space when impact, recurrence, discovery cost, actionability, durability, and scope justify it |99| `Duplication` | The same guidance is not repeated across layers or docs |100101Map any additional memory-quality criterion to a dimension above before102reporting rather than changing the audit target.103104## Step 4: Verify findings105106Before proposing a cleanup, verify it:107108| Finding type | Verification |109|--------------|--------------|110| Missing or stale file path | Check the path exists |111| Missing function, type, command, or symbol | Search for the referenced name |112| Stale command | Run the safest relevant command, or explain why execution is unsafe |113| Contradicted behavior | Inspect source or run the smallest relevant check |114| Duplicate content | Cite both locations |115| Now-derivable hidden knowledge | Cite the code, docs, git history, or AGENTS.md main-body section that now covers it, then assess whether it remains valuable in another surface |116| Entry better placed as a code comment | Confirm the owning symbol or file exists, the knowledge is scoped to it, and its existing doc comments do not already cover it |117| Potentially low-value derivable entry | Show the shared-policy score and the lower-cost source or document that would replace it |118| Memory assertion backed by a linked doc | Open that one linked doc and confirm it still supports the assertion |119| Explicit docs promotion candidate | Cite the named entry, verify it changes recurring agent behavior, score its prompt value, and confirm it is absent from the nearest `AGENTS.md` |120121If a finding cannot be verified, label it `Needs user input` instead of treating122it as fact.123124**Scope guard — linked docs are a verification method, not an audit target.**125Open only the specific doc a memory assertion links to, confirm it still supports126that assertion, and stop. Do **not** enumerate `docs/`, score doc quality, or127traverse cross-links; doc-level quality (including redundancy) is owned by a128separate audit, not `/agent-docs:remember`. The economics differ — `AGENTS.md`129is prompt-resident and uses the highest value threshold, while `docs/` is130pull-based and may legitimately be longer or more detailed. The only question131here is whether the linked doc still backs the memory claim that cites it.132133## Step 5: Classify actions134135| Action | Use when |136|--------|----------|137| `Promotions` | Lower-level guidance affects multiple packages, belongs in a higher-level `AGENTS.md`, or an explicitly named docs rule earns prompt space in the nearest `AGENTS.md` |138| `Deletions` | Content fails a hard gate, or derivable content scores too low for prompt-resident memory; derivability alone is insufficient, and valid non-derivable content must be retained or rerouted |139| `Relocations to code` | A prompt-resident entry is scoped to a single code artifact and fits a concise doc comment or module doc on it; scope and conciseness trigger this, never derivability alone. Keep a one-line pointer in `AGENTS.md` only when agents must know before opening the file |140| `Rewrites` | Content is true but unclear, too verbose, misplaced within the same file, or missing verification context |141| `Duplicates` | Exact or overlapping guidance appears in multiple places |142| `Conflicts` | Two files or sections contradict each other and need user judgment |143| `No Action Needed` | Content is valid, placed correctly, and useful |144145**Relocation scope guard.** Verifying a relocation opens exactly the one146source file that owns the symbol — a verification method, not a license to147audit or rewrite source. Do not enumerate the source tree or propose148unrelated code changes from `/agent-docs:remember`.149150**Rewrite heuristic — prefer stable references over line numbers.** When memory151points at source, prefer stable references (symbol name, package path, heading152anchor, or file) over line numbers. Line numbers drift on every unrelated edit,153so a stale `file.go:42` is a recurring false signal. If a cited line number no154longer points at the named symbol, propose a `Rewrite` to the symbol/package form155(e.g. `the Run method in deploy_v3.go`) rather than just bumping the number —156bumping only fixes it until the next edit.157158## Step 6: Present the report159160Output a structured report:161162```markdown163## Memory Health Report164165### Summary166167- Files reviewed: <count and paths>168- Surfaces reviewed: <Quick Reference / Architecture / Key Patterns / Golden Rules / Hidden Knowledge / sub-package AGENTS.md>169- Changes proposed: <count>170- Items needing user input: <count>171172### Promotions1731741. `<source file>`: "<entry>" -> move to `<target file>` because <dimension + verification evidence>175176### Deletions1771781. `<file>`: "<entry>" -> delete because <dimension + verification evidence>179180### Rewrites1811821. `<file>`: "<entry>" -> rewrite as "<new wording>" because <dimension + verification evidence>183184### Relocations1851861. `<file>`: "<entry>" -> move into a doc comment on `<symbol or file>` because <scope evidence + conciseness>; keep a one-line pointer only if agents must know before opening the file187188### Duplicates1891901. "<entry>" appears in `<file A>` and `<file B>` -> keep `<file A>`, remove `<file B>` because <reason>191192### Conflicts1931941. `<file A>` says "X" but `<file B>` says "Y" -> needs user input: <question>195196### No Action Needed197198<brief note on entries that are valid and well-placed>199```200201If no `AGENTS.md` memory surfaces exist beyond placeholders, say so and suggest202running `/agent-docs:learn` after a future session discovers valuable knowledge.203204## Step 7: User approval205206- Stop after presenting the report. Modify only proposals the user explicitly207 approves; they may approve any subset, reject all, or request revisions.208- Never auto-delete or auto-merge conflicts. Ask which version is correct before209 editing.210- After applying approved changes, report applied changes, rejected proposals,211 unresolved conflicts, and residual risks.
gzb1128