One Obsidian vault, 8 AI agents, one shared memory that cleans itself every night. Here's the complete manual.

Full version with every update: https://theaioperator.io/p/build-an-obsidian-second-brain-every

TL;DR

obsidian-second-brain turns one Obsidian vault into shared memory for Claude Code, Codex, Grok Bot and 5 more agents.
You install it in 5 minutes, then use three commands: init, save and find.
Every night an agent fixes old facts, links loose notes and rebuilds the index, so every session starts clean.

Last updated: October 14, 2026. This is the living manual. Every new feature lands here first.

Every AI agent forgets you when the session ends. Your projects, your decisions, the people you work with. Gone, and you explain it all again tomorrow.

For a team, that costs hours a week in repeated context. It also means the same bad call gets made twice, because nobody wrote down why it failed.

I built obsidian-second-brain to fix that for myself. Over 4,700 developers have starred it since. This post is the whole manual: what it is, which agents it works with, how to install it and what each part does.

What obsidian-second-brain is

It's an open-source skill that turns an Obsidian vault into memory your AI agents read and write. A skill is a set of instructions and scripts an agent loads to do a job.

The vault is plain markdown files on your disk. No database, no cloud account, no lock-in. If you stop using the skill, your notes stay readable.

It started from Andrej Karpathy's LLM Wiki pattern, where an AI keeps a wiki for you. This skill takes the idea further in one direction: a new source rewrites the pages it touches instead of adding a new page next to them. I wrote about why in Claude Code as a Second Brain: What the Tutorials Skip.

Which AI agents it works with

One codebase compiles into 8 builds. The vault behaves the same in all of them. Only the install path changes.

Claude Code, the default, installed as a plugin.
Codex CLI, OpenAI's coding agent.
Grok Bot, xAI's AI teammate (not the Grok chat app).
Gemini CLI, Google's command-line agent.
OpenCode, the open-source coding agent.
Hermes, Nous Research's agent.
Pi, the Pi coding agent.
Agent Skills, the open standard that Antigravity, Codex, OpenCode and GitHub Copilot CLI all read.

Each build is checked in CI on every push. CI means the automatic tests that run on every change.

The repo also ships an MCP server. MCP is the standard way AI apps plug into outside tools. Any MCP client, such as Claude Desktop or Cursor, can search, read and save notes through it.

I run my own vault across several of these at once. Notes one agent writes, the next one reads. More on that in I Run My Second Brain on Four AI CLIs.

How to install it in 5 minutes

For Claude Code:

Open any Claude Code session.
Run: /plugin marketplace add eugeniughelbur/obsidian-second-brain.
Run: /plugin install obsidian-second-brain@obsidian-second-brain.
Set OBSIDIAN_VAULT_PATH to your vault folder in your Claude Code settings.
Restart, then run: /obsidian-second-brain:obsidian-init inside the vault.

Init asks which preset fits you: developer, founder or operator, writer, or researcher. It builds the folders and the vault manual from that answer.

The other builds have their own install section in the README. Windows works the same as macOS and Linux since v0.15.

The three commands to start with

The skill ships 47 commands. You need three on day one:

/obsidian-init sets up the vault and writes its operating manual.
/obsidian-save pulls every decision, person, task and idea out of the conversation and files each one in the right note.
/obsidian-find searches the vault and answers with context, not only file names.

One /obsidian-save after a meeting writes about five linked notes: the person, the project with the decision, the task, the board card and the daily note. You never open Obsidian to do it.

What happens while you sleep

Four agents run on a schedule:

Morning brief pulls your calendar, overdue tasks and overnight changes into today's note.
Nightly cleanup runs five steps: closes the day, fixes contradictions, finds patterns across sources, links orphan notes and rebuilds the index.
Weekly review summarizes the week from the vault's own history.
Health check flags duplicates, broken links and stale claims.

Devin from Cognition added a nightly memory cleanup in October 2026 and called it Dreaming. This vault has run one since April. The effect is the same: the next session starts from clean notes, not a pile.

How it learns from what you read

/obsidian-ingest takes a URL, PDF, voice memo or screenshot. It doesn't write one summary note. It updates the 5 to 15 pages the source touches: people, projects, concepts and the claims that changed.

Seven research commands feed the vault:

/research and /research-deep for sourced web research, vault first.
/x-read and /x-pulse for X posts and what's trending.
/youtube and /podcast for transcripts and summaries.
/notebooklm for answers grounded only in your own notes.

Every finding saves to the vault, so you never research the same thing twice.

Tools that argue with you

A second brain that only agrees with you is a diary. These commands push back:

/obsidian-challenge finds your past failures on the same topic before a big decision.
/obsidian-emerge surfaces patterns from the last 30 days you never named.
/obsidian-reconcile finds notes that contradict each other and resolves them.
/obsidian-brainstorm interviews you one question at a time until an idea is sharp.

Why the notes are written for agents

Every note follows the AI-first rule. It opens with a short "For future agent" summary, then frontmatter, dates on every claim, links and sources. Agents read the summary first and skip the rest when it doesn't apply.

Facts carry two dates: when they were true and when the vault learned them. So an old fact doesn't overwrite a new one by accident. A file called CRITICAL_FACTS.md loads who you are in about 120 tokens at the start of every session.

This is why you don't need a vector database. I explained the trade-off in How I gave Claude Code memory without a vector DB.

What's new

This section changes with each release:

October 2026 (in progress): German commands, CI on Windows, company and tool notes count as entities in search.
v0.17, The Neighbors (September 26): the skill now knows when another Obsidian plugin writes to the same vault, and says whose rules apply.
v0.16, The Silent Failure (September 15): checks that stayed quiet when something broke now speak up.
v0.15, The Port (September): full Windows support, contributed across two pull requests.

The project has 18+ outside contributors and a test suite of over 700 tests that runs on every change.

Frequently asked questions

What is an Obsidian second brain?It's an Obsidian vault an AI agent keeps for you. The agent saves decisions, people and research into linked notes and reads them back in later sessions.

Does obsidian-second-brain work without Claude Code?Yes. It has builds for Codex CLI, Grok Bot, Gemini CLI, OpenCode, Hermes, Pi and any Agent Skills tool like Antigravity. MCP clients such as Cursor connect through its MCP server.

Is obsidian-second-brain free?Yes. It's MIT licensed. The core vault commands need no API keys. Research commands use your own Perplexity, Grok or Gemini keys if you add them.

Do I need a vector database for AI memory in Obsidian?No. The vault uses plain markdown, links, frontmatter and a rebuilt index. Agents find notes by search and links.

How do I give Claude Code persistent memory?Install the plugin, point OBSIDIAN_VAULT_PATH at your vault and run /obsidian-init. Every session then loads the vault's manual and critical facts at start.

Does it work on Windows?Yes. Since v0.15 it handles Windows paths, line endings and encodings the same as macOS and Linux.

Key takeaways

One Obsidian vault can serve as shared memory for 8 agent builds plus any MCP client.
Plain markdown beats a database for personal AI memory: readable, portable and free.
A nightly cleanup agent keeps memory useful by fixing old facts and linking loose notes.
New sources should rewrite existing pages, not pile new ones on top.
Notes written for agents load faster: a short summary first, then dated claims and sources.
Three commands cover day one: init, save and find.

Keep up with updates

This manual gets a new section with every release. The canonical, always-current version lives on The AI Operator: https://theaioperator.io/p/build-an-obsidian-second-brain-every

Subscribe there to get each update the day it ships.

Build an Obsidian Second Brain Every AI Agent Can Use

Job breakdowns