快速判断

01这个 Skill 是干嘛的: 用命令、研究工具和维护规则把 Obsidian 变成可持续的 AI 知识工作台。
02它能解决什么问题: 解决笔记只积累不连接、信息过期、检索困难和研究结果无法回流的问题。
03它适合谁来用: 适合愿意让 Agent 深度参与 Obsidian 捕获、研究、整理和维护的知识工作者。

obsidian-second-brain

用 Obsidian 建立可持续的个人知识整理、连接与写作流程。

主要能力

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).

使用方式

仓库级安装会保留完整目录；本次核验的入口是 SKILL.md。使用前先阅读英文 README 与原始 SKILL.md，并按当前 Agent 的目录规范安装。

适用边界

仓库结构带有作者个人方法偏好，不宜未经筛选整体照搬。

许可与来源

来源：GitHub 公开仓库。核验许可：MIT。本页是贴近原仓库结构的中文导读，具体参数、依赖和更新记录以英文 README 为准。

One codebase. Six CLIs. Same brain.

<h1 align="center">obsidian-second-brain</h1>

An evolution of <a href="https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f">Karpathy's LLM Wiki pattern</a>: a vault that rewrites itself. Every source updates existing pages instead of just appending new ones. Contradictions reconcile automatically. Your vault compounds while you sleep. Powered by <a href="references/freshness-policy.md">OKM - Open Knowledge Metabolism</a>: every stored fact is timeless, dated, or a pointer - so your knowledge base never fills with facts that used to be true. 44 commands · auto-synthesis · thinking tools that argue with you live research from X, the web, and YouTube · 4 scheduled agents · 4 role presets write-time AI-first validator · <code>/create-command</code> interview flow · multilingual trigger schema <a href="DEMOS.md">Demos</a> · <a href="#the-vault-is-alive">OKM</a> · <a href="#what-happens-when-you-install-this">See it in action</a> · <a href="#44-commands">All commands</a> · <a href="#install">Install</a> · <a href="#choose-your-preset">Presets</a> · <a href="https://github.com/eugeniughelbur/obsidian-second-brain/discussions">Discussions</a>

<a href="DEMOS.md"> <img src="media/obsidian-save.gif" alt="One /obsidian-save command turns a conversation into five cross-linked AI-first notes: a person, a project with the decision, a task, a board card, and the daily note." width="100%" /> </a> One <code>/obsidian-save</code> - five cross-linked notes. Real footage, synthetic vault. <a href="DEMOS.md">More demos →</a>

v0.12 - The Stress Test (July 2026): we stress-tested our own tool with 32 AI agents and fixed what they found - 175 findings, 24 fix PRs, search 2-4x better, and tools that can no longer eat your notes. Plus a native Claude Code plugin-marketplace install, a multilingual embedding default, and a 134-test CI wall. <a href="CHANGELOG.md">See the changelog →</a>

From the blog · <a href="https://theaioperator.io">The AI Operator →</a>

Featured: <a href="https://theaioperator.io/p/huge-update-on-obsidian-second-brain">"HUGE update on obsidian-second-brain: The Architect"</a> <code>/obsidian-architect</code> · document your codebase into your vault · the full before-and-after

Deep dive: <a href="https://theaioperator.io/p/i-rebuilt-karpathys-llm-wiki-heres">"I rebuilt Karpathy's LLM Wiki. Here's what's missing from the original."</a> Why append-only breaks at scale · the AI-First Vault Principle · three bugs in v1

Origin story: <a href="https://theaioperator.io/p/i-built-this-for-myself-then-1374">"I built this for myself. Then 1,374 strangers cloned it."</a> Two disconnected tools · the institutional-amnesia problem · 1,000+ stars in 7 weeks

One post per Tuesday on Obsidian + AI workflows and bringing AI into real work.

Research toolkit · dual-track <code>/x-read</code> · <code>/x-pulse</code> · <code>/research</code> · <code>/research-deep</code> · <code>/notebooklm</code> · <code>/youtube</code> · <code>/podcast</code>

Open-web track · <code>/research-deep</code> via Perplexity + Grok. Pulls fresh signal from outside. Source-grounded track · <code>/notebooklm</code> via Gemini File Search. Reads your own vault. Run both for high-stakes topics. Contradictions across the two are where the insight is.

Built by <a href="https://github.com/eugeniughelbur">Eugeniu Ghelbur</a> · AI Automation Engineer @ Single Grain building in public · sharing what works

Follow along

Weekly posts on AI second-brain systems, vault patterns, and what actually works.

</td> </tr> </table>

</div>

---

The Problem

You use Claude every day. Every session starts from scratch. You re-explain everything. The conversation ends. Everything disappears.

You take notes in Obsidian. Hundreds of files. They just sit there. You make the same decision twice because you forgot you made it six months ago. Ideas rot in daily notes. Nobody connects the dots.

Two powerful tools. Completely disconnected.

---

How this extends Karpathy's LLM Wiki

Karpathy's pattern is brilliant. Drop sources, LLM creates wiki pages, ask questions. This skill takes it further:

	Karpathy's LLM Wiki	obsidian-second-brain
New sources	Append new pages, cross-reference	Rewrite existing pages. People get updated, claims revised, stale facts replaced.
Contradictions	Flagged, you resolve manually	`/obsidian-reconcile` resolves them automatically
Patterns	Surface when you ask	`/obsidian-synthesize` finds unnamed patterns and writes synthesis pages on its own
When it runs	On demand, when you prompt	4 scheduled agents: nightly close, weekly review, contradiction sweep, vault-health check
Note format	Human-readable wiki pages	AI-first: `## For future Claude` preamble + frontmatter for LLM retrieval, not human review

If Karpathy's wiki is a knowledge base you maintain with an LLM, this is a knowledge base that maintains itself.

---

What Happens When You Install This

After a meeting: /obsidian-save Claude pulls out every decision, person, task, and idea and saves each one to the right note. You do nothing.

You recorded a voice memo: /obsidian-ingest meeting.m4a Claude transcribes it with Whisper, identifies speakers, extracts every promise and action item, and distributes across entity pages, task boards, and the daily note.

You screenshot a whiteboard: /obsidian-ingest photo.png Claude reads the image, extracts text and structure, creates concept notes, links to related projects. A photo becomes knowledge.

You find a great video: /obsidian-ingest https://youtube.com/... Claude doesn't summarize into one note. It REWRITES your existing pages. People get updated. Contradictions get resolved. Patterns trigger new synthesis pages. One URL in. The vault is smarter.

Before a big decision: /obsidian-challenge Claude searches your vault for past failures and reversed decisions on the same topic. Pushes back with your own words. Your vault holds you accountable.

You want to see the big picture: /obsidian-visualize Claude generates a visual canvas of your entire vault. Hub nodes centered, color-coded by type, orphans highlighted. Open it in Obsidian and see the shape of your knowledge.

You go to sleep: The nightly agent runs 5 phases: closes the day, reconciles contradictions, synthesizes cross-source patterns, heals orphan notes, and rebuilds the index. You wake up to a smarter vault.

You start a new day: /obsidian-daily Claude pulls your calendar events, overdue tasks, and overnight changes into today's note. Your morning starts informed.

Someone shares an X post: /x-read https://x.com/... Grok with live X access fetches the post, the thread, and the replies. Returns verbatim text + TL;DR + key claims + reply sentiment + voices to watch. No more screenshots.

You're planning today's content: /x-pulse "AI automation" Grok scans X for what's trending in your topic right now. Returns 3-5 emerging themes (with rep posts + key voices), gaps nobody is filling, hook formats that are working, and 3 specific post ideas you could write today.

You need real research: /research "AI memory tools" Perplexity Sonar Pro pulls a deep dossier with citations: summary, key facts (every claim with a recency marker and source domain), timeline, key players, contrarian views, recommended further reading, open questions. Saved to your vault, auto-opens in Obsidian.

You want vault-first deep research: /research-deep "AI memory tools" Scans your vault for what you already know. Identifies gaps. Spawns 3-5 targeted searches via Perplexity (web) and Grok (X discourse). Synthesizes a delta report: what's new, what's confirmed, contradictions to resolve, recommended vault updates. Vault baseline doesn't get re-researched. Only gaps get filled.

You hit a great YouTube video: /youtube https://youtu.be/... Free transcript via youtube-transcript-api. Optional metadata + top comments via YouTube Data API v3. Grok summarizes into TL;DR, Key Points, Notable Quotes (verbatim), Themes, Comment Sentiment, and Worth Following Up On. Saved as an AI-first note in your vault. Add --visual to also watch it: scene-change frame extraction (ffmpeg) that Claude reads with its own vision to capture on-screen text, code, diagrams, and demos the transcript misses.

You never open Obsidian. Everything happens through Claude.

---

Before & After

	Without this skill	With this skill
Saving decisions	Copy-paste or lose them	Auto-saved to the right project note
Daily notes	Write it yourself, forget half the time	Created automatically
Finding patterns	Re-read dozens of notes	`/emerge` finds them for you
Challenging yourself	Nobody pushes back	`/challenge` uses your own history against you
Session continuity	Re-explain every time	`/world` loads full context in 10 seconds
Ingesting content	Read it, forget it	`/ingest` rewrites 5-15 vault pages from 1 source (URLs, PDFs, audio, screenshots)
Contradictions	You don't know they exist	`/reconcile` resolves them automatically
Synthesis	You connect dots manually	`/synthesize` finds patterns across sources on its own
Sharing vault data	Only Claude can read it	`/export` gives any AI tool a clean snapshot
Facts change over time	Old info gets overwritten	Bi-temporal facts track when it was true AND when the vault learned it
Starting a new session	Re-explain who you are	`CRITICAL_FACTS.md` loads your identity in ~120 tokens
Reading an X thread	Open X, scroll, screenshot, paste	`/x-read [url]` returns post + thread + sentiment + voices
Knowing what to post	Guess what's trending	`/x-pulse` scans X and returns hot themes + gaps + hooks + post ideas
Web research	Open 12 tabs, copy quotes manually	`/research [topic]` returns a sourced dossier with recency markers
Researching what you already know	Re-research from scratch	`/research-deep` scans vault first, fills only the gaps, flags contradictions
YouTube videos	Watch passively, forget	`/youtube [url]` transcript + summary + quotes saved to vault
Vault notes for future-Claude	Notes for human reading	AI-first rule: every note has "For future Claude" preamble + recency markers + citations

---

How It Works

  +------------------------------------------+
  |                                          |
  |   LAYER 1: Operations (28 commands)      |
  |   Claude remembers everything            |
  |                                          |
  +------------------------------------------+
  |                                          |
  |   LAYER 2: Thinking Tools (8 commands)   |
  |   Claude thinks with you                 |
  |                                          |
  +------------------------------------------+
  |                                          |
  |   LAYER 3: Context Engine (1 command)    |
  |   Claude knows who you are               |
  |                                          |
  +------------------------------------------+
  |                                          |
  |   LAYER 4: Research Toolkit (7 commands) |
  |   Claude pulls knowledge in              |
  |                                          |
  +------------------------------------------+
  |                                          |
  |   ALWAYS ON                              |
  |   Background agent + 4 scheduled agents  |
  |   Auto-synthesis + save reminders        |
  |                                          |
  +------------------------------------------+

44 commands total. The calendar command (/obsidian-calendar) is Claude Code only (needs the Google Calendar MCP), so the Codex / Gemini / OpenCode / Hermes / Pi builds ship 43.

Layer 1 saves, organizes, ingests, reconciles, exports, schedules your calendar, and maintains your vault. Layer 2 challenges your ideas, surfaces hidden patterns, bridges unrelated domains, and graduates ideas into projects. Layer 3 loads your identity and current state so every session picks up where the last one ended. Layer 4 pulls live external knowledge into the vault: X posts, X trends, web research with citations (key-less by default), YouTube and podcast transcripts. Vault-first synthesis knows what you already know. Always On keeps the vault alive without you lifting a finger.

---

44 Commands

Operations -- Claude remembers

Command	What it does
`/obsidian-save`	Saves everything from the conversation -- decisions, tasks, people, ideas
`/obsidian-ingest`	Drop a URL, PDF, audio file, or screenshot. The vault REWRITES itself. 5-15 pages touched per source.
`/obsidian-synthesize`	Auto-finds patterns across sources and writes synthesis pages
`/obsidian-reconcile`	Finds contradictions and resolves them. The vault maintains its own truth.
`/obsidian-export`	Clean JSON/markdown snapshot any AI tool can read
`/obsidian-daily`	Creates or updates today's daily note
`/obsidian-calendar <mode>`	One calendar command, four modes: `agenda` (read a snapshot), `reconcile` (flag commitments not yet scheduled), `meeting` (event to note), `schedule` (create/move an event from a task or standalone)
`/obsidian-recurring`	Tracks a recurring obligation with a cadence and a computed next-due date
`/obsidian-log`	Logs a work session, links it everywhere
`/obsidian-task`	Adds task to the right board with priority and due date
`/obsidian-person`	Creates or updates a person note
`/obsidian-capture`	Zero-friction idea capture
`/obsidian-catchup`	Process captures dumped from the Telegram bot (voice/text/image/PDF/link) into the vault
`/obsidian-find`	Smart search with context
`/obsidian-recap`	Summary of a day, week, or month
`/obsidian-review`	Structured weekly or monthly review
`/obsidian-board`	Kanban board view and updates
`/obsidian-board-hygiene`	Bulk-triage a board -- surface stale/overdue items, then archive / reschedule / mark-Done in one pass
`/obsidian-project`	Project note with board and daily links
`/obsidian-projects`	Live project status from git + local docs -- infers all context from vault notes, no config required
`/obsidian-health`	Vault audit -- contradictions, gaps, stale claims, orphans, freshness violations (the freshness policy: every fact timeless, dated, or a pointer)
`/obsidian-retrieval-eval`	Measures vault search quality -- recall@k + MRR on natural-language questions, with the concrete failures and ranked fixes
`/obsidian-decide [--formal]`	Logs decisions to the right project notes; `--formal` writes a full ADR record (the vault knows why it's structured this way)
`/obsidian-visualize`	Generates a visual canvas map of your second brain
`/obsidian-learn`	Reviews vault learnings, prunes stale ones, surfaces patterns to promote into rules
`/obsidian-init`	Generates `_CLAUDE.md`, `index.md`, `log.md`
`/obsidian-architect`	Scans a codebase and writes maintained architecture notes (overview, modules, decisions) into the vault; re-run to refresh
`/create-command`	Interview flow that scaffolds a new command into `commands/<name>.md`, no markdown editing

Thinking -- Claude thinks with you

Command	What it does
`/obsidian-challenge`	Your vault argues against your idea using your own history
`/obsidian-panel`	Convenes a panel of distinct perspectives on a decision, one verdict each + synthesis
`/obsidian-emerge`	Surfaces patterns from 30 days of notes you never named
`/obsidian-connect [A] [B]`	Bridges two unrelated domains to spark new ideas
`/vault-deep-synthesis [topic]`	Cross-references every note on a topic: agreements, contradictions, stale claims, gaps
`/obsidian-distill [note or source]`	Condenses a long note/source into key claims, each tagged with provenance back to the exact source block
`/idea-discovery`	Ranks 3-5 next-direction candidates from ideas, open questions, and orphan research
`/obsidian-graduate`	Turns an idea fragment into a full project with tasks

Context -- Claude knows you

Command	What it does
`/obsidian-world`	Loads identity + state with progressive token budgets (L0-L3)

Research -- Claude pulls knowledge in

Powered by xAI Grok (live X access) + Perplexity Sonar (web research) + YouTube. Findings save to Research/ as AI-first notes (preamble, frontmatter, recency markers, sources verbatim).

Command	What it does
`/x-read [url]`	Deep-read an X post: verbatim post + thread + TL;DR + claims + reply sentiment + voices
`/x-pulse [topic]`	Scan X for what's trending: themes, voices, hooks, post ideas
`/research [topic]`	Web research with citations: full dossier with recency markers and open questions. Uses Perplexity when keyed, free key-less sources (Wikipedia, HackerNews, arXiv, Reddit, and more) otherwise
`/research-deep [topic]`	Vault-first synthesis (open web): scans your vault, finds gaps, fills them via Perplexity + Grok (or free key-less sources when unkeyed), propagates updates across people/projects/ideas
`/notebooklm [topic]`	Vault-grounded synthesis via Gemini File Search. Uploads top 12 vault notes, returns a grounded answer with citations. No browser, one HTTP call. Pairs with `/research-deep` for dual-track research.
`/youtube [url] [--visual]`	Extract transcript + metadata + top comments → AI-first summary. `--visual` adds scene-change frame extraction Claude reads with its own vision
`/podcast [url]`	Apple Podcasts or RSS → transcript (RSS tag / Whisper / show-notes) + AI-first summary

Setup: copy .env.example to ~/.config/obsidian-second-brain/.env, add your keys (xAI, Perplexity, YouTube optional, OpenAI optional for podcast Whisper). Run install.sh and answer "y" to the research prompt to do this automatically.

No keys? /research and /research-deep still work. With no PERPLEXITY_API_KEY set they automatically fall back to free, key-less sources (Wikipedia, HackerNews, arXiv, Reddit, Lobsters, dev.to, OpenAlex, Semantic Scholar, CrossRef, DuckDuckGo) and Claude synthesizes the dossier. Pass --free to force it even when keyed, or --academic to restrict to scholarly sources. The other research commands (/x-read, /x-pulse, /notebooklm, /youtube) still need their respective keys.

<details> <summary>See the thinking tools in action</summary>

/obsidian-challenge

You: "I want to rewrite the API in Rust."

Claude finds your 2025 post-mortem where the Rust rewrite failed. Finds your decision log committing to TypeScript for 2 years. Says: "Your own notes say this failed. Still want to proceed?"

---

/obsidian-emerge

Claude scans 30 daily notes. You mentioned "onboarding friction" in 4 unrelated projects.

"Onboarding is your bottleneck across projects. You never named it."

---

/obsidian-connect "distributed systems" "cooking"

Traces both clusters in your link graph. Finds shared concepts: preparation and load distribution. Generates 3 actionable ideas at the intersection.

---

/obsidian-graduate

An idea from 3 weeks ago. Claude reads it, finds related projects and people, generates a full spec with goals, phases, tasks, and board entries. The idea gets tagged graduated.

</details>

<details> <summary>See /obsidian-ingest in action</summary>

/obsidian-ingest https://youtube.com/watch?v=example

Saves original to raw/videos/ (immutable)
REWRITES entity pages with new context
REWRITES concept pages if the source adds depth or contradicts them
Creates synthesis pages when patterns emerge
Resolves contradictions and documents why
Updates index.md, log.md, daily note

One URL in. The vault rewrites itself.

</details>

<details> <summary>See the research toolkit in action</summary>

/x-read https://x.com/garrytan/status/2048121438914154664

Grok with live X access fetches the post and replies. You get verbatim text, TL;DR, key claims, reply sentiment (~70% positive, 20% skeptical, 10% off-topic), notable counter-arguments with the @ handles of who said them, and "voices to watch" (the replies that added real signal). ~$0.05/call.

---

/x-pulse "AI automation"

WHAT'S HOT (last 24-72h)
  1. Agentic AI vs Basic Automation — voices: @NVIDIAAP, @woisau1
  2. Self-Improving Sovereign Agents — voices: @tom_doerr, @AIDailyGems
  3. Control Layers & Execution Gaps — voices: @ZIQING_JP

WHAT'S UNDEREXPLORED
  - ROI numbers for non-developer small business users
  - Integration of digital agents with physical robotics

HOOKS THAT ARE WORKING
  - "Automation executes. Autonomy reasons." — @NVIDIAAP

POST IDEAS FOR YOU TODAY
  1. Thread: "I gave an open-source agent its own GitHub repo and watched it self-improve"
  2. Single: "Automation executes. Autonomy reasons. Here's the control layer..."

What you'd spend 2 hours scrolling X to find. Returned in 30 seconds for ~$0.13.

---

/research "AI memory tools"

Returns a structured dossier: Summary, Key Facts (each with (as of YYYY-MM, source.com)), Timeline, Key Players, Contrarian Views, Recommended Further Reading, Open Questions, full citations. Saved to Research/Web/ as an AI-first note. ~$0.05/call.

---

/research-deep "AI memory tools"

Phase 1: Vault scan
  Found 8 relevant notes (e.g. Knowledge/2026-02-15 - Mem0 vs Letta.md)

Phase 2: Gap analysis (Perplexity sonar-pro)
  Identified 5 targeted queries to fill what vault is silent or stale on

Phase 3: Targeted research
  [web] Anthropic Claude memory tool 2026 features
  [web] Mem0 Series A reactions and concerns
  [x]   developer reactions to Letta vs Mem0
  ...

Phase 4: Synthesis (sonar-reasoning-pro)
  → What's New Since Vault Baseline
  → What's Confirmed
  → Contradictions / Updates Needed (with [[wikilinks]] to specific vault files)
  → Synthesis bullets
  → Recommended Vault Updates (instructions for /obsidian-save)
  → Open Questions

Vault-first means it doesn't waste tokens re-researching what you already knew. ~$0.40/call.

---

/notebooklm "AI-first vault rule" - vault-grounded, no browser

Scans the vault, uploads the top 12 most relevant notes to a Gemini File Search store, asks Gemini 2.5 Flash to synthesize against THOSE sources only with citations, writes the synthesis to Research/NotebookLM/ as an AI-first note, deletes the store.

Vault baseline: 12 notes
Model: gemini-2.5-flash
Uploading 12 notes... done
Asking Gemini, grounded against the uploaded sources...

=== SAVED ===
Research/NotebookLM/2026-05-15 - ai-first-vault-rule.md

Pair with /research-deep on the same topic. Open-web view + vault-grounded view rarely contradict. Where they do, that's where you have a take worth posting. ~$0.004/call on free-tier Flash, ~$0.06 on paid Pro.

---

/youtube https://youtu.be/... (add --visual to watch, not just read)

Free transcript via youtube-transcript-api + optional metadata + comments via YouTube Data API v3 (free tier). Grok summarizes into TL;DR, Key Points, Notable Quotes (verbatim), Themes, Comment Sentiment, and Worth Following Up On. ~$0.04 for the Grok call. Frontmatter includes view count, channel, published date, like count for Dataview queries.

--visual downloads the video (yt-dlp, <=720p) and extracts one frame per scene change (ffmpeg scene detection, not a fixed timer), so on-screen text, code, diagrams, slides, UI, and b-roll are captured. Claude reads the frames with its own vision (no extra API call) and writes a timestamp-keyed ## Visual notes section; hero frames are embedded in the note. Requires yt-dlp + ffmpeg on PATH; skips gracefully if missing. --max-frames N caps frames read (default 24). Pipeline ported from claude-watch / claude-video (MIT).

---

/podcast https://podcasts.apple.com/... (or paste an RSS feed URL)

Resolves Apple Podcasts URLs to RSS via the free iTunes Lookup API. Picks the best transcript source available: <podcast:transcript> tag in the RSS feed (free, high fidelity) → Whisper API if OPENAI_API_KEY is set (~$0.006/min) → show-notes fallback. Grok summarizes into TL;DR, Key Points, Notable Quotes, Themes, Guests & People Mentioned, and Worth Following Up On. ~$0.04 for the Grok call (plus Whisper if used). Spotify URLs aren't supported (DRM).

---

Auto-open after every save. Obsidian pops open at the new note. Disable with RESEARCH_AUTOOPEN=0 if you're running batch saves.

</details>

---

The Vault is Alive

Traditional vaults are filing cabinets. You put things in. They sit there.

This vault rewrites itself with every input:

Ingest a source -- existing pages get rewritten, contradictions resolved, patterns synthesized
Save a conversation -- entities, concepts, and decisions distribute across the vault
Ask a question -- the Two-Output Rule means every answer also updates pages
A fact changes -- bi-temporal facts track when it was true AND when the vault learned it. "You believed X on Tuesday. After ingesting Y on Wednesday, you shifted to Z." Full audit trail.
Do nothing -- background agent and scheduled agents maintain it while you sleep
Wait a week -- auto-synthesis finds cross-source patterns and writes connection pages

The vault after a week is fundamentally different from the vault you started with.

The maintenance layer has a name: OKM (Open Knowledge Metabolism). Storage is the easy half; keeping stored knowledge true is the hard half, and it is where this project spends its effort. OKM is the open standard behind that: every stored fact must be timeless, dated, or a pointer. Slow-changing knowledge (how things work, decisions, ownership) is stored; fast-changing facts (counts, statuses, balances) are linked to where they live with an as of stamp, never copied in to rot. The rule is a one-page spec (references/freshness-policy.md), enforced by a linter (scripts/freshness_lint.py) that /obsidian-health runs. Where OKF (Google's Open Knowledge Format) standardizes how agent knowledge is written, OKM standardizes how it stays true - the metabolism to OKF's format. It is storage-agnostic: any folder of markdown an AI maintains, not just Obsidian vaults.

---

Choose Your Preset

Pick your role at bootstrap. Each preset creates tailored folder structures, templates, and kanban boards.

Preset	Who it's for	Kanban style
executive	Founders, operators, managers	OKRs / Quarterly / Weekly
builder	Developers, engineers, architects	Backlog / Sprint / Done
creator	Writers, YouTubers, marketers	Ideas / Drafts / Published
researcher	Academics, analysts, deep-divers	Reading / Processing / Synthesized

python bootstrap_vault.py --path ~/my-vault --name "Your Name" --preset builder

No preset? You get a general-purpose vault that works for everyone.

---

Background Agent & Scheduled Agents

Background: fires after every context compaction. You keep working. The vault updates itself.

PostCompact -> obsidian-bg-agent.sh -> claude -p (headless) -> vault updated

Scheduled:

Agent	When	What
`morning`	8 AM	Daily note + overdue tasks
`nightly`	10 PM	Sleeptime consolidation: close day + reconcile + synthesize + heal orphans
`weekly`	Fridays 6 PM	Weekly review
`health`	Sundays 9 PM	Vault health audit

Save reminders: Claude nudges you to /obsidian-save after 10+ exchanges or when you say "done" or "thanks". No lost conversations.

---

Vault Architecture

Wiki-style (default) -- LLM-first

Claude is the reader and writer. The vault is a database.

vault/
+-- _CLAUDE.md          # Operating manual
+-- index.md            # Page catalog (Claude reads FIRST)
+-- log.md              # Activity timeline
+-- SOUL.md             # Your identity
+-- CRITICAL_FACTS.md   # ~120 tokens, always loaded (timezone, manager, location)
+-- raw/                # IMMUTABLE source material
+-- wiki/               # Claude's workspace
|   +-- entities/       # People, companies, tools
|   +-- concepts/       # Ideas, frameworks, synthesis
|   +-- projects/       # Project notes
|   +-- daily/          # Daily notes
|   +-- logs/           # Work session logs
|   +-- reviews/        # Weekly/monthly reviews
|   +-- tasks/          # Task notes
|   +-- decisions/      # ADRs
+-- boards/             # Kanban boards
+-- templates/          # Note templates

---

Install

One codebase, six platforms. Pick yours below. The vault behavior is identical across all of them; only the install path and the dispatcher file (CLAUDE.md / AGENTS.md / GEMINI.md / .pi/) differ.

Prerequisites: Claude Code (or one of the other five platforms below), git, and uv for the Python helpers (health check, research toolkit, bootstrap). Optional: jq (used by setup.sh), Ollama for local semantic search. No API keys needed for the core vault commands.

Claude Code (default)

Native plugin install (recommended). Inside any Claude Code session:

/plugin marketplace add eugeniughelbur/obsidian-second-brain
/plugin install obsidian-second-brain@obsidian-second-brain

That ships all 44 commands, the skill manual, the session-context hook, the opt-in background agent (inert until you arm it - see hooks/postcompact.hook.example.json), and the vault MCP server. Then tell Claude where your vault lives by adding to the env section of ~/.claude/settings.json:

"env": { "OBSIDIAN_VAULT_PATH": "/path/to/your/vault" }

Restart Claude Code, then run /obsidian-second-brain:obsidian-init inside your vault. Plugin commands are namespaced, so every command is /obsidian-second-brain:<name> (type /obsidian-second-brain: to see all 44). Update later with /plugin update obsidian-second-brain.

Classic install (script). Use this if you want the commands as bare names (/obsidian-init, /research, ...) or you are developing the skill and want live edits. One line (clones the skill, installs the slash commands, registers the session-context hook, and offers the research env):

curl -fsSL https://raw.githubusercontent.com/eugeniughelbur/obsidian-second-brain/main/scripts/quick-install.sh | bash

Or step by step:

git clone https://github.com/eugeniughelbur/obsidian-second-brain ~/.claude/skills/obsidian-second-brain
bash ~/.claude/skills/obsidian-second-brain/install.sh
bash ~/.claude/skills/obsidian-second-brain/scripts/setup.sh "/path/to/your/vault"

No vault yet? Create a ready-to-use one first (folders, templates, boards, dashboards - passes its own health check out of the box):

cd ~/.claude/skills/obsidian-second-brain
uv run python scripts/bootstrap_vault.py --path ~/Documents/MyVault --name "Your Name"
bash scripts/setup.sh ~/Documents/MyVault

Then open Claude Code and run /obsidian-init inside your vault.

Codex CLI / Gemini CLI / OpenCode

git clone https://github.com/eugeniughelbur/obsidian-second-brain
cd obsidian-second-brain
bash scripts/build.sh --platform codex-cli   # or gemini-cli, or opencode
cp -R dist/codex-cli/. /path/to/your/vault/   # or .gemini-cli / .opencode/

Then start your CLI from the vault root.

The Codex build emits native Codex Agent Skills: one skill per command under .agents/skills/<name>/SKILL.md. Codex discovers them automatically with progressive disclosure (only each skill's name + description load until it's selected), and they run in your current session - invoke one with @@CODE1@@lt;name>, pick it from /skills, or just describe the task and let Codex match it implicitly. AGENTS.md stays as a thin always-on manual (vault conventions + the AI-first rule); there is no routing table to maintain because the skill list is the router. The Gemini / OpenCode builds still emit a GEMINI.md / AGENTS.md dispatcher with an auto-generated routing table to command files under .gemini/ / .opencode/.

Run bash scripts/build.sh with no arguments to build every platform at once. See dist/<platform>/INSTALL.md after building for platform-specific notes.

Pi Coding Agent

git clone https://github.com/eugeniughelbur/obsidian-second-brain
cd obsidian-second-brain
bash scripts/build.sh --platform pi
pi install ./dist/pi          # or: cp -R dist/pi/.pi/ /path/to/your/vault/

The Pi build emits a native Pi package: prompt templates under .pi/prompts/ (invoke as /obsidian-save, /obsidian-daily, etc.) plus a discovery skill under .pi/skills/obsidian-second-brain/ (load with /skill:obsidian-second-brain). Pi reads the same ~/.config/obsidian-second-brain/.env keys as the other platforms. It has no background-agent equivalent - run /obsidian-nightly manually or via cron. (Contributed by @Gepetdo.)

Run on Hermes / open models

The skill is model-agnostic. The OpenCode build (and the Codex / Gemini builds) are plain instruction files, so they run on whatever model the host CLI is pointed at - including open models like Nous Research Hermes. No separate build, no code changes. You set the model on OpenCode's side.

There is also a dedicated Hermes Agent build that emits the commands as native Hermes skills (skills/<category>/<name>/SKILL.md, agentskills.io-compatible), so Hermes discovers and runs them through its own Skills System rather than via a host CLI:

bash scripts/build.sh --platform hermes
# then follow dist/hermes/INSTALL.md (copy into ~/.hermes/skills/ or add as a tap)

This is the skill/playbook half of the Hermes work; the bounded vault-data half is the MCP connector. Native cron and lifecycle-hook integration are tracked in Issue #79.

Point OpenCode at Hermes via OpenRouter. Authenticate once (/connect, search OpenRouter, paste your key - or export OPENROUTER_API_KEY=...), then in opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "openrouter/nousresearch/hermes-4-70b",
  "provider": {
    "openrouter": {
      "models": {
        "nousresearch/hermes-4-70b": {}
      }
    }
  }
}

Hermes models on OpenRouter (as of 2026-06, openrouter.ai):

Model id	Best for	Cost (in / out per 1M tokens)
`nousresearch/hermes-4-70b`	Default. Cheap, capable, 131k context.	$0.13 / $0.40
`nousresearch/hermes-4-405b`	Strongest instruction-following for the synthesis-heavy commands.	$1.00 / $3.00
`nousresearch/hermes-3-llama-3.1-405b:free`	Zero-cost trial (needs any OpenRouter key to authenticate).	free

For the privacy story, run a smaller Hermes locally through Ollama or LM Studio and point OpenCode at the local endpoint - no data leaves your machine.

What to expect (open models follow instructions less reliably than Claude, so this is honest, not a promise of parity): the core commands - /obsidian-save, /obsidian-daily, /obsidian-capture, /obsidian-find, /obsidian-task, and /research in free mode - hold up well. The sub-agent-heavy commands and the deep synthesis ones (/obsidian-architect, /obsidian-reconcile, /research-deep) lean hard on instruction-following, so prefer hermes-4-405b (or Claude) for those. The AI-first vault rule still applies on every write regardless of model.

Research toolkit (optional)

The 7 research commands use API keys (2 of them fall back to free sources without any). Run install.sh and answer "y" to the research prompt. That sets up ~/.config/obsidian-second-brain/.env. Or do it manually:

mkdir -p ~/.config/obsidian-second-brain
cp .env.example ~/.config/obsidian-second-brain/.env
chmod 600 ~/.config/obsidian-second-brain/.env
# then paste keys into the file
uv sync   # installs Python deps

Keys you need:

Key	Where	Required for	Cost
`XAI_API_KEY`	console.x.ai	`/x-read`, `/x-pulse`, `/research-deep` X pulse, `/youtube` summary	Pay-per-use, ~$0.05/call
`PERPLEXITY_API_KEY`	perplexity.ai/settings/api	`/research`, `/research-deep`	Pay-per-use, ~$0.02-$0.50/call
`GEMINI_API_KEY`	aistudio.google.com/apikey	`/notebooklm` (vault-grounded synthesis via Gemini File Search)	Free tier covers it. Paid: ~$0.004/call (Flash), ~$0.06/call (Pro).
`YOUTUBE_API_KEY`	console.cloud.google.com	`/youtube` metadata + comments (optional, transcripts free without)	Free tier 10k units/day
`OPENAI_API_KEY`	platform.openai.com	`/podcast` Whisper transcription (optional, falls back to show-notes if unset)	~$0.006/min

Without keys, the 37 non-research commands work fully, and /research + /research-deep fall back to free, key-less sources. The rest of the research toolkit degrades gracefully.

Semantic search (optional, off by default)

Search (/obsidian-find and the MCP connector) works out of the box as fast keyword search - no setup, no model, nothing to install. You can optionally add a meaning-based layer that finds notes even when your query shares no words with them. It is opt-in by setup and, when present, leads the ranking with keyword search as tiebreak and freshness signals on top (measured on a ~2,350-note vault: keyword recall@10 1.0, paraphrased-question recall@10 77%, and non-English queries went from ~0 to 63% recall@5 with the multilingual default model - full reference in scripts/eval/BASELINE.md). If the model is ever unreachable, search silently falls back to keyword - it never breaks or hangs.

Two ways to provide the embedding model:

Local + private (recommended), via Ollama: install Ollama, ollama pull bge-m3, then build the index once: uv run python scripts/eval/semantic_search.py --path "<vault>" --build. Your notes never leave the machine.
No Ollama? Any OpenAI-compatible endpoint. Set OBSIDIAN_EMBED_BACKEND=openai, OBSIDIAN_EMBED_URL=<base url>, OBSIDIAN_EMBED_MODEL=<model>, and OBSIDIAN_EMBED_KEY=<key if needed>. This covers other local runtimes (LM Studio, llama.cpp's server) for free/private use, or a cloud API (OpenAI, a gateway) for top quality - note a cloud endpoint means note text leaves your machine, so use OBSIDIAN_EMBED_EXCLUDE=<folder prefixes> to keep private folders local-only.

Knobs: OBSIDIAN_SEARCH_SEMANTIC=0 disables the layer entirely; the index is rebuilt incrementally (only changed notes re-embed) so re-run --build occasionally as the vault grows. The index file is large and regenerable - gitignore it.

---

FAQ

What is a Claude Code skill?

A Claude Code skill is a reusable behavior package for Anthropic's Claude Code CLI. It bundles slash commands, scripts, references, and operating instructions that Claude loads automatically. Skills give Claude domain expertise without prompt-engineering each session.

Is this an Obsidian plugin or a Claude Code skill?

This is a Claude Code skill, not an Obsidian plugin. An Obsidian plugin lives inside Obsidian and adds UI features there. A Claude Code skill lives inside Claude Code (Anthropic's terminal AI coding agent) and gives Claude the ability to read, write, and reason over your Obsidian vault from outside Obsidian. You install this skill into Claude Code, not into Obsidian. Your vault is unchanged, just better-leveraged.

What's the difference between an Obsidian Claude Code skill and a regular Obsidian plugin?

An Obsidian plugin runs inside Obsidian and is written in TypeScript against Obsidian's plugin API. A Claude Code skill for Obsidian runs inside Claude Code and is written as a set of markdown command files plus optional Python scripts. Plugins are constrained to what Obsidian's API exposes. Skills are constrained only by what Claude can do in your shell, which is why this skill can do things plugins can't: pull live web research into vault notes, run scheduled agents that update your vault while you sleep, and synthesize knowledge across years of notes using Anthropic's Claude.

How do I add this Obsidian Claude skill to Claude Code?

Run the one-line installer from the Install section below. It clones the repo to ~/.claude/skills/obsidian-second-brain and symlinks the slash commands into ~/.claude/commands/ so Claude Code picks them up automatically. Restart Claude Code after install. The skill loads on every session that touches an Obsidian vault.

Does this work with Codex CLI, Gemini CLI, or OpenCode?

Yes. The repo ships a build script that compiles the platform-neutral source into six platform-specific outputs: Claude Code (slash commands + CLAUDE.md), Codex CLI (native Agent Skills), Gemini CLI (GEMINI.md + .gemini/commands/), OpenCode (AGENTS.md + .opencode/commands/), Hermes (native skills), and Pi (package.json + .pi/). Run bash scripts/build.sh --platform codex-cli (or another platform name), then copy the resulting dist/<platform>/ tree into your vault. The non-Claude builds auto-generate a routing table that maps natural-language triggers to command files, so the same 43 cross-platform commands work no matter which CLI you use (the calendar command is Claude Code only, since it depends on the Google Calendar MCP). The vault rules (AI-first notes, frontmatter, wikilinks, recency markers) are identical across all six platforms.

Does this run on Hermes or other open models?

Yes. The skill is model-agnostic - the OpenCode, Codex, and Gemini builds are plain instruction files, so they run on whatever model the host CLI uses, including open models like Nous Research Hermes. The most common path is OpenCode pointed at Hermes via OpenRouter (or a local Hermes through Ollama / LM Studio for full privacy). See "Run on Hermes / open models" in the Install section for the exact config. Honest expectation: the core save / daily / capture / find / task commands and free-mode /research hold up well; the sub-agent-heavy and deep-synthesis commands (/obsidian-architect, /obsidian-reconcile, /research-deep) want a stronger instruction-follower, so prefer hermes-4-405b or Claude for those.

Does this work with Obsidian Sync?

Yes. The skill writes to your vault as standard markdown files. Obsidian Sync, iCloud, Syncthing, and Git-based sync all work without modification.

Do I need API keys to use this?

Mostly no. The vault commands (/obsidian-save, /obsidian-daily, etc.) need no API keys. /research and /research-deep are also key-free now - with no Perplexity key they automatically fall back to free, key-less sources (Wikipedia, HackerNews, arXiv, Reddit, and more) and Claude synthesizes the dossier. The remaining research commands (/x-read, /x-pulse, /notebooklm, /youtube, /podcast) need their respective keys (xAI Grok, Perplexity, Google Gemini, optionally YouTube Data API v3 / OpenAI Whisper) and exit with a clear setup message when one is missing. The calendar command (/obsidian-calendar, all four modes) needs the Google Calendar MCP connector rather than an API key.

How is this different from Notion AI or Mem?

Notion AI and Mem are closed-source SaaS products that own your data. This skill stores everything as plain markdown in your local Obsidian vault, with no vendor lock-in. The AI is on top of your data, not behind it. You can switch tools or stop using the skill at any point and still have your full vault.

Can it document my codebase?

Yes - that is the headline of v0.10 ("The Architect"). The /obsidian-architect command scans a software project (languages, modules, dependencies, entry points) and writes maintained architecture notes into your vault: an overview with a diagram, one note per module, and a key-decisions note mined from your git history. Re-running it refreshes only the generated content and never overwrites the notes you added by hand, so the docs stay current as the code changes. It puts "how does this project work, and why" in the same vault as your ideas and decisions.

How does the code documentation stay current without overwriting my edits?

/obsidian-architect writes generated content inside sentinel markers (` blocks). On a re-run it replaces only what is inside those blocks and leaves your ` blocks (and anything outside the markers) untouched. So you can hand-annotate the architecture notes and re-run the scan as the code evolves without losing your additions.

What is the AI-first vault rule?

The principle that vault notes are written for future-Claude to retrieve and reason over, not for human reading. Notes have machine-readable structure, recency markers per claim, mandatory [[wikilinks]], source URLs preserved verbatim, and confidence levels. See references/ai-first-rules.md for the full specification with frontmatter schemas per note type.

Is this safe to run on my existing vault?

Yes. The skill never deletes or modifies notes destructively without explicit confirmation. Existing notes stay as-is. New notes follow the AI-first rule. /obsidian-health flags pre-AI-first notes so you can update them on your own schedule.

What is OKM (Open Knowledge Metabolism)?

The maintenance layer, given a name. Its one rule: every stored fact must be timeless, dated, or a pointer - so a knowledge folder can never quietly fill with facts that used to be true. Slow knowledge is stored; fast facts are linked to their live source with an as of stamp instead of copied in. It ships as a one-page spec (references/freshness-policy.md) and a stdlib-only linter (scripts/freshness_lint.py) that /obsidian-health runs, and it is storage-agnostic (any markdown folder an AI maintains). Think of it as the companion to OKF (Open Knowledge Format): OKF standardizes how knowledge is written, OKM keeps it true.

What does `/research-deep` do that `/research` doesn't?

/research runs a single Perplexity query and returns a dossier with citations. /research-deep is vault-first: it scans your existing notes, identifies what you already know about the topic, spawns 3-5 targeted follow-up searches to fill only the gaps, and produces a delta report (what's new, what's confirmed, contradictions to resolve, recommended vault updates). Vault-first means you stop re-researching what's already in your notes.

What do the research commands cost?

Approximate per-call costs as of 2026-04: /x-read ~$0.05, /x-pulse ~$0.13, /research ~$0.04, /research-deep ~$0.40-$0.80, /youtube ~$0.04, /podcast ~$0.04 Grok call (plus ~$0.006/min if Whisper is used; free if RSS provides a <podcast:transcript> tag or you accept the show-notes fallback). Costs for Grok calls are logged to ~/.research-toolkit/usage.log for visibility. No hard caps. You're trusted to monitor your own spend.

Can I use this on Windows or Linux?

The core vault commands work anywhere Claude Code runs. install.sh supports Linux, macOS, and Windows (MSYS2/Git Bash): on Linux/macOS slash commands are symlinked so git pull keeps them current; on Windows they are copied and update.sh refreshes them. The research toolkit auto-open step uses open on macOS, xdg-open on Linux, and notepad on Windows.

Can I have a separate vault per project (multi-repo workflows)?

Yes. The default scripts/setup.sh writes OBSIDIAN_VAULT_PATH globally to ~/.claude/settings.json, but every hook in this skill reads that env var at fire-time. Claude Code merges per-project .claude/settings.json on top of the global one, so you can put {"env": {"OBSIDIAN_VAULT_PATH": "/path/to/repo-vault"}} in each repo's .claude/settings.json and Claude will use that repo's vault whenever you launch a session from that directory. The slash commands and hooks remain globally installed; only the vault path changes. Full recipe in SKILL.md. One thing this does NOT give you: isolation within a single vault (no --scope on commands yet).

How do I update to the latest version?

cd ~/.claude/skills/obsidian-second-brain && git pull

On Linux/macOS: nothing else to run - slash commands are symlinked so they pick up the new files automatically. On Windows: also run bash update.sh to refresh the copied command files. Restart Claude Code after either path. See CHANGELOG.md for what's in each release.

Where do I file issues or feature requests?

GitHub Issues: https://github.com/eugeniughelbur/obsidian-second-brain/issues. PRs welcome, see Contributing below.

---

Philosophy

Most second brain tools make you the janitor.

This skill inverts that. You think, work, and talk. Claude handles the memory. Then it uses that memory to make you think better -- surfacing what you'd miss, challenging what you'd assume, connecting what you'd never link, and synthesizing patterns you didn't ask for.

The vault doesn't grow. It evolves.

Your notes are the moat.

Inspired by Andrey Karpathy's LLM-Wiki.

---

Contributing

PRs welcome:

New thinking tools
Note type schemas (habits, books, investments)
MCP integrations (Calendar, Linear, Slack)
Alternative vault structures
VS Code / Cursor setup guides

Building a domain-specific fork (academic, legal, finance, medical)? See ECOSYSTEM.md. The upstream repo ships primitives; forks own the domain knowledge. First proof case: scholarbrain for academic research.

Customizing your own fork? Copy references/DELTAS.template.md to a DELTAS.md at your fork root and record your local deviations there. Upstream never touches that file, so you can keep merging upstream/main cleanly instead of fighting conflicts in stock commands.

---

Author

Built by Eugeniu Ghelbur, AI Automation Engineer @ Single Grain

If this skill helped you, the best thanks is following along.

</td> </tr> </table>

</div>

---

License

MIT

obsidian-second-brain

主要能力

使用方式

适用边界

许可与来源

Follow along

The Problem

How this extends Karpathy's LLM Wiki

What Happens When You Install This

Before & After

How It Works

44 Commands

Operations -- Claude remembers

Thinking -- Claude thinks with you

Context -- Claude knows you

Research -- Claude pulls knowledge in

The Vault is Alive

Choose Your Preset

Background Agent & Scheduled Agents

Vault Architecture

Wiki-style (default) -- LLM-first

Install

Claude Code (default)

Codex CLI / Gemini CLI / OpenCode

Pi Coding Agent

Run on Hermes / open models

Research toolkit (optional)

Semantic search (optional, off by default)

FAQ

What is a Claude Code skill?

Is this an Obsidian plugin or a Claude Code skill?

What's the difference between an Obsidian Claude Code skill and a regular Obsidian plugin?

How do I add this Obsidian Claude skill to Claude Code?

Does this work with Codex CLI, Gemini CLI, or OpenCode?

Does this run on Hermes or other open models?

Does this work with Obsidian Sync?

Do I need API keys to use this?

How is this different from Notion AI or Mem?

Can it document my codebase?

How does the code documentation stay current without overwriting my edits?

What is the AI-first vault rule?

Is this safe to run on my existing vault?

What is OKM (Open Knowledge Metabolism)?

What does /research-deep do that /research doesn't?

What do the research commands cost?

Can I use this on Windows or Linux?

Can I have a separate vault per project (multi-repo workflows)?

How do I update to the latest version?

Where do I file issues or feature requests?

Philosophy

Contributing

Sponsors

Author

License

What does `/research-deep` do that `/research` doesn't?