How AI Agents Remember: Portable, Model-Agnostic Memory
July 10, 2026 · 8 min read
An AI agent can plan a migration, triage an incident, or work a change across dozens of files in a single sitting. Then the session ends, and it forgets all of it. The next session — maybe a newer model, maybe a different tool entirely — starts from nothing. It re-reads the same code, re-discovers the same gotchas, and every so often re-breaks something the last one already fixed.
The instinct is to reach for a bigger context window or a vector database. But the durable fix is older and simpler: treat the agent's memory as plain files on disk, in a format any model can read. Done well, that gives an agent a memory that outlives the model running it— which is exactly what you want the day you swap models, add a second agent, or hand the work to whatever comes next.
Four layers on disk
CLAUDE.mdOperating rules— the standing conventions every session followsevery sessionindex.mdThe index— one line per memory, so the agent knows what existsevery sessionmemory/*.mdFact files— one per change: what, why, current state, how to undoon demand// + .bakBreadcrumbs— context left beside the code and configs it explainson readRetrieval runs outside the model
Swap the reader — the store and the retrieval don't change:
The one idea: the model reads the memory, it never contains it
A model's weights are frozen and its chat history evaporates when the session closes. Neither is a place to keep anything you need next week. Anchoring on that single fact changes the whole design: nothing durable lives inside the model. It lives in files. The model is just the current reader.
That is what makes the system model-agnostic in a way a proprietary memory feature never can be. The intelligence readsthe context; it doesn't store it. Swap the reader — a smaller model, a future one, a different framework, or a human — and the memory is untouched.
Four layers of durable context
“Memory” is really a few different jobs, and it helps to keep them in separate layers rather than one giant scratchpad.
- Operating rules.One always-loaded instructions file — Claude Code, for example, reads a file named
CLAUDE.mdat the start of every session — holding the standing conventions that rarely change. This is the constitution: how we operate here. - An index. One small file that lists every memory in a single line each. Kept deliberately short so it always fits in the working context, it is the table of contents the agent sees on every run.
- Fact files. One file per fact or decision. The useful ones carry five things: what changed, why, the current state, how to undo it, and the gotchas. That last pair is what lets a cold agent safely continue or revert instead of guessing.
- In-place breadcrumbs.Context that travels with the thing it describes — a short note beside the line of code it explains, a dated backup beside the file it can restore. This is the memory an agent finds exactly when and where it needs it.
Retrieval belongs outside the model
Here is the piece people miss. The decision of whichmemories matter for a given task should not be the model's job. It runs in a small, deterministic step before the model ever sees the prompt: match the request against each memory's one-line description, pull in the handful of hits, and hand them to the model as context.
Because that matching step lives outside the model, it behaves identically no matter who is driving. Trade a large model for a small one, or for next year's release, and the store and the retrieval don't change — only the reading and reasoning do, which is the part models are actually good at. A better model doesn't need a different memory; it simply understands the same files more deeply.
Why plain files hold up
- Portable by construction. Markdown with a small structured header. No embeddings database, no vendor memory API, nothing to orphan when you change models or tools. It stays greppable, diffable, and readable by a person.
- Self-correcting. When a fact turns out wrong, you edit the file. The next reader inherits the correction, not the mistake — unlike an append-only log that quietly accretes stale claims nobody trusts anymore.
- Concurrency-safe.When several agents share one index, writes go through a single locked, atomic step so two of them can't silently clobber each other's notes.
The honest limits
A pattern earns trust by naming where it breaks, so three caveats worth stating plainly:
- A memory is a snapshot. The file or line it points to can move, so an agent should verify against the live system before trusting an old note — re-check, don't assume.
- The always-loaded index has a size ceiling. Past it, entries get dropped, so the index needs periodic curation to stay useful.
- It is only as good as the discipline feeding it. The memory exists because every session is expected to write down what it did — skip that habit and the store goes stale.
Why this matters for trustworthy AI
The pattern is deliberately unglamorous: text files, a matching step, and a writing habit. But it is what separates a clever one-off from a system you can rely on over time. An agent that forgets is a demo; an agent whose successors pick up exactly where it left off — whatever model powers them — is infrastructure.
That is the same reason trust in AI has to rest on things you can inspect. A memory you can open and read, a retrieval step you can reason about, a record that corrects itself in the open — these are verifiable properties, not promises. As more of the web is read, judged, and acted on by AI, the systems that win are the ones whose trustworthiness you can actually check.
Can AI systems verify that your site is trustworthy?
Run all 43 trust checks — identity, security, content, reputation, and AI readiness — and see exactly what ChatGPT and Claude weigh before they cite you.