> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agents-squads.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Learning Loop

> Capture insights that compound across sessions

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

```bash theme={null}
# 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

| Category  | Use When                                    |
| --------- | ------------------------------------------- |
| `success` | Something worked well                       |
| `failure` | Something didn't work (learn from mistakes) |
| `pattern` | A reusable approach                         |
| `tip`     | General advice                              |

## Viewing Learnings

```bash theme={null}
# 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`:

```markdown theme={null}
# 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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```markdown theme={null}
---
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

<AccordionGroup>
  <Accordion title="Capture immediately">
    Don't wait until end of session. Capture learnings as they happen.
  </Accordion>

  <Accordion title="Be specific">
    "API is slow" → "API calls over 100 items trigger rate limiting, batch at 50"
  </Accordion>

  <Accordion title="Include the why">
    "Use pnpm" → "Use pnpm instead of npm - 40% faster installs in CI"
  </Accordion>

  <Accordion title="Tag for findability">
    Use `--tags` for learnings you'll want to find later.
  </Accordion>
</AccordionGroup>

## The Compounding Effect

| Session | Without Learnings           | With Learnings                      |
| ------- | --------------------------- | ----------------------------------- |
| 1       | Fix auth bug (2 hours)      | Fix auth bug (2 hours) + capture    |
| 2       | Fix similar bug (1.5 hours) | Check learnings, apply fix (15 min) |
| 3       | Fix similar bug (1 hour)    | Immediate fix (5 min)               |

A 30-second `squads learn` call can save hours of re-discovery.

## Next Steps

<CardGroup cols={2}>
  <Card title="Using Memory" icon="brain" href="/guides/using-memory">
    Memory for current state
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli-reference">
    All learn commands
  </Card>
</CardGroup>