claude-obsidian: Self-Organizing AI Second Brain for Obsidian + Claude Code

Claude + Obsidian knowledge companion and self-organizing AI second brain. A running AI notetaker that builds and maintains a persistent, compounding wiki vault. Every source you add gets integrated. Every question you ask pulls from everything that has been read. Knowledge compounds like interest.

Open-source Obsidian AI plugin for AI note-taking, personal knowledge management (PKM), second-brain workflows, and a private Notion alternative. 15 Claude Code skills, multi-agent support, multi-writer safe (v1.7+), first-class methodology modes (LYT / PARA / Zettelkasten / Generic via v1.8), and the 10-principle thinking framework (v1.9). Based on Andrej Karpathy's LLM Wiki pattern.

Two ways to get this skill. Pick the one that fits how you work.

• 🌐 Public open-source build (latest: v1.9.2, recommended): the free, MIT-licensed release on Daniel Agrici's GitHub. Open to anyone, no membership required. Ships everything: v1.7 Compound Vault, v1.8 methodology modes, and the v1.9 thinking framework plus audit hardening.
• ⚡ AI Marketing Hub Pro: the same MIT-licensed core, plus earliest access to in-development features before they land here, direct collaboration, and the Pro community. Pro members install from the AI Marketing Hub org mirror (swap note under Option 2 below).

✨ v1.7 "Compound Vault" refoundation: Obsidian CLI as default transport, hybrid retrieval (contextual prefix + BM25 + cosine rerank per Anthropic's Sept 2024 research), per-file advisory locking that closes a latent multi-writer corruption hole, and substrate alignment with kepano/obsidian-skills. Full guide: docs/compound-vault-guide.md. Optional DragonScale Memory extension (log folds, deterministic page addresses, semantic tiling lint, boundary-first autoresearch).

Contents

• What It Does
• Why claude-obsidian?
• Quick Start
• Commands
  • /wiki: setup, scaffold, continue
  • /autoresearch: autonomous research loop
  • /canvas: visual layer
  • /think: 10-principle thinking loop
• Methodology Modes (v1.8+)
• Vault Use Cases (v1.0+)
• Cross-Project Knowledge Base
• What Gets Created
• Architecture
• MCP Setup (Optional)
• Plugins
• CSS Snippets
• Banner Plugin
• File Structure
• AutoResearch Configuration
• Seed Vault
• Companion: claude-canvas
• FAQ
• Requirements
• Uninstall
• Contributing
• Related Projects
• Community
• License

What It Does

YouTube Demo

You drop sources. Claude reads them, extracts entities and concepts, updates cross-references, and files everything into a structured Obsidian vault. The wiki gets richer with every ingest.

You ask questions. Claude reads the hot cache (recent context), scans the index, drills into relevant pages, and synthesizes an answer. It cites specific wiki pages, not training data.

You lint. Claude finds orphans, dead links, stale claims, and missing cross-references. Your wiki stays healthy without manual cleanup.

At the end of every session, Claude updates a hot cache. The next session starts with full recent context, no recap needed.

Why claude-obsidian?

Most Obsidian AI plugins are chat interfaces. They answer questions about your existing notes. claude-obsidian is a knowledge engine. It creates, organizes, maintains, and evolves your notes autonomously.

📖 Deep dive: I Turned Obsidian Into a Self-Organizing AI Brain. Full breakdown with data visualizations, market context, and workflow demos.

Quick Start

ℹ️ The commands below install the public open-source build from AgriciDaniel/claude-obsidian (recommended, no membership needed). AI Marketing Hub Pro members who want early access to in-development features can swap AgriciDaniel/claude-obsidian for AI-Marketing-Hub/claude-obsidian (Option 2 also swaps the plugin slug; see the note under that option).

Option 1: Clone as vault (recommended, full setup in 2 minutes)

git clone https://github.com/AgriciDaniel/claude-obsidian
cd claude-obsidian
bash bin/setup-vault.sh

Open the folder in Obsidian: Manage Vaults → Open folder as vault → select claude-obsidian/.

Open Claude Code in the same folder. Type /wiki.

ℹ️ setup-vault.sh configures graph.json (filter + colors), app.json (excludes plugin dirs), and appearance.json (enables CSS). Run it once before the first Obsidian open. You get the fully pre-configured graph view, color scheme, and wiki structure out of the box.

Option 2: Install as Claude Code plugin

Plugin installation is a two-step process. First add the marketplace catalog, then install the plugin from it.

ℹ️ Which version are you installing?

• Public (recommended, no membership): the commands below install the free, MIT-licensed release from AgriciDaniel/claude-obsidian. Nothing to sign up for.
• AI Marketing Hub Pro member? For early access to in-development features, swap AgriciDaniel/claude-obsidian for AI-Marketing-Hub/claude-obsidian and the plugin slug claude-obsidian@agricidaniel-claude-obsidian for claude-obsidian@ai-marketing-hub-claude-obsidian. The org mirror requires an authenticated gh auth login (or GitHub PAT) with access to the AI-Marketing-Hub org. If /plugin marketplace add returns a 404, your account is not in the org yet. DM in the Skool community to get added.

# Step 1: add the marketplace
claude plugin marketplace add AgriciDaniel/claude-obsidian

# Step 2: install the plugin
claude plugin install claude-obsidian@agricidaniel-claude-obsidian

In any Claude Code session: /wiki. Claude walks you through vault setup.

To check it worked:

claude plugin list

Option 3: Add to an existing vault

Copy WIKI.md into your vault root. Paste into Claude:

Read WIKI.md in this project. Then:
1. Check if Obsidian is installed. If not, install it.
2. Check if the Local REST API plugin is running on port 27124.
3. Configure the MCP server.
4. Ask me ONE question: "What is this vault for?"
Then scaffold the full wiki structure.

Commands

✨ Want more? claude-canvas adds 12 templates, 6 layout algorithms, AI image generation, presentations, and full canvas orchestration. Install both, they complement each other.

/wiki: setup, scaffold, continue

First-run setup walks through:

1. Check Obsidian is installed
2. Check Local REST API plugin (if MCP transport desired)
3. Ask "What is this vault for?" (one question, drives the scaffold)
4. Scaffold per chosen Methodology Mode and Vault Use Case
5. Seed hot.md, index.md, log.md, wiki/meta/dashboard.base
6. Suggest the first ingest

On subsequent runs, /wiki continues where you left off. It checks vault health, surfaces stale claims, and shows recent activity from hot.md.

/autoresearch: autonomous research loop

Configurable program at skills/autoresearch/references/program.md:

• Max rounds (default 3)
• Max pages per session (default 15)
• Source preference rules (academic, official docs, news)
• Confidence scoring + domain constraints

The loop:

1. Round 1, broad search: decompose into 3-5 angles, run 2-3 queries per angle, fetch top 2-3 results per angle
2. Round 2, gap fill: targeted searches for contradictions and missing pieces
3. Round 3, synthesis check (optional): one more pass if major gaps remain
4. Filing: synthesis page + source pages + entity pages + concept pages, all cross-referenced

URL validation + content sanitization applied per the ## Web egress hygiene (v1.8.2+) policy in skills/autoresearch/SKILL.md: rejects file:// / javascript: / RFC1918 hosts, strips <script> and wikilink-injection attempts, caps fetch bodies at 50KB.

/canvas: visual layer

Add images, PDFs, notes, and AI-generated images to an Obsidian canvas. Zone management for grouping. Auto-layout positions nodes without overlap.

/canvas                       # open or create the canvas
/canvas add image <path>      # add an image with auto-layout
/canvas add pdf <path>        # render PDF as preview node
/canvas add note <wiki-page>  # pin a wiki page as a linked card
/canvas zone <name>           # add a labeled zone
/canvas from banana           # capture recent banana-generated images

JSON Canvas 1.0 spec compliant (skills/canvas/references/canvas-spec.md). Full orchestration (12 templates, 6 layout algorithms, presentations) in the companion claude-canvas.

/think: 10-principle thinking loop

Apply the OBSERVE-OBSERVE-LISTEN-THINK-CONNECT-CONNECT-FEEL-ACCEPT-CREATE-GROW framework to any non-trivial problem (architectural decisions, audits, post-mortems, ambiguous user requests).

/think <problem statement>

The framework walks Claude through 10 stages with prompts at each. Use when problem novelty + irreversibility justify the discipline. See skills/think/SKILL.md for the full framework. Every other skill has a "How to think" appendix mapping the framework to its specific work. The v1.8.0 pre-push audit used this framework as its methodology spine.

Methodology Modes (v1.8+)

Four organizational philosophies, opt-in via bash bin/setup-mode.sh. The wiki-mode skill (v1.8+) reads .vault-meta/mode.json and routes new pages accordingly. Default is generic (v1.7 behavior, no opinion imposed).

Switching modes does NOT auto-migrate existing files. Full guide: docs/methodology-modes-guide.md.

Vault Use Cases (v1.0+)

These describe what your vault is for. They compose with Methodology Modes (which describe how it is organized).

Use cases can be combined. A Business + Research vault organized in PARA is a valid composition.

Cross-Project Knowledge Base

Point any Claude Code project at this vault. Add to that project's CLAUDE.md:

## Wiki Knowledge Base
Path: ~/path/to/vault

When you need context not already in this project:
1. Read wiki/hot.md first (recent context cache)
2. If not enough, read wiki/index.md
3. If you need domain details, read the relevant domain sub-index
4. Only then drill into specific wiki pages

Do NOT read the wiki for general coding questions or tasks unrelated to [domain].

Your executive assistant, coding projects, and content workflows all draw from the same knowledge base.

What Gets Created

A typical scaffold creates:

• Folder structure for your chosen use case + methodology mode
• wiki/index.md: master catalog
• wiki/log.md: append-only operation log
• wiki/hot.md: recent context cache
• wiki/overview.md: executive summary
• wiki/meta/dashboard.base: Bases dashboard (primary, native Obsidian)
• wiki/meta/dashboard.md: Legacy Dataview dashboard (optional fallback)
• _templates/: Obsidian Templater templates for each note type
• .obsidian/snippets/vault-colors.css: color-coded file explorer
• Vault CLAUDE.md: auto-loaded project instructions

Architecture

Three diagrams explain the substantive design choices of the plugin.

Vault flow

Sources land in .raw/. The /wiki-ingest agent reads each source, extracts entities and concepts, files them into the appropriate wiki/ subfolder (per active methodology mode), and updates the index, log, and hot cache. Queries read hot → index → pages in that order to keep token cost low.

Multi-writer safety (v1.7+)

Parallel ingest sub-agents can target the same wiki page if the user batches multiple sources. scripts/wiki-lock.sh provides per-file advisory locks: one writer acquires, the other waits and retries on the next pass. The PostToolUse auto-commit hook checks the lock list before staging, deferring the commit while writes are in flight.

Hybrid retrieval (v1.7+, opt-in)

The /wiki-retrieve skill ships a three-tier retrieval pipeline based on Anthropic's Sept 2024 contextual retrieval research. BM25 is the always-on sparse layer. The contextual-prefix tier is consent-gated (--allow-egress) for users who want to send page bodies to the Anthropic API for prefix generation. Cosine rerank uses a local ollama model by default. The 50-query benchmark in v1.7 measured +32 percentage points top-1 accuracy and +41 percent error reduction vs the v1.6 baseline.

ℹ️ Provision the pipeline with bash bin/setup-retrieve.sh. It builds the BM25 index, prompts for egress consent, and validates the ollama connection. The pipeline degrades gracefully: if any tier is unavailable, the rest still return useful results.

MCP Setup (Optional)

MCP lets Claude read and write vault notes directly without copy-paste.

Option A (REST API based):

1. Install the Local REST API plugin in Obsidian
2. Copy your API key
3. Run:

claude mcp add-json obsidian-vault '{
  "type": "stdio",
  "command": "uvx",
  "args": ["mcp-obsidian"],
  "env": {
    "OBSIDIAN_API_KEY": "your-key",
    "OBSIDIAN_HOST": "127.0.0.1",
    "OBSIDIAN_PORT": "27124",
    "NODE_TLS_REJECT_UNAUTHORIZED": "0"
  }
}' --scope user

Option B (filesystem based, no plugin needed):

claude mcp add-json obsidian-vault '{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@bitbonsai/mcpvault@latest", "/path/to/your/vault"]
}' --scope user

ℹ️ Both transports are auto-detected by scripts/detect-transport.sh. The result lands in .vault-meta/transport.json. To pin a manual choice, edit that file and set "manual_override": true (v1.8.2+ honors it).

Plugins

Core Plugins (built into Obsidian, no install needed)

Pre-installed Community Plugins (ship with this vault)

Enable in Settings → Community Plugins → enable:

* Excalidraw main.js (8MB) is downloaded automatically by setup-vault.sh. It is not tracked in git.

Also install from Community Plugins (not pre-installed)

Also install the Obsidian Web Clipper browser extension. Sends web pages to .raw/ in one click.

CSS Snippets (auto-enabled by setup-vault.sh)

Three snippets ship with the vault and are enabled automatically:

Banner Plugin

Add to any wiki page frontmatter:

banner: "_attachments/images/your-image.png"
banner_icon: "🧠"

The page renders a full-width header image in Obsidian. Works great for hub pages and overviews.

File Structure

claude-obsidian/
├── .claude-plugin/
│   ├── plugin.json              # manifest
│   └── marketplace.json         # distribution
├── skills/                       # 15 Claude Code skills (v1.9.2)
│   ├── wiki/                    # orchestrator + references
│   ├── wiki-ingest/             # source ingestion
│   ├── wiki-query/              # answer questions from the vault
│   ├── wiki-lint/               # vault health check
│   ├── wiki-cli/                # Obsidian CLI transport (v1.7+)
│   ├── wiki-retrieve/           # hybrid retrieval (v1.7+, opt-in)
│   ├── wiki-mode/               # methodology modes router (v1.8+)
│   ├── wiki-fold/               # log rollup (DragonScale opt-in)
│   ├── save/                    # /save: file conversations to wiki
│   ├── autoresearch/            # autonomous research loop
│   ├── canvas/                  # visual layer (images, PDFs, notes)
│   ├── defuddle/                # web extraction wrapper
│   ├── obsidian-bases/          # Bases schema reference
│   ├── obsidian-markdown/       # OFM syntax reference
│   └── think/                   # 10-principle thinking framework (v1.9+)
├── agents/
│   ├── verifier.md              # pre-commit audit agent (v1.7.1+)
│   ├── wiki-ingest.md           # parallel batch ingestion agent
│   └── wiki-lint.md             # health check agent
├── commands/                     # slash command entry points
├── hooks/
│   └── hooks.json               # SessionStart + Stop + PostToolUse hooks
├── scripts/                      # 12 helper scripts (transport, locking, retrieval, etc.)
├── tests/                        # 9 hermetic test suites (~1240 assertions, make test)
├── bin/                          # 5 setup scripts (setup-vault, setup-retrieve, setup-mode, etc.)
├── _templates/                   # Obsidian Templater templates
├── wiki/                         # seeded vault content (demo)
│   ├── canvases/                # welcome.canvas + main.canvas
│   ├── concepts/                # seeded: LLM Wiki Pattern, Hot Cache, Compounding Knowledge
│   ├── entities/                # seeded: Andrej Karpathy
│   ├── sources/                 # populated by your first ingest
│   └── meta/
│       ├── dashboard.base       # Bases dashboard (primary)
│       └── dashboard.md         # Legacy Dataview dashboard (optional)
├── docs/                         # guides + audits + release notes
├── .raw/                         # source documents (hidden in Obsidian)
├── .obsidian/snippets/           # vault-colors.css (3-color scheme)
├── WIKI.md                       # full schema reference
├── CLAUDE.md                     # project instructions
└── README.md                     # this file

AutoResearch: program.md

The /autoresearch command is configurable. Edit skills/autoresearch/references/program.md to control:

• What sources to prefer (academic, official docs, news)
• Confidence scoring rules
• Max rounds and max pages per session
• Domain-specific constraints

The default program works for general research. Override it for your domain. A medical researcher would add "prefer PubMed". A business analyst would add "focus on market data and filings".

Seed Vault

This repo ships with a seeded vault. Open it in Obsidian and you will see:

• wiki/concepts/: LLM Wiki Pattern, Hot Cache, Compounding Knowledge
• wiki/entities/: Andrej Karpathy
• wiki/sources/: empty until your first ingest
• wiki/meta/dashboard.base: Bases dashboard (works in any Obsidian v1.9.10+)
• wiki/meta/dashboard.md: Legacy Dataview dashboard (optional fallback)

The graph view will show a connected cluster of 5 pages. This is what the wiki looks like after one ingest. Add more sources and it grows from there.

Companion: claude-canvas

For the visual layer, claude-canvas adds AI-orchestrated canvas creation: knowledge graphs, presentations, flowcharts, mood boards with 12 templates and 6 layout algorithms. Auto-detects claude-obsidian vaults.

claude plugin install AgriciDaniel/claude-canvas

FAQ

What is the best AI second brain app? The best AI second brain keeps your data yours. claude-obsidian stores everything as plain Markdown files you own (no database, no lock-in, no subscription) and lets Claude read, link, and organize them into one connected knowledge graph. It is free and open source (MIT).

How do I build a second brain with AI? Drop any source into the vault. Claude reads it, extracts the entities and concepts, links them to what you already have, and files it into a structured Obsidian vault. You ask questions; it answers from everything it has read and cites the pages. The knowledge base gets richer and more connected with every session.

How do I connect Claude to Obsidian as a second brain? Two lines: git clone https://github.com/AgriciDaniel/claude-obsidian, then cd claude-obsidian && bash bin/setup-vault.sh. Open the folder as an Obsidian vault, open Claude Code in the same folder, and type /wiki. Full steps in Quick Start.

Is there a good Notion alternative for a private, AI-powered knowledge base? Yes. claude-obsidian is an open-source, local-first alternative: your notes are plain Markdown on your own disk instead of a hosted database, and AI organizes them for you. No vendor lock-in and no monthly fee.

Does this auto-sync across devices? Not on its own. The vault is a plain folder of Markdown files. Pair with Obsidian Sync, Obsidian Git, or any file-sync tool (Syncthing, iCloud, Dropbox) for cross-device sync.

Can multiple people edit the same vault safely? Yes (v1.7+). Per-file advisory locking via scripts/wiki-lock.sh prevents concurrent writes from corrupting pages. Parallel ingest sub-agents acquire locks before writes. Stale locks self-reap after 60 seconds.

What is the difference between hot.md and index.md? hot.md is the recent-context cache (~500 words, refreshed each session). index.md is the master catalog of every page in the vault. Claude reads hot.md first, then index.md, then drills into specific pages. The two-layer design keeps token cost low for repeat queries.

Can I use this without Claude Code? The skills are Agent Skills compatible (experimental support for OpenAI Codex CLI, Cursor, Windsurf, Gemini CLI, Goose). Production verification is only on Claude Code today. Cross-host install paths follow each host's conventions but skill discovery may differ.

How do I migrate from Dataview to Bases? Both ship side-by-side. wiki/meta/dashboard.base is the primary; wiki/meta/dashboard.md is the legacy Dataview fallback. Pick one in Obsidian, the other is harmless. Bases requires Obsidian v1.9.10+ (August 2025).

What is the difference between Methodology Modes (LYT/PARA/Zettelkasten) and Vault Use Cases (Website/GitHub/Business)? Methodology Modes (v1.8+) control how pages are organized: folder structure + filename conventions. Vault Use Cases (v1.0+) describe what the vault is for: content type. They compose. A "Business" vault using PARA methodology is a valid configuration.

Does this send my notes to Anthropic? No by default. The optional /wiki-retrieve skill has API egress (contextual-prefix.py) gated behind the --allow-egress consent flag. Without that flag, retrieval is fully local (BM25 + optional ollama rerank). Web egress in /autoresearch follows the same opt-in principle.

What is the difference between the public build and AI Marketing Hub Pro? Both share the same MIT-licensed core on AgriciDaniel/claude-obsidian, which is the recommended install for everyone. AI Marketing Hub Pro members get earliest access to in-development features before they ship here, plus direct collaboration and the community. There are no paid-only features in the core.

What is DragonScale Memory? An optional opt-in extension (bash bin/setup-dragonscale.sh) that adds four memory mechanisms: log folds (rollup of past entries), deterministic page addresses (counter-based unique IDs), semantic tiling lint (chunk-boundary validation via ollama), and boundary-first autoresearch (research the vault's "frontier" first). Not required for normal use. Full guide: docs/dragonscale-guide.md.

Requirements

Optional:

• ollama (for local rerank in /wiki-retrieve)
• defuddle-cli (for clean web extraction in /defuddle)
• Anthropic API key (for /wiki-retrieve contextual prefix tier, opt-in via --allow-egress)
• Local REST API plugin (for the REST-API MCP transport)

Uninstall

Plugin install:

claude plugin uninstall claude-obsidian@agricidaniel-claude-obsidian
claude plugin marketplace remove AgriciDaniel/claude-obsidian

Clone install (delete the folder):

rm -rf /path/to/claude-obsidian

Your vault content (under wiki/) is plain Markdown and survives uninstall. To clear the runtime state without uninstalling, run make clean-test-state from the repo root.

Contributing

PRs welcome. Read these first:

• CONTRIBUTING.md: workflow, six-cut self-review checklist, commit conventions, hermetic test requirements
• CODE_OF_CONDUCT.md: Contributor Covenant v2.1
• SECURITY.md: responsible security disclosure policy
• CHANGELOG.md: version history (latest: v1.9.2)

Issue + PR templates available under .github/. CI runs make test + SKILL.md frontmatter validation + plugin manifest JSON validity on every PR. The pre-commit verifier agent at agents/verifier.md applies the six-cut + agent kernel to staged diffs.

Related Projects

• 🎨 claude-canvas: visual canvas orchestration (12 templates, 6 layout algorithms, AI image generation). Companion to this plugin.
• 📊 claude-ads: multi-platform paid advertising audit (250+ checks across Google, Meta, LinkedIn, TikTok, Microsoft, Apple, Amazon Ads).
• 🔍 claude-seo: technical SEO + GEO audit suite.
• 🧠 best-practices: composable engineering kernel. Source for the six-cut + agent kernel that agents/verifier.md enforces.

Community

• 📝 Blog post: deep dive with competitor analysis, data charts, and workflow demos
• 💬 AI Marketing Hub: 2,800+ members, free community
• ⚡ AI Marketing Hub Pro: early access to in-development features and direct collaboration
• 🎬 YouTube: tutorials and demos
• 🔧 All open-source tools: claude-seo, claude-ads, claude-blog, and more

License

MIT License. See LICENSE for full text. Free for personal and commercial use. Attribution appreciated but not required.

Star History

Based on Andrej Karpathy's LLM Wiki pattern. Built by Agrici Daniel. Compounding knowledge is the highest-leverage habit a thinking person can build.