Developers complain that AI repeats the same mistakes. "I've explained five times that we don't use Redux here." "It suggested FTP again instead of a queue." "It keeps ignoring our naming conventions."
That's not a model problem. It's an engineering gap.
Why the agent "doesn't learn"
Every new agent session starts from a blank slate. The model has no memory of previous conversations. Everything it knows about your project is what you put in its context. If you put nothing specific in — you get the average of the internet.
Without domain context, the agent falls back on its training distribution, where production-grade architectural decisions appear far less often than beginner tutorials. The result: FTP instead of event-driven, global state where local state belongs, camelCase where your codebase has used snake_case for three years.
The problem isn't that AI "doesn't learn." The problem is that no one gave it anything to learn from.
The mechanism: two files
Any agent that automatically pulls a rules file into context at the start of each session can become an accumulating system with two lines of instruction.
For Claude Code, this is CLAUDE.md. For Cursor, it's .cursorrules or .mdc files. The principle is the same: instructions stored in the repository get loaded automatically on every run.
Add two lines to your rules file:
- If you made a decision that proved correct and cost real effort — log it in decisions.md (pattern + why it worked, 3 sentences max).
- If you made a mistake that caused a problem — identify the root cause (not the symptom) and log it in mistakes.md.That's it. Two plain text files at the root of the project.
From the first session, the agent starts filling both files. Every subsequent session opens with them in context. The agent now sees that in this project:
- dual write is forbidden (and why),
- Redis cache is the wrong tool for this data type,
- last time this pattern was used, it caused this specific failure.
Mistakes stop repeating. Domain context is in the toolchain now — it wasn't before.
The principle behind it
There's a rule I've tested across different contexts — from AI enablement programs with 100+ engineers at a $680M retail enterprise to smaller team settings: a rule that isn't in the tool doesn't exist.
Explaining standards at a quarterly meeting doesn't work, and neither does a Confluence page nobody opens. Only what the agent reads on every run actually sticks.
The same principle drives more complex setups. The github.com/dobryakov/cursor-rules repository packages architectural standards as versioned .mdc files in git. A new team member inherits the same guardrails from the first commit. The AI assistant won't propose violating an architectural rule because that rule is in its context, not buried in a corporate wiki. The decisions/mistakes pattern is a lightweight version of the same idea — for individual and small-team projects where you don't need the full governance infrastructure.
Failure modes
The pattern is simple. But a few places break it if you don't address them upfront.
Files grow without bounds. Without format constraints, after a few months mistakes.md turns into 300 lines where 200 are variations of the same root pattern. Fix: limit each entry to 3 sentences, don't duplicate root causes, and only write mechanisms — not symptom descriptions like "there was an API error."
Root cause isn't identified. The agent writes "there was an API error" instead of "attempted to read from Redis before the connection pool finished initializing." Add an explicit instruction: root cause must be a specific technical mechanism, not a description of the symptom.
Context window gets consumed. Large files compete with working code for context space. Fix: periodically ask the agent to compress the files, keeping only unique patterns. One root cause = one entry, regardless of how many incidents it produced.
Entries go stale after refactoring. After a stack change, some entries describe a reality that no longer exists. Add a date stamp to each entry — stale ones become visible immediately.
Scale
The pattern isn't limited to personal projects.
Personal project: one rules file, two memory files. The agent remembers what you've already tried, what didn't work, what "correct" looks like in your specific context.
Team: files in git — decisions.md and mistakes.md as shared artifacts. A new developer gets the accumulated team knowledge when they clone the repo. Every team member's AI assistant operates with the same domain context.
Enterprise: modular structure — separate .mdc files by domain (architecture, security, API style), decisions/mistakes split by service or team. The mechanism is the same: files in the repository, auto-loaded into context.
Why RAG is overkill here
When people hear "agent memory," the conversation usually jumps to vector databases, RAG pipelines, and fine-tuning. That's all valid — but for most projects it's overengineering.
RAG is for when you have thousands of documents and need semantic filtering — not everything in context, just what's relevant. decisions.md is for when you have dozens of patterns and all of them should always be in context. These are different problems.
When the rules file fits entirely in the context window, plain text beats RAG: no embedding drift, no index versioning, no retrieval latency. Just markdown the agent reads completely at startup.
The pattern works with any agent that auto-loads rules into session context. Exact paths depend on your tool. The mechanism is the same.