Add memory-grooming pattern

documents/patterns/memory-grooming.md

@@ -0,0 +1,99 @@
+---
+authors: [svetkis]
+---
+
+# Memory Grooming
+
+## Problem
+
+AI context rots. So does AI memory.
+
+Persistent memory files make up for the model's statelessness. But they are not the only thing that rots. `AGENTS.md` and project-level `CLAUDE.md` are rules, not memory, yet they overlap with it: the same fact can exist as a rule in `AGENTS.md` and as a note in `.serena/memories/`. Groom them together, or contradictions will hide in the gaps. But left alone, they degrade:
+
+- **Duplicates**: the same fact recorded three times with different wording.
+- **Contradictions**: one file says "use X," another says "avoid X."
+- **Fuzziness**: vague statements that once meant something specific but now could mean anything.
+- **Outdated entries**: rules about a library you removed six months ago.
+- **Marker drift**: context markers and decision guards copied without their meaning, becoming decorative noise.
+
+The agent won't groom its own memory. It can't tell a duplicate from a stale entry, or a sharp anchor from a vague phrase. It writes whatever sounds right in the moment. Left alone, memory bloats context, confuses the agent, and quietly breaks instructions.
+
+## Pattern
+
+Maintain agent memory actively. Don't just accumulate notes.
+
+1. **Schedule grooming sessions**
+   - After every major feature.
+   - When context feels "heavy" or responses start ignoring known rules.
+   - When you notice the agent citing a memory you do not remember writing.
+   - After a silent misalignment surfaces — it may be caused by stale or contradictory memory.
+
+2. **Deduplicate**
+   - Find redundant entries and merge them into one clear statement.
+   - Prefer the version tied to a concrete example or decision.
+
+3. **Resolve contradictions**
+   - If two memories conflict, decide which one is current.
+   - Archive or delete the loser; do not leave both in place.
+
+4. **Sharpen fuzzy entries with semantic anchors**
+   - Replace long descriptions with well-known domain terms.
+   - Use established names like "TDD, London School" or "arc42" instead of describing the same idea in your own words.
+   - The agent records memory as prose; you rewrite it as anchors.
+
+5. **Refresh markers and guards**
+   - Check that context markers and decision guards still mean what they say.
+   - Remove markers that no longer activate useful behavior.
+   - Update references if the underlying file moved.
+
+6. **Delete obsolete memory**
+   - Before deleting, make sure the decision is recorded elsewhere — git history, ADR, or code comments. If yes, delete without keeping an archive.
+   - Archives rot too: nobody grooms them, they grow, and sooner or later someone pulls old garbage back into context.
+
+7. **Keep memory composable by scope**
+   - Split large memory files by topic or area of application.
+   - Contradictions are acceptable when scopes are explicit: `frontend-testing.md` and `backend-testing.md` can disagree.
+   - Grooming still covers every file; composition just makes contradictions local and resolvable.
+
+Groom memory before it becomes noise. Clean memory is smaller, easier to follow, and easier to debug when the agent goes wrong.
+
+## Example
+
+**Before grooming:**
+
+```markdown
+# AGENTS.md
+
+- Start every reply with 🍀.
+
+Always write tests first.
+We do TDD here, red-green-refactor.
+Make sure to create a failing test before implementation.
+Use test doubles for external dependencies.
+
+# memory/project.md
+
+Project uses Jest for testing.
+Testing approach: write tests before code.
+Do London-style TDD.
+Avoid mocking too much.
+```
+
+After a few iterations, the agent starts using mocks inconsistently. It has four overlapping descriptions of the testing process and a contradiction about when to mock.
+
+**After grooming:**
+
+```markdown
+# AGENTS.md
+
+- Start every reply with 🍀.
+- TDD, London School.
+```
+
+The agent now has one clear anchor (`TDD, London School`) instead of five overlapping paraphrases. The name activates the methodology; no explanation needed. The mock contradiction is folded into the anchor: London School TDD uses mocks for external dependencies. The marker 🍀 stays explicit and checkable.
+
+## When to Stop
+
+Don't groom memory into perfection. Aim for "good enough to be reliable."
+
+If grooming keeps surfacing contradictions that are really scope differences, apply Knowledge Composition: split the memory by area of application so each file has one coherent scope. Then groom each file separately.

documents/relationships.mmd

@@ -13,6 +13,8 @@ graph LR
   patterns/chain-of-small-steps -->|solves| obstacles/degrades-under-complexity
   patterns/chain-of-small-steps -->|solves| obstacles/limited-focus
   patterns/check-alignment -->|solves| anti-patterns/silent-misalignment
+  patterns/memory-grooming -->|solves| anti-patterns/perfect-recall-fallacy
+  patterns/memory-grooming -->|solves| anti-patterns/silent-misalignment
   patterns/check-alignment -->|solves| obstacles/black-box-ai
   patterns/chunking -->|solves| obstacles/limited-focus
   patterns/chunking -->|solves| obstacles/limited-context-window
@@ -85,9 +87,21 @@ graph LR
   patterns/contextual-prompts -->|solves| obstacles/selective-hearing
   patterns/decision-guards -->|solves| obstacles/obedient-contractor
   patterns/decision-guards -->|solves| obstacles/context-rot
+  patterns/memory-grooming -->|solves| obstacles/context-rot
+  patterns/memory-grooming -->|solves| obstacles/cannot-learn
+  patterns/memory-grooming -->|solves| obstacles/limited-context-window
+  patterns/memory-grooming -->|related| obstacles/black-box-ai
   patterns/decision-guards -->|uses| patterns/knowledge-document
   patterns/decision-guards -->|related| patterns/reminders
   patterns/decision-guards -->|related| patterns/semantic-anchors
+  patterns/memory-grooming -->|uses| patterns/semantic-anchors
+  patterns/memory-grooming -->|uses| patterns/context-markers
+  patterns/memory-grooming -->|related| patterns/context-management
+  patterns/memory-grooming -->|uses| patterns/knowledge-composition
+  patterns/memory-grooming -->|uses| patterns/knowledge-document
+  patterns/memory-grooming -->|uses| patterns/extract-knowledge
+  patterns/memory-grooming -->|related| patterns/reminders
+  patterns/memory-grooming -->|uses| patterns/decision-guards
   patterns/contextual-prompts <-->|similar| patterns/reminders
   patterns/feedback-loop <-->|similar| patterns/playgrounds
   patterns/feedback-loop <-->|similar| patterns/chain-of-small-steps