Your AI forgets everything. Build it a memory.
The file system that lets me run months-long projects with a collaborator that wakes up blank every session.
Every AI session starts at zero. The model that shipped a feature with you yesterday has no idea it happened. Left alone, a long project with an AI collaborator rots in a specific, predictable way: you re-explain the same context, it re-argues decisions you settled weeks ago, and it re-makes mistakes you already paid to learn from.
Most people respond by pasting more into the chat. That’s backwards. The chat is the most perishable place you can put anything.
The fix is boring and it works: externalize the project’s memory into files the AI is required to read. Not one giant file — a small system of them, each with one job. Here’s the one I run a game, two apps, and a marketing operation on. It’s survived three model generations and two different AI tools, because it’s just markdown.
The files
A current-state file. What’s true right now: the active focus, the latest built state, what not to break, and the next tasks. This file has a hard size cap — mine holds the last ~8 working sessions, about 300 lines. When it grows past that, the oldest blocks move to an archive in the same commit. This cap is not optional. An unbounded status file becomes a history archive, and a history archive is where current truth goes to hide.
A decision log. Every decision that was expensive to make or is likely to get re-argued. When the AI proposes renaming something you named on purpose, or “simplifying” an architecture you chose for a reason, you don’t debate it — the log settles it. (I ran this file for months before learning software teams have a name for the practice: Architecture Decision Records, ADRs, in use since long before AI. I didn’t know that. I was just tired of re-arguing settled questions. Converging on a twenty-year-old engineering practice from outside the profession made me trust the file more, not less.)
A drift-checks file. The mirror image of the decision log: things not to build. Directions explicitly rejected. AI is relentlessly helpful, and unsupervised helpfulness drifts. This file is the fence.
A lessons library. One file per solved hard problem: what broke, why, the fix, and the general method. Written the same day the problem was solved, before the details fade. Next time that class of problem appears, the lesson gets loaded instead of relearned. Mine has about thirty entries. Each one is a mistake I only paid for once.
An index. A routing file that says which lessons are mandatory reading for which kind of work. Nobody — human or AI — reads thirty files before every task. The index means the right two get read.
The two protocols
Files alone aren’t enough. Two rituals keep them honest.
Session start: the AI reads current-state, the decision log, and drift-checks before touching anything. Not optional, not “when relevant.” Every session, before work.
Session close: before ending, the AI updates current-state, files any new lessons, and records any new decisions. I trigger mine with a literal phrase — “update all docs and prepare for clear” — that means stop building, start remembering. The docs update in the same commit as the code they describe, every time, because docs updated “later” are docs that lie.
One detail that matters more than it looks
Old documents don’t announce that they’re stale. An AI searching your files will happily treat a superseded plan from March as current truth, because agents search by words, not intent. So every document that could be mistaken for current guidance carries a status header: ACTIVE, or SUPERSEDED — see decision log. Two lines. They’ve prevented more confusion than anything else in the system.
Why this outlives the tools
Nothing above depends on any vendor’s memory feature, context window size, or model. It’s files in a repo. When the next tool arrives, the memory transfers in one command, and the new collaborator is productive on day one — which is more than I can say for most humans joining a project.
The models will keep getting better. They will also keep waking up blank. Build the memory outside the head.