obsidian-second-brain

obsidian-second-brain

A routing-first front door for obsidian-second-brain — an evolution of Karpathy's LLM-Wiki pattern into a vault that rewrites itself. Where the LLM-Wiki appends new pages, this skill REWRITES existing ones: people get updated, claims revised, stale facts replaced, contradictions reconciled automatically, and cross-source patterns synthesized on their own — while you sleep.

Keyword: obsidian second brain · self-rewriting vault · obsidian-save · obsidian-ingest

One codebase, four CLIs (Claude Code · Codex CLI · Gemini CLI · OpenCode), same brain.

When to use this skill

• The user wants an Obsidian vault that maintains itself instead of a static filing cabinet.
• The user wants to capture work into the vault: save a conversation, ingest a URL / PDF / audio / screenshot, log a session, create daily notes, track tasks/people/decisions.
• The user wants the vault to reconcile contradictions and synthesize cross-source patterns automatically.
• The user wants thinking tools that push back: challenge a decision against their own history, convene a perspective panel, surface unnamed patterns, bridge unrelated domains.
• The user wants research pulled into the vault: deep-read an X post, scan X trends, web research with citations, vault-first deep research, source-grounded NotebookLM synthesis, YouTube/podcast transcripts.
• The user wants to install the second-brain skill on Claude Code, Codex CLI, Gemini CLI, or OpenCode (incl. open models like Hermes).
• The user wants to scan a codebase and write maintained architecture notes into the vault (/obsidian-architect).

Route out when the real job is narrower:

• obsidian — Obsidian plugin development, CLI automation, URI handoff, JSON Canvas, Bases content patterns.
• llm-wiki — the underlying raw/wiki markdown layer, source summaries, query filing, lint passes.
• okf — exporting the vault as a portable, vendor-neutral Open Knowledge Format bundle.
• notebooklm — standalone source-grounded NotebookLM queries outside a vault workflow.
• scrapling — adaptive web scraping when you only need raw content extraction, not vault ingestion.

Invoking in jeo — the $ entrypoint

In jeo-code (jeo) a skill loads only through the $ entrypoint, never through /slash typing. The aliases: frontmatter still publishes all 45 names into jeo skills, the skill picker, and shell autocomplete for discovery, but the live trigger is:

$obsidian-second-brain <command-or-intent> [args]

$obsidian-s (or any unambiguous prefix) resolves too; bare $obsidian does not — that exact-matches the separate obsidian skill. Everything after the skill token is handed to this file as the intent. Dispatch the intent deterministically:

1. Explicit command — if the first intent word matches one of the 45 command names (with or without a leading / and with or without the obsidian- prefix), run that exact command and treat the rest of the line as its arguments. All of these route to /obsidian-ingest:

   $obsidian-second-brain /obsidian-ingest https://example.com/post
   $obsidian-second-brain obsidian-ingest https://example.com/post
   $obsidian-second-brain ingest https://example.com/post
   

   More examples:

   $obsidian-second-brain save                    → /obsidian-save
   $obsidian-second-brain reconcile               → /obsidian-reconcile
   $obsidian-second-brain challenge "migrate to X" → /obsidian-challenge
   $obsidian-second-brain research-deep "rag eval" → /research-deep
   $obsidian-second-brain world                   → /obsidian-world
   $obsidian-second-brain x-read <url>            → /x-read
   

   The non-prefixed names that stay literal (no obsidian-): create-command, idea-discovery, notebooklm, podcast, research, research-deep, vault-deep-synthesis, x-pulse, x-read, youtube.

2. Natural-language intent — if the first word is not a command name, classify the request through Step 1 below (layer → command) and state the route before acting, e.g. $obsidian-second-brain save everything from this chat → "Operations → /obsidian-save".

The chosen command's behavior, the AI-first vault rule, and propagation are identical to the slash version — only the trigger surface ($ instead of /) differs. Full command table in references/commands.md.

Instructions

Step 1 — Classify the request into one of the 4 layers

The skill is organized into four layers plus an always-on automation tier. Pick the layer first, then the command. Full command table in references/commands.md.

Layer	Purpose	Pick when the user wants to…
1 · Operations (28 cmds)	Claude remembers	save, ingest, reconcile, export, daily notes, tasks, people, decisions, calendar, project/vault maintenance, architecture notes
2 · Thinking Tools (7 cmds)	Claude thinks with you	challenge an idea, convene a panel, surface patterns, bridge domains, deep-synthesize a topic, rank next directions, graduate an idea into a project
3 · Context Engine (1 cmd)	Claude knows who you are	load identity + state with progressive token budgets (/obsidian-world)
4 · Research Toolkit (7 cmds)	Claude pulls knowledge in	X read/pulse, web research, vault-first deep research, NotebookLM, YouTube, podcast
Always On	Vault stays alive	background agent (post-compaction) + 4 scheduled agents (morning/nightly/weekly/health) + save reminders

State the route explicitly before acting, e.g. "Operations → /obsidian-ingest" or "Research → /research-deep (vault-first)".

Step 2 — Honor the AI-first vault rule on every write

This is the core invariant — it applies on every note write, regardless of model:

• Each note opens with a ## For future Claude preamble (what this note is, why it matters, how to use it).
• Frontmatter is for LLM retrieval, not human review (type, tags, recency markers, sources verbatim).
• Rewrite, don't append: when a source adds depth or contradicts a page, rewrite that page and record why.
• Bi-temporal facts: track when a fact was true AND when the vault learned it ("You believed X on Tuesday; after ingesting Y on Wednesday, you shifted to Z").
• Two-Output Rule: every answer also updates the relevant pages.
• raw/ is immutable — original sources are never edited, only summarized/rewritten into wiki/.

Step 3 — Run the matching command and propagate updates

For the high-leverage flows:

• /obsidian-save — pull every decision, person, task, and idea out of the conversation; distribute each to the right note.
• /obsidian-ingest <url|file|image|audio> — saves the original to raw/ (immutable), then REWRITES 5–15 entity/concept pages, resolves contradictions, creates synthesis pages, updates index.md / log.md / daily note.
• /obsidian-reconcile — find contradictions across the vault and resolve them, documenting why.
• /obsidian-synthesize — find unnamed cross-source patterns and write synthesis pages.
• /obsidian-challenge — search the vault for past failures/reversed decisions on the topic and push back with the user's own words.
• /research-deep <topic> — scan the vault first, identify gaps, fill only the gaps via Perplexity (web) + Grok (X) or free key-less sources, then propagate updates across people/projects/ideas. Vault-first means it never re-researches what you already know.

Step 4 — Install / build for the target CLI when asked

Install path differs per CLI; vault behavior is identical. Full matrix + research-toolkit key table in references/install.md.

• Plugin (recommended for this jeo-skill front door): npx skills add https://github.com/akillness/jeo-skills --skill obsidian-second-brain (or bash scripts/install.sh).
• jeo-code (jeo): discovered automatically. Invoke via the $ entrypoint — $obsidian-second-brain <command-or-intent> (see Invoking in jeo); the 45 names from the aliases: frontmatter surface in jeo skills / picker / autocomplete for discovery, but jeo never loads a skill from /slash typing. JEO=1 VAULT=<dir> bash scripts/install.sh also registers an advisory write-time AI-first validator as a post-turn hook (jq-merged with backup, append-only, idempotent; remove with UNINSTALL=1). The Claude-only / palette, SessionStart loader, and PostCompact agent are not ported — jeo lacks those hook events.
• Upstream Claude Code: curl -fsSL https://raw.githubusercontent.com/akillness/obsidian-second-brain/main/scripts/quick-install.sh | bash, then /obsidian-init.
• Upstream Codex / Gemini / OpenCode: git clone then bash scripts/build.sh --platform <codex-cli|gemini-cli|opencode> and copy dist/<platform>/ into the vault. Codex needs bash scripts/install-codex-wrappers.sh for named command shims.
• Research toolkit (optional): cp .env.example ~/.config/obsidian-second-brain/.env, add keys, uv sync. Or bash scripts/install.sh and answer "y" to the research prompt. /research + /research-deep work key-less.

Step 5 — Set up automation when the user wants the vault to stay alive

• Background agent fires after every context compaction (PostCompact → headless claude -p → vault updated).
• Scheduled agents: morning (8 AM daily note + overdue), nightly (10 PM consolidation: close + reconcile + synthesize + heal orphans + rebuild index), weekly (Fri 6 PM review), health (Sun 9 PM audit).
• Save reminders: nudge /obsidian-save after 10+ exchanges or on "done"/"thanks".

Vault layout, presets (executive / builder / creator / researcher), and agent details live in references/vault-architecture.md.

Integrity guardrails

• Never fabricate vault facts, citations, or research sources. Research notes record sources verbatim with recency markers (as of YYYY-MM, source.com).
• Rewrite over append, but never silently destroy an opposing claim — reconcile it and keep the audit trail (bi-temporal facts).
• Respect raw/ immutability — original sources are read-only.
• Open models follow instructions less reliably than Claude. Prefer Claude or hermes-4-405b for the synthesis-heavy commands (/obsidian-architect, /obsidian-reconcile, /research-deep); the AI-first vault rule still applies on every write.
• API keys stay local — ~/.config/obsidian-second-brain/.env, chmod 600, never committed.

Reference files

• references/commands.md — all 45 commands grouped by layer, with triggers and what each does.
• references/install.md — 4-CLI install matrix, Hermes/open-model setup, research-toolkit key table.
• references/vault-architecture.md — vault layout, presets, background + scheduled agents, the AI-first vault rule.

Upstream: akillness/obsidian-second-brain (origin: eugeniughelbur/obsidian-second-brain, MIT).