🧠 Second Brain — an Obsidian vault as Claude's external memory

A Claude skill that turns an Obsidian vault into durable, token-efficient external memory — so context survives /compact, long sessions, and new chats. Every note is written twice: a rich human version and an ultra-condensed AI version with zero information loss.

English · Français

---

Table of contents

• Why this exists
• How it works
• The two registers
• Prerequisites
• Installation
• Usage
• Optimal setup
• Repository structure
• FAQ
• Contributing
• License & credits

---

Why this exists

Claude is brilliant within a conversation, but its context is finite. Long sessions get /compact-ed (summarized), new chats start blank, and hard-won decisions evaporate. The usual fix — pasting a giant context blob every time — is expensive and lossy.

Second Brain flips the model: your knowledge lives in an Obsidian vault on disk, and Claude treats it as durable memory it can read to bootstrap and write to never forget. Because the memory is external, after a /compact Claude just re-reads the relevant notes and rebuilds full context. Nothing is lost — as long as it was written down.

The twist: notes are stored in two twin registers.

• 🤖 AI/ — caveman style: telegraphic, symbol-dense, no filler. ~60–75 % fewer tokens. This is what Claude reads and writes. Cheap to load, cheap to keep current.
• 👤 human/ — rich, structured, pedagogical, with callouts and diagrams. This is what you read in Obsidian.

Both encode the same information set. The AI register compresses the wording, never the information — it is lossless by contract, not a summary.

Golden rule: an unrecorded change is a lost change.

---

How it works

flowchart TD
  subgraph Capture["🔵 Capture — same pass, both twins"]
    direction LR
    C[You + Claude<br/>establish a fact] --> AI["AI/ twin<br/>caveman · lossless"]
    C --> H["human/ twin<br/>rich · pedagogical"]
    AI <-. "twin: frontmatter" .-> H
  end
  AI ==>|"🟢 bootstrap — cheap"| K["Claude reads AI/ only<br/>(MOC → links → leaf)"]
  H -->|browse| U["You read human/<br/>in Obsidian"]
  K -. "survives /compact:<br/>re-read AI/ to rehydrate" .-> K

Loading

• Split per area. Each subject is a top-level folder that splits at its root into two 1:1 mirror trees: AI/ and human/. A note's twin is the same path with AI/ ↔ human/ swapped.
• Co-authored twins. On every capture, both versions are written in the same pass and cross-linked via frontmatter. Neither is auto-generated from the other.
• Progressive disclosure. A small Map of Content (MOC) routes Claude to the one note it needs — it loads links on demand instead of the whole vault.
• Shared meta. CLAUDE.md (imperatives) and 00-Meta/ (conventions, changelog) sit at the area root, shared by both trees.

Before / after (the same fact)

👤 human register	🤖 AI register
"Vaultwarden runs in LXC 101 (10.0.0.12:8000), self-signed HTTPS. The community-script update fails (cargo not found, Rust build); not in active use yet, migration from Bitwarden cloud planned, ideally to the official Docker image."	LXC 101 @ 10.0.0.12:8000 · self-signed HTTPS. ⚠️ community-script update ❌ (cargo not found) → not in active use. Migrate Bitwarden cloud → official Docker image.

Every value (101, IP, port, cargo not found, Docker) survives on both sides — only the connective tissue differs.

---

The two registers

	🤖 AI register	👤 Human register
Optimized for	tokens (read/write by Claude)	reading & understanding
Style	fragments, symbols → = ⚠️, no articles/copulas	prose, intro/why, callouts, tables, mermaid
Claude loads it at boot	✅ (only this side)	❌ (unless asked to edit prose)
Hard constraint	lossless — compress wording, never info	completeness — same info, elaborated
Full rules	ai-register.md	human-register.md

---

Prerequisites

• Claude Code (CLI, desktop, or IDE extension) — or any Claude surface that supports Agent Skills. The skill is plain markdown; no dependencies, no scripts to run.
• An Obsidian vault (recommended) — or honestly any folder of .md files. Obsidian is ideal because the skill leans on [[wikilinks]], the graph view, and backlinks, but nothing here is Obsidian-exclusive.
• (Recommended Obsidian setting) absolute path links — see Optimal setup.

---

Installation

1. Get the skill into ~/.claude/skills/

macOS / Linux

git clone https://github.com/hess0ul/second-brain.git
cp -r second-brain/second-brain ~/.claude/skills/second-brain

Windows (PowerShell)

git clone https://github.com/hess0ul/second-brain.git
Copy-Item -Recurse second-brain\second-brain $env:USERPROFILE\.claude\skills\second-brain

Want the French version of the skill instead? Copy second-brain/translations/fr/second-brain to ~/.claude/skills/second-brain. Install one language (both use the same skill name).

2. Verify

Start Claude Code and type /second-brain. The skill loads and is then active for the whole conversation. (You can also just mention it — the description is written to trigger on its own — but invoking it explicitly is the reliable way to load the full instructions.)

Advanced — keep the source in your vault (no drift)

The repo author runs the skill straight from their Obsidian vault, so editing the note edits the live skill. Point ~/.claude/skills/second-brain at the source with a symlink/junction:

# Windows — directory junction (no admin needed)
New-Item -ItemType Junction -Path "$env:USERPROFILE\.claude\skills\second-brain" `
  -Target "C:\path\to\your\vault\...\second-brain"

# macOS / Linux — symlink
ln -s /path/to/your/vault/.../second-brain ~/.claude/skills/second-brain

---

Usage

Your start-of-conversation ritual:

1. State your goal for the session.
2. Invoke /second-brain. Claude bootstraps the relevant area by reading the AI/ side only (MOC → rules → the few notes the task touches).
3. Work normally. As facts are established or change, Claude captures them into both twins in the same pass and ripples the indexes — no need to ask each time.
4. After a /compact, invoke /second-brain once more to reload the manual and re-hydrate from the vault.

Typical prompts that put it to work:

"We're setting up monitoring for my homelab. You have a brain at ~/Vaults/brain — use /second-brain to load the Homelab area, then help me, keeping the vault in sync."

"Start a new brain area called AI Watch to track models and papers I care about. Use /second-brain to scaffold it in dual-register."

---

Optimal setup

• Obsidian → Settings → Files & Links → New link format = Absolute path in vault. The skill uses absolute [[full/path/note|Alias]] links so Claude can navigate the graph unambiguously.
• One vault, many subjects. Each subject is a top-level folder. Start a subject in dual-register if a human will read it; mono-register (a single dense tree) is fine for Claude-only scratch areas.
• Let CLAUDE.md carry the imperatives. Claude Code auto-injects CLAUDE.md files; put your hard rules there and keep them dense (pairs well with the claude-md-management skills).
• Version the vault with git for history beyond the in-vault CHANGELOG.
• Don't fight the AI register. It will look terse — that's the point. The human twin is where readability lives.

---

Repository structure

.
├── README.md                         # you are here (English)
├── README.fr.md                      # French
├── LICENSE                           # MIT
├── CHANGELOG.md
├── second-brain/                     # ← the skill (English, canonical) — install this
│   ├── SKILL.md
│   └── references/
│       ├── ai-register.md            # caveman rules + lossless guarantee
│       ├── human-register.md         # rich/pedagogical rules
│       ├── conventions.md            # structure, links, frontmatter, density
│       ├── templates.md              # MOC, hub, twin leaf, CLAUDE.md, ADR, scaffold
│       └── bootstrap-compact.md      # read protocol + /compact recovery
└── translations/
    └── fr/second-brain/              # the skill (French) — same structure

---

FAQ

Does this require Obsidian? No — it writes plain .md. Obsidian just gives the best experience (graph, backlinks, link autocompletion). Any markdown editor works.

Is the AI version a summary? No. It's lossless by contract: it carries every fact, number, name, and decision the human version does — only the phrasing is stripped. A summary loses information; this doesn't.

Won't two copies drift? They're co-authored in the same pass and bound by a twin: frontmatter link, with a "parity" self-check. Updating one twin without the other is explicitly forbidden by the skill.

Does the skill stay active all conversation? Yes. Once /second-brain is invoked, its instructions stay in context. Reference files load on demand. After a /compact, invoke it again to reload cleanly.

Mono-register vs dual-register? Use dual-register when a human will read the notes. Use mono-register (one dense tree, no human/) for Claude-only working memory. The mode is recorded per area in 00-Meta/conventions.md.

Why "caveman"? The AI register is inspired by the caveman project's terse, fragment-based style — adapted here with a strict no-information-loss rule.

---

Contributing

Issues and PRs welcome — improvements to the register rules, templates, translations, or examples especially. Keep the AI register lossless and the human register readable; if you change one twin in an example, change the other.

---

License & credits

MIT © 2026 hess0ul.

• Inspired by JuliusBrussee/caveman for the terse AI writing style.
• Built for Claude Code Agent Skills.
• Conventions battle-tested on a real Obsidian homelab vault.