localvectordb documentation
A document-first vector database. SQLite + FAISS, zero infrastructure.
You bring documents; LocalVectorDB handles chunking, embedding, and indexing. Search them by meaning, by keyword, or both at once — through one API that works identically against a local file and a remote server.
from localvectordb import VectorDB
db = VectorDB("my_docs", "./data")
db.upsert([
"Python is a programming language",
"Machine learning with neural networks",
])
for result in db.query("programming", k=5):
print(f"{result.id}: {result.score:.3f} {result.content}")
That is a complete, running program. No server to stand up, no index to configure, no chunking to hand-roll.
Install it, index your first documents, and run a hybrid search in about five minutes.
End-to-end tutorials: a RAG pipeline, an FAQ bot, a downloads indexer, and a custom embedding provider.
How documents, chunks, embeddings, and metadata fit together — and why the API is shaped the way it is.
Full API reference for the library, the HTTP server, the CLI, and the TypeScript SDK.
What makes it different
Plenty of libraries will embed a list of strings for you. These are the things LocalVectorDB does that most vector stores do not.
In a long report the answer is usually a whole section, not one stray sentence — so LocalVectorDB embeds each section’s own text and retrieves it alongside chunks. Not a hunch: a controlled study across three local encoders puts it +0.03–0.08 nDCG@10 over a chunk-only baseline for finding the right document, and +0.07–0.17 for the right section. Read the study.
Point it at LLM-generated text and your corpus, and it scores each claim for grounding — citing a supporting excerpt, or flagging the claim as unsupported or contradicted.
Nearest neighbours and similarity matrices at whole-document level, t-SNE and PCA embedding maps, and synteny ribbons showing how two documents align chunk by chunk.
Choose your path
Working in Python. Start with Quickstart, then Query Types and Return Modes for the search API and Metadata Filtering Guide for narrowing results by structured fields.
Standing up a service. Server covers the FastAPI server,
authentication, and rate limiting. JavaScript / TypeScript SDK documents the TypeScript
client, and Command-Line Interface the lvdb command.
Wiring it into an AI agent. MCP Server sets up the built-in Model Context Protocol server, which lets Claude Code, Claude Desktop, and other MCP clients search your databases directly — read-only by default.
Tuning for scale. Chunking and Embeddings control what gets indexed and how. Document Scoring Methods covers the chunk-to-document aggregation strategies. Performance Tuning Guide has the benchmark numbers.
Retrieving from long documents. Hierarchical Embeddings turns on section-level indexing and explains the knobs; Raw-Span Hierarchical Retrieval: Method and Evaluation is the controlled study behind its defaults — read it if you want to know whether the feature is worth enabling for your corpus and encoder, and why.