AI Agent Memory: How Agents Remember Between Sessions
AI agents have no built-in long-term memory: every session starts blank. The reliable fix is not a bigger context window or a memory framework, but a small set of plain text files the agent reads at the start of every session and updates before it ends. Our own operation runs on six files, but the minimum viable version is one: a single state file that answers where things stand, what comes next, and what is blocked. This page is the full reading path, from why the forgetting happens to the exact file system that solves it.
The reason this matters is that most people reach for the wrong fix first. Told that an agent "forgot," they go shopping for a larger context window or a plugin that promises memory. Neither addresses the actual gap, because the forgetting happens at the boundary between sessions, and that boundary exists at every context size. What carries knowledge across the boundary is text saved outside the session. Files, not settings.
Do I need a vector database or a memory framework?
No, not at solo scale. A vector database and a memory framework solve retrieval over large document sets; they do not solve the basic problem that a new session wakes up not knowing what the last one did. For running a single agent as an employee, a handful of hand-editable markdown files beats an opaque memory store on every axis that matters: you can read them, diff them in git, correct them by hand, and move them to a different tool. Start with plain files. Add machinery only when a specific need appears that files genuinely cannot meet, which at solo scale is later than you think.
Start here: the reading path
Read these in order. The first three explain the problem and the one-file fix; the rest build out the full file system and the habits that keep it honest.
- Why your AI agent forgets everything (and the 1-file fix) - the cause in one page: each session is a blank instance, and the minimum fix is a single state file.
- How do I give an AI agent a second brain? - the eight plain text files that survive between sessions and the two-minute startup that loads them.
- What is a CLAUDE.md file? (And why your agent needs one) - the file Claude Code reads automatically every session, its five sections, and how it differs from AGENTS.md.
- CLAUDE.md examples: the job contract pattern - the sections that turn a config file into an employment contract the agent follows.
- How to make an AI agent remember every decision - the four-field decision log that stops future sessions from reopening settled calls.
- What happens when an AI agent's session dies mid-task? - why hourly checkpoints make a crash a two-minute recovery instead of a lost day.
- Why bigger context windows won't fix your agent's amnesia - the direct answer to the fix people try first, and why you want the files regardless.
- How to give Claude Code persistent memory - no plugins, just files - the concrete file structure that reconstructs full context in two minutes, every session.
- AI agent memory: do you need a vector database? - files versus frameworks, and why plain markdown wins at solo scale on auditability and portability.
FAQ
What is the minimum viable memory for an AI agent?
One file. Create a single STATE.md with three headings - current status, next steps, and blockers - and tell the agent, in its instructions, to read it at the start of every session and update it before stopping. That one change removes most of the daily pain of re-explaining, and you split off further files only when the single file starts to strain. You do not need the full system to feel the difference; you need one file and the habit of reading and writing it.
Does a bigger context window fix the memory problem?
No. A larger context window lets one session hold more at once, but the next session still starts blank no matter how large its window is. The forgetting happens at the boundary between conversations, and that boundary exists at every size. A bigger window is a bigger desk, not a filing cabinet. The only thing that carries knowledge past the end of a session is text saved outside it, which is exactly what a state file is.
Does this work with any AI agent, or just Claude?
Any agent. The files are plain markdown and model-agnostic: the same STATE, BACKLOG and contract that work with Claude Code work with any tool that can read a file at the start of a session. That portability is a feature, not an accident - your operation is not locked to one vendor, because the memory lives in files you own rather than in a product's hidden memory feature.