Skip to main content

​
The Problem

Every session, your agents discover things:
  • Bugs and how to fix them
  • Patterns that work well
  • Approaches that failed
  • Tips that save time
Without capturing these, the next session starts from scratch. You rediscover the same things. Knowledge doesn’t compound.

​
The Learning Loop

Session 1: Fix bug → Learn root cause → Capture insight
Session 2: Similar bug → Check learnings → Apply fix immediately
Each captured insight makes future sessions smarter.

​
Capturing Learnings

# After fixing a bug
squads learn "PostgreSQL connection pool exhaustion was caused by unclosed transactions in error paths"

# After discovering a pattern
squads learn "Always check memory before researching to avoid duplicate work" --category pattern

# After something worked well
squads learn "Using TypeScript strict mode caught 3 type errors before runtime" --category success

# After something failed
squads learn "Don't batch API calls over 100 items - rate limiting kicks in" --category failure

​
Categories

CategoryUse When
successSomething worked well
failureSomething didn’t work (learn from mistakes)
patternA reusable approach
tipGeneral advice

​
Viewing Learnings

# View squad learnings
squads learnings show engineering

# Filter by category
squads learnings show engineering --category pattern

# Filter by tag
squads learnings show engineering --tag postgres

# Search across all squads
squads learnings search "authentication"

​
Storage

Learnings are stored in markdown at .agents/memory/<squad>/shared/learnings.md: 
# engineering - Learnings

> Accumulated knowledge from sessions

---
_2025-01-15_

● **Success**: Using TypeScript strict mode caught 3 type errors before runtime
Tags: `typescript, types`

---
_2025-01-14_

✗ **Failure**: Batching API calls over 100 items triggers rate limiting
Tags: `api, performance`

​
Auto-Tagging

The CLI automatically extracts tags from your insights: 
squads learn "The auth token needs refreshing after 1 hour, not on 401 errors"
# Auto-tags: auth
Recognized patterns: auth, api, bug, perf, ux, test, db, deploy

​
Session Integration

​
Stop Hook

Add to .claude/settings.json to prompt for learnings at session end: 
{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "squads memory sync && echo \"\\n💡 Capture learnings: squads learn \\\"<insight>\\\"\\n\"",
        "timeout": 15
      }]
    }]
  }
}

​
The /squads-learn Skill

When you run squads init, it creates a skill that Claude can invoke: 
---
name: squads-learn
description: Capture learnings after completing work. Use when finishing a task,
  fixing a bug, discovering a pattern, or learning something worth remembering.
---
Claude will auto-invoke this skill when:
  • Finishing a task
  • Fixing a bug
  • Discovering a pattern
  • Learning something worth remembering

​
Best Practices

Don’t wait until end of session. Capture learnings as they happen.
“API is slow” → “API calls over 100 items trigger rate limiting, batch at 50”
“Use pnpm” → “Use pnpm instead of npm - 40% faster installs in CI”
Use --tags for learnings you’ll want to find later.

​
The Compounding Effect

SessionWithout LearningsWith Learnings
1Fix auth bug (2 hours)Fix auth bug (2 hours) + capture
2Fix similar bug (1.5 hours)Check learnings, apply fix (15 min)
3Fix similar bug (1 hour)Immediate fix (5 min)
A 30-second squads learn call can save hours of re-discovery.

​
Next Steps

Using Memory

Memory for current state

CLI Reference

All learn commands