extract-learnings

Distill learnings from conversations and place them at the correct layer in the memory hierarchy for maximum agent attention. Bridges recall memory (past conversations) into archival memory (persistent, curated knowledge).

Memory Hierarchy

Learnings are placed based on scope, persistence needs, and attention priority. Closer to Layer 0 = loaded every session = more agent attention.

Placement Decision Tree

For each candidate learning, ask in order:

1. Project-independent behavioral preference? → Layer 0 (~/.claude/CLAUDE.md) Example: "Always use bun instead of npm", "Never auto-commit without asking"

2. Project-specific technical knowledge? → Layer 1 (<repo>/CLAUDE.md) Example: "FTS cascade: FTS5 → FTS4 → LIKE", "Always bump version in two files"

3. Concise working note the agent should see every session? → Layer 2 (MEMORY.md) Example: "v0.5.1: added Python 3.7 compat", "User prefers conventional commits"

4. Detailed reference too long for Layer 2? → Layer 3 (topic file in memory/) Example: Deep debugging guide, complex architecture notes, long reference tables

5. Repeatable workflow pattern? → Meta: suggest creating a skill or command Example: "We keep doing X manually → propose a skill for it"

Context Gathering Tools

Reuse the past-conversations tools when retrieval from prior sessions is needed.

recent_chats

python3 ${CLAUDE_PLUGIN_ROOT}/skills/past-conversations/scripts/recent_chats.py --n 10

search_conversations

python3 ${CLAUDE_PLUGIN_ROOT}/skills/past-conversations/scripts/search_conversations.py --query "keyword"

See the past-conversations skill for full option reference (--n, --project, --verbose, etc.).

Workflow

Four stages: Gather → Analyze → Propose → Execute. Never skip the proposal stage.

Stage 1: Context Gathering

Deduce intent from available context. Do not assume where learnings come from.

• Current conversation signal ("save this for next time", "remember this pattern"): Source material is already in context. Do not fetch past sessions.

• Past session signal ("we figured out that...", "remember when we..."): Use search_conversations.py or recent_chats.py to retrieve that context. Extract substantive keywords to build the query.

• Broad extraction request ("extract learnings from recent sessions"): Use recent_chats.py --n 10 to gather recent context.

• Ambiguous intent: Use AskUserQuestion to clarify what to extract and from where. Do not guess.

Stage 2: Analysis & Distillation

Identify candidate learnings from gathered context. For each candidate, determine: the learning itself (condensed to 1-2 sentences), the target layer (via the decision tree above), and the target section within that file.

Learning Categories

Stage 3: Placement Proposal

This is the critical stage. Never write without explicit approval.

1. Read current state of all target files that have candidates aimed at them. Only read files with pending changes.

2. Check for duplicates — scan target files for existing content covering the same concept. If already captured (even in different words), skip it and note the duplicate.

3. Present the proposal — for each learning, use this format:

   ### Learning: <one-line summary>
   **Target:** <file path> → <section name>
   **Rationale:** <why this layer, why this section>
   
   ```diff
   + <the exact line(s) to add>
   

4. Layer 0 extra gate — if any learning targets ~/.claude/CLAUDE.md, add an explicit warning: "This will be added to your global instructions loaded in every session across all projects. Confirm?"

5. MEMORY.md line check — if MEMORY.md is near the 200-line limit, warn and suggest moving content to topic files (Layer 3) to free space. Lines beyond 200 are truncated by the auto-memory system.

6. Get approval — use AskUserQuestion with options:

   • "Approve all" — apply all proposed changes
   • "Approve selectively" — let user pick which learnings to apply
   • "Reject and redirect" — user wants changes placed differently

Stage 4: Execution

Apply approved edits:

• Existing files (Layers 0-2): Use Edit to insert at the target section. Preserve existing structure and formatting.
• New topic files (Layer 3): Use Write to create memory/<topic>.md. Link from MEMORY.md if appropriate.
• Skill suggestions (Meta): Describe the proposed skill and let the user decide.

Output a summary table:

| Learning | Target | Status |
|----------|--------|--------|
| "Always use bun" | ~/.claude/CLAUDE.md | Applied |
| "FTS cascade order" | repo CLAUDE.md | Applied |
| "v0.6.0 changes" | MEMORY.md | Applied |

Content Quality Rules

Every candidate must pass these filters before being proposed.

DO persist

• Commands or workflows discovered through trial and error
• Non-obvious gotchas that caused debugging time
• Architectural decisions and their rationale
• Behavioral corrections from the user ("don't do X", "always do Y")
• Configuration quirks not obvious from reading code
• Package/module relationships not obvious from imports
• Version history milestones

DO NOT persist

• Information obviously readable from the code itself
• Generic programming best practices ("write tests", "use meaningful names")
• One-off bug fixes with no recurring pattern
• Verbose explanations — condense to a one-liner or skip
• Content already captured in the target file (semantic dedup)
• Temporary state or session-specific context
• Speculative conclusions not verified against the codebase

Must-pass checklist

Before proposing any learning:

• Would the agent benefit from knowing this in future sessions?
• Is it condensed to the minimum needed to be useful?
• Is it placed at the right layer (not too broad, not too narrow)?
• Does the target file not already contain this knowledge?

Examples

Example 1: Project gotcha → Layer 1

User: "save this — FTS triggers must be created after the tables, not before, or SQLite silently drops them"

This is a project-specific technical gotcha about the claude-memory codebase. Routes to Layer 1 (repo CLAUDE.md), Database section. Proposed addition: "FTS triggers must be created after their backing tables — SQLite silently drops triggers on nonexistent tables."

Example 2: Behavioral preference → Layer 0

User: "I keep forgetting to tell you — never run past-conversations unless I explicitly ask"

Universal behavioral preference, not project-specific. Routes to Layer 0 (global CLAUDE.md). Extra confirmation gate required since this affects all projects.

Example 3: Broad extraction → Multiple layers

User: "extract learnings from our recent sessions"

Gather via recent_chats.py --n 10. Identify 3-4 significant learnings across conversations. Propose each at its appropriate layer with diffs and rationale. Use AskUserQuestion for batch approval before writing anything.