# Obsidian Second Brain

> Routing front door for obsidian-second-brain — a self-rewriting Obsidian vault that evolves Karpathy's LLM-Wiki pattern. Every source REWRITES existing pages instead of appending: people updated, claims revised, contradictions reconciled, patterns synthesized automatically. 45 commands across 4 layers, background + 4 scheduled agents, 4 role presets, AI-first write validator. Cross-CLI: Claude Code, Codex CLI, Gemini CLI, OpenCode.

- Skill: `akillness/obsidian-second-brain` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add akillness/obsidian-second-brain`
- Raw SKILL.md: https://api.skillmd.com/api/skills/akillness/obsidian-second-brain/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: akillness (https://skillmd.com/u/akillness)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/akillness/obsidian-second-brain

---


# obsidian-second-brain

A routing-first front door for [**obsidian-second-brain**](https://github.com/akillness/obsidian-second-brain)
— an evolution of [Karpathy's LLM-Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
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](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](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](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](#invoking-in-jeo--the--entrypoint)); 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](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](references/commands.md) — all 45 commands grouped by layer, with triggers and what each does.
- [references/install.md](references/install.md) — 4-CLI install matrix, Hermes/open-model setup, research-toolkit key table.
- [references/vault-architecture.md](references/vault-architecture.md) — vault layout, presets, background + scheduled agents, the AI-first vault rule.

Upstream: [akillness/obsidian-second-brain](https://github.com/akillness/obsidian-second-brain)
(origin: [eugeniughelbur/obsidian-second-brain](https://github.com/eugeniughelbur/obsidian-second-brain), MIT).