Claude as a second brain: build one in Claude Code

A Second Brain that you check three times a week and forget for a month is not a Second Brain. It is a graveyard. The reason most personal knowledge management systems die is the friction tax: every capture, query, and review requires opening another app, remembering another shortcut, and switching mental modes.

If you already live in Claude Code or any terminal-first workflow, you can collapse that tax to zero and use Claude as your second brain. Your Second Brain becomes a folder. Your interface becomes the CLI you already have open. Your memory becomes a skill the model loads on demand. This guide walks through the build.

You will end with a working system that captures notes, decisions, and project state, retrieves them through natural-language queries, and survives across sessions. No Notion, no Obsidian sync, no SaaS subscription.

Why Claude works as a second brain (and Notion does not)

The case for Claude Code as a Second Brain host comes down to three properties Notion does not have at any price tier.

Files you own, in formats you can grep. Markdown sitting on your disk is searchable by every tool you already know: grep, ripgrep, fd, your editor. Notion's database is queryable only through Notion's UI or its API. If Notion is down or you decide to leave, your data is hostage to an export.

An assistant that lives in the same window. Claude Code reads, writes, and reasons about your files in the directory you are already in. Notion's AI lives inside Notion. Switching context kills capture.

Skills and MCP servers as native primitives. A Second Brain needs routines: morning briefing, weekly review, decision capture, project state. In Claude Code those are skills (markdown files in .claude/skills/) and MCP servers (small programs your assistant can call). In Notion they are buttons you have to remember to click.

This does not mean Notion is bad. It means terminal-first PKM optimizes for a different person. If you want to see how the wider field compares, I reviewed the best AI second brain solutions separately.

What you need before you start

• Claude Code installed (npm install -g @anthropic-ai/claude-code or via the official installer)
• A folder you control, with git initialized
• 30 minutes for the initial setup, then 10 minutes per week for maintenance

That is the entire prerequisite list. If you want a managed version of this exact setup with templates and example workflows, Iwo's Second Brain template ships ready to drop in.

Step 1: Pick the folder structure

Your Second Brain is a directory. Mine looks like this:

~/brain/
├── CLAUDE.md                  # The operating manual
├── .claude/
│   ├── skills/                # Routines as on-demand skills
│   └── rules/                 # Auto-loaded domain rules
├── memory/
│   ├── episodic/              # Things that happened (meetings, decisions)
│   ├── semantic/              # Facts, references, definitions
│   └── procedural/            # How-to notes, runbooks
├── projects/
│   └── {project-slug}/        # One folder per active project
├── inbox/                     # Capture everything unsorted here first
└── archive/                   # Closed projects, old notes

The principle: separate by lifecycle, not by topic. Episodic notes age fast. Semantic facts are evergreen. Procedural runbooks live until the procedure changes. Projects are short-lived. Inbox is friction-free capture. Archive is read-only history.

You can adapt this. The structure that matters is the one you will actually maintain. Your folder layout is not just tidy storage. It is a prompt the model reads before you type a word, which is why your Claude Code folder structure is worth getting right.

Step 2: Write the CLAUDE.md operating manual

CLAUDE.md at the root of your brain folder is the file Claude Code reads on every session. It tells the model what this folder is for, where things live, and what it should do when you ask vague questions.

Keep it short. Under 100 lines is the goal. If it grows, push details into .claude/rules/*.md and let progressive disclosure handle the load.

A minimal example:

# Brain, Personal Second Brain

This is Iwo's personal knowledge folder. Treat all entries as first-person notes.

## Quick commands

- `/morning`, read inbox, surface open loops, suggest top 3 tasks
- `/capture [note]`, file a note in inbox/ for later sorting
- `/decide [decision]`, write a decision record to memory/episodic/decisions/
- `/review`, weekly review, surface what closed and what is still open

## Folder map

- `memory/episodic/`, meetings, decisions, journal entries (dated files)
- `memory/semantic/`, evergreen facts, references, definitions
- `memory/procedural/`, runbooks and how-tos
- `projects/{slug}/`, active project folders with their own README
- `inbox/`, raw captures, sort weekly
- `archive/`, closed material, read-only

## Writing rules

- Markdown only. No HTML, no images inline.
- Filenames: YYYY-MM-DD-slug.md for dated material, otherwise kebab-case.
- One decision per file. One meeting per file. Atomic units.

That file plus the folder structure is already a usable Second Brain.

Step 3: Add skills for routines

A skill in Claude Code is a markdown file at .claude/skills/{name}/SKILL.md with YAML frontmatter naming the trigger. When you invoke the skill, Claude loads it and follows the instructions inside.

For a Second Brain, the four highest-leverage skills are:

Skill	What it does	Trigger
morning	Reads inbox, lists open loops, proposes top 3 tasks	/morning
capture	Saves the next message as a dated markdown file in inbox	/capture
decide	Writes a structured decision record with date, context, choice, alternatives	/decide
review	Weekly: lists what closed, what is still open, what got stuck	/review

A skill file is small. Here is morning:

---
name: morning
description: Morning briefing, reads inbox, surfaces open loops, proposes top 3 tasks for today
---

# Morning Briefing

1. List every file in inbox/ created in the last 7 days
2. List every project folder where the most recent file is older than 14 days (stuck projects)
3. Scan memory/episodic/decisions/ for decisions marked "needs-followup" in frontmatter
4. Surface a top-3 task list, prioritized by:
   - Open loops from yesterday's session
   - Decisions waiting on action
   - Stuck projects that need a small unblocking move

Output a single screen of plain text. No tables, no markdown styling. Just the briefing.

That is the entire skill. Drop it in .claude/skills/morning/SKILL.md, restart Claude Code or wait for the next session, and /morning is live.

Iwo's Second Brain Bootcamp walks through writing your own skills if you want a structured path.

Step 4: Install a memory MCP server

Skills handle routines. Memory MCP servers handle persistent state across sessions. Without one, every conversation starts cold.

The minimum viable setup: install Iwo's MemoryOS MCP for structured memory with recall scoring. Configure it once in your MCP client config, point it at your brain folder, and the assistant can read and write memory entries without you copy-pasting context.

npm install -g @iwo-szapar/second-brain-health-check

Then in your Claude Code MCP config:

{
  "mcpServers": {
    "memoryos": {
      "command": "second-brain-health-check",
      "args": ["--brain-path", "~/brain"]
    }
  }
}

Restart Claude Code. The memory tools are now available. The model can store and recall structured memory entries on demand.

If you want a simpler start, the official Anthropic Memory MCP gives you a basic knowledge graph for free. Upgrade to MemoryOS when you outgrow the JSON blob.

Step 5: Populate the brain with what you have

The empty-folder problem: a Second Brain is useful only when it has something in it. Spend one focused hour seeding it.

Capture in three passes:

1. Open loops from your head. What are you thinking about that has no home? Dump each one into inbox/ as a single file. Five minutes per item, max.
2. Decisions from the last quarter. What did you choose, and why? One file per decision in memory/episodic/decisions/.
3. Reference material you keep re-Googling. Settings, recipes, command lines, formulas, contacts. One file each in memory/semantic/.

After an hour you will have a brain with 30 to 50 files. That is enough to start running queries.

Step 6: Run your first queries

Open Claude Code in your brain folder. Try these:

• What decisions did I make last month?, pulls from memory/episodic/decisions/
• Summarize project X, reads projects/x/ and gives you the state
• What is in my inbox?, lists inbox/ contents
• Did I write anything about [topic]?, semantic search across the brain

The model uses the folder structure from CLAUDE.md to route the query. If the answers feel wrong, the fix is almost always in CLAUDE.md: clarify what lives where, and queries get sharper.

Step 7: Make it sustainable

A Second Brain dies from one of two failure modes: capture friction (you stop putting things in) or decay (you put things in but never look back).

Fix capture by lowering the cost. The capture skill should accept a one-line message and file it. No tags required, no folder choice required. Sort later.

Fix decay by scheduling a weekly review. The review skill takes five minutes on a Friday afternoon. It surfaces what closed, what stuck, what you forgot about. Anything older than 30 days in the inbox moves to archive or gets deleted.

The system rewards small consistent use. Twice a day for 90 seconds beats once a week for an hour.

FAQ

Why Claude Code instead of just using Claude Desktop?

Claude Code runs in the same terminal where you do everything else: write code, run scripts, edit files. Capture friction drops to zero because you do not switch apps. Claude Desktop is great for chat but does not have the same direct file-access model with skills and MCP servers wired in by default. I compared the two in detail in Claude Code CLI vs Desktop.

Do I need MCP servers, or is the folder enough?

The folder alone gives you 70% of the value. MCP servers add persistent memory across sessions, semantic recall, and integration with external tools. Start with the folder, add MemoryOS MCP when you find yourself re-typing the same context every morning. The same memory layer is not limited to Claude Code. A cheaper agent like Z.ai's ZCode forgets your project between sessions in exactly the same way, and the same MCP setup fixes it there too.

How is this different from Obsidian?

Obsidian is a markdown editor with graph view, plugins, and rendering. Claude Code is an LLM client that can read and write the same markdown files. They are complementary, not competing. Many people run both: edit in Obsidian, query through Claude Code.

What about syncing across machines?

Use git. Push your brain folder to a private repo, pull on your other machine. It is the same flow as syncing a code project. The .gitignore should exclude inbox/.draft/ or wherever you keep noisy in-progress captures.

How long does this take to set up?

The folder structure plus CLAUDE.md is 30 minutes. The four core skills is another 60 minutes if you write them yourself. Installing one MCP server is 10 minutes. So under two hours from zero to working system. The Second Brain Bootcamp covers the full build with templates and example skills if you want a guided version.

Can a team share a brain like this?

Yes, but the design choices change. Personal brains optimize for low capture friction. Team brains need permissions, attribution, and shared review rituals. Team Brain is the version of this stack designed for teams of 3-15 people. Here is how we built a company second brain with Claude Code agent teams.

What is the failure mode I should watch for?

The one I see most often: people over-engineer the folder structure in week one, then never write anything in it. Start simpler than you think. Five folders is too many to begin with. Two folders (inbox/ and archive/) is genuinely enough for the first month.

---

Want a working Second Brain template you can clone and adapt? See Iwo's Second Brain. For a guided 4-week build, Iwo's Second Brain Bootcamp ships every Monday.