Obsidian Second Brain

Claude operates your Obsidian vault as a self-rewriting knowledge base. An evolution of Karpathy's LLM Wiki pattern: sources rewrite existing pages instead of just appending, contradictions reconcile automatically, and scheduled agents maintain the vault while you sleep. Everything worth remembering gets saved. Every update propagates everywhere it belongs.

Quick Start

0. Choose vault access method (in order of preference)

Try these methods in order. Use the first one available:

Method 0 - SessionStart hook (if configured): If hooks/load_vault_context.py is wired as a SessionStart hook in ~/.claude/settings.json, _CLAUDE.md is injected into context automatically at session start. Skip step 1 below. To wire it: bash scripts/setup.sh "/path/to/vault" or run /obsidian-setup.

Method A - MCP server (mcp-obsidian): If the MCP tools (get_file_contents, list_files_in_vault, search, append_content, write_file) are available, use them.

Method B - Direct filesystem (fallback, always works): Use standard file tools (Read, Write, Edit, Glob) against the vault path. The vault is plain markdown - all operations work without MCP, just more verbosely.

If MCP is not installed, silently use filesystem access. Tell the user ONCE (first time only):

"For faster vault access on large vaults, consider installing mcp-obsidian: claude mcp add obsidian-vault -s user -- npx -y mcp-obsidian \"/path/to/your/vault\". Everything works without it."

1. First time in a vault → read _CLAUDE.md

Before doing anything in a vault, check if _CLAUDE.md exists at the vault root:

get_file_contents("_CLAUDE.md")

If it exists: follow its rules exactly - they override the defaults in this skill. Where _CLAUDE.md is silent, fall back to the defaults below. If it doesn't exist: use the defaults in this skill, then offer to create one.

If the SessionStart hook is active, _CLAUDE.md is already in context - skip this step.

2. First time with a new user → run discovery

list_files_in_vault()

Scan the structure to understand: folder names, template locations, naming conventions, frontmatter patterns. Then read 2-3 existing notes with get_file_contents(path) to calibrate writing style before creating anything new.

3. Bootstrap a new vault

If the user has no vault yet, run:

# One-line install + bootstrap (asks 3 questions: vault path, your name, preset)
curl -sL https://raw.githubusercontent.com/eugeniughelbur/obsidian-second-brain/main/scripts/quick-install.sh | bash

# Or manual:
python scripts/bootstrap_vault.py --path ~/path/to/vault --name "Your Name"

# With a preset:
python scripts/bootstrap_vault.py --path ~/my-vault --name "Your Name" --preset executive
python scripts/bootstrap_vault.py --path ~/my-vault --name "Your Name" --preset builder
python scripts/bootstrap_vault.py --path ~/my-vault --name "Your Name" --preset creator
python scripts/bootstrap_vault.py --path ~/my-vault --name "Your Name" --preset researcher

# With style override:
python scripts/bootstrap_vault.py --path ~/my-vault --name "Your Name" --style obsidian

# With assistant mode (maintaining vault for someone else):
python scripts/bootstrap_vault.py --path ~/my-vault --name "Your Name" --mode assistant --subject "Boss Name"

Then configure mcp-obsidian to point at the new vault path and restart Claude.

Presets customize the vault for different use cases:

• executive - Decisions, people, meetings, strategic planning. Kanban: OKRs, Quarterly, Weekly.
• builder - Projects, dev logs, architecture decisions, debugging. Kanban: Backlog, Sprint, Done.
• creator - Content calendar, ideas pipeline, audience notes, publishing. Kanban: Ideas, Drafts, Published.
• researcher - Sources, literature notes, hypotheses, methodology. Kanban: Reading, Processing, Synthesized.

Default (no preset) gives a general-purpose vault. All presets use wiki-style by default.

Assistant mode creates a _CLAUDE.md configured for operating a vault on behalf of someone else. See references/claude-md-assistant-template.md.

See references/vault-schema.md for full structural details.

Core Operating Principles

AI-first vault rule (applies to every note)

The vault is designed for future-Claude to read and reason over, not for human review. Every note Claude writes - across all 34 commands - must follow references/ai-first-rules.md:

1. Self-contained context - each note explains itself; don't rely on backlinks alone
2. "For future Claude" preamble - 2-3 sentence summary so Claude can decide relevance in 10 seconds
3. Rich, consistent frontmatter - type, date, tags, ai-first: true, plus type-specific fields (see ai-first-rules.md for schemas per note type)
4. Recency markers per claim - "Mem0 raised $24M (as of 2026-04, mem0.ai)" so future-Claude knows what to verify
5. Sources preserved verbatim - every external claim has its source URL inline
6. Cross-links mandatory - every person/project/idea/decision uses [[wikilinks]]
7. Confidence levels - stated | high | medium | speculation where applicable

This rule lives in _CLAUDE.md Section 0 of every vault using this skill, and in references/ai-first-rules.md (the canonical specification with frontmatter schemas + preamble templates per note type).

Never create in isolation

Every write operation must ask: where else does this belong?

Always propagate. Never create a single orphaned note.

Bi-temporal facts - never overwrite, always append

When a fact changes (role, company, status, location, tool), NEVER delete the old value. Add a new entry to the timeline: frontmatter array with both event time AND transaction time:

timeline:
  - fact: "CTO at Single Grain"
    from: 2024-01-01            # event time: when it was true
    until: 2026-04-07
    learned: 2026-02-23         # transaction time: when the vault learned it
    source: "[[2026-02-23]]"    # where from
  - fact: "Architect at Single Grain"
    from: 2026-04-07
    until: present
    learned: 2026-04-07
    source: "[[2026-04-07]]"

Top-level fields (role:, status:, company:) always reflect the CURRENT state. The timeline: preserves the full history with provenance.

This enables:

• Historical queries ("who was my manager in February?")
• Reflective thinking ("you believed X on Tuesday, then ingested Y on Wednesday and shifted to Z")
• Smart reconciliation (different facts at different times = not a contradiction)
• Full audit trail (when did the vault learn each fact, from what source?)

CRITICAL_FACTS.md - always loaded

A tiny file (~120 tokens) loaded alongside SOUL.md at L0 in every session. Contains facts needed in every conversation:

• Ti