Self-Improving AI Agents via AGENT_LEARNINGS.md and External Memory Scaffolding
How AI coding agents like Claude record past mistakes and improve iteratively using external memory scaffolding (AGENT_LEARNINGS.md)—without model retraining.
A practical technique used internally by Anthropic engineers to enhance Claude-based AI coding agents was shared by tech creator Swadesh Kumar (@swadeshkumar_). Without requiring complex fine-tuning or model retraining, this approach allows an AI agent to reflect on past failures and progressively boost its capabilities across sessions using a single markdown file—a pattern known as external memory scaffolding.
Image source: @swadeshkumar_ / X
In typical software engineering agent loops, models frequently stumble into repetitive errors across sessions—such as invoking outdated API methods, repeating syntax mistakes, or failing edge cases—because each reset wipes conversational context. Rather than altering model weights, external memory scaffolding provides an explicit, persistent feedback loop that an agent inspects at runtime.
External Memory Scaffolding: Anatomy of AGENT_LEARNINGS.md
The core of external memory scaffolding lies in maintaining a dedicated file named AGENT_LEARNINGS.md at the project root, instructing the agent to update and review it continuously as part of its operational loop.
Whenever the agent makes an error or receives corrective feedback, it updates AGENT_LEARNINGS.md with three structured components:
- Mistakes it made: Concrete failure scenarios, such as build breakdowns, invalid CLI flags, or unexpected runtime exceptions.
- Patterns to avoid: Anti-patterns or flawed assumptions that directly caused the issue.
- Better approaches: Verified solutions, canonical syntax, or safer implementation workflows that succeeded.
Before commencing any new task, prompt guidelines require the agent to read AGENT_LEARNINGS.md first. By priming its immediate context with accumulated lessons, the agent avoids falling into identical traps, steadily acquiring project-specific engineering proficiency without any weight modifications to the underlying foundation model.
Community Caveat: Preventing Context Bloat by Graduating Rules
Following the initial reveal by Swadesh Kumar, engineer Ian Finlay (@ian_finlay) raised an essential architectural consideration for production deployments:
"The ones that repeat should graduate to lint rules or tests. otherwise the file just grows forever"
Unchecked accumulation of failure logs creates significant downstream operational friction:
- Context Window Exhaustion: As the document expands, ingesting it at the start of each task consumes an increasing share of available tokens, shrinking the effective context window for active code.
- Attention Dilution: A bloated log full of historical edge cases can diffuse model attention, making it harder for the agent to focus on instructions relevant to the immediate objective.
To prevent perpetual file bloat, recurring mistakes must not linger in text memory indefinitely. Once a failure mode recurs multiple times, it should "graduate" into automated, deterministic enforcement: dedicated linter rules (such as ESLint or Ruff) or strict unit and integration test assertions. Combining this graduation cadence with periodic pruning keeps the memory file lean and token-efficient.
Alignment with Claude's Context Management and File Memory Architecture
This scaffolding approach directly aligns with the broader context management and persistent memory architecture introduced on the Claude Developer Platform by Anthropic.
To help production agents handle long-horizon tasks without degrading performance or exceeding token limits, Anthropic introduced context editing—which purges stale tool outputs while preserving conversational continuity—alongside file-based memory tools where Claude can autonomously create, update, and read persistent text files within a dedicated memory store. Through these capabilities on the Claude Developer Platform, Claude dynamically manages external file-based stores while clearing stale tool results across long-running tasks.
Even without full API infrastructure, adopting a simple file-based convention like AGENT_LEARNINGS.md gives developers an immediate, zero-overhead mechanism to instill cumulative self-improvement into their daily agent workflows.