Memory Consolidation: Curate and Update CLAUDE.md

Output must add precise, actionable bullets that future tasks can immediately apply.

Memory Consolidation Workflow

Phase 1: Context Harvesting

First, gather insights from recent reflection and work:

• Identify Learning Sources:

• Recent conversation history and decisions

• Reflection outputs from /reflexion:reflect

• Critique findings from /reflexion:critique

• Problem-solving patterns that emerged

• Failed approaches and why they didn't work

If scope is unclear, ask: “What output(s) should I memorize? (last message, selection, specific files, critique report, etc.)”

• Extract Key Insights (Grow):

• Domain Knowledge: Specific facts about the codebase, business logic, or problem domain

• Solution Patterns: Effective approaches that could be reused

• Anti-Patterns: Approaches to avoid and why

• Context Clues: Information that helps understand requirements better

• Quality Gates: Standards and criteria that led to better outcomes

Extract only high‑value, generalizable insights:

• Errors and Gaps

• Error identification → one line

• Root cause → one line

• Correct approach → imperative rule

• Key insight → decision rule or checklist item

• Repeatable Success Patterns

• When to apply, minimal preconditions, limits, quick example

• API/Tool Usage Rules

• Auth, pagination, rate limits, idempotency, error handling

• Verification Items

• Concrete checks/questions to catch regressions next time

• Pitfalls/Anti‑patterns

• What to avoid and why (evidence‑based)

Prefer specifics over generalities. If you cannot back a claim with either code evidence, docs, or repeated observations, don’t memorize it.

• Categorize by Impact:

• Critical: Insights that prevent major issues or unlock significant improvements

• High: Patterns that consistently improve quality or efficiency

• Medium: Useful context that aids understanding

• Low: Minor optimizations or preferences

Phase 2: Memory Curation Process

Step 1: Analyze Current CLAUDE.md Context

Read current context file

@CLAUDE.md

Assess what's already documented:

• What domain knowledge exists?

• Which patterns are already captured?

• Are there conflicting or outdated entries?

• What gaps exist that new insights could fill?

Step 2: Curation Rules (Refine)

For each insight identified in Phase 1 apply ACE’s “grow‑and‑refine” principle:

• Relevance: Only include items helpful for recurring tasks in this repo/org

• Non‑redundancy: Do not duplicate existing bullets; merge or skip if similar

• Atomicity: One idea per bullet; short, imperative, self‑contained

• Verifiability: Avoid speculative claims; link docs when stating external facts

• Safety: No secrets, tokens, internal URLs, or private PII

• Stability: Prefer strategies that remain valid over time; call out version‑specifics

Step 3: Apply Curation Transformation

Generation → Curation Mapping:

• Raw insight: [What was learned]

• Context category: [Where it fits in CLAUDE.md structure]

• Actionable format: [How to phrase it for future use]

• Validation criteria: [How to know if it's being applied correctly]

Example Transformation:

Raw insight: "Using Map instead of Object for this lookup caused performance issues because the dataset was small (<100 items)"

Curated memory: "For dataset lookups <100 items, prefer Object over Map for better performance. Map is optimal for 10K+ items. Use performance testing to validate choice."

Step 4: Prevent Context Collapse

Ensure new memories don't dilute existing quality context:

Consolidation Check:

• Can this insight be merged with existing knowledge?

• Does it contradict something already documented?

• Is it specific enough to be actionable?

Specificity Preservation:

• Keep concrete examples and code snippets

• Maintain specific metrics and thresholds where available

• Include failure conditions alongside success patterns

Organization Integrity:

• Place insights in appropriate sections

• Maintain consistent formatting

• Update related cross-references

If a potential bullet conflicts with an existing one, prefer the more specific, evidence‑backed rule and mark the older one for future consolidation (but do not auto‑delete).

Phase 3: CLAUDE.md Updates

Update the context file with curated insights:

Where to Write in CLAUDE.md

Create the file if missing with these sections (top‑level headings):

Project Context

• Domain Knowledge: Business domain insights

• Technical constraints discovered

• User behavior patterns

Code Quality Standards

• Performance criteria that matter

• Security considerations

• Maintainability patterns

Architecture Decisions

• Patterns that worked well

• Integration approaches

• Scalability considerations

Testing Strategies

• Effective test patterns

• Edge cases to always consider

• Quality gates that catch issues

Development Guidelines

• APIs to Use for Specific Information

• Formulas and Calculations

• Checklists for Common Tasks

• Review criteria that help

• Documentation standards

• Debugging techniques

Strategies and Hard Rules

• Verification Checklist

• Patterns and Playbooks

• Anti‑patterns and Pitfalls

Place each new bullet under the best‑fit section. Keep bullets concise and actionable.

Memory Update Template

For each significant insight, add structured entries:

[Domain/Pattern Category]

[Specific Context or Pattern Name]

Context: [When this applies]

Pattern: [What to do]

approach: [specific approach]
validation: [how to verify it's working]
examples:
  - case: [specific scenario]
    implementation: [code or approach snippet]
  - case: [another scenario]
    implementation: [different implementation]

Avoid: [Anti-patterns or common mistakes]

- [mistake 1]: [why it's problematic]

- [mistake 2]: [specific issues caused]

Confidence: [High/Medium/Low based on evidence quality]

Source: [reflection/critique/experience date]

Phase 4: Memory Validation

Quality Gates (Must Pass)

After updating CLAUDE.md:

- 
Coherence Check:

- Do new entries fit with existing context?

- Are there any contradictions introduced?

- Is the structure still logical and navigable?

- 
Actionability Test:  A developer should be able to use the bullet immediately

- Could a future agent use this guidance effectively?

- Are examples concrete enough?

- Are success/failure criteria clear?

- 
Consolidation Review: No near‑duplicates; consolidate wording if similar exists

- Can similar insights be grouped together?

- Are there duplicate concepts that should be merged?

- Is anything too verbose or too vague?

- 
Scoped: Names technologies, files, or flows when relevant

- 
Evidence‑backed: Derived from reflection/critique/tests or official docs

Memory Quality Indicators

Track the effectiveness of memory updates:

Successful Memory Patterns

- Specific Thresholds: "Use pagination for lists >50 items"

- Contextual Patterns: "When user mentions performance, always measure first"

- Failure Prevention: "Always validate input before database operations"

- Domain Language: "In this system, 'customer' means active subscribers only"

Memory Anti-Patterns to Avoid

- Vague Guidelines: "Write good code" (not actionable)

- Personal Preferences: "I like functional style" (not universal)

- Outdated Context: "Use jQuery for DOM manipulation" (may be obsolete)

- Over-Generalization: "Always use microservices" (ignores context)

Implementation Notes

- Incremental Updates: Add insights gradually rather than massive rewrites

- Evidence-Based: Only memorize patterns with clear supporting evidence

- Context-Aware: Consider project phase, team size, constraints when curating

- Version Awareness: Note when insights become obsolete due to tech changes

- Cross-Reference: Link related concepts within CLAUDE.md for better navigation

Expected Outcomes

After effective memory consolidation:

- Faster Problem Recognition: Agent quickly identifies similar patterns

- Better Solution Quality: Leverages proven approaches from past success

- Fewer Repeated Mistakes: Avoids anti-patterns that caused issues before

- Domain Fluency: Uses correct terminology and understands business context

- Quality Consistency: Applies learned quality standards automatically

Usage

# Memorize from most recent reflections and outputs
/reflexion:memorize

# Dry‑run: show proposed bullets without writing to CLAUDE.md
/reflexion:memorize --dry-run

# Limit number of bullets
/reflexion:memorize --max=5

# Target a specific section
/reflexion:memorize --section="Verification Checklist"

# Choose source
/reflexion:memorize --source=last|selection|chat:<id>

Output

- Short summary of additions (counts by section)

- Confirmation that CLAUDE.md
 was created/updated

Notes

- This command is the counterpart to /reflexion:reflect
: reflect → curate → memorize.

- The design follows ACE to avoid brevity bias and context collapse by accumulating granular, organized knowledge over time (https://arxiv.org/pdf/2510.04618
).

- Do not overwrite or compress existing context; only add high‑signal bullets.

Remember: The goal is not to memorize everything, but to curate high-impact insights that consistently improve future agent performance. Quality over quantity - each memory should make future work measurably better.