Ask how to give an AI agent persistent memory and you'll be handed an architecture diagram: embeddings, a vector database, a retrieval pipeline, a reranker. I run agent fleets across five brands — content engines, deploy pipelines, scheduled jobs producing real output with nobody watching — and my production agent memory system contains none of that. It's one markdown index file linking to small, single-topic markdown files, all readable by a human in a text editor. It has survived months of daily sessions, and it works better than conversation recall ever did.
TL;DR
Persistent AI agent memory doesn't require a vector database. My production system is a single MEMORY.md index — one compressed line per lesson — linking to small typed files: feedback_ for permanent corrections, reference_ for stable facts, project_ for the state of long-running work. The index loads at the start of every session; detail files load on demand. Corrections written as rules beat searchable conversation history, because an agent doesn't need to remember a mistake — it needs to be forbidden from repeating it.
What "agent memory" actually means
Strip the vendor language and agent memory is one question: what does the agent know at the start of a session that it didn't get from you in that session?
Out of the box, the answer is nothing. A model's weights hold general knowledge; they hold nothing about your infrastructure, your brand's forbidden claims, or the correction you made yesterday. Every conversation starts naive. So "memory" for an agent is any mechanism that carries information across that boundary — and the mechanism matters far less than what you choose to carry.
Most memory products carry conversation history: they embed past chats and retrieve "relevant" fragments. That answers "what did we talk about?" The question that actually determines whether your fleet is safe to run unattended is different: "what rules govern this task?" Those are not the same question, and optimizing for the first one is how you end up with an agent that can recall a discussion about a mistake while cheerfully repeating it.
Why corrections-as-rules beats conversation recall
Here's the failure mode of recall-based memory. Three weeks ago you told an agent "never email a link before verifying it's live." That instruction is now one utterance among thousands in an embedding store. Whether it surfaces today depends on semantic similarity between the current task and the old conversation — a probabilistic bet. If today's task is phrased as "send the launch announcement," the retrieval may never connect it to a correction phrased around link verification. The rule exists somewhere and governs nothing.
Now the same correction in my system. The moment I made it, it became a file — feedback_verify_link_before_emailing.md — stating the rule in imperative form: a link must be published and return HTTP 200 before it goes in any email. One line in the index points to it, in a "TOP RULES — read first" section at the very top. Every session, without exception, reads that index before doing anything. The rule doesn't need to be retrieved; it's constitutionally present.
The distinction generalizes:
- Recall is probabilistic; rules are guaranteed. Retrieval can miss. An index that loads every session cannot.
- Recall stores what was said; rules store what was decided. A conversation about a mistake contains exploration, backtracking, and the fix. The agent needs only the fix, stated as a directive.
- Recall grows without judgment; rules grow through it. Every correction I write forces me to compress the lesson to one imperative line plus a small detail file. That editorial pass is the memory system. A vector store never makes you decide what mattered.
An agent doesn't need to remember that it once made a mistake. It needs to be forbidden from making it again. Those require different data structures, and the second one is a rulebook, not a search engine.
The taxonomy: three prefixes, three kinds of knowledge
Every file in the memory directory is named by type, and the prefix tells any agent — and me — what kind of knowledge it holds and how to treat it:
| Prefix | Holds | Lifecycle | Real examples from my index |
|---|---|---|---|
feedback_ | Permanent corrections — "never do X, always do Y," written the moment I correct an agent | Permanent; almost never deleted | feedback_verify_link_before_emailing (published AND HTTP 200 before any email), feedback_photography_pages_frozen (never touch listed live pages unless asked), feedback_never_fake_edits |
reference_ | Stable facts an agent needs but shouldn't rediscover — infrastructure, accounts, gotchas | Updated when reality changes | reference_launchd_claude_path_bug (a PATH gotcha that silently kills scheduled jobs), reference_cloudflare_login, reference_acromatico_architecture |
project_ | State of long-running work, so the next session resumes instead of restarting | Living; pruned or archived when the project ends | project_career_engine, project_ecolosophy_detox_journal_engine, project_marketing_os |
The taxonomy does real work. A feedback_ file is law — it overrides convenience, templates, and anything a task brief says. A reference_ file is a fact sheet — trusted until reality changes, then edited. A project_ file is a save point — the current state of an effort, expected to churn. When an agent opens the index, the prefix alone tells it which entries constrain behavior versus which merely inform it. No metadata schema, no tags database. The filename is the type system.
Each file is small and single-topic on purpose. One lesson per file means one line per lesson in the index, updates that touch nothing else, and links that take an agent straight to exactly the detail it needs — no more.
How the index stays small enough to load every session
The whole design lives or dies on one constraint: MEMORY.md must be cheap enough to load at the start of every single session. The moment it's too long to always load, you're back to probabilistic retrieval and the guarantee is gone.
So the index is written like a telegram, not a document. Rules that keep it that way:
- One line per lesson. Each entry is a link plus a compressed gist — just enough for an agent to know the rule exists and when to open the detail file. The full reasoning, examples, and exact wording live in the linked file, loaded only when relevant.
- Detail lives one hop away. This is the same always-on-versus-on-demand budget discipline I apply to instructions generally — every always-loaded token competes with the actual task for attention, the core argument of context engineering for solo-operator fleets.
- A TOP RULES section sits first. The most dangerous rules — the ones where a violation costs money or trust — are the first thing any new session reads. Even a session that skims gets the non-negotiables.
- Grouped by domain below that. Entries cluster under headings per brand and per concern, so an agent working one project reads its cluster and skips the rest.
- Pruning is part of writing. When a project ends, its
project_entry gets collapsed or removed. When two feedback entries say the same thing, they merge. An index nobody prunes becomes a document, and a document stops getting read.
The compounding loop is the point. Every correction becomes a file and an index line before the session ends — that habit is the highest-leverage part of the entire system, and it's the memory layer of the four-layer instruction stack I described in how CLAUDE.md and skills stop agent drift. Without it, every session starts naive and repeats last month's mistakes. With it, the fleet gets harder to break every week — which is the only way one operator runs five brands without the whole thing decaying.
And because it's all plain markdown, I can audit it in any editor, diff it, grep it, and fix a wrong memory by editing a file. Try doing that to an embedding.
When you actually do need vector search
Honest boundary: this system is a rulebook, and rulebooks have a size limit. Vector search earns its complexity when the problem is genuinely search, not governance:
- Large corpora you can't curate. Thousands of support tickets, a decade of documents, a codebase's history — nobody is hand-writing an index line per item. Semantic retrieval over uncurated volume is what embeddings are for.
- Recall of specifics nobody promoted to a rule. "What did the client say about pricing in March?" is a retrieval question. My system deliberately doesn't store conversations; if the answer wasn't worth a file, it's gone.
- Many users, no editor. My index works because one operator curates it. A memory system serving a whole team's agents, with no human distilling lessons, needs automated retrieval because nothing else scales without an editor.
The trap is reaching for that stack first. For a solo operator or a small team, the knowledge that determines whether agents are safe to run unattended — corrections, facts, project state — fits comfortably in an indexed set of markdown files, curated in the minute after each correction. Start with the index. Add retrieval when you have a corpus, not because a diagram told you to.
FAQ
Do AI agents have memory?
Not by default. A model remembers nothing between sessions — each conversation starts from zero plus whatever files load into its context. "Agent memory" is always an external mechanism that carries information across sessions: context files loaded at start, an index like the one described here, or a retrieval system over stored history. The mechanism you choose determines whether what persists is rules (guaranteed to load) or recollections (retrieved probabilistically).
How do I give Claude persistent memory?
Create a MEMORY.md index that loads at the start of every session — alongside CLAUDE.md, which holds always-on instructions — and a directory of small, single-topic markdown files it links to. Name files by type: feedback_ for corrections written as imperative rules, reference_ for stable facts, project_ for the state of ongoing work. Keep the index to one line per lesson with a TOP RULES section first, and write every correction into a file the moment you make it. No embeddings or database required.
Why not just use a vector database for agent memory?
Because retrieval is probabilistic and rules need to be guaranteed. A correction stored as an embedded conversation surfaces only if today's task happens to be semantically similar to the old chat; a correction stored as a rule in an always-loaded index governs every session unconditionally. Vector search is the right tool for searching large uncurated corpora — it's the wrong first tool for a curated set of operating rules that fits in one index.
What's the difference between agent memory and CLAUDE.md?
CLAUDE.md is standing context — identity, voice, constraints for a project — written once and edited deliberately. Memory is the accumulating record: corrections, facts, and state that grow session by session as the agent works and gets corrected. In practice they cooperate: CLAUDE.md says who the agent is and what's forbidden; the memory index says what's been learned since, with the index loading first every session.
Work with me
If you want a memory system like this — plus the SOPs, skills, and verification gates around it — designed and installed for your own operation, that's the work I do. Tell me what you're running.
— Italo Campilii