extract-candidate-memories

name	extract-candidate-memories
description	Use when reading a SUMMARY.md or REVIEW.md to identify long-term-valuable insights worth committing to project or user memory. Required for the orchestrator agent after each task completion.

Extract Candidate Memories

Your job: read a task's SUMMARY.md (and REVIEW.md if present), identify items worth remembering long-term, and emit candidate memory entries.

What Qualifies as a Memory

Memory is for things that will be true tomorrow, next week, next month. Things that:

• Affect future code in this project (project memories)
• Reveal user preferences or workflow choices (feedback memories)
• Document non-obvious tooling/library decisions (project memories)
• Point to external resources for ongoing context (reference memories)

Memory is NOT for:

• One-off task details (that's what SUMMARY.md is for)
• Code patterns derivable from the codebase
• Git history facts (use git log)
• Temporary state or in-progress work

Categories Available

Type	When to use
project	Codebase-specific decisions, ongoing context, gotchas, deployment quirks
feedback	User preferences expressed during this task ("don't do X", "always Y")
reference	Pointers to external systems (Linear project, Slack channel, dashboard URL)
user	Things learned about the user themselves (rare during task execution)

The Extraction Process

1. Read the SUMMARY's "Notes for downstream tasks" section

Most candidates live here. The implementer wrote them because they thought future work might need them.

For each note, ask: "Will this still be relevant after this feature ships?"

• YES → likely a project memory candidate
• NO (only relevant within this feature) → keep as task context, not memory

2. Read the SUMMARY's "Deviations" section

When the implementer deviates from the spec for a real reason (technical constraint, library bug, build issue), the reason is often memory-worthy.

Examples:

• "Used bcryptjs instead of bcrypt — native compile fails on Alpine" → project memory (will be true next time too)
• "Used 4-space indent because the file already had 4-space indent" → NOT memory (derivable from the file)

3. Read the REVIEW's findings (if present)

If a finding was classified as bad_spec or intent_gap, the resolution often reveals a long-term truth. Look for "we decided X because Y" patterns.

4. Read user interactions captured in the SUMMARY

If the user clarified something ("for this app, always use Y instead of X"), that's almost always a feedback memory.

Output Format

Emit a YAML list of candidate memories:

candidate_memories:
  - type: project
    name: bcrypt-alpine-incompatibility
    description: Use bcryptjs not bcrypt on this codebase due to Alpine native compile failures
    body: |
      The Docker base image is Alpine-based. bcrypt's native modules fail to compile.
      Use bcryptjs (pure JS) instead. Performance difference is negligible at our scale.
  - type: feedback
    name: explicit-error-messages
    description: User prefers error messages that name the failing field
    body: |
      During task-02, user corrected a generic "validation failed" error.
      Use specific messages like "email field is invalid: must be a valid email address".
      Reason: helps debugging in production logs.

Each candidate gets passed back to the orchestrator, which decides whether to commit it via the auto-memory system.

The "Will Future Me Be Glad I Saved This?" Test

For every candidate, imagine working on this codebase 6 weeks from now. Would having this memory load automatically at the start of a related task save you from rediscovering it the hard way?

• Yes → save it
• Probably not → skip

When in doubt: skip. Memory bloat is real. Better to have 20 high-signal memories than 200 mediocre ones.

What NOT to Save

• "Task X created file Y" — covered by git history and SUMMARY
• "Test command is npm test" — covered by package.json
• "We decided to use TypeScript" — covered by tsconfig.json existing
• "User wanted feature X" — covered by the ticket/PLAN.md
• Anything that contradicts what's already in CLAUDE.md or other project docs

Special Case: Conflicting Memories

If you find a candidate that contradicts an existing memory, surface it in the output:

candidate_memories:
  - type: conflict
    existing_memory: bcrypt-is-fine
    reason: "Existing memory says bcrypt works, but task-01 found Alpine incompatibility. Update or remove the existing memory."

The orchestrator handles the resolution.