DEV Community

Cover image for How to build a second brain with Obsidian and Claude Code (step by step)
Malik Chohra
Malik Chohra

Posted on • Originally published at codemeetai.substack.com

How to build a second brain with Obsidian and Claude Code (step by step)

Six folders, one context file, a memory directory, and a handful of slash commands. The exact setup, in build order.

TL;DR

  • A second brain fails when notes pile up and nobody reads them again. The fix is a layer underneath the notes that an LLM reads for you.
  • This is the setup I built in about a day and have run for two weeks: PARA folders, a CLAUDE.md context file, a memory directory, and slash commands.
  • Obsidian holds the markdown. Claude Code reads it, writes to it, and runs commands against it.
  • Steps 1 to 4 are the structure. Steps 5 and 6 are the part that makes it stick.
  • It is plain markdown in a folder. Nothing is locked in. If Claude disappears tomorrow, you still have your notes.

For the full guide, with the prompt that you can use directly to generate your second brain, and a step-by-step, detailed guide, is here: https://choumed.gumroad.com/l/nhgsxf. you can grab it for free

What is a second brain?

A second brain is a personal knowledge system that lives outside your head. It holds your ideas, decisions, project state, and references in a place you can return to and build on. The term comes from Tiago Forte's book Building a Second Brain. His original framing assumed a human would read the notes back. Mine assumes an LLM will.

Two tools do the work.

Obsidian is the storage. A desktop app that opens any folder of markdown files and adds links, search, and a graph view on top. Your files stay on your disk. No cloud unless you turn it on, no proprietary database, no export step. If you want your notes back, you already have them.

Claude Code is the operator. A tool from Anthropic that runs in your terminal, reads files in a folder you point it at, and runs against saved prompts. You tell it to read your vault and act. It does.

The pair is the whole idea. Obsidian makes the notes legible to a human. Claude Code makes them executable by a machine. Neither one alone gets you a second brain. Together, they do.

Why most second brains die, and the one change that fixes it

I have started a second brain six times. Roam, Notion, Tana, Logseq, Notion again, a short flirtation with Reflect. All six died the same way. I built the structure on a Sunday, filed notes through Wednesday, and by the next weekend the vault was just another inbox to clean.

The standard diagnosis is "capture is easy, retrieval is hard." That is correct. You write 200 notes and six months later cannot find the thinking behind the decision you made in March. The graph view looks great in screenshots. It does not answer questions.

But that diagnosis blames the tool. The real problem is that you were the only retrieval engine. Asking a human to read 500 markdown files back every week is asking them to be a database. They will not do it. The vault rots.

The fix is to put a reader underneath the notes. Not a human. An LLM that treats your vault as required reading. That is the whole trick. Everything below is how to set it up.

What you are actually building

Three parts, and the order matters.

  • The vault is your brain. Plain markdown files in folders. This is Obsidian's job.
  • Claude Code is the operator. It reads the vault, writes to it, and runs commands against it.
  • Slash commands are the interface. They turn the folder from a place you file things into a place you work from.

A vault without the operator is a filing cabinet. The operator without commands is a chat window. You need all three.

Step 1: Build the PARA skeleton

Install Obsidian and create a vault. A vault is just a folder. Inside it, create six folders at the top level:

00-Meta/        # the operating layer (read first by everything)
01-Projects/    # active work with a deadline and an outcome
02-Areas/       # ongoing responsibilities, no deadline
03-Resources/   # reference material and templates
04-Archives/    # done, paused, dead
05-Daily/       # one note per day, the journal
Enter fullscreen mode Exit fullscreen mode

The middle four are Tiago Forte's PARA method. The two numbered additions are what a developer's vault needs and PARA does not specify: 00-Meta for the files that run the system, and 05-Daily for the journal.

Treat 01-Projects the way you treat a codebase. One folder per project. Each gets a progress.md (a dated log of what shipped) and a roadmap.md (what is next). Feature first, same as your repo.

second brain
The folders took me 30 minutes. Do not spend a Sunday on this. The structure is not the hard part, and it is not where the value is.

Step 2: Write CLAUDE.md, the file Claude reads first

This is the step that carries the weight. Create 00-Meta/CLAUDE.md. It is the file Claude Code reads before doing anything else, every session.

Keep it to 200 to 300 lines. Mine covers:

  • Who I am and what I am working toward right now
  • My current projects and how they relate
  • How I want Claude to work with me (direct, opinionated, no hedging)
  • Voice rules for anything it writes
  • A list of canonical source files, in priority order
  • Locked decisions that should not be reopened

Here is the shape of it, stripped to a skeleton:

# CLAUDE.md: context for this vault

## Who I am
[Role, what you are building, what you are optimizing for.]

## Current priorities
[The 3 to 5 things that matter this quarter.]

## How to work with me
[Tone, format, what to push back on.]

## Canonical sources (trust these first)
1. CLAUDE.md (this file)
2. [Your day plan file]
3. [Your active-work file]

## Decisions locked (do not reopen)
- [Decision, with date.]
Enter fullscreen mode Exit fullscreen mode

The difference this makes is large. Without it, every session starts cold and you get generic productivity advice. With it, you ask "plan my day" and get a briefing that already knows your deadlines, your constraints, and the decision you locked last week. You stop repeating yourself. That alone is worth the setup.

Edit this file when decisions change. Twice a week is normal.

Step 3: Add the memory layer

CLAUDE.md is static context. It does not change much. But the state of your work changes daily: what shipped, what got renamed, which decision got made in last night's notes.

That state needs its own home. Claude Code keeps a memory directory per project. Drop one file per fact in there, plus a MEMORY.md index that lists them all.

Naming is boring on purpose:

decision_pricing_locked.md
project_app_launch_timeline.md
feedback_always_run_tests_first.md
Enter fullscreen mode Exit fullscreen mode

One file, one fact. When you lock a decision in a chat session, write it to memory before the session ends. The next session reads the index, pulls what is relevant, and never asks "wait, what did we decide about pricing?" This is the part that gives the vault continuity. Obsidian gives you the spatial layout. The memory directory is what makes next week start from a richer state than last week.

Step 4: Link notes with wikilinks

Obsidian links files with this syntax: [[Project-Name]]. Use it everywhere. The rule I follow: when I create a file, I add links to the related project or area before I save it.

This builds the graph. Obsidian's graph view turns the vault into a visual map of how everything connects.

The graph looks impressive, and that is the trap. The pretty picture is not the point. The point is that wikilinks let Claude Code traverse relationships. When it reads a project file and sees a link to a decision note, it can follow it without you telling it where to look. The graph is for the machine, not for the screenshot.

Step 5: Write the slash commands

This is the step that converts the vault from storage into a system. A slash command in Claude Code is a markdown file in .claude/commands/. It is a saved prompt. That is all. today.md becomes /today.

I run 13. The ones that matter daily:

  • /context loads the full vault state at the start of a session. It reads CLAUDE.md, the memory index, and the active project files, then prints a situation report.
  • /today produces the day's briefing. It reads the day plan and the active work, then outputs a top priority with the steps under it.
  • /log structures the evening journal into the daily note.
  • /sunday runs the weekly review.

The rest are thinking tools: /trace to see how a decision evolved, /challenge to poke holes in a plan, /drift to catch where I am slipping from my goals. Start with the four above. Add the others when you feel the need, not before.

Writing a command is not hard. Open a markdown file, describe what you want Claude to read and what you want it to output, and save it in .claude/commands/. The first version of mine took an afternoon.

Step 6: Run the loops

Structure is dead weight without a rhythm. Two loops keep the vault alive.

The daily loop. Morning: open Claude Code in the vault, run /context then /today. Evening: record a short voice memo about what worked and what broke, paste the transcript into Claude, run /log. The command writes a structured note into 05-Daily/. A bare daily note looks like this:

# 2026-05-22

## Top 3 today
1.
2.
3.

## Shipped
- What:

## Wins
-

## Friction
-

## Notes and ideas
-

## End of day reflection
> One thing I would do differently tomorrow?
> What should move into a project file or the inbox?
Enter fullscreen mode Exit fullscreen mode

No elaborate template. Five headings. The structure exists so /sunday can read across the week and find patterns.

The weekly loop. Sunday: run /sunday. It reads the week's daily notes, surfaces patterns you missed, and outputs one win, one friction, one thing to change. That output becomes next week's starting context.

Capture flows in through /log. Context flows out through /context. Decisions get locked into memory. That loop is the second brain. The folders were never the hard part.

How I built mine

I scaffolded the vault with Claude in an afternoon. Folders, CLAUDE.md, the first four slash commands. Then I did the harder part. I took my phone to a park, sat in the sun, and opened the Claude mobile app. For about three hours I talked to it like a partner. What I am working on, what is stuck, what I have been avoiding. It asked clarifying questions. I answered. When I got home, I opened the Claude desktop app, pointed it at the vault, and asked it to sync the conversation into the right files. Et voilà. The skeleton I had built in the morning was filled in with my actual life by the evening.

Structure first, content second. Use the mobile app for the talking, the desktop for the filing.

Where this breaks

The honest section, because tutorials never have one.

  • CLAUDE.md drifts from reality. Rename a file, forget to update CLAUDE.md, and /context produces confidently wrong output. Keep a changelog of structural changes. I still forget to use mine about a third of the time.
  • The memory directory will outgrow a flat folder. Thirty files is fine. Three hundred will need search or embeddings. The naming convention buys you a long runway, not forever.
  • It depends on Claude Code as the reader. If pricing changes hard or the CLI gets killed, the executable layer evaporates. The mitigation is that your notes are plain markdown and the commands are short prompts. You lose the operator, not the brain.

Get the prompt that builds this for you

If you want to skip starting from a blank page, paste the Vault Architect prompt into Claude, answer four short rounds of questions, and it builds the whole vault customized to you. Folders, your CLAUDE.md, the four slash commands, the daily template.

The whole thing is a free kit on Gumroad: this guide plus that prompt. Get the Second Brain Vault Kit, free.

I also write Code Meet AI, a weekly newsletter on AI-native developer workflows. One issue a week, tactical, no fluff.

FAQ

How do I connect Obsidian to Claude?

Obsidian stores your vault as plain markdown files in a folder. Open Claude Code with that folder as the working directory and it reads the files directly. There is no plugin or API to wire up. The connection is just the shared folder.

Do I need Claude Code, or does ChatGPT work?

The folder structure and the CLAUDE.md context file work with any LLM that reads context, including ChatGPT custom instructions and Cursor rules. The slash commands are specific to Claude Code, but they are short markdown prompts you can port to any CLI agent.

What folders should a developer second brain have?

Start with PARA: Projects, Areas, Resources, Archives. Add two more that PARA does not specify but a developer needs: a meta folder for the operating files like CLAUDE.md, and a daily folder for the journal. Six folders total. Resist adding more until something genuinely does not fit.

Is Obsidian or Notion better for an AI second brain?

Obsidian, for one reason: the vault is plain markdown in a folder you control, so an LLM can read it with no export step. Notion's data lives behind a database and an API, which adds friction. If you are starting fresh, Obsidian plus a local folder is the cleaner path.

How long does it take to build?

The folders take 30 minutes. The first CLAUDE.md took me about two hours. The slash commands were an afternoon. Total upfront cost is under a day. The memory directory then fills in on its own as you work.

Top comments (0)