Who claude-obsidian is for#
Researchers building a literature review base
Drop local files and transcripts into the inbox folder. wiki-ingest extracts named entities, creates concept pages, and cross-references every new source against what is already in the vault. The /autoresearch skill runs up to 12 pages of bounded web research hands-free. The result is an Obsidian graph of a literature base the AI maintains without manual linking.
Skip if:
Your primary sources are PDFs that require full-text semantic extraction. Built-in PDF support covers metadata and file hash only; semantic extraction requires configuring an external runner before ingestion works as expected.
Developers managing technical knowledge graphs
Run claude-obsidian from Claude Code or a compatible Agent Skills host against a vault of architecture notes, decision records, and code context. The hot cache restores working memory at session start so you spend no tokens re-establishing where you left off. wiki-query answers questions from evidence already in the vault rather than hallucinating from training data.
Skip if:
You need real-time hosted collaboration for a team. claude-obsidian is a local-first, single-vault tool; concurrent multi-user editing is not its design target.
Solopreneurs replacing cloud PKM subscriptions
The four methodology modes (LYT, PARA, Zettelkasten, Generic) let you bring your existing filing convention or adopt a new one without bulk-moving existing notes. The vault is Markdown on disk: version-control it with Git, back it up like any folder, and open it in Obsidian without an internet connection. No per-seat pricing, no feature tiers, no lock-in.
Skip if:
You rely on shared team workspaces with concurrent editing, inline comments, and a hosted web interface for non-technical collaborators. Paid tools like Notion remain better suited for that collaboration model.
The problem it solves#
Personal knowledge bases fail quietly. Notes go in, but links never get made, tags drift, and six months later the vault is a graveyard you feel guilty about. The bottleneck is not method; every PKM system recommends the same techniques (Zettelkasten, PARA, bidirectional links). The bottleneck is maintenance: linking each new note to every related concept, keeping the index current, and flagging when a new source contradicts what you already believed.
Paid tools like Notion and Mem move this work to a hosted service, which solves the maintenance challenge but creates a new one: your knowledge lives in their database, under their export rules, at their price point. AI note-taking features on those platforms still require you to organize and tag; they assist the filing rather than replacing it. The result is the same abandoned vault, now in a proprietary format.
How it solves it#
15-skill knowledge operating system
Ships 15 skills covering the full PKM lifecycle: /wiki scaffolds a vault from a description, /wiki-ingest turns raw sources into linked pages, /wiki-query answers questions from existing vault evidence, /autoresearch runs bounded web research up to 12 pages hands-free, /canvas builds visual reference boards in Obsidian Canvas, and /think runs a structured reasoning loop. Skills share one provenance model so every ingested source traces back to its origin.
Zero-database local-first storage
The vault is a plain directory of Markdown, JSON, and source files. No embeddings server, no vector index to maintain, no background worker consuming RAM. Retrieval uses deterministic BM25 keyword search by default, with optional contextual prefixes and cosine reranking when you enable an external model. Files remain readable in Obsidian, a text editor, or the terminal with no AI running at all.
Hot cache for session continuity
Every new AI conversation starts with total amnesia. claude-obsidian keeps a hot cache file holding roughly 500 words of recent context: what you were working on, key decisions made, which pages changed, and open next steps. The plugin reads this at session start, restoring working memory for roughly 500 tokens instead of the 2,000 to 3,000 you would otherwise spend re-establishing context.
Transaction-safe vault writes
One knowledge operation is one recoverable transaction. The system reads every target file and records its SHA-256, lets parallel workers produce drafts, merges changes into one bundle, inspects the bundle, then applies it once. A changed target is a conflict, not a silent overwrite. Interrupted operations recover to the prior state via a single CLI command.
Four methodology modes
wiki-mode routes new notes using LYT (Maps of Content and linked atomic notes), PARA (Projects, Areas, Resources, Archives), Zettelkasten (stable identifiers and atomic notes), or Generic (sources, concepts, entities, and sessions). Switching modes changes how new notes are filed without silently reorganizing existing knowledge.
Hybrid retrieval with BM25 and reranking
wiki-retrieve combines contextual prefixes, BM25 keyword search, and optional cosine reranking. Anthropic's contextual retrieval research, cited in the project, cut retrieval failures by up to 49% and up to 67% with reranking. BM25 runs locally and deterministically; remote reranking is gated by explicit egress consent so the default setup never phones home.
Strengths and trade-offs#
Strengths
- Plain Markdown you own permanentlyEvery page the plugin writes is a normal Markdown file in your Obsidian vault directory. You can read it, move it, version-control it with Git, or open it in Notepad ten years from now. Unlike Notion, Mem, or Reflect, there is no proprietary export format, no API dependency, and no service that can hold your knowledge hostage.
- No cloud dependency in the default setupThe core runs entirely on local files. Retrieval uses deterministic BM25 with no vector index to maintain, no third-party database bill, and no background worker eating RAM. External model calls for contextual prefixes or cosine reranking are optional and gated by explicit egress consent, so the default setup has zero ongoing cloud cost beyond the Claude API calls you initiate.
- Knowledge compounds with every source addedWhen you ingest a new source, the plugin cross-references it against every existing wiki page. The 50th source you add weaves new notes into a mesh of existing pages, making each subsequent answer sharper. This compounding behavior is the core premise of the Karpathy LLM Wiki pattern the project implements.
- Multi-agent-safe vault lockingPer-file advisory locking lets multiple agents ingest concurrently without corrupting the vault. Parallel workers return drafts only; one orchestrator inspects and applies the complete change as a single recoverable transaction. This is stated explicitly in the README as part of the trust architecture, not an aspirational claim.
Trade-offs
- -PDF, URL, and OCR need external runnersBuilt-in support for PDF and EPUB covers metadata, hash, and file size only; semantic text extraction requires a configured external runner. URL and YouTube ingestion similarly require an external runner. OCR needs a local-file consent plan plus a configured external runner. If your primary sources are PDFs or web pages, plan for this dependency before committing to the tool.
- -Windows vault writes require WSLOn native Windows (including Git Bash), read-only inspection and dry-run CLI commands work, but vault writes require WSL. Approval hashes bind to the reviewing environment, so you must review and apply inside WSL when working on Windows. This is a meaningful setup overhead for Windows users who have not used WSL before.
- -Requires Python 3.11, Obsidian, and a Claude API keyThe portable core requires Python 3.11 or newer, and the visual vault experience requires Obsidian. The plugin is not a standalone app or a web interface; it runs from Claude Code (or a compatible Agent Skills host) pointed at your vault directory. Teams expecting a hosted web UI out of the box will find the local setup model unfamiliar.
claude-obsidian vs alternatives#
claude-obsidian vs Notion AI
Both tools aim to help knowledge workers capture and retrieve information, but they operate on fundamentally different models. Notion AI is a hosted feature layer on top of Notion's proprietary database; your notes live in Notion's cloud, in Notion's format, under Notion's pricing tiers. claude-obsidian writes everything as plain Markdown files on your disk, with no cloud dependency unless you explicitly add one.
| Feature | claude-obsidian | Notion AI |
|---|---|---|
| License | MIT | Proprietary |
| Data format | Plain Markdown | Proprietary database |
| Self-hosted | Yes | No |
| AI memory | Explicit, skill-based | Integrated, passive |
| Collaboration | Local-first, single vault | Real-time multi-user |
| Retrieval | BM25 + optional cosine rerank | Notion AI search |
claude-obsidian is the better choice when data ownership matters: you can open your vault in any Markdown editor, version-control it with Git, or move to a new AI tool next year without an export step. Notion AI is still the better choice for teams that need real-time collaborative editing, structured databases, and a hosted web interface without any local setup.
claude-obsidian vs Mem
Mem uses AI to automatically tag and surface notes based on semantic similarity across a hosted account. claude-obsidian takes a different approach: rather than passively surfacing existing notes, it actively writes new pages, builds cross-references, and maintains an index when you explicitly run a skill. Mem stores your knowledge in Mem's cloud with no local option. claude-obsidian requires Python, Obsidian, and a Claude API key but gives you full control over your files.
Mem is the better choice for users who want a zero-configuration AI memory layer with no local tooling. claude-obsidian is the better choice for users who want to own their raw files, understand exactly what is in their knowledge base, and use structured vault operations rather than passive AI surfacing.
claude-obsidian vs Reflect and Tana
Reflect and Tana are hosted note-taking tools with subscription pricing and daily note patterns. claude-obsidian differs on two axes: it is local-first with MIT licensing, and it uses active AI ingestion of external sources rather than passive networked note-linking. If your primary workflow is daily journaling with a hosted, zero-setup product, Reflect and Tana are easier to start with. If you want to own your files, run AI ingestion on research sources, and avoid per-seat pricing, claude-obsidian serves that workflow without the subscription overhead.
Install and self-host#
Setup uses git clone followed by vault initialization via the portable Python CLI.
```bash
git clone https://github.com/AgriciDaniel/claude-obsidian.git
cd claude-obsidian
```What it's built on#
- Languages
- Python
FAQ#
Is claude-obsidian free to use?
Yes. The plugin is MIT licensed and free to run on your own infrastructure. You supply your own Claude API key; the only ongoing cost is the Claude API calls you make. There are no subscription fees, no per-seat pricing, and no feature tiers gating the 15 skills.
Does claude-obsidian require a vector database or embeddings server?
No. The core retrieval layer uses BM25 keyword search, which runs locally with no external dependencies. Optional contextual prefixes and cosine reranking are available but gated by explicit egress consent. The default setup stores everything as plain Markdown files with no background services running.
Can I use an existing Obsidian vault with claude-obsidian?
Yes. The portable CLI provides a non-destructive adopt workflow for existing vaults. It previews its exact operation as a JSON plan before applying anything, and you approve the plan by passing its SHA-256 hash. Migration preserves existing vault content byte-for-byte and does not infer claims from existing prose.
Which AI hosts does claude-obsidian support beyond Claude Code?
The skills are built on the Agent Skills standard and work with compatible hosts including Codex, OpenCode, Gemini, Cursor, and Windsurf. The setup script handles host-specific configuration. Claude Code is the primary host; the Obsidian CLI transport is the default there, with plain filesystem access as a fallback so a missing dependency never blocks you.
What happens to my vault if I stop using claude-obsidian?
Nothing. Your vault is a normal directory of Markdown files in Obsidian. Removing the plugin or host links never touches vault content. Your notes, sources, ledgers, and Obsidian settings remain exactly as they were. The README states this explicitly: delete only the integration you installed.
Similar open-source tools#
omi
Open AI memory assistant for meetings, screens, and wearables
Comp AI CRM
Open source agentic CRM with a durable research agent
OpenCompany
Self-hosted AI agent canvas for every business function
Inbox Zero
AI email assistant that drafts replies and clears your inbox
rakazo
AI teammates you own: your keys, your model, your machine.
everyone-can-use-english
AI pronunciation coaching, audio shadowing, and memory drills