Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt

Use this file to discover all available pages before exploring further.

Find answers to common questions about VectoriaDB.

​
General

VectoriaDB is a lightweight in-memory vector database for semantic search. It uses transformers.js to generate embeddings locally, so your data never leaves the server. It’s designed for tool discovery, document search, and recommendation systems.
Use VectoriaDB when you need:
  • Semantic search over tools, documents, or prompts
  • Offline operation without external API dependencies
  • Privacy-first applications where data can’t leave the server
  • Type-safe metadata with TypeScript generics
For simple keyword matching without semantic understanding, consider the TF-IDF variant instead.
FeatureVectoriaDBTFIDFVectoria
UnderstandingSemantic (understands meaning)Keyword-based (exact matches)
Dependenciestransformers.js (~22MB model)Zero dependencies
InitializationAsync (model download)Synchronous
Reindex requiredNoYes, after changes
Use VectoriaDB for semantic understanding, TFIDFVectoria for simple keyword matching.
Yes. VectoriaDB includes production-ready features:
  • Operational guardrails: Rate limits, batch validation, document size limits
  • Persistence: File and Redis storage adapters
  • Error handling: Typed error classes with machine-readable codes
  • HNSW indexing: Sub-millisecond queries at scale

​
Performance

VectoriaDB can handle 100,000+ documents efficiently:
  • Brute-force search: Good for < 10,000 documents
  • HNSW indexing: Required for > 10,000 documents, supports 100,000+
Memory usage is approximately 1.5KB per document (384-dimensional embeddings + metadata).
The first query after initialization may be slower because:
  1. Model warmup: The first embedding generation warms up the model
  2. JIT compilation: JavaScript engines optimize hot code paths
Subsequent queries are significantly faster. Consider running a warmup query during startup.
Memory usage depends on:
  • Embeddings: ~1.5KB per document (384 dimensions x 4 bytes)
  • Metadata: Variable based on your metadata size
  • HNSW index: ~50-100 bytes per document for graph connections
For 100,000 documents, expect ~150-200MB memory usage.

​
Configuration

Yes. VectoriaDB supports any transformers.js-compatible model:
src/custom-model.ts
const db = new VectoriaDB({
  modelName: 'Xenova/paraphrase-MiniLM-L6-v2',
  dimensions: 384, // Match model dimensions
});
The default Xenova/all-MiniLM-L6-v2 provides good quality with fast inference.
Enable HNSW for datasets > 10,000 documents:
src/enable-hnsw.ts
const db = new VectoriaDB({
  useHNSW: true,
  hnsw: {
    M: 16,           // Connections per node
    efConstruction: 200, // Build quality
    efSearch: 50,    // Search quality
  },
});
See HNSW guide for tuning details.
Use a storage adapter to persist embeddings between restarts:
src/persistence.ts
const db = new VectoriaDB({
  storageAdapter: new FileStorageAdapter({
    cacheDir: './.cache/vectoriadb',
    namespace: 'my-index',
  }),
});

await db.initialize();
await db.addMany(documents);
await db.saveToStorage();
See Storage guide for details.
The default threshold is 0.3. Adjust based on your use case:
  • 0.3-0.4: Loose matching, more results
  • 0.5-0.6: Moderate matching, balanced
  • 0.7+: Strict matching, high precision
Start low and increase if you’re getting too many irrelevant results.

​
Troubleshooting

You must call initialize() before any operation:
src/fix-not-initialized.ts
const db = new VectoriaDB();
await db.initialize(); // Required!

await db.add('id', 'text', metadata);
initialize() is idempotent - calling it multiple times is safe.
Common causes:
  1. Threshold too high: Lower the threshold option
  2. No matching documents: Check that documents are indexed
  3. Filter too restrictive: Review your filter function
src/debug-search.ts
// Debug: search without filters
const results = await db.search(query, {
  threshold: 0.1, // Low threshold
  topK: 20,       // More results
  // No filter
});
console.log('Found:', results.length);
If model download fails:
  1. Check network: Ensure internet access to Hugging Face
  2. Check permissions: Ensure write access to cacheDir
  3. Use a proxy: Set HTTPS_PROXY environment variable
  4. Pre-download: Download the model manually
The model is cached after first download.
To improve search quality:
  1. Check document text: Ensure text is descriptive
  2. Adjust threshold: Try different values
  3. Inspect scores: Look at result.score values
  4. Review embeddings: Use includeVector: true to inspect
src/debug-quality.ts
const results = await db.search(query, {
  topK: 10,
  threshold: 0.0, // Show all
  includeVector: true,
});

for (const r of results) {
  console.log(`${r.id}: ${r.score.toFixed(3)}`);
}

Common Errors

Error reference and solutions

Error Handling

Programmatic error handling