Vaultkeeper

Note: This plugin is being vibe coded. So, if you are not wanting AI code in your vault, please do not use this plugin. Though I am a full time Full Stack Developer so I can validate none of the code is leaking secrets or collecting personal data if that helps you.

A comprehensive Obsidian plugin that organizes and manages attachments, renames pasted files automatically, and extracts text from images and PDFs using OCR — all within your vault.

🚀 Features

📁 Attachment Organization

• Flexible destination: Move attachments using Obsidian's built-in setting, same folder as the linking note, or a separate named folder
• Subfolder sorting: Sort into subfolders by date, file type, or a custom pattern using tokens like {{year}}, {{month}}, {{day}}, {{type}}, {{filename}}
• Configurable extensions: Define exactly which file types count as attachments
• Ignore rules: Skip specified folders during organizing or purging
• Empty folder cleanup: Folders left empty after organizing are automatically deleted
• Auto-organize: Run on startup and/or on a repeating interval

✏️ Paste Rename

• Automatically rename files when pasted or dropped into a note
• Five modes: do nothing, date-based, custom pattern, ask each time, or date pre-filled + ask to confirm
• Tokens: {{year}}, {{month}}, {{day}}, {{time}}, {{type}}, {{filename}} (active note name), {{original}} (pasted file's original name)
• Embed links in the note are updated automatically to match the new filename

🧹 Attachment Cleanup

• Find Unlinked Attachments: Identify attachment files not linked from any note
• Purge Unlinked Attachments: Safely delete unlinked attachments — select all, none, or individual files via checkboxes, then confirm before anything is deleted

🔍 OCR (Optical Character Recognition)

• Four providers: a custom/self-hosted OpenAI-compatible server (Ollama, LM Studio, vLLM, llama.cpp, LiteLLM), OpenAI, Anthropic, or Google Gemini
• Extract text from images (PNG, JPG, JPEG, WEBP, BMP, GIF, HEIC, HEIF) and PDFs
• Progress notice stays on screen with an elapsed-time counter until the run finishes — self-hosted models can take minutes
• Watch and output folders can follow Obsidian's attachment setting or Vaultkeeper's own organize destination
• Route OCR notes to a sibling folder beside watched attachment folders (for example _files → _ocr) while preserving nested paths
• Custom note properties: define whatever YAML frontmatter you want on OCR notes
• Auto-process new files added to a watch folder
• Auto-update OCR notes when source files are modified
• Process files in batches with rate-limit handling and exponential backoff
• Fully customizable prompt and output note template
• Pick any individual file to OCR via command palette

Installation

🧪 Using BRAT (Beta Reviewer's Auto-update Tool)

1. Install the BRAT plugin
2. Open BRAT settings
3. Click Add Beta Plugin
4. Enter: DudeThatsErin/vaultkeeper
5. Click Add Plugin
6. Enable "Vaultkeeper" in Community Plugins settings

📘 Usage

🔄 Organizing Attachments

1. Open Settings > Attachment Organizer > Organization Settings
2. Set your Destination:
   • Use Obsidian settings — respects your vault's "Default location for new attachments" setting
   • Same folder as current file — moves attachments to the same folder as the note that links to them
   • Custom folder within same folder as current file — creates a relative folder such as _files beside each linking note (for example 02 - Journals/August/_files)
   • Separate folder — uses a configured folder name (e.g. attachments)
3. Optionally choose Sort into subfolders by (none, date, file type, or custom pattern)
4. Run "Organize attachments" from the Command Palette (Ctrl/Cmd+P)

✏️ Paste Rename

1. Open Settings > Attachment Organizer > Paste Rename Settings
2. Choose a Rename mode:
   • Do not rename — default, no change
   • Date-based — auto-rename using a date pattern (e.g. 2026-05-04.png)
   • Custom pattern — auto-rename using any token combination
   • Ask each time — a prompt appears after each paste so you can type the name
   • Date-based + ask to confirm — prompt pre-filled with the date pattern
3. Configure the pattern using tokens: {{year}}, {{month}}, {{day}}, {{time}}, {{type}}, {{filename}} (note name), {{original}} (pasted file's original name)

🗑 Purging Unlinked Attachments

1. Run "Purge unlinked attachments" from the Command Palette
2. A modal lists all unlinked attachments with checkboxes (all selected by default)
3. Use Select All / Select None to bulk-toggle, or check/uncheck individual files
4. Click Delete Selected → review the confirmation list → click Delete to permanently remove, or ← Back to revise
5. Click Cancel at any point to abort

🔍 Using OCR

Setup

1. Open Settings > Vaultkeeper > OCR
2. Toggle Enable OCR on
3. Pick an OCR provider and configure it:
   • Custom / self-hosted — set the base URL of any OpenAI-compatible server and a vision-capable model name. An API key is optional. Use Test connection to confirm the server is reachable and lists your model.
   • OpenAI — save your API key as a secret and set a vision-capable model
   • Anthropic — save your API key as a secret and set a Claude model
   • Google Gemini — save your API key as a secret and pick a model
4. Set the OCR watch folder: a specific folder, every folder with a specific name (for example every _files folder), Obsidian's attachment folder, or Vaultkeeper's organize destination
5. Set the OCR output folder: Sibling folder next to watched folder (recommended for _files → _ocr), a specific folder, the source file's folder, Obsidian's attachment folder, or Vaultkeeper's organize destination

Self-hosted example (Ollama)

Pull a multimodal model — a text-only model will fail with "model does not support multimodal requests":

ollama pull qwen2.5vl:7b

Then set Custom server base URL to http://localhost:11434/v1 and Custom model to qwen2.5vl:7b. Nothing leaves your machine. Raise Custom request timeout if the model runs on CPU.

PDFs are only supported by Gemini and Anthropic. OpenAI and self-hosted vision models take images only — convert pages to images first.

Commands

Output format

Each OCR result is saved as a .md note (e.g. screenshot.png → screenshot (OCR).md) using a customizable template. Default structure:

---
ocr-processed: true
---

# OCR Result for screenshot.png

## Extracted Text

[extracted text here]

Turn on Note properties to add your own YAML frontmatter. For example:

source: "[[{{path}}]]"
processed: {{date}}
status: {{status}}

produces:

---
source: "[[assets/screenshot.png]]"
processed: 2026-08-11
status: completed
ocr-processed: true
---

The OCR processed field is always appended (and not duplicated if you list it yourself).

Supported file types

Images: PNG, JPG, JPEG, WEBP, BMP, GIF, HEIC, HEIF — Documents: PDF

⚙️ Settings Reference

General Settings

Organization Settings

Paste Rename Settings

Available tokens for paste rename patterns:

Purge Settings

OCR Settings

OCR Processing Settings

OCR Templates

Available variables in both the properties and the output template:

Support

• 💬 Discord Support — fastest response
• 🐛 Report Issues
• ⭐ Star on GitHub
• ☕ Buy Me a Coffee