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).Quick Start
A single switch turns on both capture and apply: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:Configuration Options
Deprecated: the older
evaluate: true / evaluate: "<prompt>" 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:
How Extraction Works
After execution (whencapture is enabled):
- LLM evaluates the execution result
- Extracts 0-3 high-confidence learnings (≥0.8 threshold)
- Deduplicates against existing learnings (60% word overlap)
- Stores in markdown format
Learning from approval comments
When Approval Gates are enabled andcapture 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.
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:
How Application Works
On next run or approval resume (whenapply: true):
- Loads up to 10 learnings from storage
- Appends them to your agent instructions as a
## Learned Guidelinessection - Tracks which learnings were applied (for analytics)
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: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 tocriteria for domain-specific extraction:
Example: Manual Review Workflow
blog-writer.learnings.md:
Best Practices
Review before auto-apply
Run with
apply: false first to verify learning quality before enabling auto-injectionCurate your instructions
The best learnings should become permanent parts of your agent file
Use custom prompts
Tailor extraction to your domain with custom evaluation prompts
Share across agents
Use
file to point multiple agents at shared learningsNext Steps
Store Guide
Persistent data storage for agents
Manager Agents
Orchestrate teams of learning agents