/extract-learnings

name: extract-learnings
description: >
  Persist learnings to memory or maintain existing memories. Triggers on
  "extract learnings", "save this for next time", "remember this pattern",
  "consolidate memories", "dream", "clean up memories".
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash(python3:*)
  - Bash(git:*)
  - Bash(find:*)
  - Bash(date:*)
  - Bash(trash:*)
  - AskUserQuestion
  - Agent

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.

• A plain "remember this" saves one note fast; a consolidation run goes further, running two agents in parallel (auditor + discoverer) that capture new knowledge and check that 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 and low-value memories, merges overlaps, and clusters overflowing sections so the always-loaded index stays small.
• Memories captured here carry forward to every future session in this project. Only L1 (the repo's CLAUDE.md) reaches teammates; L2/L3 memory lives in the user's own `~/.claude` directory.

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 | Top index: working notes + pointers to clusters/topics | | 2c | `memory/clusters/*.md` sub-index | On-demand (after a section overflows) | Section sub-index split off MEMORY.md to cap always-loaded size | | 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.

Adaptive clustering: keep MEMORY.md flat until a section exceeds 25 entries; then move that section's pointers into `memory/clusters/<section>.md` and replace the section in MEMORY.md with a single pointer to it. Only MEMORY.md loads every session, so this caps startup cost while detail stays on-demand.

Pointer Format

Every MEMORY.md and cluster entry is a load trigger, not a label — a future session must recognize its current task in the pointer and open the file. A pointer that only names a file gets ignored, so the index loads without ever being used. Two shapes:

• Triggered (default): `**When <task-condition>:** <one-line takeaway>. → [detail](file.md)`. Use whenever a sharp "when" can be written — e.g. `**When compositing a face onto a turned head:** align centers, tight ellipse. → [detail](feedback_composite_align_tight_ellipse.md)`.
• Always-on: `<terse fact>. → [detail](file.md)`. Only for rules that apply in every relevant session (locked context, global preferences), where a condition would be fake.

Choose triggered if you can name the task that should open the file; choose always-on only when the rule applies regardless of task. Cluster files carry a short always-on block at the top, then a trigger-index — every other entry is a condition pointer. Do not inline full rule bodies in a cluster; it routes to topic files, detail lives in them.

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 the memory directory. If the session's system prompt names a persistent memory directory, use it. Otherwise derive the project key the way the consolidation-check hook does, so the Phase 4 marker lands where the hook reads it: take the working directory, cut everything from `/.claude/worktrees/` onward so a worktree resolves to its base repo, then replace `/`, `:` and `.` with `-` (e.g. `/home/user/my.repo/.claude/worktrees/fix` → `-home-user-my-repo`). The directory is `$HOME/.claude/projects/<project-key>/memory/` — use Bash for `$HOME`; Glob does not expand `~`.

• 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 are required and run as parallel tool calls.

2. Read MEMORY.md + list topic and cluster files (`Glob memory/**/*.md` from resolved path) 3. Read both CLAUDE.md files (`~/.claude/CLAUDE.md` + `<repo>/CLAUDE.md`) — required for dedup quality; skipping means proposals may duplicate L0/L1 content 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. Instruct it to surface retirement and merge candidates (SUPERSEDED / REDUNDANT / LOW-VALUE / MERGE), not only factually stale entries — downward pressure is the point of consolidation.

• **Signal Discoverer**: `subagent_type: "claude-memory:signal-di