obsidian-second-brain

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 : 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). Since the bookkeeping change, every write through the server also validates the note, adds the index entry, appends the operation-log line, and runs OBSIDIAN_POST_WRITE_CMD when set - see integrations/obsidian-mcp-server/README.md , "Bookkeeping after writes". 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: # 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 : Self-contained context - each note explains itself; don't rely on backlinks alone "For future agent" preamble - 2-3 sentence summary so any compatible agent can decide relevance in 10 seconds Rich, consistent frontmatter - type , date , tags , ai-first: true , plus type-specific fields (see ai-first-rules.md for schemas per note type) Recency markers per claim - "Mem0 raised $24M (as of 2026-04, mem0.ai)" so future agent knows what to verify Sources preserved verbatim - every external claim has its source URL inline Cross-links mandatory - every person/project/idea/decision uses [[wikilinks]] 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: 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 living system The vault is not a filing cabinet. It is a living knowledge base that rewrites itself with every input. When new information enters: Existing pages get REWRITTEN with new context, not just appended to Contradictions between old and new claims get resolved or explicitly documented New patterns across multiple sources trigger automatic synthesis pages Stale claims get replaced with current information, with history preserved The vault after an ingest should be DIFFERENT - not just bigger. If pages that existed before aren't smarter, more connected, and more current, the ingest wasn't deep enough. Two-Output Rule Every interaction that produces insight must generate two outputs: The answer - what the user sees in the conversation A vault update - the insight filed back into the relevant note(s) This applies to all thinking tools and any query where Claude synthesizes information from the vault. Synthesis Hook When Claude notices a pattern during any operation (ingest, query, challenge, emerge), it should automatically create a synthesis page in wiki/concepts/ . Patterns include: The same concept appearing in 3+ unrelated sources A claim being reinforced by multiple independent sources A trend emerging across time-sequenced notes Two entities sharing unexpected connections Synthesis pages are the vault thinking for itself - connecting dots the user hasn't connected yet. Reconciliation The vault should never contain two pages that disagree without knowing they disagree. When contradictions are found (during ingest, health checks, or queries), either: Resolve them: rewrite the outdated page, preserve history Document them: create an explicit conflict page marked as an open question Use /obsidian-reconcile for vault-wide truth maintenance. Proactive save reminders Unsaved conversations are lost knowledge. Claude should proactively remind the user to save: After 10+ exchanges: suggest "Want me to run /obsidian-save before we continue?" When the user signals wrap-up (e.g., "ok", "thanks", "done", "bye", "that's it"): suggest "Before you go - want me to /obsidian-save this conversation?" When a logical work block completes (feature shipped, decision made, problem solved): suggest saving Never skip the reminder. This is especially critical on Claude Desktop where there's no background agent. Search before creating Before creating any new note, search for an existing one: search(query="keyword from title") Duplicate notes are vault rot. Merge or update instead of creating new. Never claim absence from memory, never fabricate Two failure modes corrupt the vault silently: False absence (most common): never say "no note exists" or create a note on the assumption none exists without searching exhaustively first - by every plausible name, alias, and folder, listing and grepping, not from memory. When in doubt, over-include and label the uncertainty. Fabrication: never invent facts, entities, rates, dates, or relationships that were not actually stated. Mark unknowns as TBD ; an empty section is correct when nothing was said. External claims carry a source URL + recency marker; inferences carry a confidence level. See the anti-fabrication and search-completeness hard rules in references/ai-first-rules.md . Match the vault's voice Read existing notes in the same folder before writing new ones. Match: frontmatter schema, heading style, list formatting, tone, emoji usage (or lack of it). Never introduce new conventions - extend what's already there. Frontmatter is mandatory Every note gets frontmatter. At minimum: --- date: 2026-03-24 tags: - <note-type> --- See references/vault-schema.md for full frontmatter specs by note type. Write Rules See references/write-rules.md for the complete guide. Summary: Links : Use [[Note Name]] for internal links. Always link to people, projects, and jobs mentioned in a note. Dates : ISO format ( YYYY-MM-DD ) in frontmatter. Human format ( March 24 ) in body text. Naming : YYYY-MM-DD - Title.md for dated notes. Title.md for evergreen notes. No special characters except the ASCII hyphen - . Never an em dash (U+2014) or en dash (U+2013) in a filename: link matching compares stems literally, so 2026-07-26 - Title.md will not resolve a [[2026-07-26 - Title]] link, producing an orphan and a dangling link in the same write. The write-time validator checks file CONTENT, not filenames, so nothing catches this for you. Status values : active / planning / completed / archived / on-hold for projects. in-progress / done / waiting for tasks. Kanban : Items follow the format - [ ] 🔴 **Title** · @{YYYY-MM-DD}\n\tDescription [[Link]] The _CLAUDE.md File This is the most important concept in this skill. _CLAUDE.md lives at the vault root and persists Claude's operating rules across every session and every surface (Claude Desktop, Claude Code, VS Code, terminal). Without it, Claude has to re-learn your vault conventions every conversation. Precedence rule: _CLAUDE.md wins on all vault-specific rules (folder names, naming conventions, frontmatter fields, auto-save behavior, private folders). The defaults in this skill file apply only where _CLAUDE.md is silent. Never let skill defaults override an explicit _CLAUDE.md rule. What it contains: Your vault's folder map and what each folder is for Frontmatter schemas for your specific note types Naming conventions you use What to auto-save vs. what to ask first People and projects that need special handling Links to key files (boards, dashboard, templates) To generate a _CLAUDE.md for an existing vault, run vault discovery then use the template in references/claude-md-template.md . To install it: write the file to the vault root. Every Claude session that starts in that vault should read it first. Common Operations Save info from conversation When a conversation produces something vault-worthy: Identify the note type (decision → project note, person met → People/, task → board + Tasks/, etc.) Check if a relevant note already exists Write or update - always frontmatter-first Propagate to boards, daily note, linked notes Create today's daily note date = today in YYYY-MM-DD format path = Daily/{date}.md Read Templates/Daily Note.md , fill in the date fields, create the file. Then scan recent conversation for anything worth logging in today's sections. Log a dev session Read Templates/Dev Log.md . Fill: date, project name, what was worked on, problems solved, decisions made, next steps. Save to Dev Logs/YYYY-MM-DD - Project Name.md . Link from project note's Recent Activity section and today's daily note. Update a kanban board