SECOND
BRAIN

A folder of markdown files, organized so an AI can find what it needs fast and write things back in the right place. You open the same folder in Obsidian to read and edit it yourself.

• It's yours. Plain text on your own drive. No lock-in, works with any AI, readable in 20 years.
• It's the full record. Built-in AI memory keeps summaries. The vault keeps the reasoning, the history and the links between things.
• It compounds. Every session that ends with a note written makes the next session faster.

Built-in memory and the vault work well together: let the built-in memory hold one-line pointers, and keep the full story in the vault.

1. Install Obsidian (free). It's just a nice editor for a folder of markdown files.
2. Unzip the starter vault (below) somewhere permanent, like a folder in Documents, and open it in Obsidian as a vault.
3. Give your AI access to that folder. Claude Code and the Claude desktop app can read and write files in folders you connect. With a chat-only assistant, paste the briefing file at the start of a session and copy notes back yourself.

Keep work and personal separate. I run two vaults: one for projects and business that Claude uses every day, and a personal one for journaling and reflection that it only touches when I ask.

Flat beats nested. Each folder answers one question, so both you and the AI always know where a note goes.

Profile/       who you are, how you work, what you're good at
Stack/         tools, accounts, integrations, tech choices
Projects/      active work · _active-projects.md is the index
Threads/       running topics not settled yet · _open-threads.md
Decisions/     numbered choices with reasons · _decision-log.md
Constraints/   rules the AI must follow · rules.md
Glossary/      your shorthand and acronyms · terms.md
Templates/     project.md, thread.md, decision.md

Where things go

• A fact about you or how you work → Profile
• A tool or account you use → Stack
• A project's status or scope → Projects, linked from the index
• A choice with a reason behind it → Decisions, numbered
• A topic you keep coming back to → Threads
• "Always do X" or "never do Y" → Constraints/rules.md
• Your nickname for something → Glossary

An AI that reads your whole vault every session is slow and expensive. Give it a few short files to read first, and let it open deeper notes only when the task needs them.

• _session-briefing.md: you in 30 seconds, the top rules, the top three projects, and what's connected. Read first, every time.
• _vault-map.md: what's in each folder, so the AI doesn't have to scan for it.
• _active-projects.md and _open-threads.md: one line per item with status and the next step, linked to the full note.
• _decision-log.md: a table of every decision, one line each.

Every project, thread and decision uses the same shape, so the AI reads them the same way every time. Keep them short:

# Project Name

**Status**: planning | in-progress | blocked | on-hold | shipped
**Started**: 2026-11-09
**Goal**: one line

## What This Is
two or three sentences

## Key Decisions
- [[Decisions/012-short-name]]

## Current State
what's done, what's next, any blockers

## Open Questions
- question

Use fixed status words. Projects: planning, in-progress, blocked, on-hold, shipped. Threads: active, resolved. Decisions: proposed, accepted, superseded. Then "what's blocked?" has a real answer.

Link notes with [[double brackets]]. Obsidian turns them into clickable links and a graph, and the AI can follow them.

The single most useful folder. Every real choice gets a numbered note: the context, what you decided, what you didn't pick and why, and what it means going forward. The point is that you and the AI stop relitigating settled questions. When something comes up again, the answer and the reasoning are already there.

• Name files 012-short-name.md, numbered in order, and add a row to _decision-log.md.
• When a decision changes, don't edit history. Write a new one and mark the old one superseded, with a link.

Constraints/rules.md is where standing instructions live: how you like answers, what the AI should never do, what to check before acting. Mine includes things like "be concise," "check the Stack notes instead of asking me what tools I have," and "evidence before assertions."

I also keep a playbook of lessons from real mistakes, one line each, in a format the AI can match against the task in front of it:

- [2026-08-03] Trigger: about to plan changes to an app based on
  a note describing it. Rule: open the actual file first, then fix
  the note. Why: the note was two sessions stale and hid a conflict.

Before any real task, the AI scans for lessons whose trigger matches. It's how one mistake stops being a repeat mistake.

The AI has to be told the vault exists, where it is, and how to use it. With Claude Code, put a CLAUDE.md file in the folder you work from. It's read automatically at the start of every session. The starter vault includes one:

# How to use my vault
Vault: /path/to/your/vault
1. Read _session-briefing.md first, then _vault-map.md.
2. Open other notes only when the task needs them.
3. After work that changes a project, update its note and
   the index line. New decisions get the next number.
4. Unsure about a fact? Write it with <!-- verify -->
   instead of guessing or stopping to ask.
5. Never store passwords, keys or account numbers.

You can also package these instructions as a Claude skill, so the same rules load in any session where you call it.

A stale vault is worse than no vault, because the AI trusts it.

• End every work session with a write-back: update the project note, the index line, and any new decision. Ask the AI to do it; it's good at this.
• Mark guesses. Anything the AI isn't sure of gets a <!-- verify --> marker for you to check, instead of being written as fact.
• Don't file the AI's suggestions as your decisions. Only what you actually chose goes in Decisions.
• Do a weekly sweep: stale statuses, unanswered verify markers, threads that resolved without being marked.

• Exactly one copy is the real vault. Write its full path into your CLAUDE.md and the briefing.
• Pick one sync method (Obsidian Sync, iCloud, Dropbox, git) and don't layer two on the same folder.
• Back it up like anything else you'd hate to lose.

• Passwords, API keys, recovery codes, account numbers. Note where a key lives ("in 1Password, entry X"), never the key. A vault is not a password manager.
• Other people's private details: health, finances, anything they told you in confidence.
• Anything you'd hate to see if the folder leaked. It's plain text, it syncs, and AI tools read it.