# obsidian-second-brain: a Claude Code memory skill that writes into your Obsidian vault

> The project turns an Obsidian vault into shared memory for Claude Code and six other CLI agents, with 45 commands and scheduled agents that rewrite notes. The design is opinionated about note format, and that is the part to weigh before you install it.

**eugeniughelbur/obsidian-second-brain** — Persistent memory for Claude Code and 6 other CLI agents, stored as plain markdown in your Obsidian vault. Stop re-explaining your projects, decisions and people every session. 45 commands: hybrid semantic search, self-rewriting notes, key-less web research, and scheduled agents that maintain the vault while you sleep.

- Repository: https://github.com/eugeniughelbur/obsidian-second-brain
- Website: https://eugeniughelbur.github.io/obsidian-second-brain/
- Stars: 4,652 · Forks: 577
- Language: Python
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/eugeniughelbur-obsidian-second-brain

## The gap obsidian-second-brain fills between a CLI agent and your notes

Claude Code, Codex, Gemini CLI, OpenCode, Antigravity, Hermes, Pi, and Grok Bot all start a session without memory of the last one. The README states the problem plainly: every session starts from scratch, you re-explain your projects, and the conversation ends with nothing retained. Meanwhile the notes you already wrote sit in Obsidian, unread by the tool doing the thinking.

The project's answer is to make the vault the memory store and the agent the writer. It is aimed at developers, founders and operators, writers, and researchers, and the setup asks you to choose one of four presets for the role you play. If you do not already keep notes in Obsidian, the premise does not apply to you; the tool has no memory store of its own.

## How the vault becomes memory: OKM, AI-first notes and self-rewriting pages

The README frames the project as an evolution of Karpathy's LLM Wiki pattern. In that pattern you drop sources in, an LLM creates wiki pages, and you ask questions. Here, new sources rewrite existing pages instead of appending new ones, so a person page gets updated rather than duplicated.

The mechanism behind that is OKM, short for Open Knowledge Metabolism, documented in references/freshness-policy.md. Every stored fact is classified as timeless, dated, or a pointer, which is how the project avoids a vault full of facts that used to be true. Contradictions are handled by a command, /obsidian-reconcile, rather than left for you to resolve by hand.

Note format is where the project diverges most from ordinary Obsidian use. Notes carry a "## For future agent" preamble plus frontmatter written for retrieval by a model rather than for review by a person. That is a deliberate trade: the README describes the format as AI-first, and it means your vault will not look like a hand-maintained notebook once the agents start writing. Four scheduled agents run on a cadence the README names as morning brief, nightly consolidation, weekly review, and vault-health check.

## Installing obsidian-second-brain and running your first save

The repository ships install.sh at the top level, and the README's install section is the authority on what it does. The research toolkit is a separate Python package, obsidian-second-brain-research, which declares requires-python >=3.10 and depends on openai, requests, python-dotenv, youtube-transcript-api, google-api-python-client, google-genai, feedparser, and pyyaml.

Credentials live in a dotenv file. The .env.example tells you to copy it to ~/.config/obsidian-second-brain/.env, set permissions 600, and fill in values. The vault path is the only required entry; every API key below it is optional and the corresponding command is skipped when the key is empty.

```bash
cp .env.example ~/.config/obsidian-second-brain/.env
chmod 600 ~/.config/obsidian-second-brain/.env
```

Open the file and set the vault root. The example marks this as required, and research notes are saved under it.

```bash
OBSIDIAN_VAULT_PATH=
```

Keys are added per feature. Grok powers /x-read and /x-pulse, Perplexity powers /research and /research-deep, and Gemini powers /notebooklm. Tavily and Brave are optional extra sources for the free research mode and are skipped silently when empty.

```bash
XAI_API_KEY=
PERPLEXITY_API_KEY=
GEMINI_API_KEY=
```

The README says to start with three commands: /obsidian-init to set up, /obsidian-save to capture, and /obsidian-find to recall. The other 42 exist for when you need them. A demo in DEMOS.md shows one /obsidian-save turning a conversation into five cross-linked notes: a person, a project with the decision attached, a task, a board card, and the daily note. After running it, the expected result is those five files appearing in the vault with links between them.

## Where obsidian-second-brain gets in the way

The AI-first note format is the largest commitment. Notes are structured for model retrieval, with a preamble section and frontmatter that a human reader did not design. If you have years of hand-written notes with your own conventions, the agents will be writing a different kind of file into the same folders. Nothing in the README describes a migration path for existing notes or a dry-run mode for the rewrite behaviour, so the first large save is the moment you find out how it treats what is already there.

Credentials are the second constraint. The key-less research mode exists, but the richer commands depend on paid or account-gated services. The .env.example records that Brave requires a card, with plans starting at $5 per 1,000 requests and $5 in free credits monthly as of 2026-07. Grok, Perplexity, and Gemini each need their own key from their own console.

The scheduled agents are the third. Four of them maintain the vault on a schedule, and the README describes the nightly job as consolidation. A process that rewrites your notes overnight is a real change in how you work, and the README does not document rollback for a bad consolidation run. Version control on the vault is the obvious mitigation, but the project does not state it as a requirement.

## How it differs from Obsidian's own plugins and from Karpathy's wiki

The nearest alternative is the Obsidian plugin ecosystem itself. Plugins run inside the Obsidian application and act on what you type; obsidian-second-brain runs outside it, driven by a CLI agent, and writes into the vault as files. The difference matters because the trigger is inverted. A plugin waits for you to open Obsidian; this waits for you to talk to an agent, and its scheduled agents run whether or not the Obsidian window is open.

The second alternative is Karpathy's LLM Wiki pattern, which the README credits as the origin. There, new sources append pages and cross-reference them, contradictions are flagged for you to resolve, and patterns surface only when you ask. Here, pages are rewritten in place, /obsidian-reconcile resolves contradictions, and /obsidian-synthesize writes synthesis pages on its own. The README's own summary of the difference is that if Karpathy's wiki is a knowledge base you maintain with an LLM, this is one that maintains itself. Whether that is better depends on how much you want an unsupervised writer in your notes.

A third option is simply keeping memory inside the agent, in project files or a CLAUDE.md. That keeps everything in one tool and one format, at the cost of being tied to that tool. The README's pitch is the opposite trade: the vault outlives whichever CLI you switch to.

## Maintenance, licensing and what an upgrade costs

The repository is not archived and the last push was on 2026-09-06. Releases are frequent and named: v0.13.0 The Open Standard and v0.14.0 The Harvest both landed on 2026-07-18, and v0.15.0 The Port on 2026-09-04. The v0.15.0 notes describe Windows support fixed across two contributor PRs, covering Windows paths, CRLF and BOM notes, UTF-8 handling, and a USERPROFILE-aware config home, plus Gemini-first /podcast with a free Whisper fallback, tag syntax and taxonomy checks, Simplified Chinese triggers, /obsidian-reindex, an Obsidian lint plugin, and a callout preamble.

That release cadence is the upgrade cost. Three releases in roughly two months means the command surface and note conventions can move, and the changelog is the only place that records it. The repository ships update.sh, so upgrading is a scripted step rather than a manual file copy.

Licensing is MIT, which permits commercial and private use with the licence and copyright notice retained. The .env.example states that the config file at ~/.config/obsidian-second-brain/.env is Mac-local, never committed and never synced, and should be set to permissions 600. Note that the vault itself is not covered by the licence question in the same way: whatever the agents write into it is your content, and the project does not state otherwise.

## Conclusion

Adopt it if you already keep an Obsidian vault and want Claude Code to read and write that vault instead of starting each session blank. Skip it if your notes are hand-formatted for human reading and you do not want an agent rewriting them, or if you want a hosted memory service rather than files. Before installing, confirm your vault path, decide whether the AI-first note preamble is acceptable in your existing folders, and read references/freshness-policy.md to see how the project decides which stored facts are timeless, dated, or pointers.

## FAQ

### What is the Obsidian Claude second brain?

It is a skill that gives Claude Code, Grok Bot, Codex, Gemini CLI, OpenCode, Antigravity, Hermes, and Pi persistent memory stored as plain markdown in an Obsidian vault. The README describes it as an evolution of Karpathy's LLM Wiki pattern in which new sources rewrite existing pages rather than appending new ones.

### How to set up obsidian second brain?

Run install.sh from the repository, then copy .env.example to ~/.config/obsidian-second-brain/.env, set permissions 600, and fill in OBSIDIAN_VAULT_PATH plus whichever API keys you need. The README says to start with /obsidian-init to set up, /obsidian-save to capture, and /obsidian-find to recall.

### How to use obsidian second brain?

You drive it through slash commands in your CLI agent. /obsidian-save turns a conversation into cross-linked notes, /obsidian-find recalls them, /obsidian-reconcile resolves contradictions, and /obsidian-synthesize writes synthesis pages; the README lists 45 commands in total.

### Where can I find the 2nd brain Obsidian template?

The repository includes examples/sample-vault/ alongside examples/README.md. The DEMOS.md file shows recordings made against a synthetic vault, so it is the place to look at the note structure before committing your own vault.

## Sources

- [eugeniughelbur/obsidian-second-brain on GitHub](https://github.com/eugeniughelbur/obsidian-second-brain)
- [License: MIT](https://github.com/eugeniughelbur/obsidian-second-brain/blob/main/LICENSE)
- [Project website](https://eugeniughelbur.github.io/obsidian-second-brain/)
- [README](https://github.com/eugeniughelbur/obsidian-second-brain/blob/main/README.md)
- [Releases](https://github.com/eugeniughelbur/obsidian-second-brain/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/eugeniughelbur-obsidian-second-brain