picvec

Local-first image similarity search.

日本語 · Install · Quick Start · Models · Development

---

picvec is an open-source CLI for visual similarity search. It runs vision models locally via ONNX Runtime, stores image embeddings in a local libsql database, and ranks matches with cosine distance.

Built by Arcnem AI, picvec reflects how we like to ship applied AI tools: local-first, inspectable, and useful without a cloud control plane.

Why picvec

• Local embeddings and local storage. Your images stay on your machine.
• Simple CLI workflow. init, embed, search, and list are enough to get useful results quickly.
• No external vector database. Similarity search runs from a local libsql database.
• Practical model choices. Start with CLIP for speed or switch to SigLIP2 for stronger retrieval quality.

Install

Download a release asset from GitHub Releases, or install with Go:

go install github.com/arcnem-ai/picvec@latest

To build from source:

git clone https://github.com/arcnem-ai/picvec.git
cd picvec
go build -o picvec

Release archives are currently published for macOS (arm64) and Linux (amd64).

Quick Start

picvec init
picvec embed test_images/cat1.jpg
picvec search test_images/cat1.jpg
picvec list

picvec init downloads ONNX Runtime, creates ~/.picvec/, initializes the local database, and fetches the default model.

Commands

Command	What it does
init	Download ONNX Runtime and the default model
embed [image]	Embed an image and store it
search [image]	Find similar images
list	List embedded images
set-model [name]	Set the default embedding model
config	Show current configuration
clean	Remove all picvec data

Global flag:

• -v, --verbose enables extra runtime output

Common Examples

Embed images:

picvec embed photo.jpg
picvec embed photo.jpg -m siglip2

If an embedding for the same path and model already exists, picvec skips it.

Search for similar images:

picvec search photo.jpg
picvec search photo.jpg -k 10
picvec search photo.jpg -m siglip2

Results are sorted by cosine distance. If the query image already exists in the database, it is excluded from the results.

Flag	Description	Default
-k, --limit	Number of results	5
-m, --model	Model to use	Config default

List indexed images:

picvec list
picvec list -m clip
picvec list -k 20

Flag	Description	Default
-k, --limit	Max images to show	All
-m, --model	Filter by model	All

Change the default model:

picvec set-model siglip2

Models

Name	Architecture	Embedding Dim	Notes
clip	CLIP ViT-B/32	512	Default. Fast and good for general-purpose similarity search.
siglip2	SigLIP2 Base Patch16	768	Higher-quality embeddings with a larger vector size.

Both models use 224x224 inputs and quantized ONNX weights from Hugging Face.

How It Works

1. Images are resized and normalized with the selected model's preprocessing config.
2. The selected vision model runs via ONNX Runtime and produces an embedding vector.
3. Multi-token outputs are mean-pooled, then L2-normalized.
4. Embeddings are stored as binary blobs in a local libsql database.
5. Search uses vector_distance_cos() for cosine similarity ranking.

Data Storage

All runtime data lives in ~/.picvec/:

~/.picvec/
  config.json       # Configuration such as the default model
  picvec.db         # libsql database
  models/           # Downloaded ONNX model files
  lib/              # ONNX Runtime shared library

Use picvec clean to remove everything.

Repository Layout

• cmd/ Cobra commands and user-facing output
• core/ Model registry, preprocessing, runtime setup, downloads, and embedding pipeline
• store/ Schema migration, inserts, listing, and vector search queries
• config/ ~/.picvec path helpers and config bootstrapping
• test_images/ Sample assets for manual testing

Platforms

OS	Published Release	Hardware Acceleration
macOS	arm64	CoreML when available
Linux	amd64	CPU

The runtime setup includes paths for additional architectures, but GitHub Releases currently publish the targets above because the project depends on CGO-backed libraries that need native builds.

ONNX Runtime 1.24.3 is downloaded automatically on first run.

Development

go test ./...
go build -o picvec

See CONTRIBUTING.md for contribution workflow and AGENTS.md for repo-specific agent instructions.

---

Built by Arcnem AI.