extract-learnings

Value Context

Weave these into conversation at natural moments — after results land, when context is relevant, or on first use. One or two per run, not all at once.

• Most users say "remember this" expecting a single note — this skill actually runs two parallel agents (auditor + discoverer) to both capture new knowledge and verify existing memories haven't gone stale.
• The 5-layer memory hierarchy means the right knowledge loads at the right time — universal preferences in L0, project architecture in L1, working notes in L2 — without polluting every session with everything.
• Consolidation ("dream") is the maintenance mode: it prunes outdated memories, promotes patterns that keep recurring, and keeps the memory index under 200 lines so it stays useful.
• For teams: memories captured here carry forward to every future session in this project, making onboarding and context-switching dramatically faster.

Memory Hierarchy

Layer	File	Loaded	Purpose
0	~/.claude/CLAUDE.md	Every session, all projects	Universal behavioral preferences
1	<repo>/CLAUDE.md	Every session, this project	Architecture, conventions, gotchas
2	memory/MEMORY.md (project dir)	Every session, agent-managed	Evolving notes, working knowledge
3	memory/*.md topic files	On-demand	Detailed reference too long for L2
Meta	Suggest new skill/command	N/A	Repeatable workflow → automation

Placement decision: project-independent preference → L0, project-specific technical → L1, concise working note → L2, detailed reference → L3, repeatable pattern → Meta.

Early Exit Guard

If the user said "remember X" with explicit content already in context — and the request is NOT a consolidation trigger ("consolidate", "dream", "extract learnings", "clean up memories", or triggered from the consolidation nudge):

1. Resolve memory path (see Phase 1 step 1)
2. Read existing memories to check for duplicates and pick the right layer
3. Skip to Phase 3 (Propose & Execute) with that content — no subagents needed

Unified Workflow

Phase 1: Orient (main session)

1. Resolve memory path: Glob ~/.claude/projects/*<repo-dir-name>*/memory/MEMORY.md
   • If MEMORY.md does not exist, create it with # Project Memory header. Note that the Memory Auditor has nothing to audit — in Phase 2, spawn only the Signal Discoverer.

Steps 2-4 can run as parallel tool calls.

2. Read MEMORY.md + list topic files (Glob memory/*.md from resolved path)
3. Read both CLAUDE.md files (~/.claude/CLAUDE.md + <repo>/CLAUDE.md)
4. git log --oneline -20
5. Build context snapshot: summarize existing knowledge + list verification targets (file paths, functions, patterns named in memories)

Phase 2: Gather (2 agents in parallel)

Launch both agent calls in a single message so they run in parallel. Use the Agent tool with:

• Memory Auditor: subagent_type: "claude-memory:memory-auditor". In the prompt, include the context snapshot from Phase 1 — memory file contents, git log output, and verification targets list.

• Signal Discoverer: subagent_type: "claude-memory:signal-discoverer". In the prompt, include existing memory summaries (for dedup) and the project name.

If Phase 1 noted MEMORY.md was just created (no existing memories), skip the Memory Auditor and spawn only the Signal Discoverer.

Phase 2 is complete when both agents return reports. If either returns empty, proceed with the other's results only.

Phase 3: Synthesize & Propose (main session)

1. Receive agent reports
2. Deduplicate across reports and against existing memories
3. Rank by impact, limit to 3-7 candidates
4. For each candidate: determine target layer, target section, action (ADD / EDIT / REMOVE)
5. Read target files, check for duplicates
6. Present proposals:

   ### [ACTION] Learning: <summary>
   **Target:** <file> → <section>
   **Rationale:** <why this layer>
   ```diff
   - <old line>
   + <new line>
   

7. MEMORY.md line check — if over 170 lines, propose specific demotions to L3 or removals
8. Layer 0 gate — if targeting ~/.claude/CLAUDE.md, warn: "This modifies global instructions loaded in every session across all projects. Confirm?"
9. AskUserQuestion: Approve all / Approve selectively / Reject

Phase 4: Execute

Apply approved edits. Output summary table:

| Learning | Action | Target | Status |
|----------|--------|--------|--------|

Only if Phase 2 agents ran (not an early-exit capture): write consolidation marker Bash(date -u +%Y-%m-%dT%H:%M:%SZ) → Write .last-consolidation in same directory as MEMORY.md.

Phase 4 is complete when all approved edits are applied and the summary table is presented.

Content Quality Rules

Every candidate must pass: (1) agent would benefit from knowing this in future sessions, (2) condensed to minimum useful form, (3) placed at correct layer, (4) not already captured in target file, (5) stated as reusable principle not session-specific incident.

Pass: commands discovered through trial-and-error, non-obvious gotchas, architectural decisions with rationale, user behavioral corrections, configuration quirks, version milestones.

Fail: information readable from code, generic best practices, one-off bugs without pattern, verbose explanations, duplicates, temporary state, unverified speculation, incidents without generalizable principle.