Eugeniughelbur Obsidian Second Brain Obsidian Second Brain

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 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 44 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:

• 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:

1. The answer - what the user sees in the conversation
2. 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 — (em dash).
• 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:

1. Identify the note type (decision → project note, person met → People/, task → board + Tasks/, etc.)
2. Check if a relevant note already exists
3. Write or update - always frontmatter-first
4. 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

Boards use the kanban-plugin: board frontmatter. Columns are ## Column Name headers. Items are - [ ] **Title** · @{due-date}\n\tDescription [[Links]] Completed items move to the ## ✅ Done column with a strikethrough: - [x] ~~**Title**~~ ✅ Date

Run vault health check

python scripts/vault_health.py --path ~/path/to/vault

Reports: duplicate notes, orphaned files (no incoming links), stale tasks (overdue), empty folders, broken links, notes missing frontmatter.

Proactively suggest running this when the user says the vault feels messy, notes are hard to find, they mention duplicates, or they haven't mentioned a health check in a long time. Offer: "Want me to run a vault health check?"

Commands

These slash commands can be used in any Claude surface. Each one is smart - it reads context, searches before writing, and propagates everywhere changes belong.

Name matching: If a name argument has a typo or is approximate, search the vault for the closest match, show what was found, and confirm with the user before proceeding. Never silently create a note with a misspelled name.

/obsidian-save

The master save command. Reads the entire conversation and extracts everything worth preserving.

Steps:

1. Scan the conversation and identify all vault-worthy items: decisions, tasks, people mentioned, projects started, ideas, learnings, deals, mentions/shoutouts
2. Group items by type: people, projects, tasks, decisions, ideas, deals
3. Spawn parallel subagents - one per group - so all note types are handled simultaneously:
   • People agent: search for each person, create or update notes, log interactions
   • Projects agent: search for each project, create or update notes
   • Tasks agent: parse tasks, add to the right kanban columns
   • Decisions agent: find relevant project notes, append to Key Decisions sections
   • Ideas agent: search Ideas/ for related notes, create or append
4. After all agents complete: update today's daily note with links to everything saved
5. Report back: a clean list of what was saved and where

Do not ask for guidance on where to save things - infer it. Only ask if something is genuinely ambiguous (e.g. a person mentioned with no context on who they are).

/obsidian-daily

Creates or updates today's daily note.

Steps:

1. Check if Daily/YYYY-MM-DD.md exists for today
2. If not: read Templates/Daily Note.md, fill in date fields, create the file
3. Scan the current conversation for anything relevant to today: tasks in progress, people mentioned, decisions made, what's being worked on
4. Pre-fill or update the note's sections with that context
5. If the note already exists, inject new content into the right sections rather than overwriting

Return the path of the daily note when done.

/obsidian-calendar <mode>

One calendar command with four modes. Claude Code only (needs the Google Calendar MCP). The first word selects the mode; a bare range word defaults to agenda; no argument at all defaults to agenda today.

• agenda [range] - reads the calendar and writes a re-derivable AI-first snapshot to wiki/agenda/ (type: agenda-snapshot). Range: today, tomorrow, week, next-week, a date, or a range. Cross-links attendees to [[Person]] notes; flags conflicts, 3+ back-to-back stretches, working-hours focus blocks, and externally-organized events. Read-only on the calendar; Google Calendar stays the source of truth.
• reconcile [window] - flags commitments the vault implies (project next_actions, due tasks, dated commitments in daily notes, fixed dates in CRITICAL_FACTS.md) that are NOT on the calendar, plus events with no vault context. Flag only - never adds or changes events.
• meeting [selector] - turns an event (last, next, today, event-id:<id>, or fuzzy title) into a type: meeting note in wiki/meetings/ with metadata pre-filled and empty Notes / Decisions / Action items sections (never fabricate meeting content). Cross-links attendees, backlinks any task whose calendar-event-id matches.
• schedule <args> - the only mode that writes to the calendar. Standalone ("<title>" <when> <duration>), from a task (task:<path>), or suggest-a-time (task:<...> suggest:<window>). Resolves attendee emails from person notes (never guesses), conflict-checks before writing, requests a Meet link when participants span domains, and writes calendar-event-id back into the task so a re-run reschedules rather than duplicating.

(Consolidated from the former /obsidian-agenda, /obsidian-reconcile-style calendar check, /obsidian-meeting, and /obsidian-schedule - same behaviors, one entry point. The natural-language triggers for all four still route here.)

/obsidian-recurring

Tracks a recurring obligation (payment, filing, ops) with a cadence and a computed next-due date.

State the obligation and cadence (e.g. "pay social benefits, monthly day 20"). Searches for an existing note first, then builds a type: recurring-task note with What / Cadence / Blockers / History sections and frontmatter (cadence, owner, blocker, next-due, optional amount). Adds a board card for the next occurrence; on each completion, appends a History row and advances next-due. Fills the gap that /obsidian-task (one-shot) leaves.

/obsidian-calendar

Reconciles the vault against your calendar - flags commitments implied by notes that are not scheduled. Claude Code only (needs the Google Calendar MCP).

Window argument (today / this week / this month, default this week). Pulls the calendar, then gathers vault-implied commitments by listing and grepping (project next_actions and deadlines, due tasks, commitments in recent daily notes, fixed dates in CRITICAL_FACTS.md), and reports the gap in two directions. Flag only - never adds, moves, or changes calendar events. The inverse of /obsidian-daily's calendar pull.

/obsidian-log

Logs a work or dev session to the vault.

Steps:

1. Infer the project from conversation context - search the vault if needed to find the right project note
2. Read Templates/Dev Log.md (or Templates/Work Log.md if it exists)
3. Fill in: date, project, what was worked on, problems encountered, decisions made, next steps - all inferred from the conversation
4. Save to Dev Logs/YYYY-MM-DD — Project Name.md
5. Inject a link into the project note's Recent Activity section
6. Inject a link into today's daily note Work section

/obsidian-task [description]

Adds a task to the vault and the right kanban board.

Steps:

1. Parse the task from the argument or from recent conversation context if no argument given
2. Infer: priority (🔴/🟡/🟢), due date, linked project, linked person
3. Search for the right kanban board - use _CLAUDE.md board list or search Boards/
4. Add the task card to the correct column (📋 This Week or 📥 Backlog depending on due date)
5. Create a task note in Tasks/ if the task is substantial (more than a one-liner)
6. Link the task from the relevant project note and today's daily note

/obsidian-person [name]

Creates or updates a person note.

Steps:

1. Search the vault for an existing note matching the name (fuzzy - handle typos and partial names)
2. If found: confirm with user, then update with new info from conversation
3. If not found: create People/Full Name.md with full frontmatter schema
4. Fill in everything inferable from the conversation: role, company, context, relationship strength, last interaction date
5. Log the interaction in today's daily note
6. If a People index file exists, add or update the entry there

/obsidian-decide [optional: topic]

Extracts and logs decisions from the conversation.

Steps:

1. Scan the conversation for decisions made - look for conclusions, choices, commitments, direction changes
2. If a topic argument is given, focus on decisions related to that topic
3. Find the relevant project note(s) - search if needed
4. Append each decision to the project note's ## Key Decisions section with date
5. Log a summary in today's daily note
6. If a decision affects multiple projects, log it in all of them

/obsidian-capture [optional: idea text]

Quick idea capture with zero friction.

Steps:

1. Take the argument as the idea, or pull the most recent idea/thought from the conversation
2. Search Ideas/ for a related existing note - if found, append to it
3. If new: create Ideas/Title.md with minimal frontmatter (date, tags: [idea])
4. Write the idea with any supporting context from the conversation
5. Add a brief mention in today's daily note under an Ideas or Captures section

/obsidian-catchup [today|week|all]

Process what the Telegram journal bot captured on the go. The laptop-side companion to the integrations/telegram-journal/ bot, which captures voice/text/image/PDF/link from your phone and appends each to a catchup.md queue in the vault.

Steps:

1. Read catchup.md in the vault root - each unchecked - [ ] line is an unprocessed capture (date time | kind | summary | -> where).
2. Collect the unchecked items, applying the timeframe filter (today / week / all, default all). If none, say so and stop.
3. Show them grouped by age (Today / This week / Older), flagging stale ones.
4. Process WITH the user (not autonomously): open each linked note, propose integrate (fold into the right note per the AI-first rule) / keep / discard, confirm, then write.
5. Check the item off (- [x] + processed date); never delete queue history.

Pull, not push: nothing is processed until you run this, so nothing surprises you. The phone is for fast dumb capture; this is where it becomes integrated knowledge.

/obsidian-find [query]

Smart vault search.

Steps:

1. Run search(query="...") with the provided query
2. Also try variations if results are sparse (synonyms, related terms)
3. Return results with context: note title, folder, a relevant excerpt, and what type of note it is
4. If results are ambiguous, group them by type (people, projects, tasks, etc.)
5. Offer to open, update, or link any of the found notes

Do not just return filenames - return enough context for the user to act.

/obsidian-recap [today|week|month]

Summarizes a time period from the vault.

Steps:

1. Determine the date range from the argument (default: week if not specified)
2. List all daily notes in the range with list_files_in_dir("Daily/")
3. Spawn parallel subagents - one per daily note - to read and extract key points from each simultaneously
4. Also spawn parallel agents to read dev logs and completed kanban tasks from the same period
5. Synthesize all agent results: what was worked on, decisions made, people interacted with, tasks completed, ideas captured
6. Present as a clean narrative summary - not a raw dump of note content

/obsidian-review

Generates a structured weekly or monthly review note.

Steps:

1. Ask: weekly or monthly? (or infer from context)
2. Read daily notes and dev logs for the period
3. Read active projects and check for status changes
4. Read completed tasks from kanban boards
5. Draft a review note using Templates/Review.md if it exists, otherwise use a standard structure:
   • What I accomplished
   • Key decisions made
   • People I worked with
   • What I learned
   • What to carry forward
6. Save to Reviews/YYYY-MM-DD — Weekly Review.md (or Monthly)
7. Link from the last daily note of the period

/obsidian-board [optional: board name]

Shows or updates a kanban board.

Steps:

1. If a board name is given, search Boards/ for it (fuzzy match)
2. If no name given, list available boards and ask which one
3. Read and display the current board state: columns, item counts, overdue items (past @{date})
4. Ask if the user wants to make updates - if yes, infer changes from conversation context
5. Move completed items to ✅ Done with strikethrough, add new items in the right column
6. Flag any items that are overdue or have been in the same column for more than a week

/obsidian-board-hygiene [optional: board name]

Bulk-triages a kanban board whose columns have gone stale. Where /obsidian-board only flags overdue items, this clears them.

Steps:

1. Read _CLAUDE.md for the boards folder and kanban convention (columns, @{date} format)
2. Read the target board (fuzzy-match; if none given, list boards and ask), parse every open item, compute age vs today
3. Group items into overdue (@{date} past), stale (older than N days, default 14), and undated; show counts per column so the bloat is visible
4. Propose ONE verdict per stale/overdue item with a one-line reason - done / reschedule / archive / keep - as a batch the user approves, edits, or overrides
5. Apply approved verdicts in place (additive moves + strikethrough, never silent deletion), then report what moved and log it

/obsidian-project [name]

Creates or updates a project note.

Steps:

1. Search the vault for an existing project matching the name (fuzzy - handle typos)
2. If found: show what was found, confirm, then update with new info from conversation
3. If not found: create Projects/Project Name.md with full frontmatter schema (date, tags: [project], status: active, job)
4. Fill in everything inferable from the conversation: description, goals, key people, current status
5. Add a card to the relevant kanban board in the 📥 Backlog or 🔨 In Progress column
6. Link from today's daily note

/obsidian-projects [optional: project name]

Live status overview across all tracked projects.

Reads _CLAUDE.md for the projects folder, then scans it for notes with type: project or a repo: field. For each project, spawns a parallel subagent that runs three checks: reads the vault note (status, last activity, next action, blockers), runs git log and git status if a repo: path is set, and looks for NOTES.md / TODO.md in the repo root. Merges the three into one status block (active / stalled / idle / blocked / archived inferred from activity recency), prints the full overview to the conversation ordered active-first, then injects a ## Last overview section into each project note.

If a project name argument is given, shows deep context for that one project only.

/obsidian-health

Runs a vault health check and summarizes findings.

Steps:

1. Run: python scripts/vault_health.py --path ~/path/to/vault --json
2. Parse the JSON output and split findings into categories
3. Spawn parallel subagents to handle each category simultaneously:
   • Links agent: verify broken links, attempt to resolve them
   • Duplicates agent: confirm duplicates are truly the same concept, not just similar names
   • Frontmatter agent: identify notes missing required fields by type
   • Staleness agent: check overdue tasks and unfilled template syntax
   • Orphans agent: check orphaned notes and empty folders
   • Contradictions agent: scan Key Decisions and Knowledge/ for claims that conflict or are superseded
   • Concept gaps agent: find terms mentioned 3+ times without a dedicated page
   • Stale claims agent: flag Knowledge/ notes older than 6 months on fast-moving topics
4. Merge agent results and group by severity:
   • 🔴 Critical: broken links, unfilled template syntax, contradictions
   • 🟡 Warning: duplicates, stale tasks, missing frontmatter, stale claims, concept gaps
   • ⚪ Info: orphaned notes, empty folders
5. Present a clean summary with counts per category
6. For safe fixes (missing frontmatter, obvious duplicates, creating pages for concept gaps), offer to fix them automatically
7. For destructive fixes (archiving, merging, resolving contradictions), list them and ask for explicit confirmation before touching anything
8. Append to log.md with severity counts

/obsidian-retrieval-eval [optional: N to generate | report]

Measures how well vault search actually finds the right note - so improving retrieval is a number, not a hunch.

Hybrid command backed by scripts/eval/retrieval_eval.py, which reuses the REAL search engine (integrations/obsidian-mcp-server/vault_ops.py, the term-frequency, title-weighted ranking behind /obsidian-find and the MCP connector). It bootstraps its own eval set from the vault (an LLM writes a question per sampled note, avoiding the note's title words so it tests retrieval not string-match; the note is the gold answer), then scores recall@1/3/5/10 and MRR and lists the failures - misses and notes buried below #3, naming which note wrongly ranked #1. Claude interprets the numbers, turns failures into ranked retrieval fixes (each a hypothesis to re-measure on the same cases), and optionally writes an AI-first baseline note. Generated cases hold private note paths and are gitignored. The first run on a 1,000+ note vault scored 0% recall@10 on paraphrased questions (long raw/ transcripts and log.md dominate term-frequency ranking) - proving the cheap structural fixes (exclude raw/, weight by type:) should be measured before reaching for a vector index.

/obsidian-reconcile

Finds and resolves contradictions across the vault.

Steps:

1. Read index.md to understand the full vault landscape
2. Spawn parallel subagents to find contradictions:
   • Claims agent: scan wiki/concepts/ and wiki/projects/ for conflicting factual claims
   • Entity agent: scan wiki/entities/ for outdated roles, companies, or descriptions
   • Decisions agent: scan wiki/decisions/ for reversed or superseded decisions never updated
   • Source freshness agent: compare raw/ dates against wiki/ pages for stale references
3. For each contradiction, evaluate: which is newer, which is more authoritative, is it a genuine conflict or an evolution
4. Resolve:
   • Clear winner: rewrite the outdated page, add a History section noting what changed
   • Ambiguous: create wiki/decisions/Conflict — Topic.md with both sides, mark status: open
   • Evolution: update the page to current state with historical context
5. Rebuild affected index.md sections, append to log.md, update daily note

/obsidian-synthesize

Automatic synthesis - the vault thinks for itself.

Can run manually or as a scheduled agent. Scans the vault for patterns nobody asked about.

Steps:

1. Read index.md and log.md (last 20 entries) for recent activity
2. Spawn parallel subagents:
   • Cross-source agent: find concepts appearing in 2+ unrelated sources from the last 7 days
   • Entity convergence agent: find people who appear together in multiple contexts but have no connection page
   • Concept evolution agent: find concepts updated 3+ times and document how thinking changed
   • Orphan rescue agent: find unlinked notes that should be connected to existing pages
3. For each pattern: create wiki/concepts/Synthesis — Title.md with evidence, interpretation, and suggested action
4. Link synthesis pages FROM all source notes they reference
5. Update index.md, log.md, and today's daily note

/obsidian-export

Export a clean snapshot any agent or tool can consume.

Steps:

1. Scan all notes in wiki/ and extract: path, title, type, date, status, summary, links, tags, frontmatter
2. Output as JSON (default) to _export/vault-snapshot.json or markdown to _export/vault-snapshot.md
3. The snapshot is a flat, structured representation of the vault - no folder structure knowledge needed
4. Any AI tool, automation, or agent can read this file and understand the vault
5. Append to log.md

/obsidian-init

Bootstraps _CLAUDE.md for the vault - the operating manual.

Steps:

1. Call list_files_in_vault() to map the full structure
2. Spawn parallel subagents to discover vault context simultaneously:
   • Dashboard agent: read Home.md or equivalent dashboard
   • Templates agent: read all files in Templates/
   • Boards agent: read all files in Boards/
   • Samples agent: read one existing note per major folder to capture naming conventions and frontmatter patterns
3. Merge all agent results into a complete picture of the vault
4. Generate a complete _CLAUDE.md using the template in references/claude-md-template.md, filled with real values from the vault
5. Write it to _CLAUDE.md at the vault root via append_content("_CLAUDE.md", content)
6. Confirm what was written and tell the user to restart their Claude session so the new file takes effect

If _CLAUDE.md already exists: show a diff of what would change and ask before overwriting.

/obsidian-architect

Scans a codebase and writes a maintained set of architecture notes into the vault - overview, per-module notes, key decisions. Re-runnable.

Hybrid command: scripts/architect_scan.py does a deterministic scan (stack, modules, dependencies, entry points, git commit) and emits JSON; Claude synthesizes the prose, rationale, a Mermaid diagram, and likely personas, then writes AI-first notes under Projects/<name>/Architecture/ (type: architecture-overview + type: architecture-module). Pulls decision candidates from scripts/mine_commit_decisions.py. Refresh is the same command re-run: it uses sentinel markers (<!-- @generated --> / <!-- @user -->, see references/write-rules.md) so re-running updates only the generated blocks and never clobbers your hand-edits. For builders who want their code projects documented in the same brain as their ideas and decisions.

/obsidian-ingest

Ingests a source into the vault - one source touches many pages.

Steps:

1. Accept a URL, file path, or pasted text as the source
2. Classify the source type before full read: article, PDF, transcript, video, or raw text
3. Read or fetch the full source content
4. Extract: entities (people, companies, tools), concepts, claims, action items, notable quotes
5. Save the raw source to Knowledge/YYYY-MM-DD — Source Title.md with full summary and source link
6. Spawn parallel subagents to distribute knowledge across the vault:
   • People agent: create or update People/ notes for each person mentioned
   • Projects agent: update existing project notes with new findings
   • Ideas agent: create or append to Ideas/ for new concepts
   • Knowledge agent: create or update Knowledge/ notes for factual claims and frameworks
7. Update index.md with all newly created notes
8. Append to log.md: ## [YYYY-MM-DD] ingest | Source Title (type) — X created, Y updated
9. Update today's daily note with an ingest summary

A single ingest should touch 5-15 files. Compile knowledge once, distribute everywhere.

Thinking Tools

These commands use the vault as a thinking partner - not just storage. They surface insights, challenge assumptions, and generate connections that the user cannot see on their own.

/obsidian-challenge

Red-teams your current idea against your own vault history.

Steps:

1. Identify the user's current claim, plan, or assumption - from the argument or conversation context
2. Extract the key premises behind that position
3. Spawn parallel subagents to search for counter-evidence:
   • Decisions agent: search Key Decis

…(truncated)