Obsidian Second Brain
Turn your Obsidian vault into persistent memory for Claude Code, Codex, and 6 other AI agents: plain markdown storage, 48 commands, self-rewriting notes, and a shared multi-agent logbook.
- Source repo
- eugeniughelbur/obsidian-second-brain
- Stars
- ★ 5k
- Last updated
- today
- License
- MIT
- Primary language
- Python
- FA score
- 66/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Developers who use Claude Code daily and want new sessions to pick up full context in seconds via /obsidian-world and CRITICAL_FACTS.md instead of re-explaining
- Not a fit if
- Users who refuse cloud model calls and want a fully offline brain
- Teams that use neither Obsidian nor the Crew shared logbook
- Light users unwilling to manage hooks, API keys, and scheduled agents
- Source review
- 66/100 · Some gaps
What does this agent do, and when should you use it?
obsidian-second-brain is an open-source (MIT) skill/plugin project that gives Claude Code, Codex CLI, Gemini CLI, OpenCode, Grok Bot, Hermes, Pi, and Google Antigravity a shared Obsidian vault as cross-session persistent memory. It extends Karpathy's LLM Wiki pattern: new sources rewrite existing pages instead of appending, contradictions are resolved automatically by /obsidian-reconcile, and /obsidian-synthesize finds unnamed patterns and writes synthesis pages on its own. It implements OKM (Open Knowledge Metabolism), a freshness spec where every stored fact must be timeless, dated, or a pointer, enforced by a linter run through /obsidian-health. v0.18 adds Crew, a shared job logbook that lets Claude Code, Codex, Cursor, and Grok Bot see what each other did in any plain folder, with agent lessons becoming rules only when a human runs keep. The project ships 49 commands on Claude Code (48 elsewhere) across four layers — operations, thinking tools, context engine, research toolkit — plus a background agent and 4 scheduled agents. Core vault commands need no API keys; research commands optionally use xAI Grok, Perplexity, Gemini, and YouTube.
Once installed, agents read and write your Obsidian vault through slash commands: /obsidian-save distributes decisions, people, tasks, and ideas from the conversation to the right notes; /obsidian-ingest ingests URLs, PDFs, Word/OpenDocument files, audio, screenshots, or YouTube videos and rewrites 5–15 vault pages; /obsidian-find performs semantic search; /obsidian-challenge argues against your idea using your own vault history; /obsidian-visualize generates a canvas map of the vault. The research layer includes /x-read and /x-pulse (Grok with live X access), /research and /research-deep (falling back to free key-less sources like Wikipedia, HackerNews, and arXiv), /notebooklm (vault-grounded synthesis via Gemini File Search), /youtube, and /podcast. The nightly scheduled agent runs five phases: close the day, reconcile contradictions, synthesize cross-source patterns, heal orphans, and rebuild the index. Each platform build is compiled from the same source tree via scripts/build.sh --platform and verified in CI by scripts/conformance_report.py — all eight builds (Agent Skills, Claude Code, Codex CLI, Gemini CLI, Grok Bot, Hermes, OpenCode, Pi) currently pass.
- Developers who use Claude Code daily and want new sessions to pick up full context in seconds via /obsidian-world and CRITICAL_FACTS.md instead of re-explaining
- Founders and operators who run /obsidian-save after a meeting to auto-file decisions, people, and tasks into project and person notes
- Content creators who use /x-pulse to scan X for trending themes and gaps, and /youtube to turn videos into AI-first notes with quotes and comment sentiment
- Researchers and analysts who use /research-deep to scan existing vault knowledge first, fill only the gaps, and get a delta report with citations
- Users of multiple agent tools who want Crew so Claude Code, Codex, Cursor, and Grok Bot each know what the others finished
- Long-term PKM builders who rely on /obsidian-health, the freshness linter, and /obsidian-merge to keep stale facts and duplicates out of the vault
How do you install or deploy this agent?
The simplest path is the Claude Code plugin marketplace:
/plugin marketplace add eugeniughelbur/obsidian-second-brain
/plugin install obsidian-second-brain@obsidian-second-brainThen point it at your vault in the env section of ~/.claude/settings.json:
"env": { "OBSIDIAN_VAULT_PATH": "/path/to/your/vault" }Restart Claude Code and run /obsidian-second-brain:obsidian-init inside your vault.
Classic script install (bare command names; requires git, uv, jq):
curl -fsSL https://raw.githubusercontent.com/eugeniughelbur/obsidian-second-brain/main/scripts/quick-install.sh | bashNo vault yet? Bootstrap one:
cd ~/.claude/skills/obsidian-second-brain
uv run python scripts/bootstrap_vault.py --path ~/Documents/MyVault --name "Your Name"
bash scripts/setup.sh ~/Documents/MyVaultFor other platforms (Codex CLI, Gemini CLI, OpenCode, Antigravity, Pi, Grok Bot, Hermes), build with bash scripts/build.sh --platform <platform> and follow dist/<platform>/INSTALL.md. Prerequisites: Python 3.10+ and uv; the research toolkit needs keys in ~/.config/obsidian-second-brain/.env (XAI_API_KEY, PERPLEXITY_API_KEY, GEMINI_API_KEY, etc.), though /research and /research-deep work key-less.
How do you use this agent?
Start Claude Code (or another host CLI) at your vault root and begin with three commands: /obsidian-init to set up the vault (generates _CLAUDE.md, index.md, log.md), /obsidian-save to capture the conversation, /obsidian-find to recall. Use the other 42+ commands as needed, e.g. /obsidian-ingest https://youtube.com/... to ingest a source and rewrite pages, /research "topic" for a cited dossier, /obsidian-daily to start the day. For Crew alone, run the quick-install script and then /crew setup, picking ~/crew or wiki/team/ in your vault; Codex users must run /hooks once to trust Crew's hooks. The background agent ships inert — arm it via hooks/postcompact.hook.example.json (it uses --dangerously-skip-permissions but restricts tools to Read/Write/Edit/Glob/Grep and loads no MCP servers); bounded recall is enabled with OBSIDIAN_RECALL_ENABLED=1.
What are this agent's strengths and limitations?
- Memory is plain markdown in your own Obsidian vault, so it outlives whichever CLI you switch to — one brain across 8 agent platforms
- Goes beyond Karpathy's append-only wiki: sources rewrite existing pages, contradictions resolve automatically, and the OKM freshness policy with a linter prevents facts-that-used-to-be-true from rotting
- Eight builds compile from one source tree and pass a CI conformance check (conformance_report.py), so cross-platform behavior is verifiable, not promised
- Core vault commands are free and key-less; /research and /research-deep fall back to free sources (Wikipedia, arXiv, HackerNews) without any API key
- Research commands and YouTube summaries depend on paid xAI, Perplexity, and Gemini APIs; /x-read, /x-pulse, /notebooklm, and /youtube require their respective keys
- Installation surface is wide: uv and Python 3.10+ are required, the classic install needs jq, .docx/.odt ingest needs LibreOffice 26.2+, and --visual needs yt-dlp + ffmpeg
- The background agent runs headless with --dangerously-skip-permissions; tool restrictions mitigate this but it must be consciously armed by the user
- Scheduled agents and hooks don't exist or degrade to manual prompts on Grok Bot and Pi, so platform feature parity is not complete
How does this agent compare with similar options?
The author explicitly positions this as an evolution of Karpathy's LLM Wiki pattern: Karpathy's approach appends new pages, flags contradictions for manual resolution, and runs on demand; this project rewrites existing pages, resolves contradictions automatically via /obsidian-reconcile, proactively writes synthesis pages via /obsidian-synthesize, maintains the vault with 4 scheduled agents, and uses an AI-first note format ("For future agent" preamble + frontmatter) instead of human-readable wiki pages.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Obsidian Second Brain This agent | 66 · Some gaps | Agent plugin / skillFree + model costs | ★ 5k | today | Python | Codex · Claude Code |
| Obsidian Wiki — A Digital Brain You Grow with Your AI Agent | 84 · Good | Agent plugin / skillFree | ★ 3.6k | 2d ago | Python | Codex · Claude Code |
| YouTube Fetcher to Markdown | 83 · Good | Agent plugin / skillFree | ★ 516 | 22d ago | Python | Codex · Claude Code |
| COG Second Brain | 64 · Some gaps | Agent plugin / skillFree + model costs | ★ 1.3k | 6d ago | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Partial least-privilege and confirmation evidence exists (read-only CI permissions; merge is dry-run by default with redirect-not-delete; lessons become rules only via human `keep`; Codex requires a `/hooks` trust step). Deducted because the 'Always On' layer — 4 scheduled agents and nightly self-rewriting of the vault — has no visible code in the snapshot showing its scope, opt-out, or hook behavior. Data flows per command are named (Perplexity, Grok, YouTube, Gemini), but private vault content sent to third-party cloud APIs has no redaction or localization policy, so sensitive-data handling stays at 1. Dependency side is supported by an OpenSSF Scorecard workflow and bounded version ranges. Karpathy's pattern is properly attributed.
The README contradicts itself: '49 Commands' heading vs '48 commands' elsewhere, and 'Start with three... the other 42' (3+42≠49); README says v0.18 while pyproject.toml says 0.20.0 — a clear deduction. Dependency availability is documented (LibreOffice 26.2+, Whisper, API versions). Failure messaging has concrete evidence ('clear embedding-backend failures', CI guards against stale conformance boards) but runtime error quality cannot be verified statically.
Audience and scenarios are thorough: 4 role presets and layered personas. Environment fit is strong: a dedicated Windows CI job citing specific past Windows-only bugs (#308, WSL bash, CRLF/BOM), multi-platform adapters, and a conformance board. Capability boundaries are partially documented (crew.md limits, explicitly out-of-scope formats), but most boundaries live in linked files not present in the snapshot. Trigger precision has a multilingual trigger schema and adversarial tests for description-based skill selection, though coverage is narrow.
Information architecture is excellent: 4 command layers, references/, a generated docs site with CI-enforced freshness. License is a complete MIT text — full marks. Install notes exist but use a `curl | bash` pipe of a remote script, a practice worth deducting for. Versioning links a CHANGELOG but version numbers disagree (0.18 vs 0.20.0). Maintenance responsibility is supported by SECURITY.md response SLAs and a stated solo maintainer — adequate, not more. Naming is consistent (/obsidian-* prefix). Limitations are scattered and partly behind external links.
Output shapes are described in detail (five cross-linked notes, dossier structure, delta reports), but these are all static claims with no execution evidence, hence a conservative score. Marginal value is well argued (real cross-session memory pain point; a concrete delta table vs Karpathy's pattern). Cost-benefit scores 1: usage costs of paid APIs (Perplexity Sonar Pro etc.) are unquantified; free tiers are mentioned only in passing.
Claim traceability is decent: many claims link to references/ and CHANGELOG, and demos are honestly labeled 'Real footage, synthetic vault'. Cross-source corroboration earns full marks: CI enforces that the conformance board matches real builds and that the docs site matches command files, and tests cite specific issue numbers — strong intra-repo mutual verification. Fact/inference separation is middling: marketing language ('vault compounds while you sleep', star/clone counts) is interleaved with functional facts, and effectiveness claims mostly lack checkable citations.
- Installation pipes a remote script straight into bash (`curl | bash`); review scripts/quick-install.sh before running it.
- Private vault content is sent to third-party cloud APIs (Perplexity, xAI, Google) with no stated redaction policy — assess before use with sensitive material.
- The 'Always On' scheduled agents rewrite your notes nightly; their code and opt-out mechanism are not present in the reviewed files — verify hooks and scheduling before enabling.
- Version numbers conflict (README v0.18 vs pyproject 0.20.0) and command counts are internally inconsistent (49/48/42); discount documentation claims accordingly.
- Publisher is an unverified solo maintainer; the response SLAs in SECURITY.md are unverified promises.