hnswsqlite

library0.2.1jsnpmunverified

A TypeScript library that combines HNSWlib approximate nearest neighbor vector search with SQLite persistence for lightweight semantic search. Current stable version is 0.2.1, released on [approx date]. It supports multiple embedding providers (OpenAI, HuggingFace, WebLLM, MediaPipe, TensorFlow.js) and provides a CLI tool. Key differentiators: no external dependencies beyond SQLite and HNSWlib, TypeScript-first with full type declarations, batch operations, and a plugin system for embedding generation. Suitable for building semantic search and recommendation systems.

database search

npm install hnswsqlite

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · HNSWSQLITE

hnswsqlite

databasejavascriptv0.2.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

VectorStore

✓ import { VectorStore } from 'hnswsqlite'

✗ const VectorStore = require('hnswsqlite').VectorStore

ESM module; named export. Use import syntax, not require.

OpenAIEmbedder

✓ import { OpenAIEmbedder } from 'hnswsqlite/plugins/openai'

✗ import { OpenAIEmbedder } from 'hnswsqlite'

Plugins are in subpaths; not part of main export.

VectorStore

✓ import VectorStore from 'hnswsqlite'

Default export also available: import VectorStore from 'hnswsqlite' (same as named).

type EmbeddingPlugin

✓ import type { EmbeddingPlugin } from 'hnswsqlite'

✗ import { EmbeddingPlugin } from 'hnswsqlite' (TypeScript error if used as value)

Use type import for type-only inference.

Shows basic initialization, adding a document with a dummy 5-dimensional embedding, searching with the same vector, and closing the store.

import { VectorStore } from 'hnswsqlite'; const store = new VectorStore('vectors.db', 1536); try { // Add a document with its embedding const docId = store.addDocument('hello world', [0.1, 0.2, 0.3, 0.4, 0.5]); console.log('Document added with id:', docId); // Search for similar documents const results = store.search([0.1, 0.2, 0.3, 0.4, 0.5], 5); console.log('Search results:', results); } finally { store.close(); }

Debug

Known issues

breakingVersion 0.2.x changed the constructor signature of VectorStore; old code passing options object instead of (dbPath, dim) will break.

fix

Update to new constructor: new VectorStore(dbPath, dim)

affects: >=0.2.0

deprecatedPlugin system subpaths may change; currently plugins are under 'hnswsqlite/plugins/<provider>' but final API not stable.

fix

Watch for breaking changes in plugin import paths.

affects: >=0.1.0

gotchastore.close() must be called to avoid memory leaks and SQLite locks; forgetting close() can cause file corruption.

fix

Always use try/finally or async disposers (if added).

affects: all

gotchaEmbedding dimension must match between added documents and search queries; mismatches cause runtime errors or wrong results.

fix

Ensure all embeddings have the same length as the dimension passed to constructor.

affects: all

gotchaThe library uses better-sqlite3, which requires native compilation; failure may occur on unsupported platforms.

fix

Install build tools (e.g., 'npm install -g node-gyp') or use prebuild binaries.

affects: all

Errors

Common errors & fixes

Error: Cannot find module 'hnswlib-node'

Missing peer dependency hnswlib-node

fix

Run: npm install hnswlib-node

Error: SQLITE_CANTOPEN: unable to open database file

Incorrect database path or permission issues

fix

Ensure the directory exists and is writable, or use an absolute path.

TypeError: store.search is not a function

Importing VectorStore incorrectly or using old version

fix

Use import { VectorStore } from 'hnswsqlite' and ensure version >=0.1.0.

Upgrade

Version history

0.2.1latest on npm

Audit

Dependencies

hnswlib-noderequiredProvides the HNSW algorithm implementation for approximate nearest neighbor search

better-sqlite3requiredUsed for SQLite database operations (persistence of vectors and metadata)

Agent activity

34 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/praveencs87/hnswsqlite ↗

packagehnswsqlite ↗

homepagehttps://github.com/praveencs87/hnswsqlite#readme ↗