Vector database for AI applications - pure TypeScript vector search with no native dependencies
npm install vectorvaultThe first standalone vector database for TypeScript/Node.js with native FAISS-powered similarity search.


``typescript
import { Vault } from 'vectorvault';
const vault = new Vault({
vault: 'my_knowledge',
openaiKey: process.env.OPENAI_API_KEY,
local: true
});
vault.add('The mitochondria is the powerhouse of the cell');
vault.add('Neural networks are inspired by biological brains');
await vault.getVectors();
await vault.save();
const results = await vault.getSimilar('How do cells produce energy?');
console.log(results[0].data);
// → "The mitochondria is the powerhouse of the cell"
`
| Feature | VectorVault | faiss-node | Vectra | LangChain |
|---------|-------------|------------|--------|-----------|
| Native FAISS | ✅ | ✅ | ❌ JSON scan | ✅ |
| Standalone | ✅ | ✅ | ✅ | ❌ Framework |
| Persistence | ✅ | ❌ | ✅ | ✅ |
| Metadata | ✅ | ❌ | ✅ | ✅ |
| Chunking | ✅ | ❌ | ❌ | ✅ |
| Complete API | ✅ | ❌ Bindings only | ✅ | ✅ |
VectorVault is the only library that combines native FAISS performance with a complete database API — no framework dependencies, no compromises.
- 🚀 Native FAISS — Real vector similarity search using Meta's FAISS library via native bindings
- 🎯 Zero framework dependencies — Works standalone, not a wrapper around LangChain
- 🐍 Python parity — Identical API and results to VectorVault Python (verified with test suite)
- 💾 True persistence — Save and load indexes, metadata, vectors, and prompts
- ✂️ Built-in chunking — splitText() handles documents with configurable overlap
- 📦 Metadata support — Attach any JSON metadata to your vectors
- ☁️ Cloud + Local — Use locally or connect to VectorVault Cloud
`bash`
npm install vectorvault
For local vector search, you need faiss-node:
`bash`
npm install faiss-node
> Note: faiss-node requires native bindings. If installation fails on your platform, you can still use Cloud Mode which doesn't require faiss-node.
Cloud mode connects to VectorVault Cloud and works without faiss-node:
`typescript`
const vault = new Vault({
vault: 'my_vault',
user: 'your@email.com',
apiKey: 'vv_your_api_key',
local: false // Cloud mode - no faiss-node needed
});
`typescript
import { Vault } from 'vectorvault';
// Create a local vault
const vault = new Vault({
vault: 'my_vault',
openaiKey: process.env.OPENAI_API_KEY,
local: true,
localDir: './data' // Optional: defaults to ./vaults
});
// Add items with optional metadata
vault.add('First document content', { source: 'doc1', category: 'science' });
vault.add('Second document content', { source: 'doc2', category: 'history' });
// Generate embeddings and save
await vault.getVectors();
await vault.save();
// Search
const results = await vault.getSimilar('your search query', 5);
for (const result of results) {
console.log(result.data); // The text
console.log(result.metadata); // Your metadata
console.log(result.distance); // Similarity distance
}
`
`typescript
import * as fs from 'fs';
// Load a document
const text = fs.readFileSync('book.txt', 'utf-8');
// Split into chunks (overlap, maxLength)
const chunks = vault.splitText(text, 100, 500);
console.log(Split into ${chunks.length} chunks);
// Add all chunks
for (const chunk of chunks) {
vault.add(chunk, { source: 'book.txt' });
}
await vault.getVectors();
await vault.save();
`
`typescript
import { Vault } from 'vectorvault';
const vault = new Vault({
vault: 'my_cloud_vault',
user: 'your@email.com',
apiKey: 'vv_your_api_key',
local: false
});
// Same API as local mode
vault.add('Document content');
await vault.getVectors();
await vault.save();
const results = await vault.getSimilar('query');
`
`typescript`
interface VaultConfig {
vault: string; // Vault name
openaiKey?: string; // OpenAI API key (for embeddings)
local?: boolean; // Use local storage (default: false)
localDir?: string; // Local storage directory
user?: string; // VectorVault Cloud username
apiKey?: string; // VectorVault Cloud API key
verbose?: boolean; // Enable logging
}
| Method | Description |
|--------|-------------|
| add(text, metadata?) | Add text to the vault with optional metadata |getVectors()
| | Generate embeddings for pending items |save()
| | Persist the vault to disk/cloud |getSimilar(query, n?)
| | Find n most similar items (default: 4) |getItems(ids)
| | Retrieve items by ID |editItem(id, newText)
| | Update item text |deleteItems(ids)
| | Remove items |getTotalItems()
| | Get item count |getVaults()
| | List all vaults in directory |delete()
| | Delete the entire vault |
| Method | Description |
|--------|-------------|
| splitText(text, overlap?, maxLength?) | Split text into chunks |getItemVector(id)
| | Get raw vector for an item |getDistance(id1, id2)
| | Calculate distance between two items |
| Method | Description |
|--------|-------------|
| savePersonalityMessage(msg) | Save a system personality message |fetchPersonalityMessage()
| | Retrieve the personality message |saveCustomPrompt(prompt, withContext)
| | Save a custom prompt template |fetchCustomPrompt(withContext)
| | Retrieve a custom prompt |
VectorVault uses a hybrid architecture:
1. Embeddings — Generated via OpenAI's text-embedding-3-small (1536 dimensions)IndexFlatIP
2. Vector Index — Native FAISS with L2 normalization (cosine similarity)
3. Storage — JSON metadata files + FAISS binary index for fast loading
4. Search — Query embedding → FAISS search → Return ranked results with metadata
``
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ Add Text │ ──▶ │ Embeddings │ ──▶ │ FAISS Index │
└─────────────┘ │ (OpenAI) │ └─────────────┘
└──────────────┘ │
▼
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ Results │ ◀── │ Re-rank by │ ◀── │ Search │
│ + Metadata │ │ Distance │ │ (FAISS) │
└─────────────┘ └──────────────┘ └─────────────┘
Tested with "The Prince" by Machiavelli (302KB, 264 chunks):
| Operation | Time |
|-----------|------|
| Chunking | <10ms |
| Embedding (264 items) | ~3-5s |
| Save to disk | <50ms |
| Load from disk | <100ms |
| Search query | <500ms |
VectorVault TypeScript produces identical results to VectorVault Python:
```
Python: "On the other hand, Cesare Borgia, called by the people Duke Valentino..."
TypeScript: "On the other hand, Cesare Borgia, called by the people Duke Valentino..."
✅ Same chunks, same search results, same API
If you're migrating from Python or building cross-platform applications, your vectors and results will match exactly.
- Node.js 18+
- OpenAI API key (for embeddings)
- macOS, Linux, or Windows (native FAISS binaries)
- VectorVault Python — The original Python implementation
- VectorVault Cloud — Managed vector database service
MIT © John Rood
---
Built by John Rood
Creator of the world's first serverless vector database