# VectrixDB

> VectrixDB is a Python vector database that works with no network and no accounts. The embedding model ships inside the package, so `pip install vectrixdb` and `Vectrix("name").search(...)` work offline. It adds hybrid search with a reranker, document ingestion with citations, per-person access rules, evaluation that picks a setup, a REST server with a dashboard, an MCP server, and eight storage backends including Azure AI Search.

Notes for coding agents:

- Start from `from vectrixdb import Vectrix`. `db = Vectrix("docs", path="./data")` persists to SQLite. `db.add(texts, metadata=...)` adds strings; `db.add_document(path_or_markdown)` loads, chunks and cites a file. `db.search(query, limit=10, mode=..., filter=...)` returns `Results`; each item has `.text`, `.score`, `.relevance`, `.metadata` and `.citation`, the string to cite it by.
- Modes are `dense`, `sparse`, `hybrid`, `ultimate` and `graph`. Hybrid and above rerank with a cross-encoder by default.
- The base install has five dependencies. Extras add the rest: `api` (REST server and dashboard), `signin`, `mcp`, `documents` (PDF, Office, HTML), `tracing` (OpenTelemetry), `azure`, `aws`, `postgres`, `databricks`, `hf`, `fastembed`, `masking`, `nlp`.
- Errors are typed: catch `vectrixdb.exceptions.VectrixError` or a subclass, never bare `Exception`.
- Change chunking with `db.rechunk(...)` only after showing the person `db.rechunk_preview(...)` with the same arguments.
- Tracing is off unless the person asks for it. Never turn it on silently; it is `pip install "vectrixdb[tracing]"` plus `OTEL_EXPORTER_OTLP_ENDPOINT`, and spans never carry query or document text.
- Pick a setup with `vectrixdb.evaluation.evaluate(db, "golden.jsonl")` on the person's own questions instead of guessing a mode.
- To run the server as a service, use the published image `ghcr.io/knowusuboaky/vectrixdb` with `docker/compose.yaml` or `docker/kubernetes` rather than writing a Dockerfile. It refuses to start without `VECTRIXDB_API_KEY` (or `VECTRIXDB_API_KEY_FILE`) or sign-in, and that is on purpose.

## Start here

- [Getting started](https://knowusuboaky.github.io/VectrixDB/tutorial/getting-started/): from an empty directory to a working search
- [Add VectrixDB with your coding agent](https://knowusuboaky.github.io/VectrixDB/how-to/coding-agents/): a prompt to paste into an agent, and what it should do
- [The VectrixDB skill](https://github.com/knowusuboaky/VectrixDB/blob/main/skills/vectrixdb/SKILL.md): the same rules as a skill an agent loads by itself, to copy into the skills folder your agent reads
- [Easy API](https://knowusuboaky.github.io/VectrixDB/reference/easy/): the `Vectrix` surface
- [Handle errors](https://knowusuboaky.github.io/VectrixDB/how-to/handle-errors/): every exception and what to do about it
- [Install what you need](https://knowusuboaky.github.io/VectrixDB/how-to/install/): every extra and what it adds
- [The skill for an assistant over MCP](https://github.com/knowusuboaky/VectrixDB/blob/main/skills/vectrixdb-mcp/SKILL.md): which tool when, filter after describing, cite every claim, ask before deleting

## Documents

- [Ingest documents](https://knowusuboaky.github.io/VectrixDB/how-to/ingest-documents/): chunking strategies, parent sections, duplicates
- [Extract, keep, index](https://knowusuboaky.github.io/VectrixDB/how-to/extract-keep-index/): keep the Markdown, rechunk without re-reading, preview a rechunk
- [Ingest when a file lands](https://knowusuboaky.github.io/VectrixDB/how-to/ingest-on-event/): blob and S3 events, a worker
- [Keep a collection in step with feeds and pages](https://knowusuboaky.github.io/VectrixDB/how-to/sources/): RSS, Atom, JSON Feed, podcasts and pages read again on a schedule, only what changed written
- [Run an extraction service](https://knowusuboaky.github.io/VectrixDB/how-to/extraction-service/): OCR and parsing behind HTTP
- [Trace an answer to its source](https://knowusuboaky.github.io/VectrixDB/how-to/lineage/): citations and lineage
- [Chunking](https://knowusuboaky.github.io/VectrixDB/how-to/chunking/): the strategies, parent sections, late chunking, rechunk and its preview
- [Extraction quality and blocked pages](https://knowusuboaky.github.io/VectrixDB/how-to/extraction-quality/): the score every chunk carries, the threshold, and bot-check pages refused
- [Videos, podcasts and recordings](https://knowusuboaky.github.io/VectrixDB/how-to/recordings/): speech, video, YouTube captions, cited by the second
- [Embedding models](https://knowusuboaky.github.io/VectrixDB/how-to/embedding-models/): which ship in the wheel, which download, and bringing your own

## Search quality

- [Search modes](https://knowusuboaky.github.io/VectrixDB/explanation/search-modes/): what each mode does and costs
- [Score and relevance](https://knowusuboaky.github.io/VectrixDB/explanation/relevance/): what the numbers on a result mean
- [Measure retrieval](https://knowusuboaky.github.io/VectrixDB/how-to/measure-retrieval/): recall, MRR and nDCG on golden questions
- [Evaluate every setup](https://knowusuboaky.github.io/VectrixDB/how-to/evaluate-setups/): rank every setup and pick three
- [Work with the knowledge graph](https://knowusuboaky.github.io/VectrixDB/how-to/knowledge-graph/): graph mode
- [Search options](https://knowusuboaky.github.io/VectrixDB/how-to/search-options/): every argument of search, and what a result carries

## Apps and servers

- [Run the REST API](https://knowusuboaky.github.io/VectrixDB/how-to/rest-api/): `vectrixdb serve`
- [Build an app on it](https://knowusuboaky.github.io/VectrixDB/how-to/build-an-app/): from any language, over HTTP
- [Use it from Python, TypeScript, Go or Rust](https://knowusuboaky.github.io/VectrixDB/how-to/clients/): the four clients, one surface
- [Use the command line on a server](https://knowusuboaky.github.io/VectrixDB/how-to/command-line-server/): every command with --url, a key file or a company sign-in, safe behind a gateway
- [Ship your own client or command on it](https://knowusuboaky.github.io/VectrixDB/how-to/wrap-it/): a company's wrapper around a client or the command, the licence, publishing to Artifactory or another registry
- [Run it inside your company's registry](https://knowusuboaky.github.io/VectrixDB/how-to/inside-your-registry/): JFrog Artifactory repositories for PyPI, npm, Go, Cargo, the images and the models; machines pointed at it; images built in-house with build secrets; VECTRIXDB_MODELS_URL; VECTRIXDB_OIDC_API_CLIENTS to require the company's tool
- [Use the dashboard](https://knowusuboaky.github.io/VectrixDB/how-to/dashboard/): every page
- [Sign people in](https://knowusuboaky.github.io/VectrixDB/how-to/sign-in/): single sign-on, keys, roles
- [Restrict what a search can see](https://knowusuboaky.github.io/VectrixDB/how-to/entitlements/): per-person access rules
- [Deploy the server](https://knowusuboaky.github.io/VectrixDB/how-to/deploy/): one file of settings, checked before a start
- [Run it in containers](https://knowusuboaky.github.io/VectrixDB/how-to/containers/): the signed images, Docker Compose, Kubernetes
- [Put it behind a gateway](https://knowusuboaky.github.io/VectrixDB/how-to/behind-a-gateway/): APIM, API Gateway, any proxy
- [Put your company's name on it](https://knowusuboaky.github.io/VectrixDB/how-to/branding/): branding
- [Trace searches and ingestion](https://knowusuboaky.github.io/VectrixDB/how-to/tracing/): opt-in OpenTelemetry spans
- [Use it from an assistant over MCP](https://knowusuboaky.github.io/VectrixDB/how-to/mcp-server/): the MCP server
- [Keep conversation memory](https://knowusuboaky.github.io/VectrixDB/how-to/conversation-memory/): memory for agents
- [Use it from async code](https://knowusuboaky.github.io/VectrixDB/how-to/async/): the library and the client from asyncio
- [Connect your client](https://knowusuboaky.github.io/VectrixDB/how-to/mcp-connect/): MCP config for VS Code, Cursor, a desktop assistant and a command line
- [Company sign-in for MCP](https://knowusuboaky.github.io/VectrixDB/how-to/mcp-sign-in/): the protected-resource document, Entra ID, Okta, any OIDC provider
- [Keys for a team](https://knowusuboaky.github.io/VectrixDB/how-to/mcp-keys/): roles over MCP, keys for named collections
- [MCP tools reference](https://knowusuboaky.github.io/VectrixDB/how-to/mcp-tools/): every tool, prompt and resource, and what each refuses
- [MCP on your own machine](https://knowusuboaky.github.io/VectrixDB/how-to/mcp-local/): the one-person server and its memory tools
- [Keys and roles](https://knowusuboaky.github.io/VectrixDB/how-to/keys-and-roles/): every role, scoped and expiring keys, whoami
- [Collection policies](https://knowusuboaky.github.io/VectrixDB/how-to/collection-policies/): who may search a collection at all
- [Masking](https://knowusuboaky.github.io/VectrixDB/how-to/masking/): names, addresses and ids replaced before indexing
- [Audit trail](https://knowusuboaky.github.io/VectrixDB/how-to/audit-trail/): every policy decision recorded, and how to find one

## Storage and operations

- [Choose a storage backend](https://knowusuboaky.github.io/VectrixDB/how-to/storage-backends/): SQLite, Azure AI Search, Cosmos DB, Postgres and more
- [Run without a network](https://knowusuboaky.github.io/VectrixDB/how-to/offline/): models, air-gapped installs
- [Back up, move and restore](https://knowusuboaky.github.io/VectrixDB/how-to/export-import/): export and import
- [Settings](https://knowusuboaky.github.io/VectrixDB/reference/settings/): every environment variable
- [Command line](https://knowusuboaky.github.io/VectrixDB/reference/cli/): every command and option
- [REST API reference](https://knowusuboaky.github.io/VectrixDB/reference/rest-api/): every route
- [Python client reference](https://knowusuboaky.github.io/VectrixDB/reference/client/): connect(), VectrixClient, AsyncVectrixClient
- [Filters](https://knowusuboaky.github.io/VectrixDB/reference/filters/): the filter grammar
- [Check and doctor](https://knowusuboaky.github.io/VectrixDB/how-to/troubleshoot/): settings read without starting, then every part tried
- [Size the server for load](https://knowusuboaky.github.io/VectrixDB/how-to/sizing/): model calls in line, /ready, threads, memory a process
- [Scale out](https://knowusuboaky.github.io/VectrixDB/how-to/scale/): more than one server, what they share, workers and dead letters

## Reference from the code

- [Async](https://knowusuboaky.github.io/VectrixDB/reference/aio/): the library for asyncio
- [Sources](https://knowusuboaky.github.io/VectrixDB/reference/sources/): feeds and pages
- [Ingest](https://knowusuboaky.github.io/VectrixDB/reference/ingest/): readers and chunking
- [Extract](https://knowusuboaky.github.io/VectrixDB/reference/extract/): extractors, OCR, speech, video
- [Chunk models](https://knowusuboaky.github.io/VectrixDB/reference/chunk-models/): a chat model that cuts or notes chunks
- [Extraction quality](https://knowusuboaky.github.io/VectrixDB/reference/quality/): the score and its calibration
- [Evaluation](https://knowusuboaky.github.io/VectrixDB/reference/evaluation/): golden questions and scoring
- [Policy](https://knowusuboaky.github.io/VectrixDB/reference/policy/): per-document rules
- [Masking](https://knowusuboaky.github.io/VectrixDB/reference/masking/): engines and mask
- [Conversation memory](https://knowusuboaky.github.io/VectrixDB/reference/memory/): turns, facts, recall
- [Tracing](https://knowusuboaky.github.io/VectrixDB/reference/tracing/): spans and what they carry

## Optional

- [Tips and tricks](https://knowusuboaky.github.io/VectrixDB/how-to/tips/)
- [LangChain, LlamaIndex, plugins, CLI](https://knowusuboaky.github.io/VectrixDB/how-to/integrations/)
- [What VectrixDB does not do](https://knowusuboaky.github.io/VectrixDB/explanation/limits/)
- [Threads and processes](https://knowusuboaky.github.io/VectrixDB/explanation/concurrency/)
- [HNSW and its limits](https://knowusuboaky.github.io/VectrixDB/explanation/hnsw/)
- [Memory per vector](https://knowusuboaky.github.io/VectrixDB/explanation/memory/)
- [Writing past RAM](https://knowusuboaky.github.io/VectrixDB/explanation/larger-than-ram/)
- [Benchmarks](https://knowusuboaky.github.io/VectrixDB/explanation/benchmarks/)
- [Why VectrixDB](https://knowusuboaky.github.io/VectrixDB/explanation/why-vectrixdb/)
- [Exceptions](https://knowusuboaky.github.io/VectrixDB/reference/exceptions/)
- [Errors](https://knowusuboaky.github.io/VectrixDB/reference/errors/)
- [Changelog](https://github.com/knowusuboaky/VectrixDB/blob/main/CHANGELOG.md)
