Docs

Local-first vault for blobs you have seen and saved. Short practical guides — 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.

Until the build is Apple-notarized, macOS may say the app is “damaged” after a browser download. That is Gatekeeper quarantine on an unsigned build — clear it, then open:

xattr -cr /Applications/BlobberVault.app

Notarized releases open without that step. See /download for the full install note.

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.
If macOS says BlobberVault is “damaged” (unsigned build): xattr -cr /Applications/BlobberVault.app then open again. Right-click → Open alone is often not enough.
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 (developers)

The packaged DMG ships the Tauri app + photokb-sidecar (API / Ask / Capture Python, …). The MCP stdio server (photokb-mcp) is intentionally not inside the DMG — it stays a separate CLI so Claude Desktop / Cursor can spawn it without growing the installer freeze.

If Claude “worked before,” the config almost certainly pointed at a dev venv binary from a git checkout, for example /path/to/fototof/apps/backend/.venv/bin/photokb-mcp. That process talks to the running app’s localhost sidecar via sidecar_auth.json — it is not embedded in the downloaded app.

Keep BlobberVault open (sidecar up).
From a clone: cd apps/backend && pip install -e '.[mcp]'
Point Claude / Cursor at …/.venv/bin/photokb-mcp (Settings → Local MCP has copyable snippets).
Optional: make mcp-doctor.

Collections → Expose as MCP publishes a local fleet slice — app must stay open.
Never claim MCP is “bundled in the installer.”

10. Release notes / changelog

See /changelog and GitHub Releases for version history.