From 65cff71e640f91e5707e60c5700235ee487335c8 Mon Sep 17 00:00:00 2001 From: svetkis Date: Tue, 16 Jun 2026 15:16:50 +0300 Subject: [PATCH 1/2] Add memory-grooming pattern - New pattern: documents/patterns/memory-grooming.md - Added relationships to documents/relationships.mmd - All tests pass (341/341) --- documents/patterns/memory-grooming.md | 113 ++++++++++++++++++++++++++ documents/relationships.mmd | 14 ++++ 2 files changed, 127 insertions(+) create mode 100644 documents/patterns/memory-grooming.md diff --git a/documents/patterns/memory-grooming.md b/documents/patterns/memory-grooming.md new file mode 100644 index 0000000..66be113 --- /dev/null +++ b/documents/patterns/memory-grooming.md @@ -0,0 +1,113 @@ +--- +authors: [svetkis] +related_patterns: + - semantic-anchors + - context-markers + - context-management + - knowledge-composition + - knowledge-document + - extract-knowledge + - reminders + - decision-guards +related_obstacles: + - context-rot + - cannot-learn + - limited-context-window + - black-box-ai +--- + +# 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. diff --git a/documents/relationships.mmd b/documents/relationships.mmd index b4046f6..2a0accf 100644 --- a/documents/relationships.mmd +++ b/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 From 0a4429503ceb2bb2b05d51e72203aa5549357e97 Mon Sep 17 00:00:00 2001 From: svetkis Date: Tue, 16 Jun 2026 17:52:29 +0300 Subject: [PATCH 2/2] Keep memory grooming relationships centralized --- documents/patterns/memory-grooming.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/documents/patterns/memory-grooming.md b/documents/patterns/memory-grooming.md index 66be113..7bce3a5 100644 --- a/documents/patterns/memory-grooming.md +++ b/documents/patterns/memory-grooming.md @@ -1,19 +1,5 @@ --- authors: [svetkis] -related_patterns: - - semantic-anchors - - context-markers - - context-management - - knowledge-composition - - knowledge-document - - extract-knowledge - - reminders - - decision-guards -related_obstacles: - - context-rot - - cannot-learn - - limited-context-window - - black-box-ai --- # Memory Grooming