add claude-obsidian
This commit is contained in:
김경종
@@ -0,0 +1,253 @@
|
||||
---
|
||||
name: wiki
|
||||
description: >
|
||||
Claude + Obsidian knowledge companion. Sets up a persistent wiki vault, scaffolds
|
||||
structure from a one-sentence description, and routes to specialized sub-skills.
|
||||
Use for setup, scaffolding, cross-project referencing, and hot cache management.
|
||||
Triggers on: "set up wiki", "scaffold vault", "create knowledge base", "/wiki",
|
||||
"wiki setup", "obsidian vault", "knowledge base", "second brain setup",
|
||||
"running notetaker", "persistent memory", "llm wiki".
|
||||
allowed-tools: Read Write Edit Glob Grep Bash
|
||||
---
|
||||
|
||||
# wiki: Claude + Obsidian Knowledge Companion
|
||||
|
||||
You are a knowledge architect. You build and maintain a persistent, compounding wiki inside an Obsidian vault. You don't just answer questions. You write, cross-reference, file, and maintain a structured knowledge base that gets richer with every source added and every question asked.
|
||||
|
||||
The wiki is the product. Chat is just the interface.
|
||||
|
||||
The key difference from RAG: the wiki is a persistent artifact. Cross-references are already there. Contradictions have been flagged. Synthesis already reflects everything read. Knowledge compounds like interest.
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
Three layers:
|
||||
|
||||
```
|
||||
vault/
|
||||
├── .raw/ # Layer 1: immutable source documents
|
||||
├── wiki/ # Layer 2: LLM-generated knowledge base
|
||||
└── CLAUDE.md # Layer 3: schema and instructions (this plugin)
|
||||
```
|
||||
|
||||
Standard wiki structure:
|
||||
|
||||
```
|
||||
wiki/
|
||||
├── index.md # master catalog of all pages
|
||||
├── log.md # chronological record of all operations
|
||||
├── hot.md # hot cache: recent context summary (~500 words)
|
||||
├── overview.md # executive summary of the whole wiki
|
||||
├── sources/ # one summary page per raw source
|
||||
├── entities/ # people, orgs, products, repos
|
||||
│ └── _index.md
|
||||
├── concepts/ # ideas, patterns, frameworks
|
||||
│ └── _index.md
|
||||
├── domains/ # top-level topic areas
|
||||
│ └── _index.md
|
||||
├── comparisons/ # side-by-side analyses
|
||||
├── questions/ # filed answers to user queries
|
||||
└── meta/ # dashboards, lint reports, conventions
|
||||
```
|
||||
|
||||
Dot-prefixed folders (`.raw/`) are hidden in Obsidian's file explorer and graph view. Use this for source documents.
|
||||
|
||||
---
|
||||
|
||||
## Hot Cache
|
||||
|
||||
`wiki/hot.md` is a ~500-word summary of the most recent context. It exists so any session (or any other project pointing at this vault) can get recent context without crawling the full wiki.
|
||||
|
||||
Update hot.md:
|
||||
- After every ingest
|
||||
- After any significant query exchange
|
||||
- At the end of every session
|
||||
|
||||
Format:
|
||||
```markdown
|
||||
---
|
||||
type: meta
|
||||
title: "Hot Cache"
|
||||
updated: YYYY-MM-DDTHH:MM:SS
|
||||
---
|
||||
|
||||
# Recent Context
|
||||
|
||||
## Last Updated
|
||||
YYYY-MM-DD. [what happened]
|
||||
|
||||
## Key Recent Facts
|
||||
- [Most important recent takeaway]
|
||||
- [Second most important]
|
||||
|
||||
## Recent Changes
|
||||
- Created: [[New Page 1]], [[New Page 2]]
|
||||
- Updated: [[Existing Page]] (added section on X)
|
||||
- Flagged: Contradiction between [[Page A]] and [[Page B]] on Y
|
||||
|
||||
## Active Threads
|
||||
- User is currently researching [topic]
|
||||
- Open question: [thing still being investigated]
|
||||
```
|
||||
|
||||
Keep it under 500 words. It is a cache, not a journal. Overwrite it completely each time.
|
||||
|
||||
---
|
||||
|
||||
## Operations
|
||||
|
||||
Route to the correct operation based on what the user says:
|
||||
|
||||
| User says | Operation | Sub-skill |
|
||||
|-----------|-----------|-----------|
|
||||
| "scaffold", "set up vault", "create wiki" | SCAFFOLD | this skill |
|
||||
| "ingest [source]", "process this", "add this" | INGEST | `wiki-ingest` |
|
||||
| "what do you know about X", "query:" | QUERY | `wiki-query` |
|
||||
| "lint", "health check", "clean up" | LINT | `wiki-lint` |
|
||||
| "save this", "file this", "/save" | SAVE | `save` |
|
||||
| "/autoresearch [topic]", "research [topic]" | AUTORESEARCH | `autoresearch` |
|
||||
| "/canvas", "add to canvas", "open canvas" | CANVAS | `canvas` |
|
||||
|
||||
---
|
||||
|
||||
## SCAFFOLD Operation
|
||||
|
||||
Trigger: user describes what the vault is for.
|
||||
|
||||
Steps:
|
||||
|
||||
1. Determine the wiki mode. Read `references/modes.md` to show the 6 options and pick the best fit.
|
||||
2. Ask: "What is this vault for?" (one question, then proceed).
|
||||
3. Create full folder structure under `wiki/` based on the mode.
|
||||
4. Create domain pages + `_index.md` sub-indexes.
|
||||
5. Create `wiki/index.md`, `wiki/log.md`, `wiki/hot.md`, `wiki/overview.md`.
|
||||
6. Create `_templates/` files for each note type.
|
||||
7. Apply visual customization. Read `references/css-snippets.md`. Create `.obsidian/snippets/vault-colors.css`.
|
||||
8. Create the vault CLAUDE.md using the template below.
|
||||
9. Initialize git. Read `references/git-setup.md`.
|
||||
10. Present the structure and ask: "Want to adjust anything before we start?"
|
||||
|
||||
### Vault CLAUDE.md Template
|
||||
|
||||
Create this file in the vault root when scaffolding a new project vault (not this plugin directory):
|
||||
|
||||
```markdown
|
||||
# [WIKI NAME]: LLM Wiki
|
||||
|
||||
Mode: [MODE A/B/C/D/E/F]
|
||||
Purpose: [ONE SENTENCE]
|
||||
Owner: [NAME]
|
||||
Created: YYYY-MM-DD
|
||||
|
||||
## Structure
|
||||
|
||||
[PASTE THE FOLDER MAP FROM THE CHOSEN MODE]
|
||||
|
||||
## Conventions
|
||||
|
||||
- All notes use YAML frontmatter: type, status, created, updated, tags (minimum)
|
||||
- Wikilinks use [[Note Name]] format: filenames are unique, no paths needed
|
||||
- .raw/ contains source documents: never modify them
|
||||
- wiki/index.md is the master catalog: update on every ingest
|
||||
- wiki/log.md is append-only: never edit past entries
|
||||
- New log entries go at the TOP of the file
|
||||
|
||||
## Operations
|
||||
|
||||
- Ingest: drop source in .raw/, say "ingest [filename]"
|
||||
- Query: ask any question: Claude reads index first, then drills in
|
||||
- Lint: say "lint the wiki" to run a health check
|
||||
- Archive: move cold sources to .archive/ to keep .raw/ clean
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cross-Project Referencing
|
||||
|
||||
This is the force multiplier. Any Claude Code project can reference this vault without duplicating context.
|
||||
|
||||
In another project's CLAUDE.md, add:
|
||||
|
||||
```markdown
|
||||
## Wiki Knowledge Base
|
||||
Path: ~/path/to/vault
|
||||
|
||||
When you need context not already in this project:
|
||||
1. Read wiki/hot.md first (recent context, ~500 words)
|
||||
2. If not enough, read wiki/index.md (full catalog)
|
||||
3. If you need domain specifics, read wiki/<domain>/_index.md
|
||||
4. Only then read individual wiki pages
|
||||
|
||||
Do NOT read the wiki for:
|
||||
- General coding questions or language syntax
|
||||
- Things already in this project's files or conversation
|
||||
- Tasks unrelated to [your domain]
|
||||
```
|
||||
|
||||
This keeps token usage low. Hot cache costs ~500 tokens. Index costs ~1000 tokens. Individual pages cost 100-300 tokens each.
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Your job as the LLM:
|
||||
1. Set up the vault (once)
|
||||
2. Scaffold wiki structure from user's domain description
|
||||
3. Route ingest, query, and lint to the correct sub-skill
|
||||
4. Maintain hot cache after every operation
|
||||
5. Always update index, sub-indexes, log, and hot cache on changes
|
||||
6. Always use frontmatter and wikilinks
|
||||
7. Never modify .raw/ sources
|
||||
|
||||
The human's job: curate sources, ask good questions, think about what it means. Everything else is on you.
|
||||
|
||||
## Community Footer
|
||||
|
||||
After completing a **major operation**, append this footer as the very last output:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Built by agricidaniel — Join the AI Marketing Hub community
|
||||
🆓 Free → https://www.skool.com/ai-marketing-hub
|
||||
⚡ Pro → https://www.skool.com/ai-marketing-hub-pro
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
### When to show
|
||||
|
||||
Display only after these infrequent, high-value completions:
|
||||
- Vault scaffold (after `/wiki` setup completes the 10-step process)
|
||||
- `/wiki-lint` (after health check report is delivered)
|
||||
- `/autoresearch` (after research loop finishes and pages are filed)
|
||||
|
||||
### When to skip
|
||||
|
||||
Do NOT show the footer after:
|
||||
- `/wiki-query` (too frequent — conversational)
|
||||
- `/wiki-ingest` (individual source ingestion — happens often)
|
||||
- `/save` (quick save operation)
|
||||
- `/canvas` (visual work, intermediate)
|
||||
- `/defuddle` (utility)
|
||||
- `obsidian-bases`, `obsidian-markdown` (reference skills, not output)
|
||||
- Hot cache updates, index updates, or any background maintenance
|
||||
- Error messages or prompts for more information
|
||||
|
||||
---
|
||||
|
||||
## How to think (10-principle mapping)
|
||||
|
||||
When working on this skill, apply the 10-principle loop. See [`skills/think/SKILL.md`](../think/SKILL.md) for the canonical framework.
|
||||
|
||||
| # | Principle | Application here |
|
||||
|---|-----------|-------------------|
|
||||
| 1 | OBSERVE (ext) | Is there already a vault here? What state is it in? What hooks are configured? Read before scaffolding. |
|
||||
| 2 | OBSERVE (int) | Am I assuming the user knows what they want? First-run users often don't — slow down. |
|
||||
| 3 | LISTEN | The user's one-sentence vault description — the whole scaffold flows from this. Ask before assuming. |
|
||||
| 4 | THINK | Which folders, templates, substrate (kepano-substrate vs self-hosted)? Pick deliberately, not reflexively. |
|
||||
| 5 | CONNECT (lat) | How does this vault relate to the user's other projects? Cross-project reference is a first-class use case. |
|
||||
| 6 | CONNECT (sys) | Hooks + `.vault-meta/` + plugin install + CLAUDE.md routing rules wire together at setup. |
|
||||
| 7 | FEEL | First-run UX is the make-or-break moment for adoption. Confusion at scaffold = abandoned vault. |
|
||||
| 8 | ACCEPT | The scaffold is opinionated; don't pretend it's neutral. Document the opinions in the scaffold output. |
|
||||
| 9 | CREATE | Scaffold the folders, write `hot.md` + `index.md` + `log.md` with starting structure. |
|
||||
| 10 | GROW | Vault structure should evolve — what works at month 1 may not at month 12. Build for that evolution. |
|
||||
@@ -0,0 +1,122 @@
|
||||
# Visual Customization
|
||||
|
||||
Apply during scaffold. This makes the file explorer color-coded by folder type and adds custom callout styles.
|
||||
|
||||
---
|
||||
|
||||
## CSS Snippet
|
||||
|
||||
Create this file at `.obsidian/snippets/vault-colors.css` inside the vault:
|
||||
|
||||
```css
|
||||
:root {
|
||||
--wiki-1: #4fc1ff;
|
||||
--wiki-2: #c586c0;
|
||||
--wiki-3: #dcdcaa;
|
||||
--wiki-4: #ce9178;
|
||||
--wiki-5: #6a9955;
|
||||
--wiki-6: #d16969;
|
||||
--wiki-7: #569cd6;
|
||||
}
|
||||
|
||||
/* Folder colors in file explorer */
|
||||
.nav-folder-title[data-path^="wiki/domains"] { color: var(--wiki-1); }
|
||||
.nav-folder-title[data-path^="wiki/entities"] { color: var(--wiki-2); }
|
||||
.nav-folder-title[data-path^="wiki/concepts"] { color: var(--wiki-3); }
|
||||
.nav-folder-title[data-path^="wiki/sources"] { color: var(--wiki-4); }
|
||||
.nav-folder-title[data-path^="wiki/questions"] { color: var(--wiki-5); }
|
||||
.nav-folder-title[data-path^="wiki/comparisons"] { color: var(--wiki-6); }
|
||||
.nav-folder-title[data-path^="wiki/meta"] { color: var(--wiki-7); }
|
||||
.nav-folder-title[data-path=".raw"] { color: #808080; opacity: 0.6; }
|
||||
|
||||
/* Custom callouts */
|
||||
.callout[data-callout='contradiction'] {
|
||||
--callout-color: 209, 105, 105;
|
||||
--callout-icon: lucide-alert-triangle;
|
||||
}
|
||||
.callout[data-callout='gap'] {
|
||||
--callout-color: 220, 220, 170;
|
||||
--callout-icon: lucide-help-circle;
|
||||
}
|
||||
.callout[data-callout='key-insight'] {
|
||||
--callout-color: 79, 193, 255;
|
||||
--callout-icon: lucide-lightbulb;
|
||||
}
|
||||
.callout[data-callout='stale'] {
|
||||
--callout-color: 128, 128, 128;
|
||||
--callout-icon: lucide-clock;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Enable the Snippet
|
||||
|
||||
Tell the user: Settings > Appearance > CSS Snippets > open folder > paste the file > click the refresh icon > toggle it on.
|
||||
|
||||
---
|
||||
|
||||
## Graph View Groups
|
||||
|
||||
Guide the user to set these in Graph View settings (click the settings icon in the graph view):
|
||||
|
||||
| Query | Color |
|
||||
|-------|-------|
|
||||
| `path:wiki/domains` | Blue (`#4fc1ff`) |
|
||||
| `path:wiki/entities` | Purple (`#c586c0`) |
|
||||
| `path:wiki/concepts` | Yellow (`#dcdcaa`) |
|
||||
| `path:wiki/sources` | Orange (`#ce9178`) |
|
||||
| `path:wiki/questions` | Green (`#6a9955`) |
|
||||
| `path:.raw` | Gray (dimmed) |
|
||||
|
||||
---
|
||||
|
||||
## Custom Callouts
|
||||
|
||||
This vault defines **four custom callout types** beyond Obsidian's built-in set (`note`, `tip`, `warning`, `info`, `todo`, `success`, `question`, `failure`, `danger`, `bug`, `example`, `quote`). They render correctly **only when `vault-colors.css` is enabled**. Without the snippet, they fall back to default callout styling (still readable, just plain).
|
||||
|
||||
| Custom callout | Color | Icon | Use for |
|
||||
|---|---|---|---|
|
||||
| `contradiction` | reddish-brown (rgb 209,105,105) | `lucide-alert-triangle` | New source conflicts with existing claim |
|
||||
| `gap` | beige (rgb 220,220,170) | `lucide-help-circle` | Topic has no source yet |
|
||||
| `key-insight` | bright blue (rgb 79,193,255) | `lucide-lightbulb` | Important takeaway worth highlighting |
|
||||
| `stale` | gray (rgb 128,128,128) | `lucide-clock` | Claim may be outdated, source older than threshold |
|
||||
|
||||
### Usage
|
||||
|
||||
Use these in wiki pages to flag important states:
|
||||
|
||||
```markdown
|
||||
> [!contradiction] Title
|
||||
> [[Page A]] claims X. [[Page B]] says Y. Needs resolution.
|
||||
|
||||
> [!gap] Title
|
||||
> This topic has no source yet. Consider finding one.
|
||||
|
||||
> [!key-insight] Title
|
||||
> The most important takeaway from this section.
|
||||
|
||||
> [!stale] Title
|
||||
> This claim may be outdated. Source was from 2022.
|
||||
```
|
||||
|
||||
### Why custom callouts (vs built-in)
|
||||
|
||||
The four custom types map to wiki-specific concepts that don't fit cleanly into Obsidian's default set:
|
||||
|
||||
- `contradiction` is more specific than `warning`: it signals a **resolvable conflict** between two wiki pages, not a generic warning.
|
||||
- `gap` is more specific than `question`: it signals a **missing source**, an actionable improvement.
|
||||
- `key-insight` is more specific than `tip`: it marks **the** most important takeaway from a section, used sparingly.
|
||||
- `stale` has no built-in equivalent: it signals time-based decay of a claim.
|
||||
|
||||
If you don't want custom callouts, replace them with built-ins:
|
||||
- `[!contradiction]` → `[!warning] Contradiction`
|
||||
- `[!gap]` → `[!question] Gap`
|
||||
- `[!key-insight]` → `[!tip] Key insight`
|
||||
- `[!stale]` → `[!warning] Stale`
|
||||
|
||||
---
|
||||
|
||||
## Minimal Theme (Recommended)
|
||||
|
||||
The color scheme looks best with the Minimal theme. Install via Settings > Appearance > Manage > search "Minimal".
|
||||
@@ -0,0 +1,107 @@
|
||||
# Frontmatter Schema
|
||||
|
||||
Every wiki page starts with flat YAML frontmatter. No nested objects. Obsidian's Properties UI requires flat structure.
|
||||
|
||||
---
|
||||
|
||||
## Universal Fields
|
||||
|
||||
Every page, no exceptions:
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: <source|entity|concept|domain|comparison|question|overview|meta>
|
||||
title: "Human-Readable Title"
|
||||
created: 2026-04-07
|
||||
updated: 2026-04-07
|
||||
tags:
|
||||
- <domain-tag>
|
||||
- <type-tag>
|
||||
status: <seed|developing|mature|evergreen>
|
||||
related:
|
||||
- "[[Other Page]]"
|
||||
sources:
|
||||
- "[[.raw/articles/source-file.md]]"
|
||||
---
|
||||
```
|
||||
|
||||
**status values:**
|
||||
- `seed`: exists, barely populated
|
||||
- `developing`: has real content, not yet complete
|
||||
- `mature`: comprehensive, well-linked
|
||||
- `evergreen`: unlikely to need updates
|
||||
|
||||
---
|
||||
|
||||
## Type-Specific Additions
|
||||
|
||||
### source
|
||||
|
||||
Add these fields after the universal fields:
|
||||
|
||||
```yaml
|
||||
source_type: article # article | video | podcast | paper | book | transcript | data
|
||||
author: ""
|
||||
date_published: YYYY-MM-DD
|
||||
url: ""
|
||||
confidence: high # high | medium | low
|
||||
key_claims:
|
||||
- "First key claim from this source"
|
||||
- "Second key claim"
|
||||
```
|
||||
|
||||
### entity
|
||||
|
||||
```yaml
|
||||
entity_type: person # person | organization | product | repository | place
|
||||
role: ""
|
||||
first_mentioned: "[[Source Title]]"
|
||||
```
|
||||
|
||||
### concept
|
||||
|
||||
```yaml
|
||||
complexity: intermediate # basic | intermediate | advanced
|
||||
domain: ""
|
||||
aliases:
|
||||
- "alternative name"
|
||||
- "abbreviation"
|
||||
```
|
||||
|
||||
### comparison
|
||||
|
||||
```yaml
|
||||
subjects:
|
||||
- "[[Thing A]]"
|
||||
- "[[Thing B]]"
|
||||
dimensions:
|
||||
- "performance"
|
||||
- "cost"
|
||||
- "ease of use"
|
||||
verdict: "One-line conclusion."
|
||||
```
|
||||
|
||||
### question
|
||||
|
||||
```yaml
|
||||
question: "The original query as asked."
|
||||
answer_quality: solid # draft | solid | definitive
|
||||
```
|
||||
|
||||
### domain
|
||||
|
||||
```yaml
|
||||
subdomain_of: "" # leave empty for top-level domains
|
||||
page_count: 0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
1. Use flat YAML only. Never nest objects.
|
||||
2. Dates as `YYYY-MM-DD` strings, not ISO datetime.
|
||||
3. Lists always use the `- item` format, not inline `[a, b, c]`.
|
||||
4. Wikilinks in YAML fields must be quoted: `"[[Page Name]]"`.
|
||||
5. Keep `related` and `sources` as wikilinks, not plain URLs.
|
||||
6. Update `updated` every time you edit the page content.
|
||||
@@ -0,0 +1,58 @@
|
||||
# Git Setup
|
||||
|
||||
Initialize git in the vault to get full history and protect against bad writes.
|
||||
|
||||
---
|
||||
|
||||
## Initialize
|
||||
|
||||
```bash
|
||||
cd "$VAULT_PATH"
|
||||
git init
|
||||
git add -A
|
||||
git commit -m "Initial vault scaffold"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## .gitignore
|
||||
|
||||
The root `.gitignore` in this repo already covers the right exclusions:
|
||||
|
||||
```
|
||||
.obsidian/workspace.json
|
||||
.obsidian/workspace-mobile.json
|
||||
.smart-connections/
|
||||
.obsidian-git-data
|
||||
.trash/
|
||||
.DS_Store
|
||||
```
|
||||
|
||||
`workspace.json` changes constantly as you move panes around. Excluding it keeps the diff clean.
|
||||
|
||||
---
|
||||
|
||||
## Obsidian Git Plugin
|
||||
|
||||
After installing the plugin (see `plugins.md`):
|
||||
|
||||
Settings > Obsidian Git:
|
||||
- Auto backup interval: **15 minutes**
|
||||
- Auto backup after file change: on
|
||||
- Push on backup: on (if you have a remote)
|
||||
- Commit message: `vault: auto backup {{date}}`
|
||||
|
||||
This runs silently in the background. You get a full history of every note without thinking about it.
|
||||
|
||||
---
|
||||
|
||||
## Remote (Optional)
|
||||
|
||||
To back up to GitHub:
|
||||
|
||||
```bash
|
||||
git remote add origin https://github.com/yourname/your-vault
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
Keep the repo private if the vault contains personal notes.
|
||||
@@ -0,0 +1,134 @@
|
||||
# MCP Setup
|
||||
|
||||
MCP lets Claude read and write vault notes directly without copy-paste. Four options ordered from simplest to most featureful.
|
||||
|
||||
> [!tip] Recommendation
|
||||
> If you have **Obsidian v1.12 or newer**, start with **Option D: Obsidian CLI**. It needs no MCP server, no plugins, and no TLS workarounds. Use Options A or B only if you need persistent MCP integration or are on an older Obsidian version.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Install the Local REST API Plugin
|
||||
|
||||
You must do this in Obsidian (Claude cannot do it programmatically):
|
||||
|
||||
1. Obsidian > Settings > Community Plugins > Turn off Restricted Mode
|
||||
2. Browse > Search "Local REST API" > Install > Enable
|
||||
3. Settings > Local REST API > Copy the API key
|
||||
|
||||
The plugin runs on `https://127.0.0.1:27124` with a self-signed certificate.
|
||||
|
||||
Test it:
|
||||
```bash
|
||||
curl -sk -H "Authorization: Bearer <YOUR_KEY>" https://127.0.0.1:27124/
|
||||
```
|
||||
|
||||
You should get a JSON response with vault info.
|
||||
|
||||
---
|
||||
|
||||
## Option A: mcp-obsidian (REST API based)
|
||||
|
||||
Uses MarkusPfundstein's mcp-obsidian. Requires the Local REST API plugin running.
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
> [!warning] Security
|
||||
> `NODE_TLS_REJECT_UNAUTHORIZED: "0"` **disables TLS certificate verification process-wide** for the MCP server. It is required here because the Local REST API plugin uses a self-signed certificate. This is acceptable for `127.0.0.1` (localhost) connections only. Never use this setting for any non-loopback connection. If you are uncomfortable with the global TLS bypass, prefer **Option D (Obsidian CLI)** or **Option B (filesystem-based)** which avoid this entirely.
|
||||
|
||||
Capabilities: read notes, write notes, search, patch frontmatter fields, append under headings.
|
||||
|
||||
---
|
||||
|
||||
## Option B: MCPVault (filesystem based)
|
||||
|
||||
No Obsidian plugin needed. Reads the vault directory directly.
|
||||
|
||||
```bash
|
||||
claude mcp add-json obsidian-vault '{
|
||||
"type": "stdio",
|
||||
"command": "npx",
|
||||
"args": ["-y", "@bitbonsai/mcpvault@latest", "/absolute/path/to/your/vault"]
|
||||
}' --scope user
|
||||
```
|
||||
|
||||
Replace `/absolute/path/to/your/vault` with the actual vault path.
|
||||
|
||||
Tools available: `search_notes` (BM25), `read_note`, `create_note`, `update_note`, `get_frontmatter`, `update_frontmatter`, `list_all_tags`, `read_multiple_notes`.
|
||||
|
||||
---
|
||||
|
||||
## Option C: Direct REST API via curl
|
||||
|
||||
No MCP needed. Use curl in bash throughout the session. See `rest-api.md` for all commands.
|
||||
|
||||
---
|
||||
|
||||
## Option D: Obsidian CLI (recommended for v1.12+)
|
||||
|
||||
Obsidian shipped a native CLI in v1.12 (2026). It exposes vault operations directly to the terminal. No REST API plugin, no MCP server, no self-signed certs, no TLS workarounds. Claude calls it through the Bash tool.
|
||||
|
||||
**Check if available:**
|
||||
```bash
|
||||
which obsidian-cli 2>/dev/null && obsidian-cli --version
|
||||
# or, on flatpak:
|
||||
flatpak run md.obsidian.Obsidian --cli --version
|
||||
```
|
||||
|
||||
**Common operations:**
|
||||
```bash
|
||||
# List all notes in a folder
|
||||
obsidian-cli list /path/to/vault wiki/
|
||||
|
||||
# Read a note
|
||||
obsidian-cli read /path/to/vault wiki/index.md
|
||||
|
||||
# Create or update a note
|
||||
obsidian-cli write /path/to/vault wiki/new-note.md < content.md
|
||||
|
||||
# Search notes by content
|
||||
obsidian-cli search /path/to/vault "query term"
|
||||
```
|
||||
|
||||
**Why prefer this**:
|
||||
- No plugin install required (CLI is built into Obsidian)
|
||||
- No MCP server process to manage
|
||||
- No TLS certificate bypass needed
|
||||
- Survives Obsidian restarts (no persistent connection)
|
||||
- Works identically across desktop and headless environments
|
||||
|
||||
**When to use Options A/B/C instead**: If you need persistent semantic search, frontmatter patching, or are on Obsidian < v1.12.
|
||||
|
||||
The `kepano/obsidian-skills` repo includes an `obsidian-cli` skill that wraps these commands as reusable patterns. Install it alongside this plugin for first-class CLI support.
|
||||
|
||||
---
|
||||
|
||||
## Use `--scope user`
|
||||
|
||||
Both MCP options use `--scope user` so the vault is available across all Claude Code projects, not just the one where you ran the command.
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
After setup:
|
||||
|
||||
```bash
|
||||
claude mcp list # confirm the server appears
|
||||
claude mcp get obsidian-vault # confirm the path or URL is correct
|
||||
```
|
||||
|
||||
In a Claude Code session, type `/mcp` to check connection status.
|
||||
|
||||
Then test: "List all notes in my wiki folder."
|
||||
@@ -0,0 +1,259 @@
|
||||
# Wiki Modes
|
||||
|
||||
Six modes cover the most common use cases. Pick the one that fits, or combine them.
|
||||
|
||||
---
|
||||
|
||||
## Mode A: Website / Sitemap
|
||||
|
||||
Use when: "build a sitemap wiki for my website", "map content gaps", "SEO audit wiki"
|
||||
|
||||
```
|
||||
vault/
|
||||
├── .raw/ # crawl exports, analytics, scraped pages, GSC data
|
||||
├── wiki/
|
||||
│ ├── pages/ # one note per URL: status, meta, content summary
|
||||
│ ├── structure/ # site architecture, nav hierarchy, internal link map
|
||||
│ ├── audits/ # content gaps, redirect needs, thin content flags
|
||||
│ ├── keywords/ # keyword clusters, target page assignments
|
||||
│ └── entities/ # brand, authors, topic hubs
|
||||
├── _meta/
|
||||
│ ├── index.md
|
||||
│ └── log.md
|
||||
└── CLAUDE.md
|
||||
```
|
||||
|
||||
Frontmatter for `wiki/pages/` notes:
|
||||
```yaml
|
||||
---
|
||||
type: page
|
||||
url: "https://example.com/page-slug"
|
||||
status: live # live | redirect | 404 | stub | no-index
|
||||
title: ""
|
||||
h1: ""
|
||||
meta_description: ""
|
||||
word_count: 0
|
||||
has_schema: false
|
||||
indexed: true
|
||||
canonical: ""
|
||||
internal_links_in: 0
|
||||
internal_links_out: 0
|
||||
last_crawled: YYYY-MM-DD
|
||||
tags: [page]
|
||||
created: YYYY-MM-DD
|
||||
updated: YYYY-MM-DD
|
||||
---
|
||||
```
|
||||
|
||||
Key wiki pages to create: `[[Site Overview]]`, `[[Navigation Structure]]`, `[[Content Gaps]]`, `[[Redirect Map]]`, `[[Keyword Clusters]]`
|
||||
|
||||
---
|
||||
|
||||
## Mode B: GitHub / Repository
|
||||
|
||||
Use when: "map my codebase", "architecture wiki for my repo", "understand this project"
|
||||
|
||||
```
|
||||
vault/
|
||||
├── .raw/ # README, git log exports, code dumps, issue exports
|
||||
├── wiki/
|
||||
│ ├── modules/ # one note per major module / package / service
|
||||
│ ├── components/ # reusable UI or functional components
|
||||
│ ├── decisions/ # Architecture Decision Records (ADRs)
|
||||
│ ├── dependencies/ # external deps, versions, risk assessment
|
||||
│ └── flows/ # data flows, request paths, auth flows
|
||||
├── _meta/
|
||||
│ ├── index.md
|
||||
│ └── log.md
|
||||
└── CLAUDE.md
|
||||
```
|
||||
|
||||
Frontmatter for `wiki/modules/` notes:
|
||||
```yaml
|
||||
---
|
||||
type: module # module | component | decision | dependency | flow
|
||||
path: "src/auth/"
|
||||
status: active # active | deprecated | experimental | planned
|
||||
language: typescript
|
||||
purpose: ""
|
||||
maintainer: ""
|
||||
last_updated: YYYY-MM-DD
|
||||
linked_issues: []
|
||||
depends_on: []
|
||||
used_by: []
|
||||
tags: [module]
|
||||
created: YYYY-MM-DD
|
||||
updated: YYYY-MM-DD
|
||||
---
|
||||
```
|
||||
|
||||
Key wiki pages to create: `[[Architecture Overview]]`, `[[Data Flow]]`, `[[Tech Stack]]`, `[[Dependency Graph]]`, `[[Key Decisions]]`
|
||||
|
||||
---
|
||||
|
||||
## Mode C: Business / Project
|
||||
|
||||
Use when: "project wiki", "competitive intelligence", "team knowledge base", "meeting notes"
|
||||
|
||||
```
|
||||
vault/
|
||||
├── .raw/ # meeting transcripts, Slack exports, docs, emails
|
||||
├── wiki/
|
||||
│ ├── stakeholders/ # people, companies, decision-makers
|
||||
│ ├── decisions/ # key decisions with rationale and date
|
||||
│ ├── deliverables/ # milestones, outputs, status tracking
|
||||
│ ├── intel/ # competitor analysis, market research
|
||||
│ └── comms/ # synthesized meeting notes, key threads
|
||||
├── _meta/
|
||||
│ ├── index.md
|
||||
│ └── log.md
|
||||
└── CLAUDE.md
|
||||
```
|
||||
|
||||
Frontmatter for `wiki/decisions/` notes:
|
||||
```yaml
|
||||
---
|
||||
type: decision # stakeholder | decision | deliverable | intel | meeting | competitor
|
||||
status: active # active | pending | done | blocked | superseded
|
||||
priority: 3 # 1 (highest) to 5 (lowest)
|
||||
date: YYYY-MM-DD
|
||||
owner: ""
|
||||
due_date: ""
|
||||
context: ""
|
||||
tags: [decision]
|
||||
created: YYYY-MM-DD
|
||||
updated: YYYY-MM-DD
|
||||
---
|
||||
```
|
||||
|
||||
Key wiki pages to create: `[[Project Overview]]`, `[[Stakeholder Map]]`, `[[Decision Log]]`, `[[Competitor Landscape]]`
|
||||
|
||||
---
|
||||
|
||||
## Mode D: Personal / Second Brain
|
||||
|
||||
Use when: "personal second brain", "track my goals", "journal synthesis", "life wiki"
|
||||
|
||||
```
|
||||
vault/
|
||||
├── .raw/ # journal entries, articles, podcast notes, voice transcripts
|
||||
├── wiki/
|
||||
│ ├── goals/ # personal and professional goals with progress tracking
|
||||
│ ├── learning/ # concepts being mastered, skill development
|
||||
│ ├── people/ # relationships, shared context, follow-ups
|
||||
│ ├── areas/ # life areas: health, finances, career, creative
|
||||
│ └── resources/ # books, courses, tools worth referencing
|
||||
├── _meta/
|
||||
│ ├── index.md
|
||||
│ ├── log.md
|
||||
│ └── hot-cache.md # ~500-word summary of most active context
|
||||
└── CLAUDE.md
|
||||
```
|
||||
|
||||
Frontmatter for `wiki/goals/` notes:
|
||||
```yaml
|
||||
---
|
||||
type: goal # goal | concept | person | area | resource | reflection
|
||||
status: active # active | paused | completed | abandoned
|
||||
area: career # health | career | finance | creative | relationships | growth
|
||||
priority: 1
|
||||
target_date: YYYY-MM-DD
|
||||
progress: 0 # 0-100 percent
|
||||
tags: [goal]
|
||||
created: YYYY-MM-DD
|
||||
updated: YYYY-MM-DD
|
||||
---
|
||||
```
|
||||
|
||||
Hot cache note: `_meta/hot-cache.md` is a ~500-word file Claude updates at the end of each session. It captures current focus areas, recent wins, and open threads. This prevents Claude from having to crawl the whole wiki to answer "where were we?".
|
||||
|
||||
Key wiki pages to create: `[[North Star]]`, `[[Weekly Review Template]]`, `[[Annual Goals]]`
|
||||
|
||||
---
|
||||
|
||||
## Mode E: Research
|
||||
|
||||
Use when: "research wiki on [topic]", "track papers I'm reading", "build a thesis"
|
||||
|
||||
```
|
||||
vault/
|
||||
├── .raw/ # PDFs, web clips, data files, raw notes
|
||||
├── wiki/
|
||||
│ ├── papers/ # paper summaries with key claims and methodology
|
||||
│ ├── concepts/ # extracted concepts, models, frameworks
|
||||
│ ├── entities/ # people, organizations, methods, datasets
|
||||
│ ├── thesis/ # evolving synthesis: the "state of the field" pages
|
||||
│ └── gaps/ # open questions, contradictions, research needed
|
||||
├── _meta/
|
||||
│ ├── index.md
|
||||
│ └── log.md
|
||||
└── CLAUDE.md
|
||||
```
|
||||
|
||||
Frontmatter for `wiki/papers/` notes:
|
||||
```yaml
|
||||
---
|
||||
type: paper # paper | concept | entity | thesis | gap
|
||||
status: summarized # raw | summarized | synthesized | superseded
|
||||
year: 2024
|
||||
authors: []
|
||||
venue: ""
|
||||
key_claim: ""
|
||||
methodology: ""
|
||||
contradicts: []
|
||||
supports: []
|
||||
tags: [paper]
|
||||
created: YYYY-MM-DD
|
||||
updated: YYYY-MM-DD
|
||||
---
|
||||
```
|
||||
|
||||
Key wiki pages to create: `[[Research Overview]]`, `[[Key Claims Map]]`, `[[Open Questions]]`, `[[Methodology Comparison]]`
|
||||
|
||||
---
|
||||
|
||||
## Mode F: Book / Course
|
||||
|
||||
Use when: "companion wiki for a book", "course notes wiki", "as I read [title]"
|
||||
|
||||
```
|
||||
vault/
|
||||
├── .raw/ # chapter notes, highlights, exercises
|
||||
├── wiki/
|
||||
│ ├── characters/ # characters, personas, agents, experts (adapt to content)
|
||||
│ ├── themes/ # major themes with supporting evidence
|
||||
│ ├── concepts/ # domain-specific terms and frameworks
|
||||
│ ├── timeline/ # plot structure, curriculum sequence, chapter map
|
||||
│ └── synthesis/ # your own takeaways, questions, applications
|
||||
├── _meta/
|
||||
│ ├── index.md
|
||||
│ └── log.md
|
||||
└── CLAUDE.md
|
||||
```
|
||||
|
||||
Frontmatter for `wiki/concepts/` notes:
|
||||
```yaml
|
||||
---
|
||||
type: concept # concept | character | theme | chapter | synthesis
|
||||
status: developing # stub | developing | mature
|
||||
source_chapters: []
|
||||
first_appearance: ""
|
||||
tags: [concept]
|
||||
created: YYYY-MM-DD
|
||||
updated: YYYY-MM-DD
|
||||
---
|
||||
```
|
||||
|
||||
Key wiki pages to create: `[[Book Overview]]`, `[[Theme Map]]`, `[[Character / Expert Index]]`, `[[My Takeaways]]`
|
||||
|
||||
---
|
||||
|
||||
## Combining Modes
|
||||
|
||||
You can combine modes. Examples:
|
||||
|
||||
- "GitHub repo + research on the AI approach used" -> Mode B folders + Mode E papers/ folder
|
||||
- "My SaaS business + second brain" -> Mode C intel/ + Mode D goals/
|
||||
- "YouTube channel" -> Mode F (content as "book") + Mode E (research on topics covered)
|
||||
|
||||
When combining, keep folder names distinct. Don't merge `decisions/` from Mode B and Mode C into one folder.
|
||||
@@ -0,0 +1,96 @@
|
||||
# Obsidian Setup
|
||||
|
||||
---
|
||||
|
||||
## Install Obsidian
|
||||
|
||||
### Linux (Flatpak: recommended)
|
||||
|
||||
Check if installed:
|
||||
```bash
|
||||
flatpak list 2>/dev/null | grep -i obsidian && echo "FOUND via flatpak" || \
|
||||
which obsidian 2>/dev/null && echo "FOUND in PATH" || echo "NOT FOUND"
|
||||
```
|
||||
|
||||
Install if not found:
|
||||
```bash
|
||||
flatpak install flathub md.obsidian.Obsidian
|
||||
```
|
||||
|
||||
### macOS
|
||||
|
||||
```bash
|
||||
ls /Applications/Obsidian.app 2>/dev/null && echo "FOUND" || brew install --cask obsidian
|
||||
```
|
||||
|
||||
### Windows
|
||||
|
||||
```powershell
|
||||
Test-Path "$env:LOCALAPPDATA\Obsidian" && echo "FOUND" || winget install Obsidian.Obsidian
|
||||
```
|
||||
|
||||
### All platforms: direct download
|
||||
|
||||
https://obsidian.md/download
|
||||
|
||||
---
|
||||
|
||||
## Open the Vault
|
||||
|
||||
After installing: Obsidian > Manage Vaults > Open Folder as Vault > select your vault directory.
|
||||
|
||||
---
|
||||
|
||||
## Core Plugins (Built-in: No Install Required)
|
||||
|
||||
These ship with Obsidian. Enable them in Settings > Core Plugins:
|
||||
|
||||
| Plugin | Purpose |
|
||||
|--------|---------|
|
||||
| **Bases** | Native database-like views for `.base` files. Powers `wiki/meta/dashboard.base`. Available since Obsidian v1.9.10 (August 2025). **Replaces Dataview for most wiki use cases.** |
|
||||
| **Properties** | Visual frontmatter editor. Always enabled. |
|
||||
| **Backlinks** | Outgoing/incoming links pane. |
|
||||
| **Outline** | Document heading navigation. |
|
||||
|
||||
## Recommended Community Plugins
|
||||
|
||||
Install via Settings > Community Plugins > Turn off Restricted Mode > Browse.
|
||||
|
||||
| Plugin | Purpose |
|
||||
|--------|---------|
|
||||
| **Templater** | Auto-populate frontmatter on note creation from `_templates/`. |
|
||||
| **Obsidian Git** | Auto-commit every 15 minutes. Protects against bad writes. |
|
||||
| **Calendar** | Right-sidebar calendar with word count, task, and link indicators. Pre-installed in this vault via `.obsidian/plugins/calendar/`. |
|
||||
| **Thino** | Quick memo capture panel in right sidebar. Pre-installed via `.obsidian/plugins/thino/`. |
|
||||
| **Iconize** | Visual folder icons for navigation. |
|
||||
| **Minimal Theme** | Best dark theme for dense information display. |
|
||||
| **Dataview** *(optional/legacy)* | Only needed if you're on Obsidian < 1.9.10 or want to use the legacy `dashboard.md` queries. The primary dashboard now uses Bases. |
|
||||
|
||||
**Calendar and Thino are pre-installed**. They ship with this vault. Enable them in Settings → Community Plugins → toggle on. No download needed.
|
||||
|
||||
If installing in a different vault: download `main.js` + `manifest.json` from their GitHub releases into `.obsidian/plugins/calendar/` and `.obsidian/plugins/thino/` respectively.
|
||||
|
||||
Optional additions:
|
||||
- **Smart Connections**: semantic search across all notes
|
||||
- **QuickAdd**: macros for fast note creation
|
||||
- **Folder Notes**: click a folder to open an overview note
|
||||
|
||||
---
|
||||
|
||||
## Web Clipper
|
||||
|
||||
The Obsidian Web Clipper browser extension converts web articles to markdown and sends them to `.raw/` in one click.
|
||||
|
||||
Install for Chrome, Firefox, or Safari from the Obsidian website.
|
||||
|
||||
Set the default folder to `.raw/` in the extension settings.
|
||||
|
||||
---
|
||||
|
||||
## After Installing Plugins
|
||||
|
||||
1. Enable Bases: Settings > Core Plugins > toggle on (already on by default in Obsidian v1.9.10+)
|
||||
2. Enable Templater: Settings > Templater > set template folder to `_templates`
|
||||
3. Enable Obsidian Git: Settings > Obsidian Git > Auto backup interval: 15 minutes
|
||||
4. Enable the CSS snippet: Settings > Appearance > CSS Snippets > toggle on `vault-colors`
|
||||
5. *(Optional)* Enable Dataview only if you want the legacy `wiki/meta/dashboard.md` queries to work alongside the primary `dashboard.base`
|
||||
@@ -0,0 +1,124 @@
|
||||
# REST API Quick Reference
|
||||
|
||||
Use these commands when MCP tools are not available. Requires the Local REST API plugin running in Obsidian (port 27124).
|
||||
|
||||
Set your key before running any command:
|
||||
```bash
|
||||
API="https://127.0.0.1:27124"
|
||||
KEY="your-api-key-here"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Read a file
|
||||
|
||||
```bash
|
||||
curl -sk \
|
||||
-H "Authorization: Bearer $KEY" \
|
||||
"$API/vault/wiki/index.md"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Create or replace a file
|
||||
|
||||
```bash
|
||||
curl -sk -X PUT \
|
||||
-H "Authorization: Bearer $KEY" \
|
||||
-H "Content-Type: text/markdown" \
|
||||
--data-binary @local-file.md \
|
||||
"$API/vault/wiki/entities/Name.md"
|
||||
```
|
||||
|
||||
Or with inline content:
|
||||
```bash
|
||||
curl -sk -X PUT \
|
||||
-H "Authorization: Bearer $KEY" \
|
||||
-H "Content-Type: text/markdown" \
|
||||
--data "# Page Title
|
||||
|
||||
Content here." \
|
||||
"$API/vault/wiki/concepts/Name.md"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Append to a file
|
||||
|
||||
```bash
|
||||
curl -sk -X POST \
|
||||
-H "Authorization: Bearer $KEY" \
|
||||
-H "Content-Type: text/markdown" \
|
||||
--data "- New log entry" \
|
||||
"$API/vault/wiki/log.md"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Patch a frontmatter field
|
||||
|
||||
```bash
|
||||
curl -sk -X PATCH \
|
||||
-H "Authorization: Bearer $KEY" \
|
||||
-H "Operation: replace" \
|
||||
-H "Target-Type: frontmatter" \
|
||||
-H "Target: status" \
|
||||
-H "Content-Type: application/json" \
|
||||
--data '"mature"' \
|
||||
"$API/vault/wiki/concepts/Name.md"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Append content under a heading
|
||||
|
||||
```bash
|
||||
curl -sk -X PATCH \
|
||||
-H "Authorization: Bearer $KEY" \
|
||||
-H "Operation: append" \
|
||||
-H "Target-Type: heading" \
|
||||
-H "Target: Connections" \
|
||||
-H "Content-Type: text/markdown" \
|
||||
--data "- [[New Page]]" \
|
||||
"$API/vault/wiki/entities/Name.md"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Search
|
||||
|
||||
Simple keyword search:
|
||||
```bash
|
||||
curl -sk -X POST \
|
||||
-H "Authorization: Bearer $KEY" \
|
||||
"$API/search/simple/?query=machine+learning"
|
||||
```
|
||||
|
||||
Dataview query:
|
||||
```bash
|
||||
curl -sk -X POST \
|
||||
-H "Authorization: Bearer $KEY" \
|
||||
-H "Content-Type: application/vnd.olrapi.dataview.dql+txt" \
|
||||
--data 'TABLE status FROM "wiki" WHERE status = "seed"' \
|
||||
"$API/search/"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## List all tags
|
||||
|
||||
```bash
|
||||
curl -sk \
|
||||
-H "Authorization: Bearer $KEY" \
|
||||
"$API/tags/"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## List files in a folder
|
||||
|
||||
```bash
|
||||
curl -sk \
|
||||
-H "Authorization: Bearer $KEY" \
|
||||
"$API/vault/wiki/entities/"
|
||||
```
|
||||
Reference in New Issue
Block a user