How to make your AI remember what you decided

Three different people crossed my feed this week trying to solve the same problem, and none of them mentioned each other. One shipped a small tool so a coding agent would stop making the same mistake twice. One asked a room of senior engineers what knowledge they most wish had never gotten lost. One posted a link called the session you cannot take with you, and it climbed to the front page. Same wall, three angles, and I recognized it immediately, because I already keep a file for exactly this.

If your AI agent keeps forgetting what you decided, the fix is almost never a bigger context window. It is writing the decision down as a file in the repo. Not the chat, not a longer prompt: the actual decision, the option you rejected, and the constraint that made you reject it, committed where the next run reads it before it does anything else. Memory that survives a session is a versioned artifact, not a conversation. A vibe coder who learns that one move stops re-explaining the whole project every single morning.

why does my AI agent keep forgetting what I decided?

Because a chat is not a memory, and the thing most people reach for when an agent forgets makes it worse. The reflex is to give the agent more: paste the whole history back, write a longer prompt, turn up whatever context window the tool is advertising this month. It feels right and it fails in a specific way. A bigger window is a bigger pile to search on every turn, not a better index into it. The one line that mattered from last Tuesday gets buried in ten thousand words of transcript and quietly skipped. That loop, re-explaining yesterday every morning, is the most common complaint I hear in vibe coding right now. I wrote about the failure on its own in why your AI agent keeps forgetting; the short version is that recall gets less trustworthy as the pile grows, so a longer session is a worse memory, not a longer one. If that is the wall you are at, the rest of this is the move that actually holds.

where should the decision actually live?

In the repo, next to the code, in a file that gets versioned with everything else. That is the whole trick, and it sounds too simple until you watch it work. When I make a real decision on a build, I do not trust myself to remember why a month later, and I definitely do not trust a fresh agent to. So the decision goes into a spec file or an invariant the same day I make it, in plain language, committed. The next session opens the repo, reads that file at the top, and starts from the decision instead of from zero.

The reason a file beats a chat is that a file is addressable and a conversation is not. You can point an agent at a spec or a project instructions file and say read this first, and it will, every run, the same way each time. You cannot point it at "that thing we figured out on Tuesday." A versioned artifact is the difference between memory you can rely on and memory you have to hope survived the window. This is the principle I lean on hardest across every build: context-handoff-continuity, the plain idea that the handoff from one session to the next has to ride an artifact, never a hope.

what do I actually write down?

Three things, and the second is the one people skip. The decision itself, stated flat. The option you rejected. And the constraint that made you reject it. That rejected option and its constraint are what stop the next run from cheerfully re-proposing the thing you already ruled out. A decision without its rejected alternative is an order; a decision with it is a lesson, and a lesson is the thing that actually transfers to the next session.

Here is the loop I run, and it is boring on purpose. Move one: something breaks or gets decided, and I diagnose it once, properly, all the way to the cause. Move two, the same day, I codify that finding into the spec or an invariant, with the rejected fix sitting right next to it and one line about why it fails. That is the entire ritual. The next run inherits the finding instead of rediscovering it. The last time an agent of mine started re-investigating a bug we had already solved, I did not write it a cleverer prompt. The answer was already in the file. The agent had just not been pointed at it yet. Diagnose once, codify the same day, let the next run read it. The codification is the memory. Nothing bolted on, no extra system.

what tends to break with this

The failure modes are real, and naming them is how you dodge them.

The first is the journal nobody rereads. If your memory file is a running prose diary, it rots, because prose does not tell the next run what to do. Keep it as decisions and constraints, not a narrative. The next reader is an agent that wants an instruction, not a story about your afternoon.

The second, and the one I watch hardest, is drift between the memory and the code. If you write the decision on Monday and change the code on Wednesday without touching the file, the file now lies, and a lying memory is worse than none, because the agent trusts it and acts on it. The discipline that saves you is small and non-negotiable: update the artifact in the same commit as the decision, never later. Memory and code move together or the memory becomes fiction.

The third is over-building. You do not need a memory framework, a vector store, or a bespoke system to start. You need a flat file the next run reads first. I have watched capable vibe coders spend a weekend on a memory architecture that a single committed file would have beaten, which is its own kind of forgetting: forgetting that the simple version already works. There is a reason the market is busy rebuilding, in tools, the thing a repo file has quietly always done.

questions that keep coming up

Isn't this just documentation? Close, but the audience and the cadence are different. Documentation is written for a human to read occasionally. Memory is written for the next run to read every time. A doc can be six months stale and still useful. A memory file that is one commit stale is actively dangerous, because the agent acts on it as if it were true.

Where do I put the file? In the repo, tracked in version control, read at the top of the session. A spec file, an invariants file, a project instructions file, the exact name matters far less than that it is versioned and the agent is pointed at it first. If it is not in version control, it is not memory, it is a sticky note.

Does this scale past one file? It does, and the shape stays identical. A big vibe coded build ends up with a spec per major decision area and an index that points at each one, which is just AI orchestration turned on your own reasoning: the same spec-first discipline you would use on the code, applied to the decisions behind it. You can see the same habit in how I keep a build readable as it grows.

If you are turning a pile of hard-won decisions into a process that survives the next session, and you want a sparring partner on where that memory should live, /work-with-us. The interesting part is never the file format. It is deciding which decisions are load-bearing enough to write down, and that is the part worth doing with someone who has hit the wall before.

Your agent is not going to remember Tuesday for you. Write Tuesday down where it will read it.