Claude forgets you when a session closes, even when your notes sit in an Obsidian second brain (a folder of notes kept outside your head). You explain your job, your voice and your rules again, then repeat yesterday's corrections. The fix is a harness, which is Claude plus the files it reads on startup, kept in git.
TLDR
Every rule you type into chat twice belongs in a file instead.
A fresh Claude session with no chat history is the hardest test reader, and the right one.
Each question that fresh session asks names one file your vault is missing.
Seven folders and one
CLAUDE.mdfile at the root hold the whole setup.Keep your personal second brain and your company brain in two separate repos.
That repeated explaining is rented work. You pay for it every session and keep nothing.
My vault is a folder of plain Markdown files in a private GitHub repo. The first version had one flaw. Only I could operate it, so it worked like a diary with good search.
The vault now passes a stricter test. A fresh Claude session with no chat history opens it and runs the work, because every rule lives in a file.
Here is the same Monday task, run twice. Claude has no memory of past chats either time, and only the files change.
Without files, I explain my job, then my voice, then yesterday's fixes.
That costs about 20 prompts and still ends in a generic draft.
With files, I type "write the next LinkedIn post" and nothing else.
Claude reads
CLAUDE.md, the Voice file and the matching skill.That costs about 2 prompts, and the draft arrives already checked.
Ten Terms Explain Every File in the Vault
Each term below means one thing in this guide. A search for some of them returns another person's meaning, so the graph shows how they connect.
The vault and the agent
Second brain: a folder of notes outside your head. Here it is an Obsidian vault of Markdown files.
Claude Code: Anthropic's command-line agent. It reads, writes and runs files inside one folder.
Harness: Claude plus every file it reads on startup, such as rules, identity, skills, tools and state.
MCP: Model Context Protocol, a standard way to connect Claude to an outside tool or data source.
The files Claude reads
CLAUDE.md: a Markdown file Claude Code reads at the start of each session. It holds the rules for that folder.
Load order: the sequence in which Claude reads its instruction files. An earlier file carries more weight.
Skill: a folder with a
SKILL.mdprompt. Claude loads it when a task matches its trigger.
The files that run work
Hook: a script that Claude Code runs on an event, such as a file save.
State file: a log the agent edits, such as rows of sent, pending and failed messages.
Routine: a scheduled workflow, such as a daily comment pass, stored as a file.
A Fresh Session Is a Harder Reader Than a New Hire
The test is simple to state. If you disappeared for two weeks, could someone who never met you keep the work running? Pick the hardest stranger for it, a fresh AI session with no memory of past chats.
A new hire passes a weak system. They ask a colleague, search old threads, and copy the person at the next desk. Each answer stays in their head, so the system looks finished while the gap stays open.
A fresh session has no one to ask. It reads the files, and where the files say nothing, it guesses. The guess sounds confident, so the error ships before you see it.
Open a fresh session.
Give it one task with no explanation.
Write down every question it asks.
Write the file that answers each question before the next session.
Rule of thumb: If you type the same correction twice, it belongs in a file. The second time is the signal.
Nine Steps Start an Obsidian and Claude Vault Today
Do these in order. One step takes one sitting, and the sections below explain each one.
Install Obsidian and create a vault, which is one folder of Markdown files.
Create five folders to start, named Inbox, Library, Projects, Archive and Identity.
Write an About file in the Identity folder with your role, your work and your goals.
Write a Voice file there with three paragraphs you wrote, plus the words you never use.
Write
CLAUDE.mdat the vault root with the folder map and a rule that every draft goes to a file.Install Claude Code and start it inside the vault folder.
Turn your most repeated prompt into a skill, which is one
SKILL.mdfile in its own folder.Push the vault to a private GitHub repo, and commit at the end of each session.
End each session by asking Claude to write the decisions and changes into the vault.
Steps 1 and 2. Install Obsidian and Give Each Folder One Job
Every note is a .md file on your own drive. If Obsidian stops working, the files still open in any text editor. Steph Ango, the Obsidian CEO, calls this principle file over app.
Obsidian sits in my tool directory for that reason. Obsidian Copilot sits beside it, and it answers questions from your own notes.
Browse the rest of the list in the tool directory.
Copy this folder pattern and rename the folders to suit you. Keep one job per folder, and start with five folders before you add Output and Engine.
Two files sit at the root. CLAUDE.md holds the rules and the folder map, and TODO.md holds open tasks.
Kanika shares a similar folder tree for content creators, from an ideas inbox down to an archive.
A file outside the agreed folders escapes every check. Each check looks in one known place, such as a scoring script on the drafts folder. None of them searches the whole drive, because a search that wide runs slowly and flags notes never meant to ship.
Watch out: A draft saved in the wrong folder reports zero errors, because no check opens it. Zero errors from an unread file looks the same as a clean draft.
So write the folder map into CLAUDE.md. Tell Claude to save each file type in exactly one folder. Then run a weekly script that lists every file outside the map.
Steps 3 and 4. Write the Identity Files Before Claude Drafts a Line
Most AI output sounds generic, because the model does not know what you sound like. An identity folder fixes that with plain files.
An About file says who you are and what you have built.
An Audience file names the readers you write for.
A Voice file sets the tone and the formatting rules.
A Purpose file says what each piece of writing is for.
My identity folder holds those files plus a README that tells Claude to read them first.
The files carry rules a stranger could never guess. My Voice file bans hashtags and emoji. It also says to write "second brain" with no hyphen. Claude reads that file before it drafts a line, so I never type those rules into a chat again.
Shann Holmberg calls a second brain the place for every file your agents need to do quality work.
Step 5. Write CLAUDE.md With the Folder Map and a Drafts Rule
CLAUDE.md sits at the vault root and loads first. Give it three things.
The folder map, one line per folder.
The rule that each file type goes in exactly one folder.
The rule that every draft goes into a file in the drafts folder.
The third rule matters because chat is gone when the session ends. In a long session Claude writes ten or twenty drafts, and you read three. A draft you never saw is a draft you never reviewed, and that is the one that ships with a wrong number.
Asking Claude to paste everything again at the end fails too. The drafts still sit in a place that expires.
Build one review page that lists every draft from every channel. Mark each one approve, rework or cut, and paste your verdicts back to Claude.
Harsehaj built a blog agent at Browserbase that only drafts, and a human clicks approve before any edit.
A vault grows fastest when a whole website can land in it as one note. My Site to Knowledge Note skill fetches every entry of a glossary, an ideas library or a docs set into one markdown file, then links each entry to your other notes.
Get it from the Site to Knowledge Note page in the skill pack.
Steps 6 and 7. Start Claude Code and Sort Every File Into Three Kinds
Start Claude Code inside the vault folder, so it reads CLAUDE.md on launch. Then turn your most repeated prompt into a skill. Every file you add after that is one of three kinds, and each kind has one owner.
Skill files. You write them. A skill is a folder with SKILL.md for the prompt, the trigger and the output format. It can add a scripts folder for Python checks and a references folder for examples. The skills guide shows a full set.
State files. The agent edits them, and you never do. My outreach log records every Substack DM the outreach script sends. The next run reads it and refuses a duplicate, so a hand edit can make it message someone twice.
Reference files. These are examples to copy. One folder holds a breakdown of each post format, and the LinkedIn skill copies their shape.
Tip: Skills live in two places. The skills folder in your home directory loads in every project, and a skills folder inside the vault loads only there. Keep each skill in exactly one of the two.
Step 8. Commit the Rules to a Private Repo and Never Commit the Keys
Push the vault to a private GitHub repo and commit at the end of each session. Commit these files:
The vault notes and the identity files
The skills, the hooks and the routine files
An example env file with empty values
Never commit .env, a credentials file or any API key. Keep secrets in one gitignored .env file and refill them by hand on a new machine.
A company brain is the same idea for a team. It holds company skills, company voice, and a README written for agents. Keep it in its own repo.
A help docs repo I maintain at work runs as a company brain. Its README lets a new joiner point Claude at the repo with zero context.
The global CLAUDE.md in your home directory loads in every session, and mine carries a project registry. Each row maps the words I say, such as "my website", to a local folder and its GitHub repo. I say "fix the footer on my website" from any session, and Claude works in the right folder.
When two rows collide, such as "the docs", Claude asks which one I mean.
Claude runs
git statusbefore it edits, because some repos sit on feature branches.Claude names any other repo it writes to in its reply.
A commit or a push still needs my yes.
Step 9. End Each Session by Writing Decisions Into the Vault
Ask Claude to write the decisions and changes of the session into the vault before you close it. Then run the stranger test again. Each question the fresh session asks names a file your vault is missing, so write that file next.
On a new PC, clone the config repo and run its restore script. The full backup and restore guide is in The 5 Files That Give Claude Code Permanent Memory.
Advanced Users Add Hooks, Agents and Routines as Files
The nine steps give Claude memory. The pieces below make the vault refuse bad work and run on a schedule.
Hooks block the write. My hook runs a scoring script after each file save. On a critical finding it blocks the save, so Claude cannot finish while the draft fails. A second hook prints the load order into context on any writing prompt. The load order post shows what that costs in tokens.
Scorers and a second grader close the loop. Define good and bad output, generate, score, and regenerate up to 3 to 5 times. A fresh subagent grades the rest, because an agent will not reject its own earlier answer.
Example: In one session, 21 LinkedIn comments failed the scorer and never posted.
Agents own one job each. An agent is a file that gives Claude one role and its tools.
One agent writes articles, and another turns them into social posts.
One sends outreach messages, and another writes comments.
One runs the health checks, and another files loose notes.
Routines live in git. A routine that exists only inside a Claude account vanishes when you switch accounts. So each routine is a file in a routines folder, with its input and its output state.
Connectors follow the account, and MCP servers follow the machine. A cloud connector in Claude's Connections tab works for anyone on that account. A local MCP server lives in the machine config, so a new PC needs it set up again.
Five Questions Newcomers Ask About an Obsidian Second Brain
Do I need Obsidian, or will any folder work? Any folder of Markdown files works, because Claude Code reads plain files. Obsidian adds links, search and a graph view on top of the same files.
How long does the first setup take? Plan one sitting per step, so about nine short sessions. The first five steps already stop most of the repeated explaining.
Can I start with five folders and add more later? Yes. Start with Inbox, Library, Projects, Archive and Identity, then add Output and Engine when you have drafts and skills to store.
What happens to my API keys when I push to GitHub? They stay on your machine if they live in a gitignored .env file. Commit an example file with empty values, so a new machine knows which keys to refill.
How do I know the vault is finished? It is never finished, but it passes when a fresh session runs a task without a question. Each question it does ask tells you the next file to write.
Appendix. A Starter CLAUDE.md and Gitignore to Copy
Paste this at the vault root as CLAUDE.md, then rename the folders to match yours.
# CLAUDE.md
## Folder map
- Inbox/ raw captures, not sorted yet
- Identity/ About, Audience, Voice, Purpose. Read before any draft.
- Library/ reference notes
- Projects/ one subfolder per active project
- Output/ ideas/, drafts/, published/
- Engine/ skills/, hooks/, routines/
- Archive/ retired notes. Never delete, always archive.
## Rules
1. Save each file type in exactly one folder from the map.
2. Write every draft into Output/drafts/, never only into chat.
3. Never edit a state file by hand.
4. Commit at the end of each session. Never commit .env.Add these lines to .gitignore before the first push.
.env
*.key
credentials.json
.obsidian/workspace.jsonOne row of the global project registry looks like this.
| You say | Local path | Repo |
|------------|---------------------|-------------------|
| my website | D:\Projects\website | you/your-website |