Reflect Memory
Compounding has a failure mode: unbounded growth. Rules pile up, duplicate
each other, go stale, and start contradicting — and every one of them is
loaded into context on every session. This skill is the garbage collector
and compactor for the memory reflect builds.
Surfaces
Work over, in order of impact:
- The project's
AGENTS.md / CLAUDE.md (agent-rule sections).
.reflect/observations.md and .reflect/applied.md.- Skill descriptions and command files reflect maintains (per the ledger).
~/.reflect/ when run outside a project or when asked.
Only restructure freely inside .reflect/. For instruction files, apply
safe mechanical fixes directly (exact duplicates, dead references) and
propose everything judgment-shaped.
Workflow
Inventory the load. Measure each surface: line counts, rule counts,
and rough token estimate (chars/4, labeled as estimate). This gives the
before/after for the report.
Find decay, in five classes:
- Duplicates — same rule stated twice, or a rule restating harness
or tool defaults.
- Merge candidates — three narrow rules that are one general rule
(e.g., per-command timeout rules → one testing section).
- Stale — references to files, tools, commands, or versions that no
longer exist; check, don't assume.
- Contradictions — rules that disagree with each other or with
observed recent behavior; the newer, evidence-backed one usually wins,
but flag rather than silently pick when both look intentional.
- Wrong altitude — session-specific trivia in durable files, or a
paragraph-long rule that should be a skill (and vice versa).
Fix. Apply direct fixes within boundaries; write proposals for the
rest (into .reflect/applied.md as proposed rows, long bodies under
.reflect/proposals/). Every removal or merge must preserve meaning —
when in doubt, propose.
Compact state. In observations.md, prune expired rows (untouched
~90 days). In applied.md, collapse ancient pruned rows into a single
archive line per quarter; never drop verified history.
Report.
## Memory Maintenance
**Load**: <surface>: ~n tokens → ~n tokens (estimates)
**Fixed** — duplicates removed, merges applied, stale refs corrected
**Proposed** — contradictions and judgment merges awaiting a decision
**State** — observations pruned n, ledger compacted n rows
Boundaries
- Never delete a rule you cannot show is duplicated, stale, or superseded —
"seems unnecessary" is a proposal, not a deletion.
- Preserve authorship: content the user wrote by hand gets propose-only
treatment even inside sections reflect usually maintains.
- Keep a one-line dated note at the top of
applied.md after each pass so
cadence is visible to future runs.
1---2name: reflect-memory3description: Lifecycle maintenance for accumulated agent memory: dedupe, merge, expire, and resolve contradictions across AGENTS.md/CLAUDE.md agent rules, .reflect/ state, and other agent instruction files reflect maintains. Use monthly, when instruction files feel bloated or contradictory, when the agent cites stale rules, or after many reflect runs have accumulated. Not for extracting new learnings — that is the reflect skill.4---56# Reflect Memory78Compounding has a failure mode: unbounded growth. Rules pile up, duplicate9each other, go stale, and start contradicting — and every one of them is10loaded into context on every session. This skill is the garbage collector11and compactor for the memory reflect builds.1213## Surfaces1415Work over, in order of impact:16171. The project's `AGENTS.md` / `CLAUDE.md` (agent-rule sections).182. `.reflect/observations.md` and `.reflect/applied.md`.193. Skill descriptions and command files reflect maintains (per the ledger).204. `~/.reflect/` when run outside a project or when asked.2122Only restructure freely inside `.reflect/`. For instruction files, apply23safe mechanical fixes directly (exact duplicates, dead references) and24propose everything judgment-shaped.2526## Workflow27281. **Inventory the load.** Measure each surface: line counts, rule counts,29 and rough token estimate (chars/4, labeled as estimate). This gives the30 before/after for the report.31322. **Find decay**, in five classes:33 - **Duplicates** — same rule stated twice, or a rule restating harness34 or tool defaults.35 - **Merge candidates** — three narrow rules that are one general rule36 (e.g., per-command timeout rules → one testing section).37 - **Stale** — references to files, tools, commands, or versions that no38 longer exist; check, don't assume.39 - **Contradictions** — rules that disagree with each other or with40 observed recent behavior; the newer, evidence-backed one usually wins,41 but flag rather than silently pick when both look intentional.42 - **Wrong altitude** — session-specific trivia in durable files, or a43 paragraph-long rule that should be a skill (and vice versa).44453. **Fix.** Apply direct fixes within boundaries; write proposals for the46 rest (into `.reflect/applied.md` as `proposed` rows, long bodies under47 `.reflect/proposals/`). Every removal or merge must preserve meaning —48 when in doubt, propose.49504. **Compact state.** In `observations.md`, prune expired rows (untouched51 ~90 days). In `applied.md`, collapse ancient `pruned` rows into a single52 archive line per quarter; never drop `verified` history.53545. **Report.**5556```markdown57## Memory Maintenance5859**Load**: <surface>: ~n tokens → ~n tokens (estimates)6061**Fixed** — duplicates removed, merges applied, stale refs corrected62**Proposed** — contradictions and judgment merges awaiting a decision63**State** — observations pruned n, ledger compacted n rows64```6566## Boundaries6768- Never delete a rule you cannot show is duplicated, stale, or superseded —69 "seems unnecessary" is a proposal, not a deletion.70- Preserve authorship: content the user wrote by hand gets propose-only71 treatment even inside sections reflect usually maintains.72- Keep a one-line dated note at the top of `applied.md` after each pass so73 cadence is visible to future runs.
ckorhonen