Docs

Short practical guides for a private local knowledge base — install, search, Strict Local, and local MCP. Personal local AI with explainable outputs (OCR, tags, source paths). For architecture depth, see the repository docs.

1. Install BlobberVault

Download the DMG from /download, open it, and drag BlobberVault into Applications. Launch from Applications.

First launch shows the Vault Gate while the local backend starts. Packaged cold start often takes tens of seconds (not instant). If it sticks, wait up to about 90 seconds, then use Retry or Open logs.

Current macOS builds are Apple-signed and notarized — open normally after install. See /download for checksums and release notes.

2. Import your first folder

Open Load, link a local folder, and start indexing. Originals stay on disk; derived index data lives under Application Support.

Your disk

Originals

~/Pictures · Downloads · linked folders
never copied by default

BlobberVault

Index

~/Library/Application Support/PhotoKB/
SQLite · LanceDB · thumbs (derived)

Delete the vault folder to wipe derived data. Source files stay where you left them.

Use Capture for LinkedIn / X / YouTube flows when you want browser-assisted import. Capture launches system Chrome — it does not ship a browser inside the DMG.

3. Tags & AI vision

On-device OCR and tagging run in the local pipeline. Semantic CLIP and face extras are not frozen into the public DMG sidecar — the app stays honest when those packs are missing.

Optional OpenAI is metadata-only query planning when you enable it and store a key in the Keychain — never a default vision upload of your library.

4. Search & Ask

Search covers OCR text, tags, and filters with evidence in the detail drawer. Ask runs hybrid RAG against your vault with citations after the local model pack is ready.

Stage	What happens	Where
	Link folders or Capture; originals never copied by default. Sources stay as paths on disk. Indexing is resumable from media_processing_state.	local
	On-device vision turns screens into searchable text and explainable tags. Model outputs are versioned. Scores and user-confirmed flags stay with each blob.	local
	Embeddings land in local LanceDB when the semantic pack is available. Public DMG is honest when extras are missing — no fake “fully semantic” claim.	local
	OCR, tags, filters, and evidence in one hub. Every hit can show why it matched — score, model version, confirmed flag.	local
	Hybrid RAG with citations from your vault. Optional OpenAI is metadata-only query planning — never image upload by default.	local

Click a stage name for evidence details.

5. Export / structured data

Export Markdown and JSON from the media drawer or export flows. Structured records are meant for notes, automation, and backups — not a cloud sync product.

6. Privacy & Strict Local

Default posture is Strict Local. Full Q&A lives on /privacy. Storage path: ~/Library/Application Support/PhotoKB/ (internal data directory name — product display name is BlobberVault).

7. macOS permissions / troubleshooting

Grant folder access when macOS prompts — indexing needs read access to linked sources.
Capture needs Google Chrome installed for CDP launch.
Video / YouTube readiness depends on bundled or user-provided ffmpeg / yt-dlp — check the in-app checklist.

8. Models & on-device processing

Core OCR/tagging packs download or run from the packaged sidecar. Optional SmolVLM weights download in-app when you choose them — they are not baked into the DMG. Semantic and faces extras remain opt-in / developer paths when absent from the freeze.

9. Local MCP

The packaged DMG ships the Tauri app, photokb-sidecar, and a slim MCP stdio server (photokb-mcp at /Applications/BlobberVault.app/Contents/MacOS/photokb-mcp. Cursor / Claude Desktop spawn that binary; the app does not start MCP at boot. Tools talk to the running localhost sidecar via sidecar_auth.json — your library stays on-device.

Keep BlobberVault open (sidecar up).
Copy the Cursor / Claude snippet from Settings → Local MCP or Collections → Expose as MCP (absolute path resolved for you).
Optional: make mcp-doctor.
Contributors / from-source: cd apps/backend && pip install -e '.[mcp]' then point agents at …/.venv/bin/photokb-mcp.

Collections → Expose as MCP publishes a local fleet slice — app must stay open.
Auth file is written under Application Support while the sidecar runs and cleared on quit.

10. Release notes / changelog

See /changelog and GitHub Releases for version history.