| name | compound |
| description | Capture session learnings as discoverable memory artifacts in this repo, so future sessions stop repeating the same mistakes. Run at session end, or right after something notable breaks or works. |
Compound
Turn what this session learned into committed memory the next session can find.
This is the compounding flywheel: every pitfall captured here is one a future
agent won't re-hit. It lives in the repo (not a personal scratch dir) so it
travels to every machine and teammate.
When to run
- Session end — as the last step before handing off.
- Mid-session — right after something breaks unexpectedly, a workaround is
found, the user corrects you, or an approach works notably well.
Process
1. Review the session
Scan for at most a few learnings, by category (filename prefix):
feedback_ — a user correction or stated preference.pattern_ — an approach that worked and should be repeated.pitfall_ — something that broke, failed, or wasted time.domain_ — a project fact discovered during the work.
Most sessions yield 0–2. Do not force it. Nothing notable → skip to step 4
and record a no-learnings review. The review itself is the work product.
2. De-duplicate
Scan MEMORY.md for an existing entry on the same topic. If one exists, update
that file instead of creating a near-duplicate.
3. Write the memory file(s)
Location: .claude/memory/ (committed). Filename: {prefix}_{slug}.md (lowercase,
underscores). 3–8 line body. Format:
---
name: Short imperative name
description: One line for the MEMORY.md index
type: feedback | pattern | pitfall | domain
date: YYYY-MM-DD
---
The learning, stated plainly.
**Context:** when/why it matters.
**Apply when:** the specific condition a future session should recall this under.
4. Update the index
Add one line to the right section of .claude/memory/MEMORY.md:
- [{prefix}_{slug}.md]({prefix}_{slug}.md) — one-line actionable description
5. Mark complete
If the optional /compound commit gate is enabled in
scripts/pre-commit-gate.sh, drop the per-commit marker so the next commit is
unblocked:
touch .claude/.compound_ran
Print one line: Compound: captured N learning(s) — <slugs>, or
Compound: reviewed, nothing notable to capture.
Rules
- Max ~3 learnings per session. Be selective, not exhaustive.
- Descriptions are actionable — start with a verb or "Never/Always".
- Keep
MEMORY.md scannable — consolidate related entries before it sprawls.
Do not capture
- Task status / progress (belongs in your tracker).
- Implementation detail (belongs in code comments or design docs).
- Obvious things already in
CLAUDE.md / AGENTS.md.
- One-off debugging steps that won't recur.
