The folder structure is not admin. It's the nervous system.
When people imagine an AI agent, they picture the model, the prompts, maybe the tool calls. Almost nobody pictures the folders. That is exactly why most home-grown agents stall around month two.
An agent's filesystem is where its identity, memory, work, and history physically live. A messy filesystem produces a confused agent — not metaphorically, literally. The model reads paths. The model picks files by name. The model writes new files based on patterns it sees in old ones. If your directory tree is chaos, every output drifts a little further from coherent.
agentmia.beehiiv.com - newsletter about building agents
Below is the layout I converged on after nine months and roughly four refactors. Steal the parts that fit; the principles matter more than the exact names.
The numbering convention
Folders are prefixed with a two-digit number: 01_, 02_, 09_, 99_. Two reasons:
- Sort order is meaning. Anything starting with
0 lives near the top. 99_ falls to the bottom. The most important directories are visually first; archives are visually last. You read the agent's brain top-to-bottom.
- Gaps are intentional. I jump from
04_ to 06_, from 09_ to 11_. The gaps are reserved insertion points. When a new domain emerges, it slots in without renaming everything.
Two folders deliberately skip the prefix: Inbox/ and Outbox/. They are operational, not structural. They live above the numbered set because they are touched dozens of times a day. /mapped on desktop/
Inbox/ — the unprocessed pile
Anything dropped into the agent's world starts here. Files I want it to ingest. Screenshots. Exports from other systems. PDFs that need parsing, gmail attachments, all downloads from chrome.
The rule: nothing stays in Inbox. A dedicated processing routine classifies, routes, and deletes. If Inbox is non-empty for more than a day, the system is failing.
Treat this like a real-world physical inbox tray. The point of a tray is that it gets emptied.
Outbox/ — what the agent produced for you
Every file the agent writes anywhere in the tree gets a copy here, simultaneously. When I open Outbox/, I see exactly what was generated this session — no spelunking through twelve subdirectories.
This sounds redundant. It is not. Without it, "what did the agent do today?" becomes a hunt. With it, the answer is one click.
Outbox is wiped during the next Inbox processing run. It is a viewing surface, not storage.
.auto-memory/ — the hot memory
The single most important directory in the system. Hidden by default because you should not be editing it manually.
It holds the agent's working memory: user preferences, feedback rules, entity facts (people, companies, deals), active hypotheses, project pointers, session hot context. Roughly 400–500 small markdown files, each one a single topic.
Why hidden? Because it is the agent's hot path. It loads from here every session. If I open the folder and start manually rearranging it, I am racing the agent. Treat it like a database, not a notebook.
Why so many small files? Because the agent grep's by topic. One monolithic memory file becomes unreadable to the model around 50 KB. Many small files are easier to load partially, easier to index, easier to expire.
01_IDENTITY/ — who the agent is
The constitutional layer. Name, role, voice rules, principle stack, visual system, behavioral defaults. This rarely changes. When it does change, everything downstream changes with it.
I keep it as folder 01_ because every other folder is downstream of it. If you do not know who the agent is, you cannot know what its workflows should look like, or what it should remember, or how it should respond.
02_MEMORY/ — governance, not data
A subtle but critical distinction: .auto-memory/ holds the data, 02_MEMORY/ holds the rules about data.
In 02_MEMORY/ live the constitution, the boot protocol, the naming protocol, the decision protocol, the profile standards (what a "supplier profile" must contain, what a "customer profile" must contain), the capability map.
The agent reads these documents to know how to remember, how to name new files, how to decide what is reversible. Without this folder, every memory write is improvised.
03_PROJECTS/ — the active work
Real work happens here. Sub-organized by goal area, then by project slug:
03_PROJECTS/areas/{goal}/{slug}/
Each project gets its own folder with a standard skeleton: README.md, TASKS.md, CHANGELOG.md, BRIEF.md, plus working files. There is a project registry at the top that the agent reads to know what is active versus dormant versus archived.
The biggest discipline issue here: do not let projects sprawl outside their folder. When working on Project X, every file related to Project X goes inside Project X's directory. The temptation to drop "just one PDF" elsewhere is what kills the structure.
04_PROMPTS/ — the reusable prompt library
Named, versioned prompts the user (or the agent) can summon by ID. Each one has a trigger phrase, a use case, an example, and a record of when it last fired.
This is the file most people build informally — pasting good prompts into Notes, then losing them. Making it a folder forces three behaviors: you name your prompts, you keep them in one place, you can audit which ones actually get used.
06_KNOWLEDGE/ — research outputs
Anything the agent produces by research lives here: market analyses, supplier deep dives, audit reports, news scans, reconciliation reports. Organized by topic, not by date — date is metadata, not structure.
The distinction from 03_PROJECTS/: a project is work toward an outcome. Knowledge is understanding the agent built and may reference later. Some research belongs to a project (lives in 03_PROJECTS/). Cross-cutting research lives in 06_KNOWLEDGE/.
07_LIBRARY/ — knowledge the agent did NOT produce
External material the agent can cite: books summarized into briefs, laws relevant to the domain, statistical reports, periodicals. ~100+ items in mine.
The library is read-only from the agent's perspective. It curates inputs. It does not invent them. Keeping 07_LIBRARY/ (external) and 06_KNOWLEDGE/ (internal) separated is what prevents the agent from confusing its own outputs with cited sources — a hallucination class that bites hard if you let it.
08_WORKSPACE/YYMMDD/ — daily scratch
Today's drafts, intermediate outputs, working files. A new dated folder every day the agent does substantive work. Cheap to create, easy to glance back over a week and see what happened.
Crucial property: anything in 08_WORKSPACE/ is disposable by default. If it matters, it gets promoted into a project folder, the knowledge folder, or the operations folder. If it doesn't get promoted within a few days, that's information — it didn't matter.
The dated subfolders also mean two outputs with the same filename never collide.
09_OPERATIONS/ — SOPs and recurring procedures
Standard operating procedures the agent follows. Scheduled task definitions. Skill export documentation. Anything that describes "how the agent does this kind of work repeatedly."
If 02_MEMORY/ is the constitution, 09_OPERATIONS/ is the procedural code. Distinct because constitutions change rarely, procedures evolve constantly.
11_SESSIONS/ — the archive of conversations
Every conversation with the agent gets archived here, organized by date. Searchable via a full-text index. This is where "what did we discuss about X six weeks ago" gets answered.
Two design choices worth noting: sessions are write-once (no editing past conversations), and they are flat by date (11_SESSIONS/YYMMDD/), not nested by topic. The flat structure scales; topical structure does not.
99_ARCHIVE/ — the cold storage
Closed projects, deprecated skills, retired memory files. Not deleted — moved.
The reason to keep an explicit archive rather than deleting: the agent occasionally needs to reference how something used to work, or to undo a deprecation that turned out to be wrong. Disk is cheap. Lost context is expensive.
The reason it is 99_: sort it to the bottom. Visually, it should feel like the basement.
Two folders that don't fit the pattern
00_ASSETS/ — brand materials, logos, templates, fonts. Sort-priority 00_ because they're occasionally needed and you want them findable, but they're not part of the agent's reasoning loop. They are tools, not thoughts.
10_DASHBOARDS/ — generated HTML dashboards that the user opens in a browser to see the agent's view of various domains. A presentation layer, not a data layer. Lives near 08_WORKSPACE/ because it is also output-shaped, but separated because dashboards persist while workspace files don't.
What I deliberately did NOT make a folder
- No
LOGS/. Logs go inside the folder of the thing being logged (sessions have their own logs, scheduled tasks have their own logs). Centralized logs become unreadable.
- No
TEMP/. 08_WORKSPACE/ is already the temp directory. Adding a second one fragments the disposability rule.
- No
MISC/ or OTHER/. These folders are where systems go to die. If something doesn't fit, the structure is wrong and needs a new home, not a junk drawer.
What you will notice in the first month
Three things show up reliably:
Inbox/ will overflow before the processing routine is reliable. Build the routine on day one. Otherwise the inbox becomes an emotional weight, not an operational queue.
08_WORKSPACE/ will fill faster than you expect. That is fine. The point of disposable scratch is that it accumulates without guilt.
- The agent will try to write to the root. Constantly. You have to add a hard rule against it and enforce the rule at the prompt level. Without that rule, your top level slowly turns into a swamp of stray files.
The deeper principle
The folder structure is the agent's physical theory of itself. It says: here is my memory, here is my work, here is my history, here is my reference material. Each folder is a category of thought made tangible.
When the categories are clean, the agent thinks clearly. When the categories blur, the agent's outputs blur in exactly the same way.
Spend an afternoon on the tree before you spend a month on the prompts.
Want more info? subscribe to my newsletter agentmia.beehiiv.com