Claude Code second brain: setup and review workflow

A Claude Code second brain is your notes folder with Claude Code running inside it. Claude Code is Anthropic's coding agent, but nothing about it is specific to code: it reads files, writes files, searches folders and runs commands. Point it at an Obsidian vault and it can file your inbox, turn meeting notes into project updates, answer questions from everything you've written, and keep links between notes up to date.

The difference from a chat app is that the notes are the memory. You don't paste context into each conversation. Claude reads what it needs from disk, and whatever it writes stays in plain markdown files you own. Andrej Karpathy's LLM wiki is the same idea taken further: the agent maintains a whole wiki from your sources.

There is a catch. An agent that can improve every note can also quietly change a note you rely on. So this guide covers the setup and, just as much, how to see and approve what Claude changes: with git, which works today, and with Knowtarium.

Knowtarium is an end-to-end encrypted knowledge base for notes that people and agents write together. Claude Code connects to it over MCP, every change Claude makes is signed, shows who made it and can be undone, and each note shows who wrote it (and, in folders with review on, who checked it). It's free to start. Short notes along the way say how Knowtarium handles each part.

You need Claude Code installed (see Anthropic's docs) and a folder of markdown notes. Obsidian is optional: Claude only needs the folder.

1. Take a snapshot first

Before Claude touches anything, put the vault under git and commit. This is your undo button for everything that follows, and it takes a minute. Add a .gitignore so Obsidian's layout files don't clutter every diff:

# Obsidian rewrites these constantly; keep them out of your diffs
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.trash/
CLAUDE.local.md

2. Start Claude Code in the vault

$ cd ~/Notes                  # your vault$ git init && git add -A$ git commit -m "before Claude"$ claude
> /init

/init looks at the folder and drafts a CLAUDE.md. It was designed for code, so treat the draft as a starting point and rewrite it with the rules below. Run /context to confirm the file loaded.

3. Decide how much Claude can do without asking

Claude Code has permission modes. In Manual mode it asks before each edit. Plan mode has it propose a plan without editing, which suits a first session in a vault you care about. You switch between them with Shift+Tab. The permission modes page lists which mode a session starts in, which depends on your version and account.

In Knowtarium

Permission modes decide what Claude may do during a session. Knowtarium covers the rest: you connect Claude to one workspace, only some folders if you like, and read-only or read-write. Every change it makes is signed and can be undone in one click. Agents can delete only if you gave them that permission (a deleted note comes back with Undo while your history period keeps it), and they can't mark a note as checked by you. For folders you want to approve first, turn on review ("Ask me first"), and Claude's changes there wait for you.

(opens full size in a new tab) (opens full size in a new tab)

CLAUDE.md is a markdown file Claude Code reads at the start of every session. For a vault, it should answer three questions: how the vault is organised, how Claude should write, and what it must report back. Anthropic's memory docs give the rules that matter:

• Keep it under about 200 lines. Longer files use more context and are followed less reliably.
• Write instructions you could check ("journal/ is read-only", not "be careful with my notes").
• Pull in other files with @path imports, such as a note with your current priorities.
• A CLAUDE.md in a subfolder loads when Claude reads files there, so a big project can carry its own rules.
• Put personal notes you don't want in git in CLAUDE.local.md.

# This vault
 
Personal notes, managed in Obsidian. Plain markdown, wikilinks.
 
## Layout
- inbox/: raw captures. Process them, then move them out.
- projects/: one folder per active project, with a README.md.
- areas/: ongoing topics (health, money, work).
- journal/: my daily notes. Read them, never edit them.
- archive/: finished projects. Don't touch.
 
## How to write
- Keep my wording. Add, don't rewrite, unless I ask.
- New notes get frontmatter: type, created, source.
- When you state a fact, link the note or URL it came from.
- Link people as [[First Last]], projects as [[Project Name]].
 
## After every task
- List the files you created, changed or moved.
- Add a line to log.md: date, what you did, which files.
 
Current priorities: @context/now.md

"Keep my wording" and "list the files you changed" are the two lines people most often wish they had written on day one. The first stops Claude from polishing your voice out of your notes. The second makes review possible.

Make the important rules hard rules

The docs are explicit that CLAUDE.md is context, not enforced configuration. Claude tries to follow it, with no guarantee. For folders that must never change, add a deny rule to .claude/settings.json in the vault. Edit rules cover Claude's file tools and common shell commands, though not a script that opens files itself, so keep git as the backstop.

{
  "permissions": {
    "deny": ["Edit(/journal/**)", "Edit(/archive/**)"]
  }
}

Claude Code has two kinds of memory, and it helps to know where each one lives.

When you tell Claude "remember that I review invoices on Fridays", it goes to auto memory. When you say "add this to CLAUDE.md", it goes to the file. /memory lists both and opens them.

For a second brain, keep the context you care about inside the vault, where you can read it, git tracks it and every agent can see it. A small context/now.md with this week's priorities, imported from CLAUDE.md, does more than a long memory file. Update it yourself on Mondays, or ask Claude to draft the update and review it like any other change.

Most of the value comes from a handful of repeatable jobs:

• Inbox triage. Claude proposes where each capture belongs, you approve, it moves the notes and links them.
• Meeting notes to project updates. Paste or drop a transcript; Claude writes a summary, updates the project README and lists open actions.
• Ask your notes. "What did I decide about the pricing page, and why?" Ask it to answer with links to the notes it used.
• Weekly review. Read the week's journal and project notes and draft a review note, without editing the originals.
• Link maintenance. Find orphan notes, broken links and notes that should link to each other, and propose fixes as a list.

Turn each job you repeat into a skill. A skill is a SKILL.md file in .claude/skills/<name>/; you run it by typing /<name>, and Claude can also pick it up when your request matches its description. Unlike CLAUDE.md, a skill only loads when it's used, so detailed procedures cost almost nothing the rest of the time.

---
description: Process the inbox. Use when I say 'process inbox' or 'triage'.
---
 
For each note in inbox/:
1. Decide where it belongs: a project, an area, or the bin.
2. Show me the plan as a table before moving anything.
3. After I approve, move the notes and add links from the
   project or area README.
4. Never delete a note. Put rejects in archive/inbox-rejects/.
5. List every file you touched.

In Knowtarium

Whatever the job, each note Claude writes or edits is marked in the sidebar until you open it, with its changes and an Undo one click away. For link maintenance, links to notes nobody has written yet show in the graph as ghosts. When Claude writes a note with footnote citations, point at one in Knowtarium to see the source behind the claim.

(opens full size in a new tab) (opens full size in a new tab)

Built-in commands worth knowing in a vault:

After a few weeks, a Claude Code second brain holds notes you didn't write yourself, and notes you did write that Claude has since edited. Both are fine, as long as you know which is which. Typical problems:

• A tidy-up pass rewrites a note in Claude's voice and drops the one caveat that mattered.
• A summary states a date or number that isn't in the source note.
• A move breaks links, because Claude moved the file with a shell command and nothing updated the links.
• You fix a fact in one note, and three others still carry the old version.
• A note Claude wrote months ago reads as confidently as one you checked yesterday.

Claude Code's /rewind helps within a session, with limits the checkpointing docs spell out: it doesn't track files changed by shell commands (such as mv or rm), and it's "not a replacement for version control". For notes you keep for years, you want a review step that doesn't depend on the session.

Git is the baseline. It's free and works today: commit before a session, let Claude work, then read the diff and keep only what you approve.

$ git status --short           # what changed while Claude worked$ git diff --stat$ git diff projects/           # read the edits, folder by folder$ git add -p                   # keep what's right, hunk by hunk$ git commit -m "inbox triage, reviewed"$ git restore .                # discard the rest$ git clean -n                 # preview new files you didn't keep

A few habits make this fast:

• One task per session, one commit per task. A diff of 4 files is easy to read; a diff of 60 isn't.
• Read the list of changed files first. Anything outside the folder you asked about deserves a closer look.
• Check new facts against the note or link they cite. Uncited facts are the ones to question.
• If anything commits your vault on a timer, its commits will mix your edits with Claude's. Commit by hand around Claude sessions, or review with git log -p afterwards.

Git shows you a diff when you remember to commit. Knowtarium keeps the history next to the notes, which is the setup we recommend once Claude writes more than you want to read in a terminal. Your notes live in an end-to-end encrypted workspace as an OKF bundle: plain markdown whose frontmatter records who wrote each note, who checked it, where its claims came from and when it goes stale.

• Every change is signed and undoable. Claude's changes are saved at once and signed with its own key. A dot in the sidebar marks the notes it edited until you open them, a line under the title says when and links to the changes, and Undo brings back the version before. The history keeps every version for as long as you set, from a day to a year.
• Review is there when you want it. Turn on review ("Ask me first") for a workspace or a folder, and Claude's changes there wait as diffs for you to approve or reject. Your own edits there wait until you ask Claude to check them, for example "check today's edits", and Claude compares them with everything connected.
• Who wrote it, on every note. Who wrote a note sits at the top of it. In folders with review on, it also shows who checked it, the graph can colour notes by trust tier (unverified, machine-confirmed or human-reviewed), and a note is fully verified once both you and an agent have checked it after its last change.
• Nothing goes stale quietly. The Stale and expiring page lists notes past stale_after and those due soon.
• Claude works through MCP. Knowtarium doesn't call an AI itself. Claude Code connects with npx knowtarium connect and gets the conventions with its tools. We can't read your notes; Claude sees what it reads.

Knowtarium is free to start, with 500 MB of storage and one workspace, and Starter ($5.99 a month) and Pro ($11.99 a month) add storage and workspaces. Import an Obsidian vault into a workspace and it's converted to OKF with your writing left alone, and you can export everything as plain markdown whenever you like. See the migration guide, and the comparison page for how the two apps differ.

Nothing here is specific to Claude Code. Any agent that can read and write files in a folder can run your second brain. The main difference is the name of the instruction file:

• Codex reads AGENTS.md, from ~/.codex and from the folders between the git root and where you start it, up to a combined 32 KiB by default (Codex docs).
• Cursor reads AGENTS.md too, as a simpler alternative to its .cursor/rules files (Cursor docs).
• Claude Code reads AGENTS.md when there's no CLAUDE.md, on recent versions. The portable setup is to keep your rules in AGENTS.md and make CLAUDE.md a single line, @AGENTS.md, plus anything Claude-specific.

Then every agent follows the same vault rules, and the same review catches all of them, in git or in Knowtarium's history. Our guide to AGENTS.md for knowledge bases has a fuller template. If you're choosing an app to read the result, the AI second brain overview covers the wider picture, and Karpathy's LLM wiki idea file is worth reading for the wider pattern.