Memory files (CLAUDE.md & co)

Here’s a slightly depressing truth about code agents: they have no memory. You can spend two hours explaining your project, correcting the same mistake ten times, laying down your rules, and the next session, the agent comes back to a blank page. It has forgotten everything. The LLM only remembers what fits in the current conversation. Close the window, and it all vanishes.

Except one thing: the memory file. It’s a text file the agent reads automatically at the start of every session, before you even type anything. You write down once what it should remember forever. It’s exactly what stops you from repeating yourself.

The file, and its global twin

Every agent reads a memory file. The name changes depending on the tool, but the idea is identical.

• Claude Code reads a file named CLAUDE.md. Since version 2.1.277, it also reads AGENTS.md when the project has no CLAUDE.md.
• Codex reads a file named AGENTS.md, at the repo root and in each subfolder down to the one you’re working in. It doesn’t read CLAUDE.md on its own, but one line in ~/.codex/config.toml makes it pick it up wherever AGENTS.md is missing: project_doc_fallback_filenames = ["CLAUDE.md"].
• OpenCode reads a file named AGENTS.md, and falls back to CLAUDE.md if it can’t find one.

AGENTS.md has become the shared convention: beyond Codex and OpenCode, Cursor, Gemini CLI, GitHub Copilot and many other tools read it, and the format is now stewarded by the Agentic AI Foundation, under the Linux Foundation (agents.md). To see which coding tools exist and which models each one offers, Quelle IA keeps a tools page (in French).

Same mechanism, just a different filename. And in both cases, there are two levels:

• The project file, at the root of your repo. It describes that particular project: its purpose, its stack, its rules. It travels with the code, so anyone (or any agent) who opens the repo inherits it.
• The global file, at your user level. It carries your permanent preferences, valid across all your projects. For Claude Code, that’s ~/.claude/CLAUDE.md; for Codex, ~/.codex/AGENTS.md; for OpenCode, ~/.config/opencode/AGENTS.md.

./CLAUDE.md          # project memory (at the repo root)
~/.claude/CLAUDE.md  # global memory (all your sessions)

./AGENTS.md              # project memory (at the repo root)
~/.config/opencode/AGENTS.md  # global memory (all your sessions)

./AGENTS.md              # project memory (at the repo root)
./subfolder/AGENTS.md    # rules for one folder, read after the root ones
~/.codex/AGENTS.md       # global memory (all your sessions)

What belongs in it (the real substance)

A good memory file fits in four sections. No more.

• The project context. What it is, and above all the one-sentence goal: the one you already extracted in your project brief. It’s the agent’s compass.
• The conventions and rules. The choices the agent can’t guess and you don’t want to re-justify: “always show sudo commands before running them,” “no secrets in plain text,” “we use React, not Vue,” “never touch the legacy/ folder.”
• The commands that matter. How you run, build, test, and deploy this project. The agent will repeat them faithfully instead of inventing a command that doesn’t exist.
• The hard-won lessons. The recurring trap, the counterintuitive thing, the bug you both broke your teeth on. “The API returns 429 if you hit it more than 5 times/s, throttle.” That kind of knowledge is gold and gets lost otherwise.

What must NOT go in it

A bloated memory file is worse than an empty one: it eats context every session without adding anything. Keep it dry.

• What the code already says. No need to copy the directory tree or list every file: the agent knows how to read the repo. Memory is for what’s not in the code.
• Secrets. Never. Not an API key, not a password. The file travels with the repo, see Securing access.
• Details of a single conversation. “Yesterday we renamed this button” has no place here. Memory is the permanent stuff, not the logbook.

A concrete, reusable example

Here’s what an honest CLAUDE.md looks like for a small web project. Dense, useful, no fat:

# Kino, movie dashboard

## Goal
Pull together the week's movie releases (posters, ratings, synopses),
viewable from my phone. Personal use, single user.

## Stack
- Front end: Astro + TypeScript, deployed statically.
- Data: TMDB API (key in the env var `TMDB_KEY`, never hardcoded).
- No database, no auth, no backend in v1.

## Rules
- Always show destructive commands (rm, git push --force) first.
- No secrets in plain text: everything goes through .env (already gitignored).
- TypeScript strict. No `any` without a comment justifying it.
- Never touch the `vendor/` folder (frozen third-party code).

## Commands
- Dev: `npm run dev` (port 4321)
- Build: `npm run build`
- Tests: `npm test` (Vitest)
- Lint: `npm run lint`

## Gotchas
- TMDB returns 429 above ~40 req/10s: we cache responses for 24h.
- Missing posters come back as `null`, not an empty string, test `== null`.

You can read it in fifteen seconds. That’s the goal: an agent that swallows it at startup walks away with all the context you’d otherwise have had to re-explain.

Global memory, for your own preferences

The global file, for its part, talks about no project in particular. It carries the way you work, everywhere:

# Global preferences
- Always answer in French.
- Prefer simple solutions: fewer dependencies, less abstraction.
- Before any sudo or destructive command, show it and wait for my approval.
- No obvious comments in the code. Comment the why, not the what.

Write that once, and every new project already starts tuned to you.

How to bootstrap it without starting from scratch

You don’t have to write the project file by hand staring at a blank page. Most agents can generate it by scanning your repo, then you refine it.

Memory grows with friction

Don’t try to write the perfect file on the first pass. Memory builds itself through use, and there’s a very clear signal: the day you correct the agent twice on the same thing, promote the correction to a rule.

It writes an unescaped SQL query again? → one line in memory. It systematically forgets to run the linter before committing? → one line. Every recurring friction becomes a rule, and the friction disappears. This is exactly the ”↻ loop back” from the framing guide: the project lives, and the memory learns alongside it.