obsidian-claude-integration

Obsidian 第二大脑 + Claude Code 集成

概述

通过将 Obsidian 与 Claude Code 集成，把你的 Obsidian 库转变为 AI 驱动的第二大脑。 本技能涵盖多种集成模式，从最简设置到高级自进化系统。

关键洞见：Obsidian 库本质上是由 Markdown 文件组成的代码库。Claude Code 本就擅长浏览文件结构并精准编辑文件，无需特殊插件。

集成模式

决策树

What integration level do you need?
├── Minimal (just works)?
│   └── Pattern A: Direct Access
│       └── Claude Code reads vault directly (no setup needed)
├── Enhanced discovery?
│   └── Pattern B: Manifest-Based
│       └── Add CLAUDE.md to vault root
├── Real-time bidirectional?
│   └── Pattern C: MCP Plugin
│       └── Install obsidian-claude-code-mcp
├── Self-evolving PKM?
│   └── Pattern D: COG Pattern
│       └── Git + automation + self-healing refs
└── Pre-configured structure?
    └── Pattern E: Claudesidian
        └── Adopt opinionated vault structure

模式 A：直接访问（零配置）

Claude Code 已经可以读取和编辑你的库，无需进行任何配置。

工作原理

# Claude Code navigates your vault like any codebase
cd /path/to/your/vault
claude

# Example interactions:
# "Read my daily note from today"
# "Find all notes mentioning project X"
# "Add backlinks to people mentioned in this note"

最佳实践

• 从库的根目录启动 Claude Code
• 使用自然语言描述你的需求
• 按名称或主题引用文件，而非提供精确路径

使用场景

任务	Claude Code 能力
读取笔记	直接访问文件
编辑笔记	精准编辑 Markdown
添加反向链接	查找引用并插入双向链接
创建笔记	使用适当的 frontmatter 编写新文件
搜索内容	在所有 Markdown 文件中使用 Grep 搜索
重构结构	移动文件并更新引用

模式 B：基于清单（CLAUDE.md）

添加项目清单，帮助 Claude Code 了解你的库结构和规范。

CLAUDE.md 模板

在库的根目录创建 CLAUDE.md：

# Obsidian Vault Manifest

## Vault Overview
This is a personal knowledge management vault using [describe your system].

## Folder Structure
- `00 - Inbox/` - Quick capture, unsorted notes
- `01 - Projects/` - Active project notes
- `02 - Areas/` - Ongoing responsibilities
- `03 - Resources/` - Reference materials
- `04 - Archive/` - Completed/inactive content
- `Daily/` - Daily notes (YYYY/MM/DD.md format)
- `Templates/` - Note templates

## Conventions
- Frontmatter: Always include `created`, `updated`, `tags`
- Links: Use `[[wikilinks]]` not markdown links
- Tags: Hierarchical (e.g., `#project/client-name`)
- Dates: ISO 8601 format (YYYY-MM-DD)

## Important Files
- `_index.md` - Main dashboard/MOC
- `project-context.md` - Current project context

## When Creating Notes
1. Always add proper frontmatter
2. Include backlinks to related notes
3. Tag appropriately for discoverability
4. Place in correct folder based on type

## When Editing Notes
1. Update the `updated` timestamp
2. Maintain existing link structure
3. Preserve block references (^block-id)

完整模板请参见：templates/CLAUDE.md。

模式 C：MCP 插件集成

通过 Model Context Protocol 实现实时双向通信。

安装

# Install the MCP plugin from Obsidian Community Plugins
# Plugin: obsidian-claude-code-mcp
# Repository: github.com/iansinnott/obsidian-claude-code-mcp

配置

1. 在 Obsidian 中启用插件
2. 默认 WebSocket 端口：22360
3. Claude Code 会自动发现正在运行的 Obsidian 实例

MCP 功能

功能	说明
read_note	读取笔记内容及其元数据
write_note	创建或更新笔记
search	在整个库中进行语义搜索
list_notes	浏览库的结构
get_backlinks	查找链接到某个文件的笔记
get_outlinks	查找某个文件链接到的笔记
get_tags	列出库中的所有标签

Claude Code MCP 配置

如果未自动发现，请将以下内容添加到 Claude Code 设置中：

{
  "mcpServers": {
    "obsidian": {
      "transport": "websocket",
      "url": "ws://localhost:22360"
    }
  }
}

模式 D：COG 自进化模式

基于 Git 的自进化第二大脑，支持自动整理。

架构

vault/
├── .git/                    # Version control
├── CLAUDE.md                # AI manifest
├── _meta/
│   ├── patterns.md          # Learned patterns
│   ├── conventions.md       # Auto-discovered rules
│   └── maintenance-log.md   # Self-healing log
├── notes/                   # Content
└── daily/                   # Journal

自我修复功能

1. 自动交叉引用：笔记移动时更新链接
2. 模式学习：发现并应用你的规范
3. 孤立笔记检测：识别没有链接的笔记
4. 一致性检查：验证 frontmatter 和标签

设置 Git Hooks

# .git/hooks/post-commit
#!/bin/bash
# Trigger Claude Code maintenance after commits

claude --print "Check for broken links and orphan notes in the vault.
Fix any issues and update _meta/maintenance-log.md with actions taken."

维护命令

# Ask Claude Code to perform maintenance
claude "Analyze my vault for orphan notes and suggest connections"
claude "Find notes without proper frontmatter and fix them"
claude "Update all daily notes with missing navigation links"

模式 E：Claudesidian 结构

采用预配置的库结构，以优化与 AI 的交互。

文件夹结构

vault/
├── CLAUDE.md                # Manifest (required)
├── Inbox/                   # Quick capture
├── Projects/                # Active work
├── Knowledge/               # Permanent notes
├── Journal/                 # Daily reflection
├── Templates/               # Note templates
└── _meta/                   # System files
    ├── prompts/             # Saved prompts
    ├── contexts/            # Context files
    └── exports/             # Generated outputs

关键规范

• 每篇笔记都包含带有 id、created、updated 的 frontmatter
• 标签遵循层级结构：#type/subtype
• 日记链接到前一天和后一天
• 模板中包含 Claude Code 提示词

常见工作流

自动链接人物、地点和书籍

User: "Read my journal entry from today and add backlinks to all
people, places, and books mentioned"

Claude Code:
1. Reads today's daily note
2. Extracts entity mentions
3. Searches vault for existing notes
4. Creates new notes if needed
5. Inserts [[wikilinks]] throughout

知识图谱维护

User: "Find orphan notes and suggest connections"

Claude Code:
1. Identifies notes with no incoming/outgoing links
2. Analyzes content for potential connections
3. Suggests or creates links
4. Updates MOCs (Maps of Content)

研究综合整理

User: "Synthesize all my notes on [topic] into a summary note"

Claude Code:
1. Searches for relevant notes
2. Extracts key insights
3. Creates structured summary
4. Links back to source notes

增强日记

User: "Review today's note and add structure"

Claude Code:
1. Reads raw capture
2. Adds proper frontmatter
3. Identifies tasks → adds checkboxes
4. Identifies mentions → adds links
5. Suggests tags based on content

最佳实践

适用于所有模式

1. 将库纳入版本控制——Git 支持回滚和跟踪更改
2. 使用一致的 frontmatter——帮助 Claude Code 理解笔记类型
3. 维护清单——CLAUDE.md 提供上下文和规范
4. 定期维护——定期让 Claude Code 检查问题

适用于 MCP 集成

1. 保持 Obsidian 运行——MCP 需要活动连接
2. 使用语义搜索——充分利用 MCP 的搜索功能
3. 处理冲突——留意同时编辑的情况

面向自我演进系统

1. 审查 AI 的更改——提交前检查 git diff
2. 根据偏好进行训练——纠正错误以改进模式
3. 记录例外情况——更新清单，补充边缘情况

故障排除

Claude Code 找不到笔记

# Ensure you're in the vault directory
pwd  # Should show vault path

# Check file permissions
ls -la *.md

# Verify markdown extension
find . -name "*.md" | head -20

MCP 连接失败

# Check Obsidian is running
pgrep -l Obsidian

# Verify plugin is enabled
# Settings → Community Plugins → obsidian-claude-code-mcp

# Check port availability
lsof -i :22360

# Test WebSocket connection
websocat ws://localhost:22360

编辑后 Wikilink 损坏

# Ask Claude Code to fix
claude "Find all broken wikilinks in the vault and fix them"

# Or use grep to find issues
grep -r "\[\[" --include="*.md" | grep -v "\.obsidian"

集成方式对比

功能	直接使用	清单	MCP	COG	Claudesidian
所需设置	无	最少	插件	Git + hooks	结构
实时同步	否	否	是	否	否
语义搜索	基础	基础	是	基础	基础
自我修复	否	否	否	是	部分
供应商锁定	无	无	低	无	结构
最适合	简单场景	有组织的场景	高级用户	自动化	新建库

资源

参考资料

• references/mcp-integration.md - MCP 协议详情
• references/cog-pattern.md - 自我演进架构
• references/workflows.md - 常见自动化工作流

模板

• templates/CLAUDE.md - 库清单模板
• templates/daily-note.md - 适合 AI 使用的每日笔记
• templates/project-note.md - 项目笔记模板

外部资源

• obsidian-claude-code-mcp - MCP 插件
• COG-second-brain - 自我演进模式
• Claudesidian - 预配置库
• minimal-second-brain - 极简模板

快速入门

最快路径（模式 A + B）

# 1. Navigate to your vault
cd /path/to/your/obsidian/vault

# 2. Create a minimal manifest
cat > CLAUDE.md << 'EOF'
# Vault Manifest

This is my Obsidian vault. Key conventions:
- Daily notes in `Daily/YYYY/MM/DD.md`
- Use `[[wikilinks]]` for internal links
- Frontmatter with `created`, `updated`, `tags`
EOF

# 3. Start using Claude Code
claude "What notes do I have about [topic]?"

完整集成（模式 C）

1. 安装 obsidian-claude-code-mcp 插件
2. 创建 CLAUDE.md 清单
3. 在 Obsidian 设置中启用插件
4. Claude Code 通过 WebSocket 自动连接

自我演进设置（模式 D）

1. 在库中初始化 git
2. 创建 CLAUDE.md 清单
3. 添加用于维护的 git hooks
4. 定期安排 Claude Code 审查

---

注意事项

• 库路径包含空格时，未加引号的原始 bash heredoc 会出错——构造路径时务必使用 "$VAULT"（带引号）。空格会悄无声息地将路径参数拆成两部分。
• MCP 服务生命周期：服务崩溃后会在过渡状态停留约 30s，然后才会重试——这段时间里 claude 不会显示错误，只会等待。
• Claude 追加 frontmatter 时可能悄悄重复键——YAML 允许重复键；Obsidian 显示最后一个；某些插件读取第一个。务必通过解析器就地编辑，而不要盲目追加。
• CLAUDE.md 清单放在库根目录还是 .obsidian/ 下——放在库根目录的清单对用户可见；放在 .obsidian/ 下的清单在文件夹重组后仍会保留，但不可见。
• MCP 文件系统工具遵守库沙盒限制，但原始 Bash 不遵守——很容易通过 shell 命令意外越界；应在每项技能中明确记录这一边界。