Build With a Memory

Your AI agent forgets your project every session.

So it re-derives the same decisions, and you pay for it every time. The fix is not a bigger model or a smarter prompt. It is a place to remember, and it is just files in your repo.

prompt.txt

Set up a simple project memory for THIS repository, so you and any AI coding assistant I use later can pick up where we left off instead of re-learning the project every session.

Follow these steps in order. Write down only what you can confirm from the repo. Never guess, never invent placeholder facts, and never overwrite or delete anything I already have. If a file already exists, read it and add to it.

1. LEARN THE PROJECT FIRST. Before writing anything, read what is actually here: the README, any package or build file (package.json, pyproject.toml, go.mod, Cargo.toml, Gemfile, composer.json, and so on) for the language and the real commands, the top-level folder layout, and the last 20 commits (git log --oneline -20). If the repo is empty or brand new, say so plainly and keep everything short.

2. PICK THE MAIN FILE. If CLAUDE.md exists, that is the main file. Otherwise, if AGENTS.md exists, that is the main file. If neither exists, create CLAUDE.md. Create the other one as a two-line pointer that says the real content lives in the main file, so any assistant finds it.

3. WRITE THE MAIN FILE SHORT. A newcomer should be able to read it in about a minute. Include only: what this project is (one or two plain sentences), how to run it (the real install, dev, test, and build commands you actually found), and the rules that matter (conventions, do-not-do items, gotchas you can see). If the main file already exists, keep everything useful in it and add only what is missing.

4. ADD THREE SMALL FILES in a docs folder (add to them if they exist, do not overwrite):
   - docs/now.md: what I am working on right now. A few dated lines about the current focus. (At setup, only add.) Going forward, rewrite this file instead of piling onto it: when a line is done or quiet for about two weeks, move it out (to docs/decisions.md if it was a decision, otherwise drop it). Keep it to what is active.
   - docs/decisions.md: decisions and why. One dated entry per real decision, newest first, each saying what was decided and the reason. Seed it from any clear decisions in the README or commit history. If none are clear, leave one line saying the file is for decisions as they come.
   - docs/notes.md: gotchas worth not re-discovering. Seed it with any traps you noticed while reading the repo, otherwise leave one line saying what it is for.

5. WIRE THE HABIT. Add this section to the main file (adjust the paths if you used AGENTS.md as the main file):

   ## How to use this memory
   - Start each session by reading docs/now.md to see what is active.
   - When we make a decision, write it in docs/decisions.md with the date and the reason, in the same session it happens. This is part of finishing the work, not a separate chore.
   - When we hit a gotcha worth remembering, add it to docs/notes.md the same way.
   - Keep this file short. When a section gets long, move the detail into a docs file and leave a one-line pointer here.

6. REPORT BACK with a short list of exactly what you created or changed. Nothing else.

Paste it into Claude Code, Cursor, or whatever agent you already have open. No account, no install, nothing to sign up for. The prompt and the full method are on GitHub.

Same question, two fresh sessions

An illustration, not a real log.

Without a memory

you what database does this project use?

agent I can't tell from what is open here. what are you running?

you we decided this weeks ago.

With a memory

you what database does this project use?

agent Postgres. docs/decisions.md says JSONB, and one less service to run.

What it does

It sets up a handful of plain markdown files next to your code, and tells your agent to read them first. That is the whole trick. The next session starts from what you already decided instead of asking you to explain it again.

Plain markdown files that live in your repo. Nothing to install.
No server of mine, no account, no API. The memory is files in your repo, and it goes where your repo goes.
Works with Claude Code, Cursor, or any agent that reads an instructions file.
It is structure for one person, not a hosted engine you rent. Delete it and it is gone. Keep it and it travels with your code.

Watch the memory form. Each node is a file or a decision your agent can read next session.

That is the memory. Committed next to your code, yours to keep.

What it is not

I am not promising your agent perfect recall. This is a way of working, not a product.

Not a hosted service, and not a place your data goes.
Not a benchmarked retrieval engine. It is structure, not search.
Not another tool to install. It is text files you already can write.
Not magic. You still have to write the decision down; the setup just gives it a place and makes the agent read it.

It is the instructions file you probably already have, set up so it does not go stale as the project grows.

The letter

I write a short letter every two weeks about building software and games with AI agents, including the parts of this method I am still working out. Optional, and the prompt above never needs it.

You'll get one confirmation email first. Unsubscribe is one click, any time, and I never share your address.

Who is behind this

I'm Andrew Detwiler. I make games at Turtlevania Games, and I build Playloop, a playtest tool for indie game developers. This method is how I build all of it. Same idea as this page: write down what you learn so you stop guessing. Players quit silently, and Playloop shows why they quit, not just that they quit. If that sounds useful, come take a look.