One of my agents was about to start a web search for design token naming conventions. The task was in my design system project, and watching the session live, I already knew what it would find: a mix of opinions, half-applicable patterns, and general best practices.
The thing was, this question had already been settled in another active session. Different agent, same project, working on a related part of the system. There were examples and a short doc that explained why I chose what I chose.
So I pressed ESC.
One pointer to my second brain gave it the right entry to read. Within seconds it had the same context that had taken hours to build up earlier.
The lost time was not the real issue. The real risk was different: the agent would have found something. Maybe close to the earlier decision, maybe not. Either way, it would have used what it found and silently overwritten decisions made earlier in another session, while the other agent kept building on the original ones. Two agents working on the same project, drifting apart, with no warning until much later.
Agents do forget. Context windows fill up, summarizations drop the details, and every new session starts blank. You cannot fix that inside the model. You fix it outside, with a memory that survives the next reset.
The core problem
Agents are stateless. Every new session starts at zero, with no recollection of what was decided yesterday or in the parallel branch.
This is the part that scales the wrong way. A solo agent on a small task barely notices it. The moment you run multiple sessions across multiple worktrees, the gaps multiply.
Two reactions to this are common, and both are wrong.
The first is to dump everything into the prompt: every doc, every decision, every past chat. This will bloat the context and the quality might decrease because of context rot.
The second is to hold nothing back at all. No persistence, no notes, no shared state. The agent re-researches the same questions, reopens settled debates, and quietly contradicts decisions made last week.
What you actually need is something in between: a structured memory that lives outside the context.
From Notion to agent memory
If you have ever maintained a personal knowledge system, this part will feel familiar.
For years, my own second brain lived in Notion. It was working infrastructure: documenting learnings, tracking decisions, managing tasks for my design system work. The setup did its job.
Then agents entered my workflow, and Notion stopped being part of it.
The problem was not that Notion is bad. It is good at what it does. The problem was that it is built for humans: pages are long, context-rich, and formatted for reading and skimming. I know there are MCP servers that can bridge Notion into an agent session, but each server you connect registers its tool definitions in the context, whether those tools get called or not. Every additional server bloats the agent’s base context before any actual work has started, and spending that budget on personal knowledge management is hard to justify when this context could be used for something you actually use during development.
The simpler alternative was already on my disk: a folder of markdown files in a git repo. Versioned, diffable, shareable, and free of tool overhead. The format works for the agent, the storage works for me, and the whole thing can be cloned into another machine or shared with a teammate the same way any other repo is.
Once a todo or a project is finished, the file gets deleted. Keeping the second brain small is part of the point, and git history is there if anything ever needs to be looked at again.
The underlying need was the same in both worlds: an externalized memory the new session can read on its own. Only the reader had changed.
The second brain I built in Notion was for me. This one is for my agents.
Setting it up did not require starting from scratch. The first version came together in one session with my agent. I gave it the structure and the naming conventions, it scaffolded the files, and we refined the rest as we went. None of it was perfect on day one. None of it had to be.
What it actually is
Disclaimer: The setup described in my article runs on Claude Code, because that is what I use. The structure itself is tool-agnostic: any agent that reads project files benefits from the same three layers, the same typed files, and the same Why pattern. What changes between tools is only the entry file the agent looks for by default.
On disk, the second brain is a folder of markdown files. The structure on top of those files is what makes them useful as agent memory, and it splits into three layers, each with a clear job.
The global layer lives in my ~/.claude/CLAUDE.md and contains my identity, tech stack and working style. It loads into every session, every project, and stays the same across them.
The project index lives at memory/MEMORY.md. Hard-capped at 200 lines on purpose. It does not contain knowledge itself. The project index is a list of pointers, one line per entry, each linking to the actual file. The agent reads the index first to decide what is relevant for the current task, then opens only the files that matter. Retrieval is judgment-driven, not keyword-based, and the index stays small enough to fit in context without effort.
The individual files live in the same memory/ folder, named {type}-{slug}.md. There are four types, each with a different lifecycle.
-
feedback: corrections and validated patterns ("never do X, here is why") -
project: in-flight work, decisions, bugs, todos, initiative status -
reference: where to find things in external systems, like a Figma file, or a docs path -
user: role, expertise, communication preferences
Every file follows the same shape:
- Rule or fact
- Why
- How to apply
The Why is the load-bearing part. A rule without context is something the agent follows. A rule with the reasoning attached is something the agent can apply in edge cases that nobody anticipated.
How to build it
Here is what the structure looks like for a single project:
~/.claude/
├── CLAUDE.md
└── projects/
└── my-wonderful-project/
└── memory/
├── MEMORY.md
├── user-profile.md
├── feedback-no-hardcoded-tokens.md
├── project-token-rename.md
└── reference-jira-board.md
The MEMORY.md index is the table of contents the agent reads first. It groups entries by type and links each one to its file:
## User
- [User Profile](user-profile.md): UX engineer leading the design system team
## Feedback
- [No hardcoded design values](feedback-no-hardcoded-tokens.md): a hardcoded color broke dark mode last quarter
## Project
- [Token rename](project-token-rename.md): aligning Figma variables with CSS custom properties, deadline before Q3 launch
## Reference
- [Jira board](reference-jira-board.md): design system tickets in project "DSY"
Each individual file uses YAML frontmatter for discoverability and a body shaped as rule or fact, then Why, then How to apply:
---
name: No hardcoded design values in components
description: Components must reference semantic tokens, not raw values
type: feedback
---
Never hardcode colors, spacings, or font sizes in component styles. Always reference semantic tokens.
**Why:** Last quarter, a hardcoded `#1E1E1E` slipped past review and broke dark mode for one component. Tokens turn a global update into a one-line edit. Raw values force you to grep across the codebase every time.
**How to apply:** Components only consume CSS custom properties from the token layer (`--color-surface-primary`, `--space-md`, etc.). The linter blocks hex values, raw px units, and named CSS colors in component files.
That is the entire shape, repeated for every entry.
Talking to the second brain
Two kinds of prompts cover most interactions. The first one loads context:
Before you start, check the second brain. There is a decision on design token naming conventions with examples and a short doc explaining the trade-offs.
The second one saves context:
Save this to the second brain as feedback type. Components never hardcode colors or spacings, only semantic tokens. Last quarter a hardcoded color slipped past review and broke dark mode.
The agent reads MEMORY.md, decides which files to open, and either uses what it finds or creates new files and updates the index, following the same shape.
Two real cases
For my CLI project Kigumi, work happens in parallel worktrees: one for the CLI itself, others for the wrapper templates for multiple frameworks. When a CLI refactor unblocks a wrapper, the wrapper session does not have to stop while the CLI gets fixed. The new requirement gets saved as a project entry in the second brain. The CLI session picks it up the next time it reads MEMORY.md for context. Once the todo is checked off, every other session sees the same status the next time it loads the index.
The same pattern works for design. Reading design tokens out of Figma and comparing them against the CSS custom properties in code, I spotted naming inconsistencies and a few off-by-one references. The current task did not need that fix, so the issue went into a project entry as a list of concrete todos. Two weeks later it was still there, with all the context attached.
What you will have to iterate
The first version of the second brain will be wrong in places. The early rules will be too broad. A How to apply section that seemed clear will turn out to be useless when an actual edge case shows up. A project file will grow until it stops being one entry and starts being three.
That is not a failure mode. It is how the system improves. Each time a rule misfires, the file gets sharper. Each time a project file gets too big, it gets split. The feedback type accumulates corrections over months, and what was once a vague guideline becomes a specific pattern with examples and counterexamples.
The second brain gets better because you use it, not despite it.
Conclusion
The ESC moment from the opening is the small version of a much larger pattern. Without somewhere to write things down, every agent starts blank, every decision is at risk of being made twice, and every session is one reset away from losing its context.
A second brain is not a productivity hack. It is the precondition for agentic workflows to hold together over weeks of work, across worktrees, and between agents that need to share what they know.
Top comments (0)