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:

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:

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.

1. Session-start sweep: On .learnings/LEARNINGS.md read, flag entries >90 days old for retention scoring.

1. 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

1. 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.