CRUX Skill: Memory Extract

Analyses execution artifacts from a completed unit of work, compares candidates against existing memories for novelty and conflicts, and presents ranked candidate facts for the user to accept, modify, or reject.

When to Use

Use this skill when:

• A unit of work (e.g. spec) has completed execution and you want to extract memories from it
• The /crux-dream command is invoked for a specific completed work item
• The crux-memory-dream agent orchestrates a dream workflow

Prerequisites

Before any operation:

1. Read config: Load .crux/crux-memories.json. This skill needs flags.enableMemories, cruxMemories.unitOfWork, cruxMemories.dream.* (maxCandidateFacts, maxUnrelatedChanges, stateFile, workDir), cruxMemories.storage.memoriesDir / agentMemoriesDir, and cruxMemories.typePriority. Defaults and full key descriptions live in .cursor/skills/_memory-shared.md#config-reference and .crux/crux-memories.json (authoritative).
2. Guard check: If flags.enableMemories is not "true", refuse all operations and inform the caller that memories are disabled.

Operations

1. Verify Execution

Confirm the unit of work completed successfully before extracting memories.

Input: Path to the work item directory (e.g. specs/20260403-crux-memories/)

Path validation — CRITICAL: The work item directory MUST be a subdirectory of the configured workDir (cruxMemories.dream.workDir, default specs). If the provided path points to a directory outside workDir, abort with an error listing the available specs from workDir. Do not search .ai-ignored/specs/, .ai-ignored/executed/, or other directories.

Steps:

1. Verify the work item directory exists within the configured workDir; if not, abort and list available specs
2. Look for the configured stateFile (default _execution-state.yml) inside the work item directory
3. Parse the state file and check the status field
4. If status is not complete (or equivalent success state), report the current status and abort extraction — incomplete work items should not produce memories
5. If no state file exists, return a needs_user_input response asking whether to proceed anyway (the work item may have been executed outside the standard workflow) — the calling agent will ask the user and resume you with the decision
6. Record the execution start date from the state file for use in diff analysis

2. Diff Analysis

Assess the scope of repository changes since the work item started to determine if extraction is meaningful.

Steps:

1. Determine the change boundary:
   • If the state file contains a start commit hash or timestamp, use it as the diff baseline
   • Otherwise, use the work item directory's creation date or earliest file modification as an approximation
2. Count the number of changed files in the repository since the baseline
3. Compare the count against maxUnrelatedChanges (default 50)
4. If the count exceeds the threshold:
   • Return a needs_user_input response with the warning: "Found {count} changed files since {unitOfWork} start (threshold: {maxUnrelatedChanges}). Many changes may be unrelated to this {unitOfWork}, which could reduce extraction quality."
   • Include options: proceed anyway, increase threshold, or abort — the calling agent will present these to the user and resume you with the decision
5. If within threshold, report the count and continue

The purpose of this check is to avoid extracting noise from unrelated work that happened concurrently.

3. Analyse Artifacts

Read all available execution artifacts and identify candidate facts.

Artifacts to examine (in the work item directory):

What to extract:

• Learnings: techniques, approaches, or insights that worked
• Red flags: bugs, anti-patterns, pitfalls, or mistakes discovered
• Goals: performance targets achieved or set, quality metrics established
• Ideas: speculative improvements, future work, or experiments suggested
• Core patterns: fundamental approaches that should always be followed

Extraction heuristics:

• Look for explicit statements of insight ("we learned that...", "this approach worked because...", "avoid doing X because...")
• Look for measurable outcomes (performance numbers, error rate changes, time savings)
• Look for recurring patterns across subtasks (if multiple subtasks hit the same issue, it is likely a strong candidate)
• Look for workarounds or non-obvious solutions (these often make the best memories)
• Look for agent-identified recommendations in work logs
• Ignore trivial or mechanical observations (e.g. "we created a file" or "we ran tests")

4. Compare with Existing Memories

Load existing memories and filter candidates for novelty.

Steps:

1. Scan configured memoriesDir and agentMemoriesDir recursively for all *.memory.md and *.memory.crux.md files
2. Read the frontmatter of each existing memory (title, description, type, tags)
3. For each candidate fact from step 3, compare against existing memories:
   • Exact duplicate: A memory with the same core insight already exists → discard the candidate
   • Near duplicate: A memory covers a very similar topic but with different details → flag for potential merge or update rather than creating a new memory
   • Related but distinct: Existing memories touch the same domain but this candidate adds genuinely new information → keep the candidate, note the related memories
   • Novel: No existing memory covers this territory → keep the candidate
4. Remove exact duplicates from the candidate list
5. Annotate near-duplicates with the existing memory they overlap and a suggested action (merge, update, or keep both)

5. Conflict Detection

Identify candidates that contradict existing memories.

Steps:

1. For each remaining candidate, check whether it directly contradicts an existing memory. Contradiction means the candidate and existing memory give opposing guidance on the same topic. Examples:
   • Candidate says "always use approach X" while existing memory says "avoid approach X"
   • Candidate reports a pattern works well while existing memory flags the same pattern as a red flag
   • Candidate sets a performance target that conflicts with an existing goal
2. For each detected conflict, prepare a conflict report:

⚠️ Conflict detected:

  Candidate: [candidate title]
  [candidate description]

  Conflicts with existing memory:
  File: [path to existing memory]
  Title: [existing memory title]
  [existing memory description]

  Resolution options:
  1. Keep existing — discard the candidate
  2. Replace — update the existing memory with the candidate's insight
  3. Merge — combine both perspectives into a single memory
  4. Keep both — retain both with disambiguation notes explaining when each applies

3. Conflicts always require user input — they are never auto-resolved, even in --yolo mode

6. Classify Type

Assign each candidate a memory type based on content analysis.

Classification heuristics:

When classification is ambiguous, prefer the lower-priority type (e.g. prefer learning over core). The memory can be promoted later through strength and reference tracking.

Validate the assigned type against typePriority from config. Do not assign archived — that type is only set through the rebalance workflow.

7. Agent Scoping

Determine whether each candidate should be a base memory or an agent-scoped memory.

Steps:

1. Examine the work item's execution artifacts for agent identification:
   • Subtask assignments that name specific agents (e.g. "Assigned Subagent: code-reviewer")
   • Work logs from specific agent personas
   • Changes made by specific agent types
2. For each candidate, determine if the insight is agent-specific:
   • Agent-specific: The insight relates to a specific agent's domain (e.g. review patterns for a code-reviewer, test strategies for a test-generator). Mark for placement in memories/agents/{agent-id}/{type}/
   • General-purpose: The insight applies broadly regardless of which agent is working. Place in the base memories/{type}/ directory
3. When in doubt, place in base — general-purpose learnings benefit all agents. Only scope to an agent when the memory is clearly specific to that agent's concerns
4. Record the target scope in the candidate metadata

8. Rank Candidates

Order candidates by estimated value and present the top N.

Ranking criteria (in priority order):

1. Type priority: Higher-priority types rank first (per typePriority config: core > redflag > goal > learning > idea)
2. Measurability: Candidates with quantitative evidence (performance numbers, error rates, time savings) rank higher than qualitative observations
3. Recurrence: Patterns that appeared multiple times across subtasks rank higher
4. Actionability: Insights that give clear, specific guidance rank higher than vague observations
5. Novelty: Candidates that cover genuinely new territory (no near-duplicates) rank higher

Steps:

1. Score each candidate using the criteria above
2. Sort by score descending
3. Take the top maxCandidateFacts candidates (default 5)
4. If more candidates remain beyond the limit, note how many were excluded and offer to show them

9. Resolved Bug Detection

Identify existing redflag memories whose bugs or anti-patterns appear to have been fixed by the completed work.

Steps:

1. From the existing memories loaded in step 4, filter to those with type: redflag
2. For each redflag memory, compare its described bug/anti-pattern against:
   • Code changes: Does the diff show changes that directly address the issue described in the redflag? (e.g. the anti-pattern was refactored away, the bug-causing code was rewritten)
   • Subtask outcomes: Did any subtask explicitly mention fixing, resolving, or addressing this specific issue?
   • Pattern removal: Was the problematic pattern described by the redflag removed or replaced with the recommended approach?
3. Classify each redflag into one of:
   • Likely resolved: Strong evidence — the diff contains changes that directly fix the described bug or remove the anti-pattern, or a subtask explicitly states the issue was resolved
   • Possibly resolved: Partial evidence — related code was changed but it is not conclusive whether the specific issue was fully addressed
   • Still active: No evidence of resolution — skip, do not present to the user
4. Only present redflags classified as "likely resolved" or "possibly resolved"
5. For each, prepare a resolution report (see Resolved Bug Format below)

Heuristics for matching redflags to changes:

• Compare the redflag's tags against changed file paths and content (e.g. a redflag tagged [testing, fixtures] matching changes in test files)
• Check if the redflag's "Solution" or "Prevention" section describes an approach that now appears in the codebase
• Check if the specific file, function, or pattern named in the redflag body was modified
• When in doubt, classify as "possibly resolved" rather than "likely resolved" — the user makes the final call

Resolved Bug Format

Each potentially-resolved redflag is presented with these fields:

memory_path: "memories/redflag/example-bug.memory.md"
title: "Example bug title from the memory"
confidence: "likely"          # or "possibly"
evidence: "The diff shows refactoring of X to use the recommended approach described in this memory's Solution section."
recommendation: "forget"      # always "forget" — user decides

All fields are required. confidence is likely or possibly; recommendation is always forget (user decides).

Candidate Fact Format

Each candidate is presented with these fields:

rank: 1
type: "learning"
title: "React.memo on list items reduced re-render time from 480ms to 12ms"
description: "Wrapping list item components in React.memo with a custom comparator that checks item ID and version (not deep-equal) reduced re-render time by 97% on a 500-item list."
tags: [react, performance, rendering, memoization]
scope: "base"                    # or "agents/{agent-id}"
rationale: "Quantitative performance improvement discovered during component library subtask. Recurred across 3 subtasks involving list rendering."
conflicts: []                    # or list of conflict reports
related_memories: []             # existing memories on similar topics
source: "20260401-component-library"  # work item identifier

All fields required except conflicts and related_memories. type must be one of the typePriority values (never archived). scope is "base" or "agents/{agent-id}". source mirrors the work-directory slug.

Response Format

This skill follows Pattern B — perform analysis and ranking first, then return results for the calling agent to present. Do NOT call AskQuestion; the calling agent handles all user interaction (see .cursor/skills/_memory-shared.md#user-input-escalation). Include the following structure in your response:

Analysing {unitOfWork} "{work-item-id}"...
✅ Execution verified: {subtask-count} subtasks complete
📊 {change-count} repo changes since start (within threshold)

Comparing with {existing-count} existing memories...

Top {N} candidate facts:

  1. [{type}] {title}
     {description}
     Tags: {tags}
     Scope: {scope}
     Rationale: {rationale}

  2. [{type}] {title}
     ...

  {conflict reports, if any}

If resolved bugs were detected, include them in a separate section:

🐛 Resolved bugs detected — {count} redflag memories may no longer be needed:

  1. [{confidence}] {title}
     File: {memory_path}
     Evidence: {evidence}

  2. [{confidence}] {title}
     ...

The calling agent will use AskQuestion to collect the user's accept/skip decisions for both candidates and resolved bugs, then pass those decisions back to you.

Each resolved bug the user confirms is deleted via crux-skill-memory-crud Delete operation (memory file and its reference tracker are both removed).

In --yolo mode:

• Auto-accept all new candidates except those with conflicts (conflicts always require user input)
• Auto-forget redflags classified as "likely" resolved
• Present "possibly" resolved redflags for user confirmation (insufficient confidence for auto-deletion)

After the user accepts candidates (all or individually), delegate to crux-skill-memory-crud for actual file creation. Pass the candidate's type, title, description, tags, source, and scope (agent-id if agent-scoped) directly to the CRUD skill's Create operation.

After the user confirms resolved bugs for deletion, delegate to crux-skill-memory-crud Delete operation. The memory file and its reference tracker are both removed.

Error Handling

Out-of-scope and cross-skill delegation: see .cursor/skills/_memory-shared.md#cross-skill-boundaries and the agent table in AGENTS.md.