Lesson 5 - Project Memory: CLAUDE.md and AGENTS.md

Welcome to Project Memory#

You’ve got a goal, safe permissions, a first run, and a self-check. The last piece is making all of it stick, so you don’t re-explain the brief and the checks every single session. That’s what project memory does: a plain-text file — CLAUDE.md for Claude Code, AGENTS.md for Codex — that lives in your folder and that the agent reads automatically at the start of every session. It’s your brief and your check, written once, traveling with the folder. This lesson covers how to write one, the few caveats that matter, and then the module project that ties everything together.

By the end of this lesson, you will be able to:

• Write a project memory file that carries your brief and checks
• Explain its three key caveats: once per session, guidance not enforcement, keep it short
• See how it reuses everything from Modules 2 and 3
• Complete the module project: an agent that sorts, renames, and indexes a folder

Let’s start with what these files are.

A File the Agent Reads Every Session#

A project memory file is exactly what it sounds like: standing instructions the agent loads at the start of each session, so it begins already knowing the goal, the checks, and the conventions for this folder. It’s written in plain Markdown — the same simple headings-and-bullets format these lessons use — so a non-developer can write one in a text editor. No code, no special syntax.

What goes in it is nothing new — it’s the artifacts you’ve been building all course. The goal (Module 2). The definition of done the agent should verify against (Module 3). The conventions you want followed (date formats, folder structure). And what to leave alone. Write your brief once into CLAUDE.md, and every session in that folder starts with the agent already knowing what “done” means and how you like things done — the persistent-setup idea from Module 4, now for a file agent.

Three Caveats That Actually Matter#

Project memory is powerful, but three things about how it works will bite you if you don’t know them.

It’s read once per session, not per action. The agent loads the file when the session starts and works from that copy. If you edit CLAUDE.md in the middle of a run, the change usually won’t take effect until you start a fresh session. So when you update your standing instructions, restart the agent to be sure they apply — don’t assume a mid-run edit is being followed.

Reading is not obeying. This is the guidance-versus-enforcement point from Lesson 2, and it’s worth repeating because the file feels authoritative. A memory file is guidance: it strongly shapes what the agent tries to do, but it does not lock anything. “Leave the invoices folder alone” in CLAUDE.md is a request the agent will usually honor — but if that folder must never be touched, the real protection is a permission deny, not the memory file. Use project memory to make the agent helpful and consistent; use permissions to make it safe.

Keep it short. These files have a size limit, and beyond it they get truncated — and even below it, a long, rambling memory file gets skimmed rather than followed, the same way a long prompt does. Aim for a page or two of clear, specific instructions. A tight CLAUDE.md that the agent actually reads and follows beats an exhaustive one it skims. Say what matters, plainly, and stop.

The Module Project: Sort, Rename, and Index a Folder#

Time to put the whole module together on the task that proves the point. You’ll point an agent at a messy folder and have it sort, rename, and index everything — then judge the result against a checklist you write yourself, exactly the Module 3 skill applied to an agent’s output.

Here’s the full loop, using every lesson:

1. Safety first (Lesson 2). Work on a copy of the folder. Confirm it’s backed up. Set a permission deny on anything that must not change. Start in ask mode.
2. Project memory (this lesson). Write a short CLAUDE.md/AGENTS.md: the goal (sort by type, rename cryptic files, write an index), the definition of done, conventions (naming, folder structure), and what to leave alone.
3. First run (Lesson 3). Point the agent at the copy and let it run, approving actions as it gathers, acts, and verifies.
4. Self-check (Lesson 4). Your memory file told it how to verify — no loose files, index complete, contents unchanged — so it checks its own work and fixes what it missed before reporting done.
5. Your check (Module 3). Now you judge the result against a checklist you wrote: Is every file in a sensible subfolder? Do the new names describe the contents? Does the index cover everything? Were the protected files untouched? Anything that fails goes back as a correction.

When it passes your checklist, you’ve done it: an autonomous loop, run safely over real files, verified by both the agent and you. That’s the capability this module set out to give you — and you can now point it at any messy folder you own.

Practice Exercises#

Exercise 1: Guidance or a lock?#

You put “never delete files in /archive” in CLAUDE.md. Is /archive protected? What would actually protect it?

Exercise 2: Diagnose the ignored edit#

You edited CLAUDE.md mid-run to change a naming rule, but the agent kept using the old one. Why, and what’s the fix?

Exercise 3: Write the memory file#

Sketch a short CLAUDE.md for a loop that keeps a “receipts” folder organized by month.

Summary#

Project memory — a plain-Markdown CLAUDE.md (Claude Code) or AGENTS.md (Codex) file in your folder — carries your standing instructions so the agent reads them at the start of every session and always begins briefed. What goes in it is everything you’ve already built: the goal (Module 2), the definition of done to verify against (Module 3), your conventions, and what to leave alone. Three caveats matter: it’s read once per session (edit, then restart — a mid-run change won’t apply), it’s guidance not enforcement (a request the agent usually follows, never a lock — hard safety still lives in permissions), and it should be short (there’s a size limit, and long files get skimmed). The module project ties the whole module together: work safely on a copy, write a short memory file, run the agent in ask mode, let its self-check catch its mistakes, and judge the result against your own checklist — an autonomous loop, run safely over real files, verified by both the agent and you.

Key Concepts#

• Project memory — a plain-Markdown file (CLAUDE.md / AGENTS.md) of standing instructions the agent reads each session.
• Once per session — the file is loaded at session start; edits need a restart to take effect.
• Guidance, not enforcement — memory shapes what the agent tries; permissions decide what it’s allowed to do.
• Keep it short — a page or two of clear instructions; long files get truncated or skimmed.

Why This Matters#

Project memory is what turns a one-off agent run into a standing capability: write your brief and checks into a file once, and every future session on that folder starts fully briefed — the same reuse payoff as a Project in Module 4, now for a tool that acts on your files. It’s also the direct continuation of your brief from Module 2 and your check from Module 3, proving that the artifacts you built by hand are exactly what automated loops run on. You’ve now handed a loop to an agent, safely, end to end. Next, the course turns to keeping those loops from running away — designing the stop conditions, budgets, and escape hatches that a hands-off loop needs, which matters even more once an agent is spending on its own.

Continue Building Your Skills#

You can now write project memory that carries your brief and checks with a folder, mind its three caveats, and run the full module project — an autonomous loop, safe, self-checking, and verified against your own checklist. You’ve handed a loop over completely, and kept control where it counts. Next, the course tackles what a hands-off loop most needs: knowing when to stop. In “Designing Loops That Stop,” you’ll set the budgets and escape hatches that keep an autonomous loop from running — and spending — forever.