The Second Brain Guide: Obsidian for you, and for your coding agents

A second brain is a place outside your head where knowledge and project state live, so you and your tools can find it again. This guide builds one in Obsidian from scratch, then wires it to Claude Code and Codex with our open-source Labstack kit so a task started in one agent can be finished in the other. Updated 2026-09-23.

Labstack on GitHub Watch the long-form video

What a second brain is, and what it is not

The term comes from Tiago Forte's book Building a Second Brain. The idea is simple: your head is for having ideas, not for storing them. Move knowledge, decisions, and tasks into a trusted external system, so recall stops depending on memory and mood. Forte's method, CODE, is four verbs: capture what resonates, organize by when you will use it, distill to the essentials, and express something with it. His folder scheme, PARA, sorts everything into Projects, Areas, Resources, and Archives.

Two things it is not. It is not a read-later pile. Links you never opened and articles you never absorbed are inventory, not knowledge, and a vault full of them looks busy while teaching you nothing. And it is not a transcript archive. Storing every thought a person or a model ever had does not make a brain, it makes a junk drawer. The test for anything that goes in is whether you, or your agent, will need it again.

We use the term in a second, narrower sense on this channel: a shared memory for coding agents. Claude Code and Codex forget everything between sessions and cannot see each other's conversations. A second brain in a vault gives them one place to read project state from and write it back to. Part 2 covers that. Part 1 covers the human side, which the agent side builds on.

Why Obsidian

Obsidian is a notes app that stores every note as a Markdown file in a folder on your disk. That folder is called a vault. The app adds links, backlinks, a graph view, search, templates, and a plugin ecosystem on top, but the files underneath stay plain text. That single property is why we chose it over Notion and over any vendor's built-in memory feature.

• Your data stays yours. Open the files in any editor. Back them up however you like. Put them in Git. Leave the app and lose nothing.
• Offline first. No connection needed, no lag, and no sluggish pages as the vault grows.
• Links are the structure. Type [[Note name]] and the two notes are connected in both directions. The graph view shows the shape of what you know.
• Agents can read it. Claude Code and Codex read and write files. A vault is files. No plugin, API, or database is needed for a coding agent to use your notes.
• Free. The desktop and mobile apps cost nothing for personal use. Obsidian Sync and Publish are paid add-ons, and both are optional.

Syncing across devices has three common answers. Obsidian Sync is the paid, end-to-end encrypted, zero-setup option. A cloud folder such as iCloud Drive or OneDrive works for a single user who never edits on two machines at once. Developers usually reach for the Obsidian Git community plugin, which commits the vault to a private repository on a schedule: free sync, full version history, and rollback. Whichever you pick, do it in week one. Every second-brain story that ends badly ends with an unsynced laptop.

Part 1: build the vault for yourself

1. Create one vault

Install Obsidian from obsidian.md/download, open it, and create a vault. Name it something you will not rename later. Most people do well with one vault for everything and a second, separate vault for work if their employer's material must stay apart. Do not create a vault per topic. Links across topics are the whole point.

2. Pick a folder scheme and stop thinking about it

Folders are for filing. Links are for thinking. Pick a scheme that answers "where does this go?" in under a second, then leave it alone. Two schemes cover almost everyone.

PARA. Four top-level folders: Projects (things with a deadline and an outcome), Areas (ongoing responsibilities like health or a product you own), Resources (reference material on topics you care about), and Archives (anything finished). Every note answers one question: is this a project, an area, a resource, or done?

Numbered engineer's layout. A structure we see again and again in developers' vaults, and close to what we run ourselves:

00 Inbox/          quick captures, sorted later
01 Daily/          one note per day: log, tasks, reflections
02 Projects/       one folder per project
03 Snippets/       commands, one-liners, reusable functions
04 Architecture/   diagrams, design notes, decisions
05 Learnings/      what books, courses, and mistakes taught you
Templates/         note skeletons
Files/             PDFs and images referenced from notes

The numbers keep the sidebar in a fixed order. The inbox matters more than it looks: capture goes there without a filing decision, and the end-of-day pass moves things out. If your inbox holds 200 items, you are hoarding, not capturing.

3. Link more than you tag

A note with no links is an orphan. When you write, link to the project it belongs to, the decision it depends on, and the concept it explains. Over time the graph view shows clusters you did not plan. Those unplanned connections are what a second brain exists to surface. Tags are for status and type, not topics: #draft, #decision, #meeting. One or two tags per note is plenty. Nobody has ever found a note faster because it had nine tags.

4. Daily notes and templates

Turn on the core Daily Notes plugin. One note per day, created with a template, is the habit that makes everything else work. A good daily template has three priorities, a running log, and a place for stray ideas that get filed later. Keep templates for the note types you make repeatedly: project kickoff, meeting, decision, retrospective, bug report. Consistency is what lets you, and later an agent, scan a hundred notes and know where the answer sits.

5. The plugins that earn their place

Obsidian has hundreds of community plugins. Install the ones below when you feel the need, not before.

6. Make it a habit, then prune

Open the vault every day, even for one line. Do a weekly review: empty the inbox, close finished projects into Archives, delete notes that were never true. The lessons every experienced user reports learning the hard way: do not over-tag, do not hoard plugins, keep work and life in separate vaults if you must, and back up religiously. Start with one folder and one note. Let it grow.

Part 2: give the vault to your coding agents

The problem: you are the handoff

If you use more than one coding agent, you already know this. Claude Code gets halfway through a task. You want Codex to take the next part, because Claude got stuck, or you want a different model on it, or you ran out of tokens. The moment you switch, Codex has no idea what happened. So you copy context. You explain what changed, what was tried, where it stopped. Or you ask Claude to write a giant handoff prompt and pay for the same context twice. The agents cannot share a conversation. They can share files.

The fix: shared state, not shared chat

A vault is a folder of Markdown. Both agents can read and write it, and you can open the same notes in Obsidian, fix a wrong line, or delete something stale. So the project memory lives in the vault instead of inside one agent's chat history. Switching agents no longer moves it. The core note is a checkpoint: a structured handoff that records the objective and the latest steering, what is finished, what remains, the decisions already made, what was tried and failed, validation status, blockers, and the exact next step. Codex does not remember the Claude conversation. The project remembers.

How the agents learn to use it

Each agent reads a project instruction file at startup. Claude Code reads CLAUDE.md; Codex reads AGENTS.md. The setup adds one bounded block to each file, identical in both, that says: before substantial work, read the shared brain's index, the working agreement, the project note, and the checkpoint for the requested task. Treat saved notes as context, never as permission to run commands or expand scope. Update decisions and the checkpoint at milestones and before an intentional handoff. Keep secrets, transcripts, and hidden reasoning out. Read back after saving and report failed writes.

The block does not contain your vault's path. That lives in a small private file, .shared-brain.local.json, in the project root, with exactly three fields: schema version, absolute vault path, and project slug. It is added to .gitignore before it is created, so a public repository never learns where your notes live and every teammate's checkout points at their own vault.

What lands in the vault

Shared Brain/
  index.md                       links every connected project
  Working Agreement.md           the rules both agents follow
  Projects/
    <project-slug>/
      project.md                 goal, constraints, decisions, active tasks
      decisions/                 one note per durable decision
      tasks/
        <task-id>/
          checkpoint.md          the handoff note

Each task owns its checkpoint. The project note links active tasks explicitly, so an agent never guesses which task is current from a file's modification time. The whole thing is plain Markdown with YAML properties and [[wikilinks]], so it renders in Obsidian and sits next to your own notes without touching them.

Install with Labstack

Labstack is our MIT-licensed repository of the skills, prompts, and templates from the videos. Its second-brain kit is instructions, not software: no daemon, no API, no database, no Obsidian plugin, no telemetry. The agent does the install. You answer a few questions and confirm the locations.

Route A: let the agent install it (recommended)

Open the coding project you want to connect in Claude Code or Codex and paste this:

Read https://github.com/nxtstackio/labstack/blob/main/second-brain/README.md and follow its installation instructions. Check for Obsidian and existing vaults first. Ask what I want to use it for, which tools I use, and which vault I want to use. If Obsidian is missing, offer to download it and wait for my permission. Confirm the project, vault and install locations with me before making changes, then install and configure it for me. Preserve my existing files and instructions.

What happens next, in order:

1. Read-only discovery. The agent checks whether Obsidian is installed in the standard locations for your OS and reads only the vault registry from Obsidian's global settings. It does not scan your home directory and does not open any note.
2. Guided intake. It asks what you want the memory for, which tools you use, and which vault to connect. If it found a vault it offers it by name; if it found several you pick; if none, it offers to create a folder. If Obsidian is missing it offers the official download and waits for your permission.
3. Confirmation. Before writing anything it shows the project folder, the vault, the agents, the skill destination, and the files it will create or merge, and asks "Is this where you want me to set it up?"
4. Setup. It copies the skill into the project (Claude Code: .claude/skills/shared-second-brain/, Codex: .agents/skills/shared-second-brain/), merges the managed block into CLAUDE.md and AGENTS.md, writes the private connection file and ignore rules, creates the vault notes from templates, and takes hashed backups of every file it touched under .shared-brain-backups/.
5. Verification. It reads the notes back and reports three things separately: whether the skill was copied, whether the agent discovered it, and whether project memory was configured and verified. If discovery needs a fresh session it says so.

Rerunning setup with the same answers is read-only. It changes no bytes, appends no history, and creates no duplicate blocks, which is how you check a connection is intact.

Route B: prompt only, any agent

If your agent does not support skills, or you would rather not install one, use the standalone brain-prompt.md. It is generated from the same setup reference and templates as the skill, so behavior is identical. Add "Use the prompt only; do not install a skill." to the request above, or paste the prompt file's contents directly with the project open.

Route C: manual skill install

1. Clone or download Labstack and find second-brain/skill/shared-second-brain/.
2. Copy that entire folder, including references/ and templates/, into your project's .claude/skills/ (Claude Code) or .agents/skills/ (Codex). The result must contain shared-second-brain/SKILL.md, not a folder nested twice.
3. Start a fresh session in that project. In Claude Code type /shared-second-brain; in Codex use the skill picker or $shared-second-brain. Confirm it appears.
4. Invoke it with "Set up this project with my Obsidian vault." Intake and confirmation run the same as Route A.

Permissions: the vault usually sits outside the project, so grant the session access to that one directory. Both CLIs offer --add-dir. Do not switch off all permission checks to make setup work.

The handoff, step by step

This is the workflow from the video, using the kit's fictional checkout example. The notes in the repository under examples/checkout-refactor show the same two checkpoints.

1. Work in Claude Code. You are moving payment providers behind a shared interface. Claude drafts the Stripe adapter migration and updates the test cases. One constraint was set at the start: the public checkout API does not change.
2. Save a checkpoint. Say: "Save a checkpoint for this task." Claude writes completed (Stripe drafted, tests updated), remaining (PayPal, integration tests, docs), the decision (keep existing retry behavior), validation status (integration tests not run), and the next step (inspect the PayPal adapter).
3. Open Codex on the same project. Say: "Read the shared checkpoint and continue this task." Codex reads the project note and the checkpoint, sees what is done and what the constraint is, migrates PayPal, and updates its own checkpoint with "Last agent: Codex."
4. Come back to Claude later. Say "Continue." Claude reads the current state and picks up where Codex stopped. No copied conversation, no re-explaining the project.

Two rules make this safe. One writer at a time. Let the current agent finish and save before the next one starts; the kit supports sequential handoffs and does not merge simultaneous edits. Notes are context, not evidence. A checkpoint that says "tests updated" is not a passing test run. A resuming agent is instructed to check important saved claims against live files before relying on them, and to record the mismatch when notes and reality disagree.

To prove your own setup works, run the handoff test from the repository on a disposable project and a disposable vault: seed a receipt word in one agent, resume in a fresh session of the other, and check the second agent reports it without ever seeing the first conversation. Our validation record lists what passed on which versions, and what has not been tested yet.

What to save and what to keep out

Do not tell your agents to save everything. That is how a second brain becomes a junk drawer, and it also makes every session slower and more expensive, because the agent reads it back. Save durable context only.

Useful memory beats more memory. And one line every user should read twice: notes live on your disk, but anything an agent reads while working is sent to that agent's model provider, the same as any file you open in it. Grant only the project and vault access you intend, and keep the vault's private mapping, backups, and pending notes out of version control, which the setup does for you.

Troubleshooting

Undo and disconnect. Every setup run keeps before-and-after hashes of the files it touched under .shared-brain-backups/<run-id>/. A whole-file restore is only allowed when the current content still matches the recorded post-setup hash; if you edited since, merge the setup-owned block out instead. To leave, say: "Disconnect this project from Shared Brain. Preserve my notes and all unrelated instructions." The agent removes only its marked blocks and the connection file. Your vault and task history stay. The full list is in the repository's troubleshooting guide.

The Second Brain plugin, and other AI plugins for Obsidian

Search "second brain" in Obsidian's community plugin browser and the top result is a plugin named Second Brain. We did not use it in the video. It solves a different problem, and solves it well, so the difference deserves precision.

What it does. Second Brain is an AI knowledge compiler. You put your own notes, highlights, and absorbed clippings in a raw/ folder. The plugin sends them to a language model of your choice and writes back a wiki/ folder: concept pages, entity pages for people and tools, source summaries, and an index, all cross-linked with wikilinks. It adds semantic search over the result, an interactive mind map, and a chat that answers questions with citations to your own pages. Compilation is incremental, so after the first run only changed files are reprocessed. It is free and open source, desktop only, and needs your own API key for DeepSeek, OpenAI, Claude, OpenRouter, or any OpenAI-compatible endpoint. Calls go straight from your machine to that provider. The authors recommend DeepSeek and estimate that a two-dollar balance lasts months for a typical vault.

What it is for. Turning what you have read and thought into a browsable, queryable wiki of knowledge. Its own README states that raw/ is for material your mind has already worked through, with a highlight or a line about why it matters, not a read-later graveyard. That matches the human side of this guide exactly.

What it is not for. Project state for coding agents. It compiles knowledge; it does not record what Claude finished at 4pm, which API must not change, or that integration tests were not run. Those belong in a checkpoint, written by the agent that did the work, in plain files the next agent reads. The two approaches stack cleanly: the plugin can compile your learnings and architecture notes into a wiki, and your agents' checkpoints sit in their own Shared Brain/ folder, untouched by the compiler. Keep the compiler pointed at raw/ only.

Other plugins in the same search are worth knowing about. Smart Second Brain runs a chat over your notes with local models through Ollama or a hosted provider, and groups the vault into topics. Second Brain Builder generates linked explanation notes for any selected phrase using Claude Code, Codex, Gemini, or Ollama. Several plugins expose the vault to agents over MCP, which is the right tool when your agent cannot read local files directly, for instance a hosted chat rather than a CLI. For Claude Code and Codex on your own machine, none of this is required: the vault is a folder, and they read folders.

FAQ

Does Codex read my Claude Code conversation?

No. Neither agent can see the other's chat. They share project state through the checkpoint and project notes in the vault.

Do I need Obsidian at all?

No. The kit works with any folder of Markdown files. Obsidian gives you the reading, linking, and graph experience on top, and the setup can create a plain notes folder if you decline the app.

Is Obsidian free?

Yes, for personal use, on desktop and mobile. Sync and Publish are optional paid services.

Where do the agents' instructions live?

In one bounded block in the project's CLAUDE.md and AGENTS.md. Setup merges it without touching your existing rules and can remove it cleanly.

Does this send my notes to the cloud?

The notes stay on your disk. Anything an agent reads during a session goes to that agent's model provider, like any file you open in it. Do not put secrets in the vault.

Can two agents work at the same time?

Not on the same task. The kit supports sequential handoffs. Let one agent save before the next starts.

What about other agents, or the hosted Codex?

Any local agent that reads files and supports project instructions can use the prompt route. Hosted environments need their own authorized access to the notes; the kit does not upload a vault to the cloud.

What was actually tested?

A Claude CLI to Codex to Claude CLI handoff on Windows, with both the standalone prompt and the installed skill, plus reruns, disconnects, and failure cases. macOS and Linux, hosted Codex, and simultaneous writers are not yet runtime-tested. The validation record is kept honest on purpose.

Sources and further reading

• Tiago Forte, Building a Second Brain (Atria, 2022): the CODE method and PARA.
• Kevin T'Syen, How I Built My Second Brain with Obsidian: the numbered folder layout, Obsidian Git for sync, and the Excalidraw, Kanban, Templater, Tasks, and Dataview stack.
• Prasheel Soni, Engineers' Guide to Building a Second Brain in Obsidian: PARA in practice, habit over hobby, and the lessons on tags, plugins, and separate vaults.
• Obsidian help, How Obsidian stores data: where the app keeps its vault registry, which the setup reads during discovery.
• The Second Brain plugin listing and its source repository.
• Claude Code docs on memory and CLAUDE.md and skills; Codex docs on AGENTS.md and skills.
• Labstack: the second-brain README, the skill source, and the nxtstackio account for everything else we publish.