- name
- self-improving-agent
- description
- Automatically capture corrections, failures, and reusable discoveries into
.learnings/files using signal-based filtering. Triggers when the user corrects the agent, a tool/command fails in a reusable way, or a better approach is discovered. Also handles periodic retention scoring and promotion of proven patterns into SOUL.md, AGENTS.md, or TOOLS.md.
Self-Improving Agent
Capture what matters. Ignore noise. Promote proven patterns. Automate all of it.
Source of truth
.learnings/LEARNINGS.md— corrections, env configs, reusable fixes, architecture decisions.learnings/ERRORS.md— tool/command failures with fixes.learnings/FEATURE_REQUESTS.md— missing capabilities worth tracking.learnings/ARCHIVE.md— entries scored out during retention sweeps (never injected into context, but searchable)
Write gate
Before logging anything, the candidate must pass at least ONE filter:
| Filter | Weight | Description |
|---|---|---|
| Correction | ALWAYS | Omar explicitly corrected the agent |
| Recurrence | HIGH | Same issue hit 2+ times (check existing entries) |
| Cost-to-rediscover | HIGH | Would take >2 tool calls to figure out again |
| Blast radius | MEDIUM | Affects multiple skills, projects, or workflows |
| Decay risk | MEDIUM | Non-obvious env/config detail that changes rarely |
If NONE match → do not log. This replaces any arbitrary line-count threshold.
Never log:
- routine successes
- facts obvious from docs or code
- one-off tasks with no recurrence potential
- anything already in MEMORY.md, SOUL.md, USER.md, or AGENTS.md
Entry format
LEARNINGS.md:
- [YYYY-MM-DD] [Category]: [Actionable takeaway]Categories: Correction, Env, Workflow, Testing, Skills, Git, Architecture
ERRORS.md:
- [YYYY-MM-DD] [Tool]: [What failed] → [Fix]Mark fixed items with [fixed]. Delete stale entries during retention sweeps.
Retention gate
Instead of a hard line cap, score each entry periodically:
| Signal | Score |
|---|---|
| Referenced or applied in last 30 days | +3 |
| Matches active project context | +2 |
| Direct correction from Omar | +2 |
| Has prevented a repeat error | +3 |
| Env/config still valid | +1 |
| Superseded by newer entry | −5 |
| >90 days old, never referenced | −3 |
Action:
- score ≥ 2 → keep
- 0 ≤ score < 2 → archive to
.learnings/ARCHIVE.md - score < 0 → delete
Run this sweep during heartbeat maintenance (every ~3 days) or when LEARNINGS.md feels noisy.
Automated triggers
These fire without user prompting:
- Post-task scan: After multi-step tasks, check for retried commands, error→workaround sequences, or avoidable file reads. If found, evaluate against write gate and log if it passes.
- Session-start sweep: On
.learnings/LEARNINGS.mdread, flag entries >90 days old for retention scoring.
- Promotion detector: After logging, scan for entries with the same
[Category]tag appearing 3+ times. If found, auto-suggest a one-liner promotion to:
- behavior/style → SOUL.md - workflow/process → AGENTS.md - tool/env gotcha → TOOLS.md
- Cross-session pattern detection: When
memory_searchreturns a daily note describing a workaround, check if.learnings/already has it. If not and it passes the write gate, log it.
Dedup
Before logging, scan existing entries for near-duplicates. If the lesson already exists, only update it if the new version is sharper or more general.
Quality bar
Every entry must help a future session avoid wasted work in under one glance.