claude-obsidian：为 Obsidian 与 Claude Code 打造可自组织的本地优先知识库

构建一个每次使用都会变得更有价值的 Obsidian 知识库。
采集资料、创建相互关联的笔记、检索有依据的答案，并保持 vault 健康，同时不放弃对文件的所有权。

查看工作流 · 快速开始 · 探索技能 · 安装指南 · Windows 与 WSL

claude-obsidian 是一套面向 Claude Code 及兼容 Agent Skills 主机的本地优先知识系统。它将源材料转换为带有来源引用、相互链接的 Obsidian 页面；基于 vault 中已有的证据作答；并为研究、检索、维护和可视化映射提供明确的工作流。

你的 vault 始终是一个普通目录，包含 Markdown、JSON 和源文件。它不会藏在插件缓存中，不会锁定在云端数据库里，也不会被静默上传给模型。

从资料到活的知识

大多数 AI 笔记工作流在保存文本后便止步不前。claude-obsidian 围绕一个可重复的循环组织：保留来源、为主张提供依据、连接知识，再让知识重新投入使用。

• 带着上下文采集。 通过可见的收件箱引入本地资料，并在综合整理前保留不可变、内容寻址的副本。
• 为每一项重要主张提供依据。 来源与主张台账会保留权威性、时效性、支持情况、矛盾情况、置信度和审查状态。
• 连接所学知识。 构建互链页面、索引、内容地图（Maps of Content）、具备方法论意识的结构，以及 Obsidian Canvas 视图。
• 再次使用 vault。 查询、研究、检索、检查并整合既有知识，而不是让每段对话都从零开始。

输出内容旨在无论有无 Agent 都保持可用：使用纯 Markdown 确保可移植性，使用 Obsidian 实现导航和可视化探索。

Graph 视图中的关联知识 · Obsidian Canvas 中的可视化知识地图

• 默认本地化。 vault 归用户所有，并以普通文件形式工作。网络出站是独立且明确的决策。
• 来源不会随摘要消失。 笔记会指向持久的来源证据；缺乏支持及相互矛盾的主张仍然可见。
• 知识被有意识地复利积累。 摄取、查询、检查、检索、研究和汇总共享同一个具备溯源意识的模型。
• 并行 Agent 不会争抢 vault。 工作线程只返回草稿；一个编排器负责检查并应用一项可恢复事务。
• 能力被如实说明。 系统会检测可选工具、声明成熟度；缺失的适配器会清晰降级，而不会被伪装模拟。

这不是自动对话记录器、云同步服务、事实神谕，也不能替代备份和源代码控制。

最安全的首次运行方式是使用源代码检出副本和一个独立的用户 vault。每个会改变数据的设置命令，都会在实际应用前预览其精确操作。

git clone https://github.com/AgriciDaniel/claude-obsidian.git
cd claude-obsidian

该检出副本包含产品本身，并不是你的知识 vault。

2. 初始化一个独立 vault

export GENERATED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export OPERATION_ID="init-reviewed"

python3 scripts/claude-obsidian.py init "$HOME/Documents/MyKnowledgeVault" \
  --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID"

检查 JSON 计划并复制其 approved_plan_sha256，然后应用这一完全相同的操作：

python3 scripts/claude-obsidian.py init "$HOME/Documents/MyKnowledgeVault" \
  --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID" \
  --approved-plan-sha256 "<sha256-from-the-plan>" --apply

对于现有 Obsidian vault，请使用安装指南中描述的非破坏性 adopt 工作流。

在 Obsidian 中打开新目录，然后从该目录运行带有本地插件的 Claude Code：

cd "$HOME/Documents/MyKnowledgeVault"
claude --plugin-dir /absolute/path/to/claude-obsidian

从以下操作开始：

然后将一个来源文件放入 inbox/，并调用 /claude-obsidian:wiki-ingest。通过 /claude-obsidian:save 显式保存答案；通过 /claude-obsidian:wiki-query 向 vault 提问。

对于 Codex、OpenCode 或 Gemini，请从产品检出目录预览并应用可移植技能链接：

bash bin/setup-multi-agent.sh --host codex
bash bin/setup-multi-agent.sh --host codex --apply

Cursor 和 Windsurf 使用工作区本地技能发现。市场安装、所有受支持主机、vault 采用、升级与卸载步骤均在完整安装指南中说明。

这些技能足够轻量，可以直接调用；同时又具备充分协调能力，可共享相同的证据、vault 选择和变更规则。

技能	功能
wiki	初始化或采用 vault、诊断就绪状态并路由工作
save	保存一个范围明确的答案或洞见——绝不自动记录对话全文
wiki-ingest	将已采集来源转换为互链页面和溯源记录
wiki-query	仅根据相关 vault 证据进行只读回答
wiki-lint	报告死链接、孤立笔记、元数据缺失、过时索引和空白章节
技能	新增能力
---	---
autoresearch	具有明确网络出站控制及独立规范合并流程的有界 Web 研究
canvas	限定在 Wiki 范围内的 Obsidian Canvas 创建与维护
defuddle	在摄取前清理 Web 内容，使其清晰易读
wiki-fold	对操作日志进行可追溯的抽取式汇总
wiki-mode	Generic、LYT、PARA 或 Zettelkasten 归档规范
wiki-retrieve	上下文前缀、BM25 和可选余弦重排序
wiki-cli	使用 Obsidian CLI 读取与搜索，并通过事务安全方式写入
技能	提供能力
---	---
obsidian-markdown	正确的 Obsidian Flavored Markdown、链接、嵌入和 callout
obsidian-bases	原生 .base 表格、卡片、筛选器、公式和摘要
think	一套结构化的观察、倾听、连接、创造和成长审查循环

Claude Code 提供如 /claude-obsidian:wiki-lint 这样的命名空间调用；其他主机使用其原生 Agent Skills 调用方式。触发短语和精确契约位于各个 skills/<name>/SKILL.md 中。

信任是架构的一部分

产品绝不会将源代码检出副本、插件缓存或贡献者状态视为默认 vault。vault 会通过 CLAUDE_OBSIDIAN_VAULT、最近的 .claude-obsidian.json，或唯一明确的已初始化上级目录来显式选择。若选择存在不确定性，命令将退出且不会写入。

一项逻辑知识操作就是一项可恢复事务：

1. 读取每个目标并记录其预期 SHA-256。
2. 让并行工作线程仅返回草稿和证据。
3. 将完整变更合并为一个操作包。
4. 检查该操作包，然后一次性应用。
5. 报告操作 ID 和精确的变更路径。

核心系统会在进程生命周期内持有一个 vault 锁、记录备份日志、使用原子替换，并在应用操作无法完成时恢复先前状态。目标发生变化即被视为冲突，绝不会被静默覆盖。Git 检查点、破坏性修复、网络出站和规范研究合并仍然都是显式操作。

阅读事务契约、溯源契约和 Compound Vault 架构，了解面向机器的详细信息。

如实的能力边界

输入或能力	当前支持
本地文件系统来源	已实现有界、内容寻址的字节采集
图像	元数据、哈希、大小，以及可用时的有界尺寸
PDF 和 EPUB	元数据、哈希和大小；不提供内置语义提取
URL 和 YouTube	经验证的同意计划；需要已配置的外部运行器
OCR	本地文件同意计划；需要已配置的外部运行器
BM25 检索	本地且确定性
上下文前缀或远程模型	可选，并由明确的出站同意控制
Obsidian CLI	可选用于读取/搜索；文件系统传输方式仍然可用

高风险的已接受主张需要两个独立来源。缺乏支持或相互矛盾的证据会保持可见，相较于编造引用，系统更倾向于给出有依据的拒答。当嵌入或重排序阶段不可信时，基于模型的检索会回退至确定性的 BM25。

让 vault 契合你的思维方式

wiki-mode 可以使用四种方法论路由新笔记，而不会批量移动既有知识：

模式	归档原则
Generic	来源、概念、实体和会话
LYT	内容地图和互链原子笔记
PARA	Projects、Areas、Resources 和 Archives
Zettelkasten	稳定标识符、原子笔记和密集链接

未配置模式时，Generic 为默认模式。切换模式会改变新笔记的路由方式；不会静默重组旧笔记。参见方法论模式指南。

可移植 CLI

封装器为 python3 scripts/claude-obsidian.py。

命令	效果
doctor --vault PATH	显示 vault 选择结果和就绪状态
init PATH [--approved-plan-sha256 HASH --apply]	规划或创建独立 vault
adopt PATH [--approved-plan-sha256 HASH --apply]	规划或采用现有 Obsidian vault
migrate --vault PATH [--approved-plan-sha256 HASH --apply]	添加 v1 台账与配置，而不重写旧数据
transaction inspect BUNDLE --vault PATH	在不修改数据的情况下验证写入包
transaction apply BUNDLE --vault PATH --approved-plan-sha256 HASH	应用一项已检查、可恢复的操作
transaction recover --vault PATH [--force-stale-lock]	恢复被中断的操作
lint --vault PATH [--as-of YYYY-MM-DD]	针对声明的 UTC 日期输出确定性的发现结果
contracts --verify --vault PATH	执行能力就绪契约
capture plan --vault PATH [SOURCE ...]	在不写入的情况下运行本地采集预检
capture apply --vault PATH [SOURCE ...]	规划或创建不可变的内容寻址副本
checkpoint OPERATION_ID --vault PATH	显式提交一项已完成操作
package validate	检查技能、钩子、清单与文档的一致性
release build --output FILE.zip	构建并自审计一个确定性的公开制品
release audit FILE.zip	在不解压或发布的情况下审计制品

高级变更规划器会输出 approved_plan_sha256。固定 --generated-at 和 --operation-id，审查 JSON 操作，然后将该精确哈希与 --apply 一同传入。文件系统或生成操作包发生漂移时，会在写入 vault 前失败。

仓库与 vault 布局

product repository/                user vault/
├── claude_obsidian/               ├── .gitignore
├── skills/                        ├── .claude-obsidian.json
├── hooks/                         ├── inbox/
├── scripts/                       ├── .raw/
├── templates/vault/               ├── wiki/
├── config/                        ├── .obsidian/
├── assets/                        └── .vault-meta/   # 被忽略的运行时状态
└── tests/

公开制品包含产品代码、确定性模板和经过审查的 README 资源。它们会拒绝贡献者热状态/日志状态、根目录原始来源、运行时元数据、私有路径、rec

Build an Obsidian knowledge base that becomes more useful every time you use it.
Capture sources, create connected notes, retrieve grounded answers, and keep the vault healthy—without giving up ownership of your files.

See the workflow · Quick start · Explore the skills · Installation guide · Windows & WSL

claude-obsidian is a local-first knowledge system for Claude Code and compatible Agent Skills hosts. It turns source material into linked, source-cited Obsidian pages; answers from the evidence already in the vault; and provides explicit workflows for research, retrieval, maintenance, and visual mapping.

Your vault remains a normal directory of Markdown, JSON, and source files. It is not hidden in a plugin cache, locked in a cloud database, or silently uploaded to a model.

From source to living knowledge

Most AI note workflows stop after saving text. claude-obsidian is organized around a repeatable loop: retain the source, ground the claims, connect the knowledge, then put it back to work.

• Capture with context. Bring local sources through a visible inbox and preserve immutable, content-addressed copies before synthesis.
• Ground every important claim. Source and claim ledgers retain authority, freshness, support, contradiction, confidence, and review state.
• Connect what you learn. Build linked pages, indexes, Maps of Content, methodology-aware structures, and Obsidian Canvas views.
• Use the vault again. Query, research, retrieve, lint, and fold what is already known instead of starting every conversation from zero.

The output is meant to remain useful with or without an agent: plain Markdown for portability, Obsidian for navigation and visual exploration.

Linked knowledge in Graph view · A visual knowledge map in Obsidian Canvas

• Local by default. The vault is user-owned and works as ordinary files. Network egress is a separate, explicit decision.
• Sources survive the summary. Notes point back to durable source evidence; unsupported and contradictory claims remain visible.
• Knowledge compounds deliberately. Ingestion, querying, linting, retrieval, research, and rollups share one provenance-aware model.
• Parallel agents cannot race the vault. Workers return drafts. One orchestrator inspects and applies one recoverable transaction.
• Capabilities are stated honestly. Optional tools are detected, maturity is declared, and missing adapters degrade clearly instead of being simulated.

This is not an automatic transcript recorder, a cloud sync service, a factual oracle, or a substitute for backups and source control.

The safest first run uses a source checkout and a separate user vault. Every mutating setup command previews its exact operation before it can apply.

git clone https://github.com/AgriciDaniel/claude-obsidian.git
cd claude-obsidian

The checkout contains the product. It is not your knowledge vault.

2. Initialize a separate vault

export GENERATED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export OPERATION_ID="init-reviewed"

python3 scripts/claude-obsidian.py init "$HOME/Documents/MyKnowledgeVault" \
  --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID"

Review the JSON plan and copy its approved_plan_sha256, then apply that exact operation:

python3 scripts/claude-obsidian.py init "$HOME/Documents/MyKnowledgeVault" \
  --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID" \
  --approved-plan-sha256 "<sha256-from-the-plan>" --apply

For an existing Obsidian vault, use the non-destructive adopt workflow described in the installation guide.

Open the new directory in Obsidian, then run Claude Code from that directory with the local plugin:

cd "$HOME/Documents/MyKnowledgeVault"
claude --plugin-dir /absolute/path/to/claude-obsidian

Start with:

Then place a source in inbox/ and invoke /claude-obsidian:wiki-ingest. Save an answer explicitly with /claude-obsidian:save; ask the vault with /claude-obsidian:wiki-query.

For Codex, OpenCode, or Gemini, preview and then apply the portable skill links from the product checkout:

bash bin/setup-multi-agent.sh --host codex
bash bin/setup-multi-agent.sh --host codex --apply

Cursor and Windsurf use workspace-local skill discovery. Marketplace setup, every supported host, vault adoption, upgrades, and uninstall steps are covered in the full installation guide.

The skills are small enough to invoke directly and coordinated enough to share the same evidence, vault-selection, and mutation rules.

Skill	What it does
wiki	Initializes or adopts a vault, diagnoses readiness, and routes work
save	Saves one scoped answer or insight—never an automatic transcript
wiki-ingest	Turns captured sources into linked pages and provenance records
wiki-query	Answers read-only from relevant vault evidence
wiki-lint	Reports dead links, orphans, metadata gaps, stale indexes, and empty sections
Skill	What it adds
---	---
autoresearch	Bounded web research with explicit egress and a separate canonical merge
canvas	Wiki-scoped Obsidian Canvas creation and maintenance
defuddle	Clean, readable web content before ingestion
wiki-fold	Extractive, traceable rollups of the operation log
wiki-mode	Generic, LYT, PARA, or Zettelkasten filing conventions
wiki-retrieve	Contextual prefixes, BM25, and optional cosine reranking
wiki-cli	Obsidian CLI reads and search with transaction-safe writes
Skill	What it provides
---	---
obsidian-markdown	Correct Obsidian Flavored Markdown, links, embeds, and callouts
obsidian-bases	Native .base tables, cards, filters, formulas, and summaries
think	A structured observe, listen, connect, create, and grow review loop

Claude Code exposes namespaced invocations such as /claude-obsidian:wiki-lint; other hosts use their native Agent Skills invocation. Trigger phrases and exact contracts live in each skills/<name>/SKILL.md.

Trust is part of the architecture

The product never treats a source checkout, plugin cache, or contributor state as the default vault. A vault is selected explicitly, through CLAUDE_OBSIDIAN_VAULT, by the nearest .claude-obsidian.json, or by one unambiguous initialized ancestor. If selection is uncertain, the command exits without writing.

One logical knowledge operation is one recoverable transaction:

1. Read every target and record its expected SHA-256.
2. Let parallel workers return drafts and evidence only.
3. Merge the complete change into one operation bundle.
4. Inspect the bundle, then apply it once.
5. Report the operation ID and exact changed paths.

The core holds one process-lifetime vault lock, journals backups, uses atomic replacement, and restores the prior state if an apply cannot finish. A changed target is a conflict, never a silent overwrite. Git checkpoints, destructive repairs, network egress, and canonical research merges remain explicit operations.

Read the transaction contract, provenance contract, and Compound Vault architecture for the machine-facing detail.

Honest capability boundaries

Input or capability	Current support
Local filesystem sources	Implemented bounded, content-addressed byte capture
Images	Metadata, hash, size, and bounded dimensions when available
PDF and EPUB	Metadata, hash, and size; no built-in semantic extraction
URL and YouTube	Validated consent plans; a configured external runner is required
OCR	Local-file consent plan; a configured external runner is required
BM25 retrieval	Local and deterministic
Contextual prefixes or remote models	Optional and gated by explicit egress consent
Obsidian CLI	Optional for reads/search; filesystem transport remains available

High-risk accepted claims require two independent sources. Unsupported or contradictory evidence stays visible, and a grounded refusal is preferred over an invented citation. Model-based retrieval falls back to deterministic BM25 when the embedding or reranking stage cannot be trusted.

Shape the vault to the way you think

wiki-mode can route new notes using four methodologies without bulk-moving existing knowledge:

Mode	Filing principle
Generic	Sources, concepts, entities, and sessions
LYT	Maps of Content and linked atomic notes
PARA	Projects, Areas, Resources, and Archives
Zettelkasten	Stable identifiers, atomic notes, and dense links

Generic is the default when no mode is configured. Switching modes changes how new notes are routed; it does not silently reorganize old ones. See the methodology modes guide.

Portable CLI

The wrapper is python3 scripts/claude-obsidian.py.

Command	Effect
doctor --vault PATH	Show vault selection and readiness
init PATH [--approved-plan-sha256 HASH --apply]	Plan or create a separate vault
adopt PATH [--approved-plan-sha256 HASH --apply]	Plan or adopt an existing Obsidian vault
migrate --vault PATH [--approved-plan-sha256 HASH --apply]	Add v1 ledgers and configuration without rewriting legacy data
transaction inspect BUNDLE --vault PATH	Validate a write bundle without mutation
transaction apply BUNDLE --vault PATH --approved-plan-sha256 HASH	Apply one inspected, recoverable operation
transaction recover --vault PATH [--force-stale-lock]	Restore an interrupted operation
lint --vault PATH [--as-of YYYY-MM-DD]	Emit findings deterministic for the declared UTC date
contracts --verify --vault PATH	Execute capability readiness contracts
capture plan --vault PATH [SOURCE ...]	Run a local capture preflight without writes
capture apply --vault PATH [SOURCE ...]	Plan or create immutable content-addressed copies
checkpoint OPERATION_ID --vault PATH	Explicitly commit one completed operation
package validate	Check skills, hooks, manifests, and documentation coherence
release build --output FILE.zip	Build and self-audit a deterministic public artifact
release audit FILE.zip	Audit an artifact without extracting or publishing it

High-level mutating planners emit approved_plan_sha256. Pin --generated-at and --operation-id, review the JSON operation, and pass that exact hash with --apply. Filesystem or generated-bundle drift fails before a vault write.

Repository and vault layout

product repository/                user vault/
├── claude_obsidian/               ├── .gitignore
├── skills/                        ├── .claude-obsidian.json
├── hooks/                         ├── inbox/
├── scripts/                       ├── .raw/
├── templates/vault/               ├── wiki/
├── config/                        ├── .obsidian/
├── assets/                        └── .vault-meta/   # ignored runtime state
└── tests/

Public artifacts contain product code, deterministic templates, and reviewed README assets. They reject contributor hot/log state, root raw sources, runtime metadata, private paths, recognizable personal email addresses, secrets, symlinks, unsafe archive entries, and unreviewed binaries.

The private development checkout deliberately has no marketplace catalog. The release builder injects the reviewed catalog only into the distribution-clean artifact. A public default branch must be populated from that audited tree, never by pushing contributor-vault state.

Upgrade, rollback, and uninstall

Upgrade the product independently from the vault. For an older vault, first preview the additive, idempotent migration:

python3 scripts/claude-obsidian.py migrate --vault /path/to/vault \
  --generated-at "$GENERATED_AT" --operation-id migrate-reviewed

Review its hash and rerun with --approved-plan-sha256 HASH --apply. Migration preserves the legacy raw manifest byte-for-byte and does not infer claims from prose.

After an interrupted operation, run:

python3 scripts/claude-obsidian.py transaction recover --vault /path/to/vault

Removing the plugin or host links never removes the vault. Delete only the integration you installed; user notes, sources, ledgers, and Obsidian settings remain yours.

• Python 3.11 or newer for the portable core
• Obsidian for the visual vault experience; plain Markdown remains usable without it
• Bash for setup, optional extensions, and shell test suites
• Git only for development, releases, or an explicit knowledge checkpoint

CI exercises Linux and macOS, plus a native-Windows smoke job for the portable surface. On native Windows (including Git Bash), read-only inspection and dry-run commands work; vault writes require WSL and fail closed with an UNSUPPORTED_PLATFORM error otherwise. Approval hashes bind to the reviewing environment, so review inside WSL when the apply will happen there. Platform details, the support matrix, and WSL troubleshooting (including hangs from virtualization conflicts) live in the Windows and WSL guide. The bash setup scripts and shell test suites remain POSIX-only. Optional tools such as Obsidian CLI, Ollama, and defuddle are capability-detected and affect only their dependent workflow.

The test target runs every hermetic Python and shell suite, product and capability contracts, skill and hook validation, manifest checks, and package boundaries. CI repeats the suite on supported Linux and macOS/Python combinations and verifies a byte-reproducible release build.

Build and audit locally without publishing:

python3 scripts/claude-obsidian.py release build --output dist/claude-obsidian.zip
python3 scripts/claude-obsidian.py release audit dist/claude-obsidian.zip

No command pushes, tags, publishes, opens issues, or creates releases automatically. See CONTRIBUTING.md, SECURITY.md, and CODE_OF_CONDUCT.md.

Lineage, license, and attribution

The design follows Andrej Karpathy's LLM Wiki pattern and uses kepano/obsidian-skills as the reference substrate for Obsidian Markdown, Bases, and JSON Canvas syntax.

MIT licensed. See ATTRIBUTION.md and CITATION.cff.