Vecna

Lightweight file-based semantic search for Node.js. Single JSON file, zero external dependencies, local embeddings.

Install

npm install vecna

Quick Start

Library

import { Vecna } from 'vecna'

const db = await Vecna.open('knowledge.json')

await db.add({ id: 'doc1', text: 'Machine learning is a subset of AI' })
await db.add({ id: 'doc2', text: 'Dogs are loyal companions' })

const results = await db.search('artificial intelligence', { mode: 'hybrid', k: 5 })
// [{ id: 'doc1', score: 1.0, document: { ... } }]

await db.close()

CLI

vecna init mydb.json
vecna add mydb.json --text "Hello world" --id greeting
vecna search mydb.json "hello" --mode hybrid --pretty

Features

• Three search modes: semantic (vector similarity), keyword (BM25), hybrid (both combined)
• Local embeddings: Uses Transformers.js with all-MiniLM-L6-v2 (384 dimensions)
• Single file storage: Everything in one JSON file
• ACID-like durability: Atomic writes, file locking
• CLI included: Debug and manipulate databases from the command line

Documentation

| Document | Description | |----------|-------------| | API Reference | Library methods, parameters, return types | | CLI Reference | All commands and options | | Concepts | When to use each search mode, how it works | | Errors | Error codes, causes, and fixes | | Agent Guide | Patterns for AI agents using Vecna |

Search Modes

| Mode | Best For | Speed | |------|----------|-------| | semantic | Conceptual similarity, paraphrases | ~50ms | | keyword | Exact term matching | ~1ms | | hybrid | General purpose (recommended) | ~55ms |

Scale

Designed for micro scale: 100-1,000 documents. For larger datasets, consider a dedicated vector database.

License

MIT