Appearance
Brain
The bridge between a repo and finns Obsidian second brain vault. It lets a session read back what the vault already knows – past decisions, code reviews, design – and file new notes back into it in the one consistent shape the vault needs to stay queryable. It is gated per repo by a .claude/brain-link.json file: no file and the skill is inert, so a repo has to opt in before anything reaches the vault. Passive by default – it consults and files only when asked – unless the link opts into active mode.
In Practice
Link a repo before the vault knows it exists. The skill checks for .claude/brain-link.json at the project root first. No file means it stays inert, tells you the repo is not linked, and points you at the one command that wires both ends:
/link-brainIt works out the vault path (default D:/documents/Obsidian/Brain) and the project name (default the repo folder name, lower kebab case), confirms the scope – read broad, write narrow – then writes .claude/brain-link.json here and creates the matching projects/<project>/ folder and a seeded home note in the vault. It refuses to clobber an existing config, and stops rather than guessing if the vault path does not exist.
Consult the vault on a settled question. Once the repo is linked, you ask what the record already holds:
what did we decide about the job system?The skill resolves the repo's read areas to their vault folders, greps and reads only those, and quotes the relevant adr, old review, or design back at you. It never touches the vault's .smart-env/ or smart plugin dirs – that is finns Obsidian ui, not ours – it searches by grep and read only.
File a decision back into the vault. A choice settles and you want it recorded so it does not get relitigated:
file this decision to the brainThe skill picks the note kind (adr), checks decisions is in the repo's write list, opens the matching template from the vault's templates/, fills the frontmatter, and writes it to projects/<project>/adr-<slug>.md. If the config does not grant that area it says so and stops rather than writing out of scope, then echoes back the path and frontmatter so you can veto or refile it.
An example outcome. You ask what was decided about the job system, and the skill quotes back the accepted adr you filed weeks earlier – the settled fork stays settled, and the reasoning is one question away instead of buried in an old chat.
Key Files
SKILL.md
The procedure – the gate check, the passive versus active split, and the read-back and file-back flows. It opens by looking for .claude/brain-link.json: no file and it declares the repo unlinked and stops, file present and it reads the vault path, project, read and write areas, and mode. Everything else is off until that gate passes.
brain-link.schema.md
The gate file shape – documents .claude/brain-link.json, the per repo opt-in that also scopes what the skill can reach. It carries the vault path (absolute and machine specific, which is why it lives in the repo not the skill), the project name, the read and write area lists, and the mode. Read broad, write narrow: a repo usually wants to see design and learning for context but only file decisions and reviews.
conventions.md
The filing rules – the folder map, the area-to-folder table, the naming scheme, and the frontmatter vocabulary. This is the authority when reading from or writing to the vault from another repo, and it must not drift from the vault's own CLAUDE.md; if they disagree, the vault copy wins.
link-brain.md
The /link-brain command – the one command that sets up both ends. It resolves the vault and project, refuses to clobber an existing brain-link.json, stops if the vault path does not exist rather than guessing, writes the config with mode: passive, and seeds the vault side. It keeps the project name identical on both ends or the area filters stop lining up.
The Gate and Its Modes
Nothing happens until .claude/brain-link.json exists. The file both opts the repo in and scopes it:
json
{
"vault": "D:/documents/Obsidian/Brain",
"project": "engine",
"read": ["decisions", "reviews", "design", "learning"],
"write": ["decisions", "reviews"],
"mode": "passive"
}The mode decides how far the skill reaches on its own:
passive– the default, and what a missing key means. The skill consults the vault and files to it only when finn asks. No detour into the vault before design or review, no filing unprompted; if a moment looks worth a brain trip it may say so in one line but does not act.active– the opt in. The skill also consults the vault on its own before design or review work, and offers to file a note when a decision, review, or design settles.
Areas and Folders
The read and write lists name areas, not folders. Each area resolves to a vault folder plus a filter, with <project> taken from the config:
| Area | Folder | Filter |
|---|---|---|
decisions | projects/<project>/ | type: adr |
design | projects/<project>/ | type: design |
project | projects/<project>/ | whole folder |
reviews | reviews/ | project: <project> |
retros | projects/<project>/ and uni/ | type: retro |
ideation | ideation/ | none |
learning | learning/ | none |
Every note carries frontmatter or it is invisible to the index pages. Two keys do the real work: status tracks the current state – an adr runs proposed to accepted to superseded – and outcome grades it once known (worked, mixed, failed, abandoned). An adr that later blows up gets outcome: failed without its status changing, and a reversal is a new adr referencing the old one, never a rewrite of a settled one. Consistency here is the whole game: a note filed the wrong way is invisible to the vault's index pages, so the filing rules are matched exactly or the vault stops working.
Connects to
- Shipped by the installer as a part, the skill and the
/link-braincommand – but the gate file is project owned, so the installer never ships or overwritesbrain-link.json;/link-brainscaffolds that itself. - The cross-repo counterpart to memory. A local gotcha you never want to repeat is a lesson in the in-repo memory layer; a project decision or code review you want to keep across repos is an adr or review filed to the shared vault. Brain is explicitly not for plain note taking inside the current repo.
- Ships no hook of its own, unlike safety or the hooks pack. It injects nothing and fires on no event – it is a skill gated by a file and triggered by asking, which is what keeps it passive by default.