Henner M. Kruse
104 lines
3.9 KiB
Markdown
104 lines
3.9 KiB
Markdown
# obsidian-vault-kb
|
|
|
|
Turns an Obsidian vault — a folder of Markdown notes with frontmatter,
|
|
`#tags`, and `[[wikilinks]]` — into a knowledge base Claude can search and
|
|
reason over. Works with any vault, on any topic: homelab documentation,
|
|
project notes, research, whatever you keep in Obsidian.
|
|
|
|
## What it does
|
|
|
|
- **Reads your vault's own structure** rather than imposing one: your
|
|
folders become topical categories, your tags and frontmatter become
|
|
filters, your wikilinks let Claude follow related notes (backlinks) the
|
|
same way you would clicking through the graph.
|
|
- **Answers grounded in what's actually in your notes.** If the vault
|
|
doesn't have an answer, Claude says so instead of guessing, and keeps
|
|
general knowledge clearly separate from what came from your vault.
|
|
- **Optionally writes back**, depending on the mode you choose at setup —
|
|
from strictly read-only, to appending new dated notes, to actively
|
|
updating existing ones.
|
|
|
|
## Setup
|
|
|
|
After installing the plugin:
|
|
|
|
```
|
|
/obsidian-vault-kb:setup
|
|
```
|
|
|
|
This will ask you for:
|
|
|
|
1. **The vault path(s).** You can register more than one vault (e.g. a
|
|
personal one and a work one) and refer to them by name.
|
|
2. **A mode:**
|
|
- `read-only` — Claude can search and read, never write anything.
|
|
- `append` — Claude can also file new findings as new, dated notes.
|
|
Existing notes are never touched.
|
|
- `maintain` — Claude can also update existing notes directly (e.g. add
|
|
a dated "Update" section, change a status field).
|
|
|
|
It also whitelists three narrow, read-only helper scripts (see below) so
|
|
searching your vault doesn't require a permission prompt on every single
|
|
`find`/`grep` call.
|
|
|
|
## Usage
|
|
|
|
You don't need to invoke anything explicitly — just ask Claude things like:
|
|
|
|
- "What did I write about the Ceph cluster rebuild?"
|
|
- "Check my notes for how I set up mTLS on Postfix."
|
|
- "Any open items in my homelab notes related to DNS?"
|
|
|
|
Claude recognizes references to "my notes", "my vault", "my docs", etc.
|
|
and searches automatically. Under the hood it uses three scripts:
|
|
|
|
- `vault_index.sh` — folder structure, note counts, tags, index/MOC files
|
|
- `vault_search.sh "<query>"` — full-text search, optionally scoped to a
|
|
subfolder
|
|
- `vault_backlinks.sh "<note-name>"` — notes linking to a given note
|
|
|
|
All three resolve the vault path only from
|
|
`~/.agent-skills/obsidian-vault-kb/config.json` — they can't be pointed at
|
|
a different directory than what you configured, which is what makes it
|
|
safe to whitelist them without granting broader filesystem access.
|
|
|
|
## Writing to your vault
|
|
|
|
Only relevant in `append` or `maintain` mode:
|
|
|
|
- **`append`** — new findings are filed as new notes (e.g.
|
|
`Notes/2026-08-04-dns-fix.md`), with frontmatter and wikilinks to related
|
|
topics. Existing files are never modified.
|
|
- **`maintain`** — Claude may extend an existing note directly instead of
|
|
creating a new one, when that's the more natural place for the
|
|
information. You'll always see a summary of what's about to be written
|
|
before it happens.
|
|
- Writing into the vault is never in the permissions whitelist, regardless
|
|
of mode — every write stays a normal, visible, confirmable action.
|
|
|
|
## Multiple vaults
|
|
|
|
Registered vaults live in `~/.agent-skills/obsidian-vault-kb/config.json`:
|
|
|
|
```json
|
|
{
|
|
"vaults": [
|
|
{"name": "homelab", "path": "/absolute/path/to/homelab-vault"},
|
|
{"name": "worldbuilding", "path": "/absolute/path/to/tangier-vault"}
|
|
],
|
|
"mode": "append"
|
|
}
|
|
```
|
|
|
|
If you only ever use one vault, you don't need to name it when asking
|
|
Claude to search — it's used by default.
|
|
|
|
## What's deliberately *not* included
|
|
|
|
- No generic `Bash(find:*)`, `Bash(rg:*)`, `Bash(grep:*)`, or `Bash(cat:*)`
|
|
— those would allow reading anywhere on the filesystem, not just your
|
|
vault.
|
|
- No auto-approved writes — not to notes, not to the config file.
|
|
- Binary attachments (PDFs, images) inside the vault aren't read
|
|
automatically, only referenced, unless you ask for them specifically.
|