What you’ll be able to do

This is the bit where the assistant stops being goldfish-brained. Right now, if you’re like most people, you’re the clipboard: copying decisions from one chat into the next, re-explaining what you built yesterday, pasting in context every single morning. That’s tedious, and it’s also the reason sessions feel like they never quite build on each other.

The fix is simple in shape, even if it takes a bit of setup. Your assistant writes its own plan, keeps a running note of what’s happening right now, and holds a small file of stable facts about how you work. Next session, it reads all three before doing anything. It picks up where it left off. It tells you what’s unfinished and what needs a decision from you. And when a session dies mid-task (which happens more than you’d think), the next one doesn’t start cold, because the last one left a note.

That’s the whole outcome. No more clipboard duty. The assistant remembers, because you told it where to write things down.

Before you start

Not every AI assistant can do this. You need something that reads and writes files in your project, not just a chat window. Claude Code, Cursor, GitHub Copilot’s agent mode, and Codex can all do this, because they operate directly on your repo rather than in an isolated chat. If you’re using a plain browser chat with no file access, this guide isn’t for you yet, that’s a different setup entirely (see “How to get AI to remember context” for the browser-based version of this idea).

Worth being honest about why this matters more than it sounds like it should. Sessions end. Sometimes on purpose, sometimes because context runs out or the machine restarts with zero warning. If the only record of a decision lives in your chat history, it’s gone, or at best it’s buried in a scroll-back you’ll never find again. Files outlive sessions. Chats don’t, not reliably.

One more thing before you start: think about what you’re willing to let the assistant write down. These files will sit as plain text in your repo. Never let secrets, API tokens, passwords, or anyone else’s personal data end up in them. I’ll come back to this properly later, but it’s worth having in your head from the start, because it’s much easier to keep this boundary from day one than to go scrubbing history later.

Get set up

Three files do most of the work here. You don’t need more, and honestly, more is a trap.

PLAN.md holds what you’re building, decisions made, and what’s left. This is the “why are we doing this” file. It lives in docs/ if that’s your convention, and gets ticked off as things ship.

STATE.md is the handover file, what was happening a minute ago. This is the one that saves you when a session dies unexpectedly. Whatever the assistant was mid-way through, it goes here.

MEMORY.md (or a memory folder, if it grows) holds stable facts about how you work. Not “what we’re doing today”, but things like your naming conventions, your deploy process, the fact that you always want tests before a merge. This is “what is”, not “how to”. Procedures and step-by-step how-tos belong in separate skill files, not memory. Keep the distinction, or memory becomes a junk drawer.

The trick that makes this actually happen, rather than being a nice idea you forget about, is putting the instruction where the assistant reads it automatically at start-up. For Claude Code that’s CLAUDE.md. For other tools it might be AGENTS.md or .cursor/rules. Whatever the file is, this is the block to put in it:

Read PLAN.md and STATE.md before doing anything.
Update STATE.md every 15 minutes and before you stop.
When you learn a stable fact about how I work, or a
decision I have made, add it to memory and tell me.

That’s it. That’s the rule. Not a hope, not something you mention once in a chat and never again, an actual instruction sitting in the file the assistant reads first.

A couple of Claude Code specifics worth knowing. Typing # at the prompt appends straight to CLAUDE.md, handy for quick notes without breaking flow. /memory opens the memory files directly so you can review or edit them. And hooks can run a script after tool calls, which means you can automate the nagging. I use one that pings me for a state entry once fifteen minutes have passed, because otherwise, left to their own devices, fifteen minutes becomes two hours and the handover note never happens.

Commit PLAN.md and STATE.md to git. Every change becomes visible, and reversible if the assistant writes something daft.

Try it yourself

Three prompts, three jobs. Copy them as they are.

First, at the start of a session, to prime the assistant properly rather than assuming it’s done its homework:

Before we start: read PLAN.md and STATE.md in full.
Summarise what was decided, what's unfinished, and
what you think I need to decide today.

Second, before you stop for the day, or before a break, to force the handover rather than hoping the assistant remembers to do it unprompted:

Before you stop, write a handover into STATE.md:
what you did, what is unfinished, what I need to decide.

Third, every so often, to keep memory honest rather than letting it quietly accumulate rubbish:

Review MEMORY.md: which entries are stale, contradicted
by the code, or too vague to act on?

And when the assistant actually learns something worth keeping, this is the shape to ask for:

Add to memory: [fact]. One file, one fact, link it
to related ones.

One fact per entry, linked to related ones. Not a paragraph of hedged waffle. If the assistant writes something vague, push back and ask it to rewrite in one clear sentence.

Check the result

Don’t just trust that this is working. Test it.

Start a brand new session and ask the assistant what it knows about the project before you say anything else. Does it mention what was decided last time, unprompted? If it’s blank, or guessing, the startup rule isn’t wired in properly, check the file it’s meant to read at launch.

Deliberately end a session mid-task, then start a new one and ask it to continue. Does STATE.md actually reflect what was happening? If the handover note says “all done” when it clearly wasn’t, that’s a sign the assistant isn’t updating STATE.md at the cadence you asked for, every fifteen minutes and before stopping.

Watch for the moment it learns something new. Tell it a stable fact about how you work, something like “I always want the tests run before a commit”, and see whether it writes that to memory unprompted, or whether you have to explicitly ask with the “add to memory” prompt above. If it never volunteers it, the start-up rule needs tightening.

The real test of whether it’s remembering versus hallucinating: open MEMORY.md yourself and read it against what you know is true. Does every line check out? If an entry states something that never happened, or that used to be true and isn’t any more, that’s the assistant “remembering” wrong, and it’ll happily repeat that wrong fact for weeks unless you catch it.

If it doesn’t work

The most common failure is the assistant writing entries that are vague or flattering rather than useful. Something like “the user prefers clean code” tells you nothing and can’t be acted on. Push for specifics. If it won’t give you specifics, rewrite the entry yourself.

Second failure: it remembers something wrong, and because nothing ever challenges it, that wrong fact just sits there, quietly steering decisions for weeks. This is why reviewing the memory diff now and then matters more than it sounds like it should. Git shows you exactly what changed and when. Read it occasionally. It’s boring, but it’s the only real check you have.

Third, and sneakier: the rules themselves can drift, because the assistant edited them. If you keep a section of “things the assistant may never do”, make sure that section is one the assistant is explicitly told not to edit. Otherwise you’ll find, months later, that a boundary you set has quietly loosened because nobody was watching.

The fix for all three is the same, every time: keep the files in git, and have a human, you, actually read the diff sometimes. Not every commit. Just often enough to catch drift before it compounds.

On privacy: these files are plain text, sitting in your repo, possibly synced to a remote, possibly readable by anyone with repo access. Never let secrets, tokens, passwords, or other people’s personal data go into a memory file. If you wouldn’t paste it into a public chat, don’t let the assistant write it to a file either. If you’re building a commitment ledger, a record of promises made before work starts, keep the same rule: facts about your process, never anything sensitive.

Keep exploring

If you haven’t already, “How to get AI to remember context” covers the version of this idea for assistants that can’t touch your file system. “How to get AI to understand my code” goes deeper on getting an assistant properly oriented in a codebase, which pairs well with a solid PLAN.md. And “How to get AI to automate repetitive tasks” is worth a look once your state and memory files are stable, because a lot of the nagging and checking described above can itself be automated.

Sources and review notes

https://code.claude.com/docs/en/memory https://code.claude.com/docs/en/hooks https://cursor.com/docs/rules https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions https://agents.md/

Review date: 2026-09-16