> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentuse.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Learning
> Extract insights from executions and apply them in future runs
**Experimental Feature**: Learning is experimental. The configuration and behavior may change or be removed in future versions. Discuss feedback in [GitHub Discussions](https://github.com/agentuse/agentuse/discussions).
## What is Learning?
Learning lets an agent **capture** insights from its executions into a readable markdown file and **apply** them in future runs. Capture has three sources: self-evaluation of each run, promotion of a human reviewer's approval-gate comment, and explicit manual rules saved by a reviewer (see [Learning from approval comments](#learning-from-approval-comments)).
## Quick Start
A single switch turns on both capture and apply:
```yaml theme={"system"}
---
model: anthropic:claude-sonnet-5
learning: true # capture insights AND apply them next run
---
# Blog Writer
Write short productivity blog posts.
## Guidelines
- Start with a relatable hook
- Include 3 actionable tips
```
`learning: true` is sugar for `{ capture: true, apply: true }`. Learnings accumulate in `{agent-name}.learnings.md` next to your agent file and are injected into instructions on the next run.
## Capture-Only (Review Before Trust)
For a human-in-the-loop workflow, capture insights but do not auto-apply them. Review the file, then copy the best ones into your instructions yourself:
```yaml theme={"system"}
learning:
capture: true
apply: false # accumulate for manual review, never auto-inject
```
This is the safer default for agents that touch untrusted input (web pages, emails, tickets), where an auto-applied learning could persist a bad or injected instruction. See [Best Practices](#best-practices).
## Configuration Options
| Option | Type | Description |
| ---------------- | --------- | ------------------------------------------------------------------------------------------ |
| `learning: true` | `boolean` | Shorthand for `{ capture: true, apply: true }`. |
| `capture` | `boolean` | Write learnings after execution (self-evaluation + approval comments). Defaults to `true`. |
| `apply` | `boolean` | Inject stored learnings into instructions before each run. Defaults to `true`. |
| `criteria` | `string` | Optional guidance for the capture evaluator (domain-specific extraction). |
| `file` | `string` | Custom file path for storing learnings (relative to agent file). |
**Deprecated:** the older `evaluate: true` / `evaluate: ""` field still works but maps to `capture: true` (and `criteria` for the string form). It is removed in a future release; migrate to `capture` / `criteria`.
## Storage
Learnings are stored in `{agent-name}.learnings.md` next to your agent file:
```
my-project/
blog-writer.agentuse
blog-writer.learnings.md # Auto-created, human-readable
```
Custom path:
```yaml theme={"system"}
learning:
capture: true
file: "./learnings/shared.md"
```
## How Extraction Works
After execution (when `capture` is enabled):
1. LLM evaluates the execution result
2. Extracts 0-3 high-confidence learnings (≥0.8 threshold)
3. Deduplicates against existing learnings (60% word overlap)
4. Stores in markdown format
## Learning from approval comments
When [Approval Gates](/guides/approval-gates) are enabled and `capture` is on, **any comment you leave at a gate** can be promoted into a durable learning. In practice your feedback arrives through the revise loop (leaving a comment sends the work back to be reworked and re-presents the same gate), while the final approve is usually a bare click with no comment, so comments are captured wherever they appear, not only on the approving decision. This is the highest-signal feedback an agent receives, so it is captured separately from self-evaluation.
```yaml theme={"system"}
---
model: anthropic:claude-sonnet-5
approval: true
learning: true
---
# Blog Writer
...
```
When you leave a note like "Going forward, always cite a source before publishing", a generalizability filter decides whether the comment is a **durable agent-wide rule** or a **one-off edit** to this run. Only durable rules are captured (as `src:approval`, confidence `0.95`); one-off edits (like "fix the typo in paragraph two" or "give me the source link") are ignored. Approval-sourced learnings rank ahead of auto-extracted ones when injected, so your corrections survive the per-run cap.
For faster teaching, the approval comment dialog can also save an explicit future rule. Use the comment for the current revision, then check **Remember this as a future rule** and write the durable rule separately. Checking the box is itself the opt-in, so it works on any agent, no `learning` config required to save. Manual rules are stored as `src:manual`, confidence `1.00`, and rank ahead of approval-promoted and auto-extracted learnings. They are only injected into future runs once the agent has `learning.apply` enabled (the dialog says so if it isn't). The CLI equivalent is:
```bash theme={"system"}
agentuse sessions resume 01K... \
--comment "Please revise this pass with citations" \
--remember "Always include source links before publishing."
```
## How Application Works
On next run or approval resume (when `apply: true`):
1. Loads up to 10 learnings from storage
2. Appends them to your agent instructions as a `## Learned Guidelines` section
3. Tracks which learnings were applied (for analytics)
This keeps learnings at the instruction level - where they have the most influence on agent behavior.
## Learning Categories
Learnings are categorized for context:
* **tip** - General best practices
* **warning** - Things to avoid
* **pattern** - Successful approaches
* **tool-usage** - How to use specific tools
* **error-fix** - Solutions to known errors
## Storage Format
Learnings are stored as readable markdown:
```markdown theme={"system"}
# Learnings for blog-writer
### [tip] Use specific examples over generic advice
When writing productivity tips, include concrete scenarios
like "checking emails before coffee" rather than abstract advice.
### [pattern] Structure with time estimates
Each actionable tip should include a specific time estimate
(e.g., "5-minute brain dump") to make it feel achievable.
### [tip] Cite sources before publishing
Always include source links before publishing.
```
The `src:` field records provenance: `auto` (self-evaluation), `approval` (promoted from a reviewer comment), or `manual` (explicitly saved by a reviewer). Older files without `src:` load as `auto`.
## Custom Evaluation Criteria
Pass a string to `criteria` for domain-specific extraction:
```yaml theme={"system"}
learning:
capture: true
criteria: |
Evaluate the blog post against these criteria:
1. Hook quality - Is the opening engaging?
2. Actionability - Can readers implement immediately?
3. Tone - Professional but conversational?
```
## Example: Manual Review Workflow
```yaml theme={"system"}
---
model: anthropic:claude-sonnet-5
learning:
capture: true
apply: false
---
# Blog Writer
Write short productivity blog posts (150-200 words).
## Requirements
- Start with a relatable hook
- Include 3 actionable tips
- End with a clear call-to-action
```
After 5-10 runs, review `blog-writer.learnings.md`:
```markdown theme={"system"}
### [tip] Use specific examples over generic advice
When writing productivity tips, include concrete scenarios
like "checking emails before coffee" rather than abstract advice.
### [pattern] Structure with time estimates
Each actionable tip should include a specific time estimate
(e.g., "5-minute brain dump") to make it feel achievable.
```
Then update your agent instructions with the best insights:
```yaml theme={"system"}
## Requirements
- Start with a relatable hook
- Include 3 actionable tips with specific time estimates # ← from learnings
- Use concrete scenarios, not abstract advice # ← from learnings
- End with a clear call-to-action
```
This keeps you in control while still benefiting from extracted patterns.
## Best Practices
Run with `apply: false` first to verify learning quality before enabling auto-injection
The best learnings should become permanent parts of your agent file
Tailor extraction to your domain with custom evaluation prompts
Use `file` to point multiple agents at shared learnings
## Next Steps
Persistent data storage for agents
Orchestrate teams of learning agents