# 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)