Skip to main content
Version: v2.0

Build a knowledge base for your agent

An agent's knowledge is files in its agent folder plus the lines in AGENTS.md that tell it where to look. This page builds that pattern from an empty agent. For the two folder scopes and why files cost nothing until they are read, see Files and knowledge.

Know which folder you are writing to​

Every file in the browser carries an origin badge.

  • Agent files are durable. They belong to the agent, every session sees them, and they survive the chat that made them. In the file browser they are the agent-files/ folder. This is where a knowledge base goes.
  • Session files belong to one chat and go away with it. Scratch work.

Open the file browser​

  1. In the playground, open Files at the bottom of the Configuration column, or use the right-hand rail button whose tooltip reads Show files.
  2. Click Open the files drawer for the full view.

The drawer opens at root with Search files, a file-tree toggle, a hidden-files toggle, and a More actions menu whose one item is Download all. Files only exist once a chat has run, so the section is empty on a brand new agent.

Put a file in the agent folder​

Ask the agent, in the conversation, to write it. Give the path explicitly, starting with agent-files/:

Save this as agent-files/brand/voice.md, exactly as I have written it:

Short sentences. No exclamation marks. Never call the product "solution" or "platform". Say what it does. Prices always include the currency.

The agent writes the file and the conversation shows a card with the filename, a Created badge, its size, and a Download button.

Open agent-files/ in the drawer to confirm it landed there rather than in the session folder.

The same works for anything the agent produced itself. When a report or a summary is worth keeping, tell it to save that to a path under agent-files/.

Point at the file from the instructions​

A file the agent does not know about is a file it never opens. After you save one, add a line to AGENTS.md naming the path and the moment to read it. See Write your agent's instructions for the editor.

## Where things are

- Brand voice and banned words: `agent-files/brand/voice.md`. Read it before any draft.
- Launch emails that worked: `agent-files/examples/launch-emails/`. Match their structure.
- Anything else: start at `agent-files/index.md`.

Three lines of always-loaded text buy a folder of any size, because the agent opens a file only when the moment named in that line arrives.

Give one folder its own rules​

Put an AGENTS.md inside a subfolder. When the agent works in that folder, the harness reads it on top of the main instructions, and an agent working elsewhere never loads it. Rules that apply to one area of work stay out of the file that is sent every turn.

Ask the agent to write agent-files/twitter-ads/AGENTS.md:

# Twitter ads

Campaign names are `nw-<quarter>-<audience>`, for example `nw-q3-office-managers`.
Never propose a daily budget above $300 without asking me first.
Report results as a table: campaign, spend, clicks, trials started.

A layout that works​

agent-files/
  index.md                     one line per folder, saying what is in it
  brand/voice.md               how we write
  examples/launch-emails/      three or four emails that landed well
  reports/                     what the agent has produced and you kept
  twitter-ads/
    AGENTS.md                  rules that apply only in this folder
    audiences.md

Grow it the same way each time: the agent gets something wrong, you write the missing knowledge into a file, and you add or extend one line in AGENTS.md pointing at it.

Take the files out​

Click Download on a file card in the conversation for a single file, or use Download all in the drawer's More actions menu for everything.

Next​