NodeJSmith/cm-extract-learnings

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 using Bash (Glob does not expand ~): Bash: find $HOME/.claude/projects -name MEMORY.md -path "*<repo-dir-name>*" 2>/dev/null | head -1 The result is the full path to MEMORY.md (a file). Run a second Bash call — dirname <find-result> — to print the memory directory path. Use that printed path in subsequent steps. If no result, construct the project key by replacing / with - in the current working directory path (e.g., /home/user/myrepo → -home-user-myrepo), then use $HOME/.claude/projects/<project-key>/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 are required and 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) — 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: "cm-memory-auditor". In the prompt, include the context snapshot from Phase 1 — memory file contents, git log output, and verification targets list. Remind: "Report findings only — do not write any files."

• Signal Discoverer: subagent_type: "cm-signal-discoverer". In the prompt, include existing memory summaries (for dedup) and the project name. Remind: "Report findings only — do not write any files."

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

Both agents require maxTurns ≥ 30 — verify agent frontmatter at agents/cm-memory-auditor.md and agents/cm-signal-discoverer.md. Agents with low maxTurns exit early and return truncated output that appears non-empty but contains no findings.

Phase 2 is complete when both agents return reports. If either returns empty or clearly truncated (one line, no structured findings), proceed with the other's results — but if the Signal Discoverer fails, also perform a manual fallback: run cm-recent-chats --n 5 --format json and apply the signal criteria from the Content Quality Rules section below. If cm-recent-chats fails, surface the error: "cm-recent-chats not found — run uv tool install -e packages/claude-memory to install the claude-memory package."

Phase 3: Synthesize & Propose (main session)

1. Receive agent reports
2. Deduplicate across reports and against existing memories
3. Apply acceptance criteria to each candidate — all must pass:
   • Durability: still true in 6 months once paths, SHAs, tool versions, and code shapes have changed
   • Specificity: broad enough to apply across tasks, precise enough that a future agent recognizes when to use it. Reject vague platitudes ("write good code") and hyper-specific facts
   • Convergence: findings echoed by both agents or across multiple sessions carry higher confidence. Singletons must clear a higher bar on the other criteria
   • Decision-changing: a future agent does something different because of this memory, not just reads more text
   • Structural-mechanism check: reject when a lint rule, hook, or CI check already enforces the rule or could enforce it cheaply. Memory is for things mechanisms cannot enforce
4. Rank survivors by impact, limit to 3-5 candidates
5. For each candidate: determine target layer, target section, action (ADD / EDIT / REMOVE)
6. Read target files, check for duplicates
7. Present proposals:

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

8. MEMORY.md line check — if over 170 lines, propose specific demotions to L3 or removals
9. Layer 0 gate — if targeting ~/.claude/CLAUDE.md, warn: "This modifies global instructions loaded in every session across all projects. Confirm?"
10. 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 using Bash (Write tool requires prior Read and cannot create new files): Bash: date -u +%Y-%m-%dT%H:%M:%SZ > <memory-dir>/.last-consolidation

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 that reflect recurring risk, configuration quirks, cross-cutting preferences confirmed across multiple sessions.

Fail: information readable from code, generic best practices, one-off bugs without pattern, verbose explanations, duplicates, temporary state, unverified speculation, incidents without generalizable principle, library behavior that's in the docs, process rules better enforced by tooling, hyper-specific corrections for situations unlikely to recur.

Pruning at Proposal Time

When reviewing Signal Discoverer output before presenting to the user, actively prune:

• Candidates that address a one-time incident with no recurring surface area
• Candidates where the "principle" is just a restatement of how a well-documented tool works
• Candidates that fail the acceptance criteria in Phase 3 step 3 (durability, specificity, convergence, decision-changing, structural-mechanism check)
• Aim for 3-5 proposals, not 6-10. Quality over quantity.