# Claude Vault Citations

Ask questions about your Obsidian vault and get back answers with **verified citations** to the exact notes and passages that support each claim — powered by Anthropic's [Citations API](https://docs.claude.com/en/docs/build-with-claude/citations).

> Most "chat with your notes" plugins paste your notes into a prompt and hope the model attributes its claims correctly. This one uses Claude's first-class citations support, so every cited passage is a guaranteed pointer back to a real chunk of your vault.

![sidebar screenshot placeholder](docs/screenshot.png)

## What makes it different

- **Real citations, not hallucinated ones.** Citations come from Anthropic's native API, not from a prompt asking the model to "include sources." `cited_text` is guaranteed to come from your notes.
- **Click a citation, jump to the note.** Each inline citation pill is a link to the source note at the cited paragraph.
- **Prompt caching.** Large note context is cached on Anthropic's side, so follow-up questions in the same session are cheaper and faster.
- **Granular by paragraph.** Notes are chunked into paragraph blocks before being sent, so citations land on the right passage — not the whole file.
- **Stays in your vault.** Your Anthropic API key is stored locally in the vault's plugin data. Only the top-ranked notes for a given question are sent to Anthropic.

## Install

### From the community plugins browser (after submission is approved)

1. Settings → Community plugins → Browse → search for "Claude Vault Citations"
2. Install → Enable
3. Open settings and paste your Anthropic API key

### Manual install (now)

1. Download `main.js`, `manifest.json`, and `styles.css` from the [latest release](https://github.com/nord342/obsidian-claude-citations/releases/latest).
2. Place them in `<your-vault>/.obsidian/plugins/claude-vault-citations/`.
3. In Obsidian: Settings → Community plugins → enable **Claude Vault Citations**.
4. Open settings, paste your API key from [console.anthropic.com](https://console.anthropic.com).

## Use

- Click the quote icon in the left ribbon, or run **Claude Vault Citations: Open chat** from the command palette.
- Type a question. The plugin ranks your notes against the question (BM25), sends the top-N as document blocks with citations enabled, and renders the response with clickable citation pills.
- Select text in any note → run **Ask Claude using current selection** to seed a question.
- ⌘/Ctrl-Enter sends.

## Settings

| Setting | Default | Notes |
| --- | --- | --- |
| Model | `claude-sonnet-4-6` | Opus 4.7 / Sonnet 4.6 / Haiku 4.5. Citations are supported on all current models. |
| Max response tokens | 2048 | |
| Max notes per question | 12 | More notes = better recall, higher cost |
| Max characters per note | 8000 | ≈ 2000 tokens; long notes are trimmed |
| Include / exclude folders | exclude: `.trash,.obsidian,templates` | Comma-separated paths |
| Prompt caching | on | Cache the largest document block per request |
| System prompt | (research-assistant default) | Editable |

## How it works

1. **Retrieve.** Your question is tokenized and scored against every markdown file in scope using BM25 with a small title boost.
2. **Chunk.** Each candidate note is split into paragraph blocks (code fences kept intact). Blocks are sent as a `custom content` document so the model can cite at paragraph granularity.
3. **Ask.** The notes are sent to Claude as `document` content blocks with `citations.enabled: true`. The last (largest) document gets `cache_control: ephemeral` so subsequent questions in the session are cheaper.
4. **Render.** Response text blocks are rendered inline. Each one with a `content_block_location` citation gets a clickable pill that jumps to the right note at the right line.

## Privacy

- Your API key is stored locally in `<vault>/.obsidian/plugins/claude-vault-citations/data.json`.
- For each question, only the top-N notes matched by BM25 are sent to Anthropic. Nothing else leaves your vault.
- Anthropic's [Citations docs](https://docs.claude.com/en/docs/build-with-claude/citations) state that the citations feature is eligible for Zero Data Retention if your org has a ZDR arrangement.

## Development

```bash
git clone https://github.com/nord342/obsidian-claude-citations
cd obsidian-claude-citations
npm install
npm run dev      # esbuild watch mode
npm run build    # production bundle
```

Symlink the repo into `<your-vault>/.obsidian/plugins/claude-vault-citations/` to develop against a real vault.

## License

MIT — see [LICENSE](LICENSE).