self-improving-agent

# 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: ```markdown - [YYYY-MM-DD] [Category]: [Actionable takeaway] ``` Categories: `Correction`, `Env`, `Workflow`, `Testing`, `Skills`, `Git`, `Architecture` ERRORS.md: ```markdown - [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: 1. **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. 2. **Session-start sweep**: On `.learnings/LEARNINGS.md` read, flag entries >90 days old for retention scoring. 3. **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` 4. **Cross-session pattern detection**: When `memory_search` returns 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.