Session Learning Skill

Purpose

This skill provides cross-session learning by:

Extracting learnings from session transcripts at Stop hook
Storing learnings in structured YAML format (
```
~/.amplihack/.claude/data/learnings/
```
)
Injecting relevant past learnings at SessionStart based on task similarity
Managing learnings via
```
/amplihack:learnings
```
capability

Design Philosophy

Ruthlessly Simple Approach:

One YAML file per learning category (not per session)
Simple keyword matching for relevance (no complex ML)
Complements existing DISCOVERIES.md/PATTERNS.md - doesn't replace them
Fail-safe: Never blocks session start or stop

Learning Categories

Learnings are stored in five categories:

Category	File	Purpose
errors	`errors.yaml`	Error patterns and their solutions
workflows	`workflows.yaml`	Workflow insights and shortcuts
tools	`tools.yaml`	Tool usage patterns and gotchas
architecture	`architecture.yaml`	Design decisions and trade-offs
debugging	`debugging.yaml`	Debugging strategies and root causes

YAML Schema

Each learning file follows this structure:

yaml

# .claude/data/learnings/errors.yaml
category: errors
last_updated: "2025-11-25T12:00:00Z"
learnings:
  - id: "err-001"
    created: "2025-11-25T12:00:00Z"
    keywords:
      - "import"
      - "module not found"
      - "circular dependency"
    summary: "Circular imports cause 'module not found' errors"
    insight: |
      When module A imports from module B and module B imports from module A,
      Python raises ImportError. Solution: Move shared code to a third module
      or use lazy imports.
    example: |
      # Bad: circular import
      # utils.py imports from models.py
      # models.py imports from utils.py

      # Good: extract shared code
      # shared.py has common functions
      # both utils.py and models.py import from shared.py
    confidence: 0.9
    times_used: 3

When to Use This Skill

Automatic Usage (via hooks):

At session stop: Extracts learnings from transcript
At session start: Injects relevant learnings based on prompt keywords

Manual Usage:

When you want to view/manage learnings
When debugging and want to recall past solutions
When onboarding to understand project-specific patterns

Learning Extraction Process

Step 1: Analyze Session Transcript

At session stop, scan for:

Error patterns: Errors encountered and how they were solved
Workflow insights: Steps that worked well or poorly
Tool discoveries: New ways of using tools effectively
Architecture decisions: Design choices and their rationale
Debugging strategies: Root cause analysis patterns

Step 2: Extract Structured Learning

For each significant insight:

Generate unique ID based on category and timestamp
Extract keywords from context (3-5 relevant terms)
Create one-sentence summary
Write detailed insight with explanation
Include code example if applicable
Assign confidence score (0.5-1.0)

Step 3: Merge with Existing Learnings

Check for duplicate learnings using keyword overlap
If similar learning exists (>60% keyword match), update confidence
Otherwise, append new learning to category file

Learning Injection Process

Step 1: Extract Task Keywords

From session start prompt, extract:

Technical terms (languages, frameworks, tools)
Problem indicators (error, fix, debug, implement)
Domain keywords (api, database, auth, etc.)

Step 2: Find Relevant Learnings

For each learning category:

Load learnings from YAML
Calculate keyword overlap with task

Rank by

overlap_score * confidence * recency_weight

Select top 3 most relevant learnings

Step 3: Inject Context

Format relevant learnings as context:

markdown

## Past Learnings Relevant to This Task

### [Category]: [Summary]

## [Insight with example if helpful]

Usage Examples

Example 1: Automatic Extraction

Session: Debugging circular import issue in Neo4j module
Duration: 45 minutes
Resolution: Moved shared types to separate file

Extracted Learning:
- Category: errors
- Keywords: [import, circular, neo4j, type]
- Summary: Circular imports in Neo4j types cause ImportError
- Insight: When Neo4jNode imports from connection.py which imports
  Node types, move types to separate types.py module
- Example: types.py with dataclasses, connection.py imports from types.py

Example 2: Automatic Injection

Session Start Prompt: "Fix the import error in the memory module"

Matched Learnings:
1. errors/err-001: "Circular imports cause 'module not found' errors" (85% match)
2. debugging/dbg-003: "Use `python -c` to isolate import issues" (60% match)

Injected Context:
## Past Learnings Relevant to This Task

### Errors: Circular imports cause 'module not found' errors
When module A imports from module B and B imports from A, Python raises
ImportError. Solution: Move shared code to a third module or use lazy imports.
---

Example 3: Manual Management

User: Show me what I've learned about testing

Claude (using this skill):
1. Reads .claude/data/learnings/workflows.yaml
2. Filters learnings with keywords containing "test"
3. Displays formatted list with summaries and examples

Keyword Matching Algorithm

Simple but effective matching:

python

def calculate_relevance(task_keywords: set, learning_keywords: set) -> float:
    """Calculate relevance score between 0 and 1."""
    if not task_keywords or not learning_keywords:
        return 0.0

    # Count overlapping keywords
    overlap = task_keywords & learning_keywords

    # Score: overlap / min(task, learning) to not penalize short queries
    return len(overlap) / min(len(task_keywords), len(learning_keywords))

Integration Points

With Stop Hook

The stop hook can call this skill to extract learnings:

Parse transcript for significant events
Identify error patterns, solutions, insights
Store in appropriate category YAML
Log extraction summary

With Session Start Hook

The session start hook can inject relevant learnings:

Parse initial prompt for keywords
Find matching learnings across categories
Format as context injection
Include in session context

With /amplihack:learnings Command

Command interface for learning management:

```
/amplihack:learnings show [category]
```
- Display learnings
```
/amplihack:learnings search <query>
```
- Search across all categories
```
/amplihack:learnings add
```
- Manually add a learning
```
/amplihack:learnings stats
```
- Show learning statistics

Quality Guidelines

When to Extract

Extract a learning when:

Solving a problem that took >10 minutes
Discovering non-obvious tool behavior
Finding a pattern that applies broadly
Making an architecture decision with trade-offs

When NOT to Extract

Skip extraction when:

Issue was trivial typo or syntax error
Solution is already in DISCOVERIES.md or PATTERNS.md
Insight is too project-specific to reuse
Confidence is low (<0.5)

Learning Quality Checklist

Keywords are specific and searchable
Summary is one clear sentence
Insight explains WHY, not just WHAT
Example is minimal and runnable
Confidence reflects actual certainty

File Locations

.claude/
  data/
    learnings/
      errors.yaml        # Error patterns and solutions
      workflows.yaml     # Workflow insights
      tools.yaml         # Tool usage patterns
      architecture.yaml  # Design decisions
      debugging.yaml     # Debugging strategies
      _stats.yaml        # Usage statistics (auto-generated)

Comparison with Existing Systems

Feature	DISCOVERIES.md	PATTERNS.md	Session Learning
Format	Markdown	Markdown	YAML
Audience	Humans	Humans	Agents + Humans
Storage	Single file	Single file	Per-category files
Matching	Manual read	Manual read	Keyword-based auto
Injection	Manual	Manual	Automatic
Scope	Major discoveries	Proven patterns	Any useful insight

Complementary Use:

Use DISCOVERIES.md for major, well-documented discoveries
Use PATTERNS.md for proven, reusable patterns with code
Use Session Learning for quick insights that help future sessions

Error Handling

YAML Parsing Errors

If a learning file becomes corrupted or invalid:

python

import yaml
from pathlib import Path

def safe_load_learnings(filepath: Path) -> dict:
    """Load learnings with graceful error handling."""
    try:
        content = filepath.read_text()
        data = yaml.safe_load(content)
        if not isinstance(data, dict) or "learnings" not in data:
            print(f"Warning: Invalid structure in {filepath}, using empty learnings")
            return {"category": filepath.stem, "learnings": []}
        return data
    except yaml.YAMLError as e:
        print(f"Warning: YAML error in {filepath}: {e}")
        # Create backup before recovery
        backup = filepath.with_suffix(".yaml.bak")
        filepath.rename(backup)
        print(f"Backed up corrupted file to {backup}")
        return {"category": filepath.stem, "learnings": []}
    except Exception as e:
        print(f"Warning: Could not read {filepath}: {e}")
        return {"category": filepath.stem, "learnings": []}

Missing Files

If the learnings directory doesn't exist, create it:

python

def ensure_learnings_directory():
    """Create learnings directory and empty files if missing."""
    learnings_dir = Path(".claude/data/learnings")
    learnings_dir.mkdir(parents=True, exist_ok=True)

    categories = ["errors", "workflows", "tools", "architecture", "debugging"]
    for cat in categories:
        filepath = learnings_dir / f"{cat}.yaml"
        if not filepath.exists():
            filepath.write_text(f"category: {cat}\nlearnings: []\n")

Fail-Safe Principle

The learning system follows fail-safe design:

Never blocks session start: If injection fails, session continues normally
Never blocks session stop: If extraction fails, session ends normally
Logs warnings but continues: Errors are logged, not raised
Creates backups before modifications: Corrupt files are preserved

Hook Integration

Stop Hook: Learning Extraction

Add learning extraction to your stop hook:

python

# .claude/tools/amplihack/hooks/stop_hook.py

async def extract_session_learnings(transcript: str, session_id: str):
    """Extract learnings from session transcript at stop."""
    from pathlib import Path
    import yaml
    from datetime import datetime

    # Only extract if session was substantive (not just a quick question)
    if len(transcript) < 1000:
        return

    # Use Claude to extract insights (simplified example)
    extraction_prompt = f"""
    Analyze this session transcript and extract any reusable learnings.

    Categories:
    - errors: Error patterns and solutions
    - workflows: Process improvements
    - tools: Tool usage insights
    - architecture: Design decisions
    - debugging: Debug strategies

    For each learning, provide:
    - category (one of the above)
    - keywords (3-5 searchable terms)
    - summary (one sentence)
    - insight (detailed explanation)
    - example (code if applicable)
    - confidence (0.5-1.0)

    Transcript:
    {transcript[:5000]}  # Truncate for token limits
    """

    # ... call Claude to extract ...
    # ... parse response and add to appropriate YAML files ...

def on_stop(session_data: dict):
    """Stop hook entry point."""
    # ... other stop hook logic ...

    # Extract learnings (non-blocking)
    try:
        import asyncio
        asyncio.create_task(
            extract_session_learnings(
                session_data.get("transcript", ""),
                session_data.get("session_id", "")
            )
        )
    except Exception as e:
        print(f"Learning extraction failed (non-blocking): {e}")

Session Start Hook: Learning Injection

Add learning injection to your session start hook:

python

# .claude/tools/amplihack/hooks/session_start_hook.py

def inject_relevant_learnings(initial_prompt: str) -> str:
    """Find and format relevant learnings for injection."""
    from pathlib import Path
    import yaml

    learnings_dir = Path(".claude/data/learnings")
    if not learnings_dir.exists():
        return ""

    # Extract keywords from prompt
    prompt_lower = initial_prompt.lower()
    task_keywords = set()
    for word in prompt_lower.split():
        if len(word) > 3:  # Skip short words
            task_keywords.add(word.strip(".,!?"))

    # Find matching learnings
    matches = []
    for yaml_file in learnings_dir.glob("*.yaml"):
        if yaml_file.name.startswith("_"):
            continue  # Skip _stats.yaml

        try:
            data = yaml.safe_load(yaml_file.read_text())
            for learning in data.get("learnings", []):
                learning_keywords = set(k.lower() for k in learning.get("keywords", []))
                overlap = task_keywords & learning_keywords
                if overlap:
                    score = len(overlap) * learning.get("confidence", 0.5)
                    matches.append((score, learning))
        except Exception:
            continue

    # Return top 3 matches
    matches.sort(key=lambda x: x[0], reverse=True)
    if not matches:
        return ""

    context = "## Past Learnings Relevant to This Task\n\n"
    for score, learning in matches[:3]:
        context += f"### {learning.get('summary', 'Insight')}\n"
        context += f"{learning.get('insight', '')}\n\n"

    return context

def on_session_start(session_data: dict) -> dict:
    """Session start hook entry point."""
    initial_prompt = session_data.get("prompt", "")

    # Inject relevant learnings
    try:
        learning_context = inject_relevant_learnings(initial_prompt)
        if learning_context:
            session_data["injected_context"] = learning_context
    except Exception as e:
        print(f"Learning injection failed (non-blocking): {e}")

    return session_data

Limitations

Keyword matching is imperfect - May miss relevant learnings or match irrelevant ones
No semantic understanding - Can't match conceptually similar but differently-worded insights
Storage is local - Learnings don't sync across machines
Manual cleanup needed - Old/wrong learnings should be periodically reviewed

Future Improvements

If needed, consider:

Embedding-based similarity for better matching
Cross-machine sync via git
Automatic confidence decay over time
Integration with Neo4j for graph-based learning relationships

Success Metrics

Track effectiveness:

Injection rate: % of sessions with relevant learning injected
Usage rate: How often injected learnings help solve problems
Growth rate: New learnings per week
Quality: User feedback on learning relevance

session-learning

NPX Install

Tags

SKILL.md Content

Session Learning Skill

Purpose

Design Philosophy

Learning Categories

YAML Schema

When to Use This Skill

Learning Extraction Process

Step 1: Analyze Session Transcript

Step 2: Extract Structured Learning

Step 3: Merge with Existing Learnings

Learning Injection Process

Step 1: Extract Task Keywords

Step 2: Find Relevant Learnings

Step 3: Inject Context

Usage Examples

Example 1: Automatic Extraction

Example 2: Automatic Injection

Example 3: Manual Management

Keyword Matching Algorithm

Integration Points

With Stop Hook

With Session Start Hook

With /amplihack:learnings Command

Quality Guidelines

When to Extract

When NOT to Extract

Learning Quality Checklist

File Locations

Comparison with Existing Systems

Error Handling

YAML Parsing Errors

Missing Files

Fail-Safe Principle

Hook Integration

Stop Hook: Learning Extraction

Session Start Hook: Learning Injection

Limitations

Future Improvements

Success Metrics