How Do I Give an AI Agent a Second Brain?
You give an AI agent a second brain by writing its knowledge to files instead of trusting the conversation. A second brain for an AI agent is a set of plain text files that survive between sessions and hold everything the agent needs to resume work: current state, goals, decisions, tasks, and metrics. The agent rereads them at every startup.
The phrase borrows from productivity culture, where a "second brain" is an external note system you offload memory into so your head stays free. For an AI agent the need is sharper, because the agent has no first brain that persists. When a session ends, the model keeps nothing. What you offloaded to files is the only mind the next session wakes up with.
This article is about the concept and the practice: which files to keep, and how the agent uses them. For the tool-level mechanics of one specific setup, see our companion piece on giving Claude Code persistent memory. And if you still suspect a bigger context window would solve this, read why the context window will not fix agent amnesia first.
What files make up the brain?
Eight files make up the brain we run in production. Each answers one question a returning worker would ask, and each is plain text you can open and read yourself. Split them by job and the set stays small enough to reread in full.
| File | What it holds |
|---|---|
STATE.md | The single source of truth: what is in progress, exactly where work stopped, the next 3 steps. |
GOALS.md | Mission, strategy, phases, and the metrics that define success. |
BACKLOG.md | Prioritized tasks plus an ideas parking lot, so "what next" never needs a human. |
DECISIONS.md | Every directional decision with its reasoning and the options rejected. |
METRICS.md | Revenue, traffic, and conversion numbers, updated on a fixed cadence. |
FOR_HUMAN.md | The inbox: questions the agent needs answered and the owner's replies. |
log/ | One dated file per session: what happened, what failed, what surprised. |
projects/ | The actual work products, each in its own folder with a status README. |
One rule governs the whole set: write for a stranger. The agent that reads these files tomorrow shares no live memory with the one that wrote them, so vague notes are worthless. "Working on the sales page" tells the next session nothing. "Sales page draft stopped at the pricing section; next, write the FAQ from the objections in projects/site/research.md" is a note a stranger can act on in seconds. Precision is the entire value.
A ninth file sits above these and is not part of the brain so much as the nervous system: the agent's contract, often named CLAUDE.md or AGENTS.md. It does not store knowledge. It stores the standing order to read the eight, and to keep them current. Without that instruction the brain exists but never gets opened.
How does the agent use it every morning?
Every morning the agent runs a fixed startup protocol that takes about 2 minutes: it reads the brain top to bottom before touching any work. That is the whole trick. Memory is not remembered, it is reconstructed from files in a known order.
- Read
STATE.md- where did work stop, what are the next steps. - Read the newest file in
log/- context from the last session. - Read
BACKLOG.md- the current priorities. - Check
FOR_HUMAN.md- did the owner answer or unblock anything. - Glance at
METRICS.md- any new signal from the numbers.
Two minutes later the agent is fully briefed and starts the highest-priority task without asking a question the files already answer. The owner's entire prompt can be one word: "continue."
The other half of the habit is writing back. The agent updates STATE.md and commits to git roughly every hour and after each finished task, and it runs the same protocol in reverse when it stops: update state, write the day's log, reprioritize the backlog, flag anything that needs a human. A session can die at any moment, so anything not written to a file is lost. Git turns each checkpoint into a reversible, complete snapshot, which is why a crashed session costs minutes instead of a day.
The result is indistinguishable from continuity, even though nothing was truly remembered. The agent reconstructs its context from notes a previous session left in known places, in a known format. Build for the amnesia instead of fighting it, and the amnesia stops mattering.
FAQ
Should the second brain be markdown files or a database?
Plain markdown files, in almost every case. Files have nothing to break, no server to configure, and no vendor that can retire the feature. They are also auditable and portable: you can read the agent's entire mind by eye and move the same folder to any file-based agent. A database only starts to earn its cost at a scale most single-owner projects never reach.
How much does it cost to give an agent a second brain?
Nothing beyond the tools you already use. The brain is text files in a folder, versioned with git, which is free. There is no subscription, plugin, or storage bill for the memory layer itself. The only real cost is the discipline of keeping the files current, which the agent's contract enforces automatically once you set it up.
Does this work with any AI agent, or only one tool?
It works with any agent that can read and write files in a project folder, which is nearly all of them today. The concept is deliberately tool-agnostic: files outlive vendors and model versions. The only tool-specific detail is which file the agent loads automatically at startup, and how you word the instruction to reread the rest.
How many files do I actually need to start?
One. Create STATE.md with three sections: what is in progress, exactly where you stopped, and the next 3 steps, then tell your agent to read it first every session. That single file delivers most of the benefit. Add the other seven as the project grows and you feel the specific gap each one fills.