session-learning

This skill provides cross-session learning by:

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

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

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 |

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

```

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

Step 1: Analyze Session Transcript

At session stop, scan for:

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

Step 2: Extract Structured Learning

For each significant insight:

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

Step 3: Merge with Existing Learnings

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

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:

1. Load learnings from YAML
2. Calculate keyword overlap with task
3. Rank by overlap_score confidence recency_weight
4. Select top 3 most relevant learnings

Step 3: Inject Context

Format relevant learnings as context:

```markdown

[Category]: [Summary]

```

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:

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

```

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))

```

With Stop Hook

The stop hook can call this skill to extract learnings:

1. Parse transcript for significant events
2. Identify error patterns, solutions, insights
3. Store in appropriate category YAML
4. Log extraction summary

With Session Start Hook

The session start hook can inject relevant learnings:

1. Parse initial prompt for keywords
2. Find matching learnings across categories
3. Format as context injection
4. Include in session context

With /amplihack:learnings Command

Command interface for learning management:

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

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

```

.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)

```

| 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

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

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

```

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

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

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