What a brain file is (and why your AI keeps forgetting)

You spend an hour teaching your AI how your project works. It finally gets it. The next day you open a new chat and it has no idea. It suggests a framework you don't use, rewrites a file you told it not to touch, and puts an API key right in the code.

That isn't the AI being dumb. It's the AI having no memory of your project. A brain file fixes that.

Why your AI forgets

AI models don't learn from your chats as you go. Each session, the model only knows two things:

• Its training: general knowledge about code, frozen at some point in the past. It has never seen your project.
• Its context window: the text it's been given in this session: your messages, the files it opened, tool output, and any instructions loaded automatically.

When the session ends, the context is gone. Long chats also hit limits, so older messages get summarized or dropped even inside one session. Anything important that only lives in chat history will eventually be lost.

So the fix is simple: put the important stuff in a file that gets loaded into context every time.

What a brain file is

A brain file is a plain Markdown file in your project that tells the AI what it needs to know before touching anything. Most AI coding tools look for one automatically by name and load it at the start of each session. Common names:

File	Read by
AGENTS.md	A shared convention supported by a growing list of coding agents (OpenAI Codex among them)
CLAUDE.md	Claude Code
GEMINI.md	Gemini CLI and other Gemini-based agents
.cursor/rules/*.mdc	Cursor
.github/copilot-instructions.md	GitHub Copilot

Tools change fast, so check your tool's docs for the current name and location. The formats guide goes deeper. The content is the same idea everywhere: this is the project, this is how we work here, this is what you must never do.

Even if your tool doesn't load a file automatically, you can still keep one and tell the AI "read AGENTS.md first" at the start of a session. You get most of the benefit.

What goes in it

Think of it as onboarding notes for a smart new teammate who has never seen the repo:

1. Overview. What the project is, who it's for, and what "good" looks like.
2. Stack with versions. "React" is vague. "React 19 + Vite 6 + TypeScript, no CSS framework" is useful. Versions matter most where APIs changed a lot (game engines, bot libraries, major framework releases).
3. Commands. The exact commands to install, run, build, test, and lint. The AI shouldn't have to guess.
4. Map of the code. Which folders hold what, and where new things should go.
5. Always and never rules. Short, specific, testable. "Never add a dependency without asking" beats "keep things lean".
6. Security rules. Where secrets live (and that they never go in code), what gets deployed, which commands need your OK.
7. Definition of done. Builds without errors, works on mobile, docs updated: whatever "finished" means for you.

What stays out

• Secrets. No keys, tokens, or passwords, ever. The file is committed and read by tools.
• Huge docs. Every line costs context on every request. Link to longer docs in the repo instead of pasting them.
• Vague vibes. "Write clean code" changes nothing. "Functions under 40 lines; one component per file" does.
• Stale info. A wrong rule is worse than no rule, because the AI will follow it confidently.

A starter brain file

Copy this, then replace everything in it with your project's details:

# AGENTS.md: Pixel Pantry

## Project overview
A small web app that tracks what's in my fridge and suggests recipes.
Audience: me and my roommates. Must work well on phones.

## Tech stack
- Vite 6 + vanilla JavaScript (ES modules), plain CSS
- Data stored in localStorage (no backend yet)

## Commands
- Dev: `npm run dev`
- Build: `npm run build` (outputs to dist/)

## Always
- Keep it mobile-first; test at 375px wide
- Explain changes in plain language, I'm learning

## Never
- Add a framework or npm package without asking
- Put API keys in front-end code

## Security
- Secrets live in .env (gitignored), never in code or commits
- Only dist/ is deployed

## Definition of done
- `npm run build` passes, no console errors, works on mobile

That's about 25 lines, and it already prevents the most common AI mistakes. Don't want to type it? The generator builds one from a form.

Keep it alive

A brain file is a living document. Two habits make it powerful:

• Every repeated correction becomes a rule. If you tell the AI the same thing twice ("we use fetch, not axios"), add it to the file. Now you never have to say it again.
• Prune. When something changes, update or delete the rule. Aim to keep the main file short (a page or two); move detail into separate docs the file links to.

Once that's working, you can give your AI real long-term memory with notes, decision logs, and backups. That's the long-term memory guide.