A Second Brain in Claude Code: How to Build the Structure in an Hour

Ailoot reference documentation: ailoot.ai/docs/.

Why does Claude Code need a second brain, and what is essential?#

You open Claude Code on Tuesday. You explain: this is the project, this is the audience, don’t do this. You work together. On Thursday, it’s a new chat, and you have to explain everything again.

If you have a CLAUDE.md, you’ve solved the first round of frustration. The basic rules and project description live in one file and load into every session. I explained how this file works in my guide to CLAUDE.md - you can read it first to get the foundation in place.

But CLAUDE.md is an instruction manual for a new employee. How to dress, what tone to use with clients, which commands to use for publishing. That isn’t enough to make good decisions about the project. Decisions require knowledge: what the product is, who the audience is, how the economics work, what you’ve tried and what didn’t work.

That knowledge often lives in four places: your head, Telegram chats, Google documents, and employees’ heads. A month after a decision, nobody remembers why it was made. A new person spends an hour asking the team questions to get up to speed. Claude isn’t part of that context at all.

Before the second brain, every session meant explaining all over again who the client was, how the offer was structured, and which provider handled payments. With business/, I open a chat and say, “update the offer for the new pricing plan” - Claude goes to business/company/legal.md on its own, reads the requirements, then goes to business/products/pricing.md, sees the new pricing plan, and suggests an edit in one pass. The warm-up is gone; context loads automatically.

Anthropic calls this problem context rot in its engineering blog:

In other words, the more you stuff into the window, the worse the agent is at working with specifics. The solution is to keep a structure of external files that Claude can visit on its own in response to a specific request. That’s what a second brain is.

What is a second brain, and how does it apply to Claude?#

Typically, a second brain is about productivity in general: people create an Obsidian vault and add excerpts from books, notes from calls, and project ideas.

Applied to working with Claude Code, the idea stops being about productivity and becomes about agent architecture.

In the classic approach, the second brain is yours, and you access it manually. When working with Claude Code, the second brain becomes two-way: both you and the agent access it. That changes the requirements for its format.

Since the agent accesses it on its own, files need to be in a format it understands without a separate integration. Markdown is ideal: text, a heading hierarchy, and links between files. Notion and Google Docs aren’t suitable. You can connect them through MCP, but that adds another layer, another token per request, and another point of failure.

Since the files are in the file system alongside the project, they automatically fall within Claude Code’s reach. No setup required. Start the agent in the project folder and it can see all the files inside. It’s free and works out of the box.

What memory hierarchy does Claude Code have out of the box?#

Before adding anything of your own, let’s look at what Claude can remember without your help. Anthropic describes two mechanisms in its official documentation: CLAUDE.md (rules you write) and auto memory (lessons Claude writes itself). Both load at the start of every session.

CLAUDE.md is searched for in four places at once:

All four files load into the context. The more specific the level, the higher its priority. The local file is read last, so its rules override everything else.

A CLAUDE.md file can also live in any folder inside the project. When Claude reads a file from a subfolder, it loads that subfolder’s CLAUDE.md on demand. This is useful in a monorepo: frontend rules live in frontend/CLAUDE.md, backend rules in backend/CLAUDE.md, and they load only when the agent works on the relevant part.

Auto memory appeared in Claude Code 2.1.59. These are files Claude writes about you:

~/.claude/projects/<project-name>/memory/
├── MEMORY.md          # Index, loaded in every session (200 lines or 25KB)
├── debugging.md       # Detailed notes (loaded on demand)
├── api-conventions.md
└── ...

Anthropic describes it this way in the official documentation:

Auto memory is enabled with the autoMemoryEnabled flag in ~/.claude/settings.json. Claude decides what to write there. You can read MEMORY.md and edit it manually - it’s ordinary markdown.

CLAUDE.md or a second brain - where should you draw the line?#

Here’s the analogy I use in my talks: imagine you’ve hired a new employee. What do you give them on their first day?

An instruction manual: how to dress, when to arrive, what tone to use with clients, which system to publish through. It’s a short document. It doesn’t explain what you do or why. It simply says how to behave.

And separately, access to the company wiki. It explains what the product is, who it’s for, who the audience is, what the price is and why, who the competitors are, and what mistakes you’ve made. It’s an extensive archive. Nobody reads all of it - you go there for a specific question.

CLAUDE.md = instruction manual. Second brain = wiki. You need both.

The distinction is simple. Put everything that is relevant to every task in CLAUDE.md:

• Who the agent is in this project (helper, lead, assistant)
• Which language to answer in
• Tool stack
• Publishing commands
• Prohibitions (don’t use em dashes, don’t run git push --force)
• Routing: where to go for business context and where to go for principles

Put everything that is needed on demand in the second brain:

• The product, audience, economics, and goals
• Competitors and market
• Past decisions and the reasons for them
• Client examples and reviews
• Principles and methodology

Anthropic makes the same distinction in its documentation:

Skills are one way to store episodic knowledge. A business/ folder alongside the project is another. I use both, and I’ll explain them in more detail below.

What makes up a project brain - 5 parts plus a time machine#

An example architecture:

The key methodological point is to separate profile/ and business/.

business/ answers the question “what do we do?” Product, audience, prices, competitors. It’s about the project. If you hand the project to a partner tomorrow, this folder goes with it.

profile/ answers the question “how do I make decisions?” My principles, tone, craft, and stop words. It’s about me. If I start a new project tomorrow, this folder goes with me.

What should go in business/, and what shouldn’t?#

An example top-level business/ structure:

business/
├── INDEX.md              ← folder map, read first
├── company/              ← mission, legal entity, values, legal policies
├── products/             ← products, programs, prices
├── audience/             ← client profile, segments, objections
├── goals/                ← annual, quarterly, monthly goals, metrics
├── economics/            ← unit economics, income, expenses, forecast
├── marketing/             ← channels, funnel, materials, competitors
├── execution/            ← weekly planning, backlog
└── assets/               ← design system, reviews, copy bank

This is an example, not dogma. I create folders as needed. I started with three (products/, audience/, goals/); the others were added after 2-3 months, when it became unclear where to put new things.

The folder’s main file is INDEX.md. It’s a map. It contains a “question → file” table that Claude uses to understand where to go. Without it, the agent spends tokens reading every file in order.

An example excerpt from INDEX.md:

### Where to find things

| What you need | Where to look |
|---|---|
| Who our client is and their pain points | `business/audience/avatar.md` |
| Products, plans, and prices | `business/products/` |
| Goals and metrics | `business/goals/` |
| Economics (income, expenses, unit economics) | `business/economics/` |
| Promotion channels and materials | `business/marketing/` |

Then one line in CLAUDE.md is enough: “For business questions, read business/INDEX.md and follow the map.” The agent doesn’t load the whole folder into context. It loads the map, picks the right file, and reads only that one.

Checklist of what not to put in business/:

• Raw chat correspondence without processing. If there’s an insight, distill and write it down. If not, leave it out.
• Information duplicated in code. “Which payment provider we use” isn’t needed; the agent can see it in the code.
• Screenshots and images. They increase the folder’s size and aren’t parsed by a text model without an additional step.
• Dynamic numbers. “Today there are 423 payments for the product” will be out of date in a week. Use the LIVE marker and a link to a database query.
• Sensitive or questionable information. If the repository were posted on YouTube tomorrow in front of 100 thousand strangers, keep only what you’d be willing to show. Employees, agents, and sometimes external contractors read the folder.

Why have a separate profile folder, and why shouldn’t it be mixed with business?#

The idea is simple: the business knows what we do. The profile knows how I make decisions.

An example profile/ structure:

profile/
├── INDEX.md           ← folder map
├── role.md            ← who I am, background, what matters
├── identity/          ← values, vision, mission
├── thinking/          ← mental models from talks
├── voice/             ← tone, vocabulary, style
├── principles/        ← beliefs about product, code, business
├── feedback/          ← rules learned through mistakes ← main folder
├── style/             ← stop words, Telegram format
└── reference/         ← tools, environment

The most useful folder is feedback/. It holds specific rules I learned through agent mistakes. Each rule goes in a separate file using this format:

---
name: short-name
description: one line - what’s in the file and when to apply it
type: feedback
---

A short rule in one sentence.

**Why:** why this rule exists. Context, incident, observation.

**How to apply:** specific triggers for when the rule applies.

Without Why, the rule is dead - the agent won’t transfer it to a similar situation. Without How to apply, it isn’t clear when to use the rule.

An example from my folder: the rule “hyphen, not em dash.” It came about because the em dash — is a key visual marker of generated text. It applies to any public-facing text. The file is at profile/feedback/no-em-dashes.md.

I write rules in profile/feedback/, not in CLAUDE.md. CLAUDE.md is a project file, but rules about tone and style are personal. They go with me to the next project. CLAUDE.md stays with the project.

What are Live Metrics, and why not hard-code numbers in files?#

One of the main pitfalls when starting a second brain is filling it with outdated numbers. You write “we have 320 clients,” and two weeks later it’s already 410. You write “monthly revenue is 4.7 million,” and a month later the number is missing its context: is that a target, actual, or forecast?

Here’s how it works. In the business/products/practicum.md file, there’s a marker instead of a number:

## Cohorts

> **LIVE** - run the queries in `live-metrics.md`, section “Sales”
> to see current payments by cohort.

| Cohort | Dates | Paying |
|-------|------|------------|
| 1 | March 10-12, 2026 | LIVE |
| 2 | March 24-26, 2026 | LIVE |

A separate live-metrics.md file contains ready-to-run SQL queries and descriptions of what they return:

## Sales (payments by cohort)

```sql
SELECT c.name, COUNT(p.id) AS paid, SUM(p.amount) AS revenue
FROM purchases p
JOIN cohorts c ON c.id = p.cohort_id
WHERE p.status = 'paid'
GROUP BY c.name
ORDER BY c.starts_at DESC;
```

When I ask the agent, “how many payments do we have for the second cohort?”, it:

1. Reads business/products/practicum.md
2. Sees the LIVE marker next to the number
3. Opens live-metrics.md
4. Finds the “Sales” section
5. Runs the query against the production database
6. Answers using fresh data

This solves two problems at once. Numbers don’t go stale. And decisions are made using the current picture, not last year’s.

How does AI navigate the second brain for a single request?#

A specific request, for example: “draft an email to participants about the new cohort.”

1. Claude starts with an empty window. It loads CLAUDE.md (rules, stack, routing).
2. From the routing in CLAUDE.md, it sees: “profile/INDEX.md - always read at the start of a session.” It opens the file and learns who I am, what my tone is, and which stop words I use.
3. It sees in the routing: “email templates - src/lib/email/layout.ts.” It opens the file and understands the format.
4. It sees: “product context - business/products/practicum.md.” It opens the file and reads about the product.
5. It sees the LIVE marker in the file and a reference to live-metrics.md. It opens the file and finds the ready-to-run SQL. If it needs a current number, it runs the query. If not, it marks “fetch this number at the time of sending.”
6. It sees the tone rules in profile/style/telegram-format.md, the prohibition on em dashes in profile/feedback/no-em-dashes.md, and the funnel conversion rates in business/marketing/funnel.md.

It writes the email in my tone, with fresh numbers and without em dashes or AI markers.

Anthropic calls this approach just-in-time context in its engineering blog:

In other words, Claude carries pointers to data, not the data itself. This is much more token-efficient and much more accurate, because only relevant information ends up in context. The window stays clear for reasoning.

5 second-brain anti-patterns - what should you avoid?#

Anti-pattern 1. An overgrown CLAUDE.md. 500 lines of instructions “instead of putting everything in one place.” Anthropic is direct about this:

The target length is 80-120 lines. Put everything else in separate files and route to them.

Anti-pattern 2. A catch-all folder. You throw everything into the second brain: raw chat correspondence, useless screenshots, reports nobody will read. A month later, the folder has swollen, the agent wastes tokens reading junk, and you can’t remember where anything is. The rule: each file in the second brain should answer a specific question. If nobody has opened it in six months, delete it or move it to the archive.

Anti-pattern 3. Duplication. “Payments go through the payment provider, in src/lib/payment/provider.ts; the provider is configured in .env.” The agent can see all this in the code. Don’t duplicate it in business/. Duplicates get stale: the code changes, business/ doesn’t get updated, and the agent works from outdated information.

Anti-pattern 4. Hard-coded numbers. “We have 1,247 clients, with a 6.3% conversion rate” - imagine these are numbers from some abstract fintech startup. All numbers like these will be outdated in a week. Use the LIVE marker and live-metrics.md. The section about this is above.

Anti-pattern 5. Context without an accessible route. If the second brain is in another location and the agent has neither permission nor a pointer to it, starting in the code folder is not enough. For non-sensitive shared notes, keeping business/ and profile/ inside the repository is a convenient layout. For private context, keep it in a separately controlled location and explicitly configure the permitted access and routing. Folder convenience does not override confidentiality.

How to build a second brain in an hour - a step-by-step recipe#

1. Create two root folders

   In the project root, alongside src/:

   mkdir -p business/{products,audience,goals,economics,marketing}
   mkdir -p profile/{identity,voice,principles,feedback,style}
   

2. Make an INDEX.md as a folder map

   business/INDEX.md is a “question → file” table. Start with at least 5 rows and add more as you go. Do the same in profile/INDEX.md.

3. Add short descriptions of the product and client

   business/products/main.md - what the product is, who it’s for, how much it costs, and what makes it different. 30-50 lines. business/audience/avatar.md - who the client is, their pain points, and what they buy. 30-50 lines. Don’t describe an ideal client - describe a real one. If you don’t know something, mark it “to clarify” and move on.

4. Describe yourself in profile/role.md

   Who you are, what you do, and what matters to you. 20-30 lines. That’s enough to start. Add tone, principles, and stop words when you notice the agent writing in a style that isn’t yours.

5. Add routing to CLAUDE.md

   Open CLAUDE.md and add a section:

   ## Project map
   
   - Business context → `business/INDEX.md`
   - Context about me → `profile/INDEX.md`
   - Technical plans → `plans/YYYY-MM-DD-*.md`
   - Reflections on past sessions → `retrospectives/`
   
   Always read `profile/INDEX.md` and `business/INDEX.md` at the start of a session.
   

6. Start Claude Code and check

   Open the agent. Ask: “tell me about my product and my audience.” If it answers from the folder context, it’s working. If it makes things up, check that the folders are alongside the project, that the files are named correctly, and that the routing in CLAUDE.md is written precisely.

After that, the second brain grows according to two principles.

First: every time the agent makes a mistake, add a rule. After 3-4 weeks, profile/feedback/ will contain 15-20 rule files, and the agent will stop making most common mistakes.

Second: every time you make a business decision, record it in business/. If you raise a price, add a note to business/products/pricing.md with the date and reason. If you change positioning, add a note to business/company/about.md. Six months later, you’ll have an archive that remembers “why.”

We’ve done a substantial amount of work together this week.

Analyze all the code changes from this week, all the commits we made.
What valuable information from this should live in business/ - write it into the appropriate files
with wiki links to neighboring files so the context isn’t lost.

If there are decisions in the code that I haven’t explained, ask me why
and record the reason in the appropriate file with the date noted.

Don’t duplicate what’s already obvious from the code. Only include what the agent
wouldn’t know in the next session without business/.

What next - Skills, Subagents, and context engineering#

Once the second brain is in place, there are three more tools that Anthropic describes as three different levels of context optimization.

Skills are procedural knowledge. If you have a workflow you repeat (writing a learning guide, putting together a Telegram post, auditing a website), you can encode it in a SKILL.md file with a task description. At the start of a session, Claude scans skill names and descriptions and loads only those that fit the current task. This saves tokens and keeps the focus.

Subagents are isolated instances of Claude with their own context windows. Start a subagent on a demanding task (read 30 files and put together a summary), and it works in its own window and returns only the result. Your main window stays clear. Anthropic writes:

Context engineering is managing what goes into the window at all. Anthropic called it a foundational skill for working with agents in 2025, one level above prompt engineering. Prompt engineering is choosing wording. Context engineering is choosing files, routes, skills, and subagents.

A second brain is the first building block of context engineering. Without one, Skills read an empty space, Subagents have nowhere to go, and the agent’s window fills with random information. With one, all three tools start working.

Next step. Create two folders alongside the project: business/ and profile/. Add an INDEX.md to each with 5 lines serving as a map. Add four routing lines to CLAUDE.md. In an hour, you’ll have a working second-brain framework. Then build it out using the rule “after every agent mistake, add one line to profile/feedback/.” I explain the full CLAUDE.md template that you’ll use to route to the second brain in the guide How to set up CLAUDE.md correctly.

Continue exploring Ailoot at ailoot.ai.