sqlite-muninn

library0.4.0jsnpmunverified

sqlite-muninn is an advanced SQLite extension for agentic memory and knowledge graph primitives including HNSW vector search, graph traversal (BFS, DFS, shortest path), community detection (Leiden), Node2Vec embeddings, and native GGUF LLM model loading via llama.cpp. Current version is 0.4.0 with active monthly releases. It is zero-dependency, SIMD-accelerated (ARM NEON, x86 SSE), and ships TypeScript types. Key differentiators: combines vector search, graph analytics, and LLM inference in a single SQLite extension without external services.

database ai-ml

npm install sqlite-muninn

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQLITE-MUNINN

sqlite-muninn

databasejavascriptv0.4.0

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.

default

✓ import sqliteMuninn from 'sqlite-muninn'

✗ const sqliteMuninn = require('sqlite-muninn')

ESM-only package; commonJS require not supported.

createHNSW

✓ import { createHNSW } from 'sqlite-muninn'

✗ import { HNSW } from 'sqlite-muninn'

Function to create an HNSW index, not a class.

graphTraverse

✓ import { graphTraverse } from 'sqlite-muninn'

Exported for custom graph traversal; also accessible via SQL functions.

Shows loading the extension, creating HNSW vector index, inserting vectors, performing nearest neighbor search, graph BFS traversal, and Node2Vec embedding generation in SQLite.

import sqliteMuninn from 'sqlite-muninn'; import Database from 'better-sqlite3'; const db = new Database(':memory:'); db.loadExtension(sqliteMuninn.path); // Create a table with vectors db.exec(`CREATE VIRTUAL TABLE vecs USING hnsw(dimensions=3, metric='cosine');`); // Insert vectors db.exec(`INSERT INTO vecs(id, vector) VALUES (1, '[1.0, 2.0, 3.0]');`); db.exec(`INSERT INTO vecs(id, vector) VALUES (2, '[4.0, 5.0, 6.0]');`); // Query nearest neighbors const rows = db.prepare(`SELECT id, distance FROM vecs WHERE knn_by_vector('[1.1, 2.1, 3.1]', 5);`).all(); console.log(rows); // Graph traversal (BFS) on edges table db.exec(`CREATE TABLE edges (src INT, dst INT);`); db.exec(`INSERT INTO edges VALUES (1,2), (2,3), (3,4);`); const path = db.prepare(`SELECT * FROM graph_traverse('edges', 'src', 'dst', 1) WHERE depth <= 2;`).all(); console.log(path); // Node2Vec embeddings db.exec(`SELECT create_node2vec('edges', 'src', 'dst', 'embeddings');`); const similar = db.prepare(`SELECT * FROM vecs WHERE knn_by_embedding('node2vec_embeddings', 1, 5);`).all(); console.log(similar);

Debug

Known issues

breakingLoad extension path changes between versions: prior to 0.3.0, the path was available as sqliteMuninn.extensionPath; in 0.4.0 it is sqliteMuninn.path.

fix

Use sqliteMuninn.path instead of sqliteMuninn.extensionPath when loading the extension.

affects: <0.4.0

deprecatedThe 'knn_by_vector' function signature changed in 0.4.0; the parameter for number of neighbors moved from second to third argument.

fix

Use knn_by_vector(vector, k) instead of knn_by_vector(k, vector).

affects: >=0.4.0

gotchaThe 'graph_traverse' function expects table name as first argument, not a query; using a subquery will fail silently.

fix

Pass the table name only; for custom queries, use the programmatic API graphTraverse() instead.

affects: >=0.0.0

gotchaSIMD acceleration requires CPU support; on older hardware, distance computations fall back to scalar, which may be slower.

fix

No fix needed, but be aware of performance variability on non-SIMD CPUs.

affects: >=0.4.0

breakingNode2Vec output table name changed from 'node2vec_embeddings' to 'embeddings' in 0.4.0; existing references break.

fix

Update queries to reference 'embeddings' table or rename table after creation.

affects: <0.4.0

Errors

Common errors & fixes

Error: Cannot find module 'sqlite-muninn'

Package not installed or ESM import used in CommonJS project.

fix

Install the package: npm install sqlite-muninn. If using CommonJS, use dynamic import: import('sqlite-muninn').then(mod => ...) or switch to ESM.

TypeError: Cannot read properties of undefined (reading 'path')

Using sqliteMuninn.path before asynchronous load completes (if using top-level await not supported).

fix

Ensure the import resolves before accessing path: use top-level await or load in async function.

Error: SQLITE_ERROR: no such module: hnsw

Extension not loaded properly.

fix

Call db.loadExtension(sqliteMuninn.path) with the correct path before using hnsw virtual table.

Upgrade

Version history

0.4.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node