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:

FilterWeightDescriptionCorrectionALWAYSOmar explicitly corrected the agentRecurrenceHIGHSame issue hit 2+ times (check existing entries)Cost-to-rediscoverHIGHWould take >2 tool calls to figure out againBlast radiusMEDIUMAffects multiple skills, projects, or workflowsDecay riskMEDIUMNon-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:

SignalScoreReferenced or applied in last 30 days+3Matches active project context+2Direct correction from Omar+2Has prevented a repeat error+3Env/config still valid+1Superseded 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.