Skip to main content
Version: v2.0

Files and knowledge

An agent reads and writes files. It has two folder scopes: one that lasts for a single chat, and one that every session of the agent shares. Knowing which is which tells you where a file belongs, and the shared one is where an agent's knowledge builds up over time.

The two folder scopes​

The session folder​

The session folder belongs to one chat. It is scratch space. Files the agent downloads or writes during the conversation land there, and they go away when the session ends. Open a new chat and that folder is not there.

Anything that matters only inside the current conversation belongs here: a spreadsheet the agent pulled to answer one question, a draft it is revising with you, an intermediate file in the middle of a longer task.

The agent folder​

The agent folder belongs to the agent, not to the chat. Every session of that agent sees the same folder, and it persists after a session ends. Write a file there today and next week's chat can read it.

Anything the agent should still have tomorrow belongs here: reference documents, a style guide, finished reports, notes about how your company works.

Writing files, then pointing at them​

The pattern that makes the agent folder useful is this: write what the agent learns into the folder, then point at it from the instructions.

Say your marketing agent writes launch emails. After a few good ones, you save them in examples/launch-emails/ in the agent folder and add one line to the instructions: "Before writing a launch email, read the files in examples/launch-emails/ and follow their structure."

The instructions grew by a sentence. The knowledge grew by five emails. Repeat that a dozen times and the instructions read like a map of where things are: the index is here, to do this read that file, the numbers live in that folder. The agent goes and gets what it needs.

Instructions inside a folder​

You can put an AGENTS.md file inside a subfolder of the agent folder. When the agent works in that folder, the harness reads that file automatically, on top of the agent's main instructions.

So a twitter-ads folder can carry its own rules: the naming convention for campaigns, the spending limit you want respected, the format you want reports in. An agent working somewhere else never loads them, which keeps the main instructions short.

Why this keeps every turn cheap​

Files cost nothing until the agent opens one. That is why an agent's knowledge can grow to hundreds of files while each turn stays the same size, and why knowledge belongs in the folder rather than in the instructions, which are sent again on every turn. See Cost and usage.

Next​