Pocket Vec

A CLI tool to do vector search on your files using DuckDB with VSS (Vector Similarity Search).

Installation

pip install -e .

Usage

Basic initialization

pkv init

Custom database path

pkv init my_vectors.db

Custom dimension and metric

pkv init --dim 768 --metric l2

Overwrite existing database

pkv init --force
pkv init my_vectors.db --force

Get help

pkv init --help
pkv --help

Ingest

Basic usage

pkv ingest /path/to/files

With custom database

pkv ingest /path/to/files --db my_vectors.db

With options

pkv ingest /path/to/files --chunk-size 1000 --overlap 200

Features

• 🗄️ DuckDB Integration - Fast, embedded database
• 🔍 Vector Search - VSS extension for similarity search
• ⚙️ Configurable - Custom dimensions and distance metrics
• 🛡️ Safe Defaults - Won't overwrite existing databases without --force
• 🎨 Rich CLI - Beautiful, colored terminal output

Commands

Command	Description
pkv init [DB_PATH]	Initialize a new vector database
pkv test	Test command

Options

Option	Description	Default
--dim	Vector dimension	384
--metric	Distance metric (l2, cosine, etc.)	l2
--force	Overwrite existing database	False