My agent’s memory lives in a folder of Markdown files: one note per fact, four types, and a one-line index per note, loaded at the start of every session. It now holds 101 notes, and it saves me from explaining the same thing twice.
The problem
An AI agent forgets everything from one conversation to the next. After a few weeks, I was repeating the same instructions: don’t crawl my site in bursts, quote the exact text of a template, check a figure at the source. Every correction I made vanished with the session.
The principle
Claude Code offers a file-based memory. Each note is a Markdown file, with a small header describing it:
---
name: quote-the-real-template-text
description: In a variable prompt, quote the exact sentence of the template
metadata:
type: feedback
---
The prompt said "after the preposition of", but that preposition
is written nowhere in the template. The value is inserted as is.
**Why:** the invented instruction produced a wrong sentence.
**How to apply:** quote the real text around the variable before writing the prompt.An index file, MEMORY.md, lists all the notes with a single line each: a title, a link, a short summary. It is what gets loaded at the start of each session; the agent opens a full note when the topic comes back.
The four types
My 101 notes break down like this:
| Type | Count | What goes in it |
|---|---|---|
project |
45 | The state of a project, with absolute dates |
feedback |
34 | An instruction I gave, with the why, and also what I validated |
reference |
21 | Where a resource lives, an API’s pitfalls |
user |
1 | Who I am and how I work |
The feedback notes pay off the most: each one is a mistake that doesn’t happen again. Don’t crawl your own site with an agent, check a data spike before interpreting it, never present an invented screen as a screenshot: every time, a correction made once and kept.
The rules I impose on myself
- One fact per file. A note containing three can’t be updated cleanly.
- Search before writing. If a note already covers the topic, update it instead of creating a second one.
- The index is only an index. One line per note, never the content: it is read every session, so it costs context.
- Always write the why. Without a “Why”, a rule becomes a dogma the agent applies off target; with it, the agent knows when it doesn’t apply.
- Absolute dates. “Thursday” means nothing three weeks later.
- Link notes to each other with a
[[name]]link, to find a rule’s context. - Don’t store what the code, the history or the documentation already say. Memory keeps what is written nowhere else.
What goes stale
A note describes the world as it was the day it was written. One day, the agent could no longer find tools the note said were installed: someone had removed them from the server. Claude Code does remind you of a note’s age when it reads it, and the rule is to verify before asserting: a function name, a file or a setting cited in a note must be checked against the current state.
The limits
- The index grows. At around a hundred lines, it weighs on every session: summaries must stay short, and regular cleanup (merging duplicates, removing what is wrong) is necessary.
- It contains internal data. A useful memory is a precise memory: it isn’t published, and it is reread before being shared.
- It doesn’t replace judgment. An old rule may be wrong today. When it is, I delete the note rather than work around it.
Key takeaway
Write the correction at the moment you make it: a short note, a type, a why, a line in the index. A hundred notes later, the agent behaves like someone who knows your job, your tools and your quirks, because it was told once.