Your agent hasn't read your folder

When people start working with an agent inside a folder, they assume it knows everything in that folder. Your notes, your client files, the process you wrote down last month. It’s all right there, so surely it read it.

It didn’t. When you open a new conversation, the agent knows almost nothing about what’s in your folder. It knows the folder exists and that it can look inside.

What it actually has when you start

At the first message, the model receives a short list of things:

the instructions the app wrote for it (how to behave, how to use each tool),
the descriptions of the tools it can call,
one file of yours, if you’ve written it: AGENTS.md,
and your message.

That’s the whole picture. Everything else in the folder, it has to find: list the files, search them, open the ones that look relevant. Each of those is a tool call, the same way it would search the web.

I show this in my workshop with a folder of 20 task files. In a new conversation, I ask what task 10 is about. It doesn’t answer straight away. It searches the folder, finds the file, reads it, and then answers. It works, but it had to go and get it.

7,625tokens

app instructions

tool descriptions

AGENTS.md

Your first message

Of your folder: AGENTS.md only

7,845tokens

app instructions

tool descriptions

AGENTS.md

search result

It searches the folder

One tool call: a search for "task 10"

8,395tokens

app instructions

tool descriptions

AGENTS.md

search result

task-10.md

It opens one file

The 19 other task files never enter

The app's instructionsTool descriptionsAGENTS.mdYour questionTool calls and resultsA file it readCached: already read on the step before, much cheaper to read again

Sizes are illustrative and change with every app. The point is what is missing: of a folder of 20 task files, only the one it opened ever reaches the model.

Why that’s a good thing

It’s frustrating at first. It would be convenient if the agent simply knew everything.

But think about what that would cost. Every message you send carries everything the model receives: the app’s instructions, the tool descriptions, your files, the whole conversation so far. If your folder were loaded every time, you’d pay for all of it on every message, and the model would have to find your one relevant paragraph in the middle of everything else.

Recent models can take in a lot, up to about a million tokens for some. More room doesn’t make everything useful though. Extra text is noise, and the model can get confused by it the same way you would. I try to make sure every token in there has a reason to be there.

So the agent not knowing your folder is what gives you control. You decide what it always knows, and you organise the rest so it can find things fast.

AGENTS.md is your one guaranteed slot

AGENTS.md is a plain text file at the root of your folder. The app reads it at the start of every conversation and puts it in the model’s context, next to its own instructions. It’s the one place where something is always remembered.

The test I use: open a new conversation and ask “who am I?”. If your role is in AGENTS.md, it answers straight away, without opening a single file. Same with a rule like “always answer in three bullet points”. Put it there, and every answer follows it.

alex-northwind

Who am I?

1You're Alex Martin, content marketing manager at Northwind. You own the blog, the newsletter and the company's LinkedIn.

What's task 10 about?

2search_filesquery: "task 10"

read_filetasks/to-do/T10-webinar.md

3Task 10 is the clinic owners webinar: pick a date, invite two customers as speakers, and prepare the registration page.

AGENTS.md
tasks/
to-do/
T10-webinar.md
in-progress/
done/

1
Answered straight away
No tool call. Who you are is in AGENTS.md, which was loaded before you asked.
2
Not in AGENTS.md: it has to look
A search, then a file read. Two tool calls before it can answer.
3
The answer, from the file it opened
It only knows task 10 because it went and read it.

Same conversation, two questions. The first answer comes from AGENTS.md. The second one has to be fetched.

Claude Code used to only read a file called CLAUDE.md. Recent versions read AGENTS.md too, which is the name Codex and most other tools use, so one file works for all of them. If yours doesn’t seem to be picked up, ask the agent which instructions it loaded. I wrote more about keeping one file for every tool in keep your repos harness agnostic.

What goes in it, and what doesn’t

My rule is simple. If something isn’t useful for almost every message, it doesn’t belong in AGENTS.md. A long one costs tokens on every single message, and it buries the rules that matter.

In AGENTS.mduseful for most messages

Who you are: your role, your team
The company, in two or three lines
Working rules: "say clearly when you are not sure", "explain how you got a number"
How you want answers: one-line conclusion first, then details
A map of the folder
A table of skills, with where to find each one
A table of tools, with when to use each one

In other filesread when the task needs them

The full company description and product details
Client and project information
How you write a LinkedIn post, or run a client report
Meeting notes, exports, drafts
Anything you only need once a month

AGENTS.md is a one-pager. Its job is to say what's always true and where everything else lives.

The second column isn’t less important. It’s just not needed on every message. AGENTS.md points to it (“for anything about a client, read their information.md first”), and the agent opens it when the task calls for it. That’s what makes a big folder fast to work in.

Try it

Open a new conversation in your folder and ask: “Who am I, and which instructions did you load at the start of this conversation?”

If the answer is vague, your AGENTS.md is either missing or not saying the things that matter. Ask the agent to help you write it. Then keep it to one page.