Memory Consolidation: Curate and Update CLAUDE.md

Output must add precise, actionable bullets that future tasks can immediately apply. </context>

Memory Consolidation Workflow

Phase 1: Context Harvesting

First, gather insights from recent reflection and work:

1. 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.)”

2. 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.

3. 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:

1. Consolidation Check:

   • Can this insight be merged with existing knowledge?
   • Does it contradict something already documented?
   • Is it specific enough to be actionable?

2. Specificity Preservation:

   • Keep concrete examples and code snippets
   • Maintain specific metrics and thresholds where available
   • Include failure conditions alongside success patterns

3. 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):

1. Project Context

   • Domain Knowledge: Business domain insights
   • Technical constraints discovered
   • User behavior patterns

2. Code Quality Standards

   • Performance criteria that matter
   • Security considerations
   • Maintainability patterns

3. Architecture Decisions

   • Patterns that worked well
   • Integration approaches
   • Scalability considerations

4. Testing Strategies

   • Effective test patterns
   • Edge cases to always consider
   • Quality gates that catch issues

5. Development Guidelines

   • APIs to Use for Specific Information
   • Formulas and Calculations
   • Checklists for Common Tasks
   • Review criteria that help
   • Documentation standards
   • Debugging techniques

6. 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]
```yaml
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:

1. Coherence Check:

   • Do new entries fit with existing context?
   • Are there any contradictions introduced?
   • Is the structure still logical and navigable?

2. 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?

3. 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 o