
A personal brain gives the agent a memory.
By now you have a capable agent and a skill or two, but you still pay a tax at the start of too many sessions: twenty minutes of briefing before you reach the problem. This part shows how to stop paying it by building a place the agent wakes up inside that already knows you. We call it a brain.
A nutcracker hides thousands of pine seeds each autumn, and finds most of them again under the snow.
Tanush Jagdish · Part 4 of 6 · 15 min read
You can point Claude Code at a task and get real work out the other side. Yet a new session too often starts the same way: you re-explain who you are, what you are working on, and what you have already tried, to an intern who forgets most of it overnight. Built-in memory and projects in Claude, ChatGPT, and the other agent apps from Anthropic and OpenAI now carry some of that context forward (as of September 2026). A memory you keep yourself as plain files is one you own: you set the structure, you can read and correct every line, and you can carry it to another tool.
The fix is a place the agent wakes up inside that already knows you. This part answers one question: if an AI wakes up in a folder, how do you set up that folder so it works as your digital brain?
#1Folder architecture is context
Start with the destination. When the brain is built, you stop writing essays to the agent and write one sentence instead: “Based on the PDF my client sent last week, draft a response and send the email.” Everything the agent needs (who your client is, how you write, where the PDF lives, what good looks like) is already in the brain, and the agent reads it before you type a word. Working with agents comes down to structuring layers of context, and the goal is a prompt that gets shorter over time. That is the real test of a brain: not whether the files look tidy, but whether your prompts are shrinking. If you still paste three paragraphs of background into the chat every morning, the brain is not doing its job yet.
Most people think of folders as filing, the housekeeping you do at the end of the week if there is time. That framing is wrong. With AI, your folder structure is not just where you store the work; it is the context the model reads.
When an agent opens a folder, it reads the structure before you type a word. The same task, two workspaces: one it can’t orient in, one it already understands.
“I don’t know what this project is about. Which report is current? What am I supposed to do here?”
“This is a consulting project. The research/ folder has interviews. The deliverables/ folder needs a Q1 report.”
Folder structure is context. The README tells the agent what a folder is about; AGENTS.md tells it who you are. Without these, too many sessions start from zero.
Compare the two sides. Same work, same files. On the left, forty files named FINAL and FINAL-v2, and the agent cannot tell which one is current. On the right, a clean tree where every folder says what it is. Given the same model, the agent on the right is smarter than the one on the left, because you gave it a world it can read. That is why file structure matters so much now: the agent relies on a clear hierarchy to understand where things are.
Here is the part that frees people up: the particular structure matters less than having one. You can organize by time, or by categories such as research, clients, and personal. What matters is that the structure is clear, that you write it down, and that once you set it, you follow it and build on it.
One more rule will save you later: long-term memory is your folder architecture, and short-term memory is the chat. Use the chat to solve today’s problem, then let it go. Anything you want to outlast the chat goes into a folder. So a project is not a chat you keep coming back to; it is a folder you start inside: “Let’s go into the due-diligence folder and begin.” Keep the files plain, too. Markdown or text beats Word, and Word beats PDF, because agents convert everything to text anyway. The more you give them material they read easily, the faster and cleaner the work. You are getting out of the model’s way.
#2The three levels of context
Once you accept that folders are context, the architecture has three levels. Get them right and the re-briefing problem largely goes away.
The architecture that separates AI beginners from power users: three levels of persistent context, from permanent identity down to portable abilities.
Permanent · loaded every session
Conversation & Identity
Who you are, how you work, what you know. Your permanent brief to the agent, loaded automatically.
“I’m a VC analyst. I review 20 deals a week. My deliverables are investment memos and partner updates.”
Per-folder · project-specific
Workspace Context
Context specific to a project. A README.md in each folder tells the agent what this workspace is about.
Your deal-flow/ folder carries its own README describing pipeline stages and data sources.
Portable · invoked on demand
Portable Skills
Named, reusable abilities. A SKILL.md plus supporting files. Build once, use across any project.
A “weekly-research” skill reads news, filters by your criteria, and outputs a structured brief.
Context is what separates a generic chatbot from your agent. These three levels give it memory, orientation, and abilities.
Level 1 is your identity file (CLAUDE.md or AGENTS.md), which the agent reads at the start of every session regardless of your prompt: who you are, how you work, and your hard rules. For example: “I am a VC analyst. I review 20 deals a week. My deliverables are investment memos. I do not use em dashes.” Level 2 is a README in every folder, a short file explaining what the folder is: everything you would tell a person if you handed them the folder and asked them to work with it. A research folder’s README might say who the firm is, how its reports are made, and which sources to prefer. Level 3 is your skills from Part 3, portable abilities you build once and use in any project.
One way to hold the difference between Levels 2 and 3: your workspace READMEs are vertical, and your skills are horizontal. Folders go down into specific projects, and skills cut across all of them. Context is what separates a generic chatbot from your agent, and these three levels give it memory, orientation, and abilities.
This lands quickly with experienced people, especially consultants, because it is a translation rather than a new idea. One private-equity consultant heard the three levels and mapped them immediately: folder architecture is workstream organization, READMEs are project charters, and the identity file is the permanent team brief. He did not need a new mental model; he needed to hear that his existing one applied. Context architecture is an organizational skill applied to AI.
#3Level 1: writing a CLAUDE.md
Your identity file is the most important file in your setup. It loads automatically at the start of every session, so whatever you write in it, the agent knows on the first turn. Most people’s instinct is to write a big one: your industry, your tools, your folder map, your style guide. It feels productive, and it is the most common mistake we see. Do the opposite: start with almost nothing, and add a line only when the agent makes a mistake it should not repeat.
Why almost nothing? Because the model can already read your files. It can see your folder names, your documents, and your existing work, and it already knows what private equity is. You do not need to explain what it can see for itself; your job is to correct the few things it gets wrong on its own. Public evidence points the same way. Anthropic’s best-practices guide for Claude Code warns that an overlong CLAUDE.md makes Claude ignore the instructions that matter. A February 2026 study by researchers at ETH Zurich (Gloaguen and colleagues, “Evaluating AGENTS.md”) found that context files generated by an LLM lowered coding agents’ task success compared with no context file at all, while raising inference cost by more than 20%. More context does not mean better results. A good identity file can be as short as “My name is Tanush, I do this, and I write this way.”
Grow the file by accretion. One strategy consultant started with three lines: his role, his deliverable types, and one rule about not fabricating data. Six weeks later he had 22 lines, and every one was a correction earned through real use. A rule to keep figures precise to the nearest $100K went in the day the agent rounded $14.7M to $15M in a partner update. That is how a good identity file grows: from real mistakes, one line at a time. Anthropic’s guide offers a useful test for any line you want to add: would removing it cause the agent to make mistakes? If not, the line uses context for nothing. Information that changes weekly belongs in a project README, not here, and anything a linter can enforce should be left to the linter.
Treat the whole file as disposable. Boris Cherny, who created Claude Code, recommends deleting it periodically and starting fresh as models improve. Once the file is gone, watch where the model goes off track, and add back a little at a time. He expects each new model to need less instruction than the last.
One more trap: the agent will write rules for you when you are frustrated, and they are often bad rules. Say “make sure you remember this, I am annoyed,” and it may quietly write “the user is upset about X; avoid X” into the file. That fixes the moment and distorts every future session. One consultant found a whole “trust profile” telling Claude to “always talk about it politely,” left over from a bad early experience. Delete lines like that, because every irrelevant line the model reads on every turn pulls it in the wrong direction. A naming note that trips people up: Claude Code reads CLAUDE.md, and Codex reads AGENTS.md. Claude Code now also reads AGENTS.md when it finds no CLAUDE.md in the folder or above it (as of September 2026). Both files hold the same kind of content, and you can symlink one to the other so you maintain a single file. You can keep the same content without the terminal: the Claude and ChatGPT apps hold it in their instructions settings.
#4Level 2: READMEs as briefs
If the identity file is you, the README is the folder. Think of every new session as a new analyst walking in, with the README as their brief. You already do this with people: when you hand a junior colleague a folder of spreadsheets, you explain what they are and how they relate. You just say it out loud, and it evaporates. A README is that brief written down once, so you never have to give it again. As one participant put it:
“All this babysitting that you do, it will be in these README files in the folder. The folder that has all the Excels will have a simple text file that says what they are and how they relate.”
a workshop participant
A README is a briefing card of five to fifteen lines that answers three questions: What is this? What is in it? What should I know? Its split with the identity file is clean: CLAUDE.md is you, and the README is the project, so do not duplicate between them. Let the agent maintain them; when a folder changes, “update the README for this folder” is a one-line instruction. One discipline matters more than it looks: avoid giant files. A very long file costs many tokens, and past a certain length the agent will not read all of it. Use one folder per week and one file per concept, so the agent finds things faster and actually reads them.
#5Assembling the brain
Now assemble the brain itself. Once the three levels click, the natural next step is a single home: a folder that acts as your operating system, with a few named files the agent reads when it starts.
On boot, the agent reads three named files. There are only three kinds of thing in a brain: who you are, how you operate, and where everything lives.
Voice, lane, values, hard rules. Barely changes.
- ·voice & tone
- ·what you’re trying to do
- ·the rules that never bend
Boot order, update rules, who-calls-what.
- ·boot sequence
- ·routing by caller
- ·update / write-back rules
The index of every folder and what lives in it.
- ·folder map
- ·pointers to state
- ·pointers to history
Nothing exotic: a folder with a few named files the agent reads on boot. Identity and routing rarely change; the living state and history are where the day-to-day accrues.
A brain holds three kinds of material. First come rules and identity: who you are, your voice, and your hard rules, which rarely change. This is your agents.md. If you want to split it, add a longer soul.md of 500 to 1,000 words on who you are, how you write, what you value, and what you are trying to achieve at work, kept separate from the short hard rules. Second comes living state: a short synthesis of where things stand right now, in one file rewritten in place, current_state.md. Third comes history: the running record, a diary folder that is append-only, with one entry per important piece of work.
Keep the brain separate from the body. A brain is the small set of rules and pointers. A body is where the work actually happens, and it can be anywhere: folders on your computer, Google Drive, or your email. The agents.md carries a map: read the living state first, find history in the diary, and find the actual work in these places. You can move the body without touching the brain.
In its simplest version, a brain needs only two primitives.
diary/
The raw memory stream. Every session, every decision, dated.
current-state.md
What’s true now. One short file the agent reads to know where you are today.
That’s the whole foundation. A stream that remembers everything, and a snapshot that stays current, each distilling into the next.
A diary collects everything, and a current-state file distills it. Your agent reads current-state first to know where you are today and drops into the diary when it needs specifics. That is a complete brain; everything else is refinement. Do not over-engineer it. I over-engineered the first one I built for a client, with six boot files and a whole policy layer, then cut it back to agents.md, current_state.md, and the diary, because I wanted the client to understand exactly how their brain worked. If you cannot explain your own brain, it is too complicated. Resist the urge to adopt a new app as your brain, too. When an assistant suggests setting up Notion or Obsidian as a “second brain,” you can skip it: learning new software is not worth it when plain text you already control does the job. No single structure is right. This one worked for one client, and the way you organize your work should fit you.
Here is the most reusable trick in this part. You do not make the agent remember your brain; you make its boot file point to your brain. Claude Code reliably reads CLAUDE.md at startup, because the program loads it into context for you. So the one line you put in CLAUDE.md is: “When you start, read the agents.md in my brain folder.” From that single pointer, everything cascades in the order you control: agents.md, then current_state, then the diary. It also makes the brain portable across tools. In Cursor, Codex, or Claude Code, the boot file just says “start in this brain,” so when you switch harnesses, the brain comes with you. Keep it on your laptop or on GitHub; the pointer works either way, and you own it.
#6The self-improving loop
A brain that does not grow is just a folder. What makes it a brain is that it learns from every session. This loop is simple, and you should start it by hand.
- 01
Use
run the skill on real work
- 02
Capture
note what it missed or got wrong
- 03
Refine
edit the skill to fix it
- 04
Deepen↻ back to use
next run starts from a better baseline
After each substantial piece of work, the agent writes a diary entry and decides whether to update current_state. At first you trigger this yourself by asking it to use a brain-update skill; later you attach it to a hook so it runs automatically. Either way, your memory builds a little at a time. It feels like nothing at first. Then one day you ask, “Based on the work we did this week, what is the right way to do this?” and it knows.
Your identity file improves through the same loop. Catch a mistake, correct it in the chat, and then end with one sentence. Claude Code’s creator puts it this way:
“After every correction, end with: “Update your CLAUDE.md so you don’t make that mistake again.” Claude is eerily good at writing rules for itself.”
Boris Cherny, creator of Claude Code
This loop has four steps: notice the mistake, correct it, ask the agent to add a line, and the mistake stops recurring. After a few weeks, people say the agent “just knows how I work.” It does not know; it reads. If this sounds too simple, consider that much of what AI memory products do rests on the same idea: have the model review what happened and write it down in plain files. What matters more is how you use that information.
Memory that only grows and never gets pruned becomes a liability, so design against that.
- project conventions
- naming rules (v1)
- naming rules (v2, contradicts v1)
- tone + voice guidance
- deprecated workflow notes
- duplicate setup steps
- one-off task scratch
- … 11 more accreted entries
- entries the agent forgot
A memory file that only grows gets worse with age. In mine, new facts contradicted old ones, nothing got pruned, and the agent started forgetting things.
I keep built-in memory features to a minimum. Left alone, the ones I used mostly appended: within a few weeks the memory file ran past 20,000 characters, nothing got pruned, and the extra material weighed the model down until it started forgetting things. So I run my own memory, with one file per piece of work, and I tell the agent specifically to check the memory folder for what I did last week. That way I control how memory gets used. Built-in memory now prunes some of its own notes: Claude Code, for example, keeps a short index and asks the agent to merge or drop stale entries when that index grows long (as of September 2026). Contamination is the worse failure. One founder kept getting suggestions from the agent to hand his work to someone else, until he found a line buried in a markdown file saying that infrastructure goes through the infrastructure lead. One offhand sentence, written once, was steering everything. Left uncorrected, a line like that spreads into dozens of files and becomes very hard to remove.
So review your memory files periodically and read what is in them. Do not capture everything mindlessly, either; I fell into that trap for a year. Documenting everything felt good, but the real learning was in what I paid attention to and what I got wrong, and that is what the agent learns from too. Once a week, have the agent summarize everything and email it to you for a Sunday review. One small habit pays off well: add a line to your setup that says “after each session, flag one thing I should have asked but did not.” It surfaces blind spots you would not think to ask about.
#7You are the brain
Step back from the files for a moment. What matters is what they add up to.
who it is, how it works, its lane
what it knows: state and history
what it can do: your methods
Nothing mystical. The “brain” is just files in a folder: an identity, a memory, and a set of skills: the bridge from a bare agent to a personal operating system.
Think of everything you do that lives only in people’s heads. Start routing those workflows through a folder architecture so they are saved in simple, readable text. You are building a digital twin of your working life, and every workflow you route through the brain is one more piece of it the agent can run.
Here is the mental model I use for what happens on each call. Every time you call an agent, it is like meeting a newborn who happens to be extremely intelligent. You have to hand it the map: here is the world, here is how things are arranged, and here is where to look to understand your working life. A model is brilliant and has total amnesia, waking up new every session. Your brain is the map that lets it be useful about your life in thirty seconds instead of starting from zero. One client compared it to the film 50 First Dates, in which the heroine wakes each morning, watches a film of her life, and then gets on with her day.
This changes your role. You are not learning to code. You are the brain: you need to understand how the system works, and Claude is the engineering team that makes it work well. What you own is the architecture: where the data lives, how it connects, and what the agent reads and when. That is the durable skill, and it has little to do with syntax. My best homework assignment: without any help from Claude, sketch on paper how your whole setup should work. Where does the data live, how does it connect, and where does the agent sit? Get that right, and turning it into files is the easy part.
One non-obvious source of the best context is your conversations. A conversation reveals far more about who someone is than their email does, and LLMs are good at picking it up. After an hour of conversation with you, I could write you a much better soul.md than one built from your inbox. So save your transcripts; they are the richest raw material for a brain.
#8Iterate, rebuild, and your first week
One last trap, the one I see most. People build a brain, it gets messy, and they are afraid to start over. That fear holds them back. Most people have too few versions, not too many; endlessly patching the same setup is what causes problems. When a setup gets tangled, rebuilding from scratch is now often easier than untangling it, because Claude is good enough that a fresh build usually beats a renovation. A common failure is a structure built on ten different foundations, where the agent looks at only a fraction of it when you give it a problem. You want the whole design in your head and a clean build on top of it. What you keep across rebuilds is not the files but the understanding: the mistakes you made are now in your head, not in a folder you have to drag forward. Iterate often. A brain you build next month, knowing what you know now, will likely beat the one you have been polishing for four months.
Create your AGENTS.md
Your permanent memory. Who you are, how you work, what the agent should always know before it starts.
Build the workspace
A folder structure with a README in each folder, so the agent can find its way without being re-briefed.
A README in every folder is the cheapest memory you’ll ever write: it tells the agent what lives where, every session, for free.
To stand up a first version of your brain, do five things this week:
- 1.Write a tiny identity file: three to five lines covering your name, what you do, how you write, and one hard rule. That is a complete first version.
- 2.Give your main project folder a README: what it is, what is in it, and what the agent should know, in five to fifteen lines.
- 3.Add the one-line bootstrap. Put one line in your CLAUDE.md, “On startup, read the agents.md in my brain folder,” with the full path.
- 4.Start a diary and a current_state file, and have the agent write to them after each piece of work, triggered by hand at first.
- 5.Run the loop for a week. Each time the agent makes a mistake, correct it and ask it to add one line. Watch your prompts get shorter.
That is the personal brain: a small folder the agent wakes up inside, which knows who you are, what you are working on, and what it has learned, and which improves each time you use it. From here it scales in two directions. Part 5, Managed architecture, takes the same portable brain off your laptop and onto an always-on host with its own email address and phone number, along with the upkeep that comes with it: maintaining memory, preventing sprawl, connecting APIs, and keeping up with new models. When you decide your data needs a front end, remember the fork: an agent’s knowledge base wants text files, and a dashboard wants a database. Part 6, Institutional brain, stacks many personal brains under a shared institutional one in the L1, L2, L3 architecture, where each person’s brain feeds a department brain and a company-wide brain that everyone can read. Keep the three per-person levels from this part separate from the three organizational layers in Part 6: they are different ideas with the same shape.
The research behind this part.
Continue with the next part.
Want to go faster on your real work?
Coaching is the same method with someone beside you. It is by referral or invitation, and we are at capacity. We write back as capacity opens.