Obsidian Second Brain

Source documentation, not instructions for this website. Review permissions before running any commands.

Read <vault>/_CLAUDE.md

Glob <vault>/**/*.md

# 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 assistant mode (maintaining vault for someone else):
python scripts/bootstrap_vault.py --path ~/my-vault --name "Your Name" --mode assistant --subject "Boss Name"

timeline:
  - fact: "CTO at Currentscale Labs"
    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 Currentscale Labs"
    from: 2026-04-07
    until: present
    learned: 2026-04-07
    source: "[[2026-04-07]]"

name: obsidian-second-brain
description: >
  Operate any Obsidian vault as a living, self-rewriting second brain (an evolution
  of Karpathy's LLM Wiki pattern: sources rewrite existing pages, contradictions
  reconcile automatically, scheduled agents maintain the vault while you sleep).
  Use this skill whenever
  the user asks Claude to read, write, update, search, or manage their Obsidian
  vault - including saving notes from conversation, creating daily entries, updating
  kanban boards, logging dev work, managing people notes, capturing decisions,
  tracking deals, or maintaining any vault structure. Also triggers when the user
  wants to bootstrap a new vault from scratch, run a vault health check, or drop
  a _CLAUDE.md into their vault so all Claude surfaces share the same operating rules.
  Includes a research toolkit (7 commands: /x-read, /x-pulse, /research, /research-deep,
  /notebooklm, /youtube, /podcast) for AI-powered research via Grok, Perplexity, NotebookLM,
  YouTube, and podcast feeds - findings save
  to the vault automatically following the AI-first vault rule. Use proactively whenever
  the conversation produces information worth preserving (decisions, people met, projects
  started, tasks completed, lessons learned, research findings).

---
name: obsidian-second-brain
description: >
  Operate any Obsidian vault as a living, self-rewriting second brain (an evolution
  of Karpathy's LLM Wiki pattern: sources rewrite existing pages, contradictions
  reconcile automatically, scheduled agents maintain the vault while you sleep).
  Use this skill whenever
  the user asks Claude to read, write, update, search, or manage their Obsidian
  vault - including saving notes from conversation, creating daily entries, updating
  kanban boards, logging dev work, managing people notes, capturing decisions,
  tracking deals, or maintaining any vault structure. Also triggers when the user
  wants to bootstrap a new vault from scratch, run a vault health check, or drop
  a _CLAUDE.md into their vault so all Claude surfaces share the same operating rules.
  Includes a research toolkit (7 commands: /x-read, /x-pulse, /research, /research-deep,
  /notebooklm, /youtube, /podcast) for AI-powered research via Grok, Perplexity, NotebookLM,
  YouTube, and podcast feeds - findings save
  to the vault automatically following the AI-first vault rule. Use proactively whenever
  the conversation produces information worth preserving (decisions, people met, projects
  started, tasks completed, lessons learned, research findings).
---

# Obsidian Second Brain

> Claude operates your Obsidian vault as a self-rewriting knowledge base. An evolution of [Karpathy's LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f): 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 - Direct filesystem (default, always works):**
Use standard file tools (Read, Write, Edit, Glob) against the vault path. The vault is plain markdown, so every operation in this skill works this way with no setup. This is the normal path in Claude Code - the commands below use these tools directly.

**Method B - MCP server (optional, mainly for non-Claude-Code clients):**
This repo ships its own MCP server at `integrations/obsidian-mcp-server/` that exposes the vault as tools (`obsidian_search`, `obsidian_read_note`, `obsidian_save_note`, `obsidian_capture`, plus curator tools). It exists so other MCP clients - Hermes Agent, Claude Desktop, Cursor - can use the vault as a knowledge layer; in Claude Code itself, Method A is simpler and preferred. If those `obsidian_*` tools happen to be available in your client, you may use them instead of raw file tools. Setup lives in `integrations/obsidian-mcp-server/README.md` (it is `uv run --no-project --with 'mcp<2' python .../server.py` with `OBSIDIAN_VAULT_PATH` set, not an `npx` package).

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

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

```
Read <vault>/_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

```
Glob <vault>/**/*.md
```

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

### 3. Bootstrap a new vault

If the user has no vault yet, run:
```bash
# 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 assistant mode (maintaining vault for someone else):
python scripts/bootstrap_vault.py --path ~/my-vault --name "Your Name" --mode assistant --subject "Boss Name"
```

Then just point the skill at the new vault path (Method A above). If you use the optional bundled MCP server, set `OBSIDIAN_VAULT_PATH` to the new path and restart the client.

**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 agent** to read and reason over, not for human review. Every note Claude writes - across all 46 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 agent" preamble** - 2-3 sentence summary so any compatible agent 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 agent 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). That path is relative to the install root, which is load-bearing: if it does not resolve from your working directory, search upward for it, and if you still cannot read it, say so before writing rather than producing a note that silently skips the rule. The seven requirements above are the floor and apply whether or not the spec is reachable.

### Never create in isolation
Every write operation must ask: *where else does this belong?*

| You create/update... | Also update... |
|---|---|
| A new project note | Kanban board (add to Backlog), today's daily note (link it) |
| A task completed | Kanban board (move to Done), project note (log it), daily note |
| A person note | Daily note (mention interaction), People index if it exists |
| A dev log | Daily note (link it), project note (Recent Activity) |
| A deal update | Side Biz / Deals kanban, Dashboard totals |
| A decision made | Project note (Key Decisions), daily note |
| A mention/shoutout | Mentions Log, person's note, daily note |
| A hook, contrarian angle, or content idea | `social-media/ideas.md` (if folder exists) |
| A specific reusable number or stat | `social-media/data-points.md` (if folder exists) |
| An external post that performed well + why | `social-media/swipe-file.md` (if folder exists) |
| Research findings worth keeping | `social-media/research/YYYY-MM-DD - topic.md` (if folder exists) |
| Any vault write | operation log (`Logs/YYYY-MM-DD.md` if `Logs/` exists, else `log.md`), `index.md` (update if new note created) |

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:

```yaml
timeline:
  - fact: "CTO at Currentscale Labs"
    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 Currentscale Labs"
    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:
- Timezone
- Current manager
- Current location
- Current company and role
- Any other fact that's true RIGHT NOW and relevant to every interaction

Update this file whenever a critical fact changes. Keep it under 150 tokens.

### Raw is immutable
In wiki-style vaults, the `raw/` folder contains original sources (articles, transcripts, PDFs). Claude reads these but NEVER modifies them. They are the source of truth. If a wiki page gets corrupted, re-derive it from the raw source. When ingesting, always save the original to `raw/` and the derived pages to `wiki/`.

### Maintain `index.md` and `log.md`
Two structural files that keep the vault navigable and auditable:

- **`index.md`** - A catalog of all vault pages organized by category. Claude reads this FIRST when navigating the vault instead of searching - faster and cheaper on tokens. Update it whenever a new note is created or deleted. Format: `- [[Note Name]] - brief description` grouped under folder headings.

- **`log.md`** - An append-only chronological log of every vault operation. Every save, ingest, health check, and structural change gets a timestamped entry. Never delete or rewrite entries - only append. Format: `## [YYYY-MM-DD] action | Description`

### Per-day operation logs (modernized vaults)
Vaults initialized with `/obsidian-init` (v0.9+) use a split log structure instead of a monolithic `log.md`:

- **`Logs/YYYY-MM-DD.md`** - one file per day, append-only. Format: `**HH:MM** - action | description`
- **`log.md` at vault root** - pointer file only. Never write entries here; it explains the per-day structure and ships the entry template.

To migrate an existing monolithic `log.md`: run `python scripts/migrate_log.py --vault <path>`.
To refresh the stats block in `index.md` after bulk writes: run `python scripts/vault_stats.py --vault <path>`.

When writing operation log entries, check whether the vault uses the old (`log.md`) or new (`Logs/YYYY-MM-DD.md`) structure and write to the correct location.

### The vault is a