AI Agent Memory: 5 Rules to Stop Repeating Mistakes

Every AI session starts from zero: the agent repeats yesterday's mistake and asks you the same question again. With a folder of text files and two habits, reading at the start and writing at the end, you give it a memory. It takes half an hour to set up and works with any agent that can read files.

What It Is

A second brain for your agent: a folder of markdown notes (plain text with headings and lists) that the agent reads when it starts and updates when it finishes. It holds the traps you have already hit, the solutions that work, the decisions you made and a diary of what happened each day.

Why It Matters

Without a memory that persists, every session is the agent's first day on the job. It does not know you already fixed that bug, or why you chose that library. So it does it again, and you explain again.

Since we started working this way, across six client projects in production we have seen 63% fewer known bugs coming back, and 40% less time for a new agent to find its way around a project (February 2026). For us, it is the line between a prototype and a project that holds up.

1. Start Simple: A Folder of Markdown Files

What it is: the simplest possible memory, made of text files.

Why it matters: our first version was an Obsidian vault (a free app for markdown notes) that Claude Code read and wrote in every session. Markdown, links between notes, one folder per project. Nothing more. It worked, and our whole approach to agent memory grew from there. Simple tools beat sophisticated ones when they follow real work.

How to do it: create a folder in the project, for example "memory", with four subfolders:

• traps: mistakes already made and how to avoid them, one note per trap;
• patterns: solutions that work and should be reused;
• decisions: what you chose and why;
• diary: one file per day, one line per finished job.

Obsidian is optional: it is handy for reading notes and seeing links, but the agent only needs the files.

2. Open Every Session by Reading Traps and Rules

What it is: a fixed instruction that makes the agent read its memory before working.

Why it matters: a memory nobody reads is useless. Reading must be automatic, not left to you remembering.

How to do it: put the instruction in the file your agent reads on its own at startup. In Claude Code that is CLAUDE.md, in the project folder. Other tools have a similar file, such as AGENTS.md.

Ready to copy, to paste into that file:

3. Close Every Session With a Diary Entry

What it is: one diary line at the end of the job, written by the agent.

Why it matters: the diary is the project's history. Tomorrow another agent, or you, can see what was done and what was learned without digging through conversations.

How to do it: add this instruction below the previous one, in the same file.

4. Write Little, and On Purpose

What it is: a filter on what deserves to go into memory.

Why it matters: agent memory is not a database that saves everything automatically and then searches by similarity. It is deliberate writing: rules, traps, decisions. An agent that knows what not to remember is more useful than one that remembers everything, because it does not drown in noise.

How to do it: before saving a note, run the discovery through four questions. If any answer is no, it does not get saved.

5. Link Memory to the Code and Notes to Each Other

What it is: two kinds of link. A short comment in the code pointing to the right note (we call it a breadcrumb), and links between notes about the same thing.

Why it matters: the agent opens a file and immediately finds the trap that applies, without searching. And linked notes form a map: from a trap you reach the decision that caused it. In our editor Quack, this memory became a graph: after three months it held 1,847 linked notes, with 58% fewer recurring errors and 41% fewer repeated questions to the user.

How to do it:

1. When you fix a bug that has a memory note, put a comment above the code with the note's name, for example "Memory: traps/double-charge".
2. At the bottom of every note, add links to related notes. In Obsidian you write them between double square brackets.
3. Once a month, ask the agent to find duplicate or outdated notes and propose what to merge or delete.

Small Test

Ten minutes. Think of a mistake your agent made this week. Write a note in memory/traps with title, cause and fix, and add the rule 2 instruction to the startup file. Then open a new session and give it a task close to that mistake.

It worked if the agent mentions the note before starting and does not repeat the mistake. If it does not mention it, the note's title is not clear enough: rewrite it with the words you would use to ask for the task.

Watch Out For

• Never put secrets in notes. Passwords, keys and tokens belong in a password manager, not in files the agent reads and that may end up in git.
• Notes go stale. A trap fixed by a new version becomes bad advice. Date every note and clean up.
• More memory does not mean more quality. Every note the agent reads takes up context and costs money. That is why it reads only the titles first.
• Review what the agent saves. That is why the instructions ask for your OK: a wrong rule in memory repeats in every session.
• The numbers are ours, measured on our own projects. The two habits matter more than the percentages.

Next step: if several agents share the same memory, organise them with 5 rules for parallel agents. If a trap keeps coming back in the same process, turn that process into a skill the agent runs.

In short: An agent stops repeating mistakes when it reads known traps at the start of a session, writes down discoveries at the end and saves only what will really matter.