Most people configure an AI assistant by writing one long prompt. Everything goes in, who it is, what it knows, how it should behave, what happened last week, and when the output is wrong, they add another paragraph. The prompt grows. The behaviour gets less predictable, not more.
- One long prompt mixes four kinds of information that change at four speeds.
- Four files, soul, brain, playbook and memory, let each change without disturbing the others.
- Start with two files, soul and memory, and let the rest grow from your own corrections.
I run five agents. Every one of them is built from four files instead: soul, brain, playbook, memory. The names matter less than the fact that there are four of them, and that they are separate.
This is the structure underneath everything else I have built, so it is the thing worth explaining first. It is also the practical version of what I mean by being part of the AI-native class, not using an assistant, authoring one.
The problem
Why not one file.
A single long prompt fails for a reason that has nothing to do with prompt quality. It fails because it mixes four kinds of information that change at four different rates.
Who the agent is barely changes. What it knows changes when you learn something. How it behaves changes when you correct it. Where the project currently stands changes every session. Put all four in one document and every update to the fastest-moving layer risks disturbing the slowest one. You edit "what we're working on this week" and accidentally reshape the agent's judgement.
There is research behind the instinct that long prompts degrade. Liu and colleagues found that language models use information best when it sits at the beginning or end of a long input, and noticeably worse when it is buried in the middle.1 A long prompt gives your instructions more places to be lost.
Four rates of change want four files.Anything else is one file fighting itself.
The separation is not tidiness. It is the mechanism. Each file can be rewritten without touching the others, which means the agent can learn a new fact without forgetting who it is, and finish a project without losing how it works.
The stack
What each file holds.
Identity, values in ranked order, voice, the non-negotiables. Written once, revised in months rather than days. If you find yourself editing this weekly, something from another layer has leaked in.
Domain expertise, frameworks, named people and how to work with them, and, the part people skip, an explicit list of what it does not know. Mine ends with a section called "What You Don't Know," and that section prevents more bad output than anything else in the file.
Procedures, decision rules, what to do in which situation. When the agent gets something wrong and you explain why, the fix belongs here. This is the file that accumulates your judgement.
Current focus, live blockers, what is in flight, key dates, and pointers to the rest of the state. Deliberately short and deliberately disposable.
My memory.md opens with a line that explains the whole design:
The agent is not remembering. The file system is remembering, and the agent is reading. That inversion is the useful part, because a file you can open is a memory you can audit, correct and hand to someone else. A model's internal state is none of those things.
The build
How it actually runs.
The four files load in a fixed order at the start of every session: memory first (where am I), then soul (who am I), then playbook (how do I act), then the hard rules. Context assembles in layers, slowest-changing underneath, fastest on top.
On top of the four files sit skills, one folder per repeatable workflow, each with instructions the agent reads only when that workflow is the job. The rule I use for promoting something into a skill is blunt: if I have done it twice, it becomes a file. Not a mental note, not a saved prompt. A file, in the repo, that the next session inherits. The library has grown past ninety of them.
The clearest proof it works is the agent that runs my own store. It operates the commerce side of this business, products, collections, orders, inventory, discounts, the blog, through twenty-seven commands, on the same four files, with a store-specific brain and playbook. Same skeleton as the agents I use for other kinds of work. Completely different contents.
That is the part that surprised me. The pattern is portable in a way a prompt never is. Adding a capability to one agent is close to a copy-paste away from being available to all five.
What I learned
Three things I got wrong first.
I put too much in soul. The first version had procedures in it, because procedures feel like character. They are not. Anything you might change after one bad output belongs in the playbook. Soul is only the things you would defend in an argument.
I made memory too long. It started as a log and became unusable, because the agent read three months of history to find out what was happening today. Memory should be embarrassingly short and mostly pointers. If something matters permanently, it graduates to brain. If it does not, it gets deleted.
I skipped writing down what it does not know. The most valuable section in the whole stack turned out to be the negative one, cannot access production, should not guess at metrics, does not know what happened after a given date, verify names rather than recalling them. An agent that knows the shape of its own ignorance asks instead of inventing.
The file that improved my agents most was the list of things they are not allowed to assume.
In practice
Where does this correction go?
The test for which file something belongs in is how often it changes, and why. Here are eight items for an imagined assistant that helps run a small shop, sorted by that test.
| Item | File | Why |
|---|---|---|
| Be direct and warm, never pushy. | soul | A trait you would defend. It rarely changes. |
| Never state a price you have not checked. | soul | A line you would not cross. |
| Returns are accepted within 30 days. | brain | A fact about the world. It changes when the policy does. |
| We do not ship to PO boxes. | brain | Another fact. Knowledge, not behaviour. |
| If a customer asks for a refund outside the window, offer store credit and flag it for a human. | playbook | A decision rule. It changes when you correct it. |
| Reply to shipping questions within one business day, checking the order first. | playbook | A procedure. |
| This week: drafting the spring launch email. | memory | Where things stand. It changes every session. |
| Waiting on the supplier's quote, due Thursday. | memory | Live state. Delete it when it resolves. |
Four patterns that mean a file is overloaded.
- Soul has grown paragraphs of procedure. Move them to the playbook and keep only the principle.
- Brain holds opinions that change weekly. Those are memory, or a playbook rule waiting to be written.
- Memory keeps everything. Delete whatever is not needed tomorrow.
- Playbook rules contradict each other. The soul is probably silent on the principle underneath them.
Take it home
Start with two files, not four.
Do not architect this. Open a folder for whatever you already use an assistant for, and write two files.
-
soul.md, five sentences on who this agent is and what it will not do. -
memory.md, what you are working on this week, and nothing else.
Use it for a week. Every time you correct the agent, put the correction in a third file called playbook.md instead of repeating yourself. Every time you have to re-explain a fact, put it in a fourth called brain.md. The stack builds itself out of your own corrections, which is the only way it ends up genuinely yours.
A prompt is something you write to an assistant. Four files are something you build. The difference compounds, and it compounds in your directory rather than someone else's product.
Sources
- Liu, N. F., Lin, K., Hewitt, J., Paranjape, A., Bevilacqua, M., Petroni, F., and Liang, P. (2024). Lost in the middle: How language models use long contexts. Transactions of the Association for Computational Linguistics, 12, 157 to 173. aclanthology.org/2024.tacl-1.9
Writes The Visionary, field notes from the AI-native frontier. Building in public: practical builds, named methodology, receipts, no fluff.