@soulcraft/brainy (13.0.3)
Installation
@soulcraft:registry=npm install @soulcraft/brainy@13.0.3"@soulcraft/brainy": "13.0.3"About this package
Brainy
One install. Any scale. Sovereign by construction.
The database for the AI era — vectors, graph, metadata, files, and time
in one native engine, on machines you own, with zero configuration.
Quick start · Filter pushdown · Features · Scale · Benchmarks · Licensing · Docs
Brainy is the whole database in one install: vectors, relationships, metadata, files, and point-in-time history in one engine, native Rust under every hot path. No code changes between scales. No configuration, ever. Activation is loud — engine: native — core 12/12 — a missing license refuses by name with its cures listed, and a broken install makes init() throw rather than quietly run slow. Underneath sits an open on-disk format with an MIT reader: Open Brainy, the reference engine. Run engine: 'reference' (or run unlicensed) and everything keeps working on the same files at open-source speed. That's the contract in both directions — the exit door is code, not a promise.
| The reference engine (Open Brainy) serves it as | Brainy serves it as | You get |
|---|---|---|
| HNSW vector index (in-RAM) | Adaptive DiskANN — mmap-native, self-tuning, streaming segments | billion-scale ANN on one box; recall@10 0.96 at 100M (measured) |
find() composed in JS |
one fused native query: metadata ∩ graph ∩ vector | exact filters inside the vector walk, not after it |
| JSON field index | LSM postings + columnar sort/aggregate, mmap-durable | cold open serves instantly — restart = warm (measured) |
| graph adjacency in JS maps | u64 LSM adjacency + native traversal/analytics | whole-graph reads as single cursor walks |
| JS distance loops | SIMD kernels (f32, SQ8, SQ4-packed) | the hot inner loop in vector search, compiled |
| WASM embedding model | Candle ML runtime, in-process | batch on-box embeddings — no API fees, no data egress |
| time-travel reads in JS | generation-pinned reads across all three substrates | asOf() at native speed |
Quick start
npm install @soulcraft/brainy # or: bun add @soulcraft/brainy
import { Brainy, NounType, VerbType } from '@soulcraft/brainy'
const brain = new Brainy({ storage: { type: 'filesystem', path: './data' } })
await brain.init() // look for "engine: native — core 12/12"
const brainy = await brain.add({
data: 'Brainy swaps compiled Rust in under every Open Brainy hot path',
type: NounType.Concept,
subtype: 'library',
metadata: { layer: 'native', year: 2026 },
})
const openBrainy = await brain.add({
data: 'Open Brainy is the open-source knowledge database',
type: NounType.Concept,
subtype: 'library',
metadata: { layer: 'engine', year: 2026 },
})
await brain.relate({ from: brainy, to: openBrainy, type: VerbType.DependsOn, subtype: 'runtime' })
const hits = await brain.find({
query: 'native acceleration', // vector — what it means
where: { layer: 'native' }, // metadata — pushed INTO the walk
connected: { to: openBrainy }, // graph — what it touches
}) // one call, three indexes, fused
Get a license — or don't: Open Brainy alone is free, MIT, and genuinely enough at small scale. When you want native speed, pick your organization's tier at soulcraft.com/account (flat and yearly, sized by your org — never by your data). Then set the key — one variable, or one file:
export BRAINY_LICENSE=sc_brainy_...
# or, on a workstation, the machine file:
mkdir -p ~/.config/soulcraft
printf '%s\n' "sc_brainy_..." > ~/.config/soulcraft/brainy-license
chmod 600 ~/.config/soulcraft/brainy-license
npx brainy license status # what the engine actually sees
There is nothing to activate, redeem, or log into. A key is one self-contained token that verifies offline in Rust — no network call at startup, no license server to run, air-gapped installs included. It is checked when the engine opens and at no other moment, so a key that expires under a running database never interrupts it. And a missing or expired key never breaks anything: Brainy steps aside and you're on open-source Open Brainy, same files.
Exact filters inside the vector walk
Pure vector databases post-filter — search first, discard non-matches — so selective filters return too few or lower-recall results. Brainy computes the exact matching set first (roaring-bitmap intersection), searches only that provably-correct space, and switches to an exact scan when the set is small (recall 1.0).
await brain.find({
query: 'quarterly revenue anomalies',
where: { region: 'EMEA', year: 2026 }, // resolved to an exact bitmap FIRST
})
// the vector walk only ever visits entities that already match —
// selective filters get MORE accurate, not less
Brainy pushes the exact filter into the vector search; everyone else filters after.
Feature tour
Adaptive DiskANN — it tunes itself to your machine
A 100% pure-Rust implementation of the DiskANN algorithm (Microsoft Research, NeurIPS 2019: Vamana graphs + product quantization + an mmap-native format). Zero knobs, by design:
const brain = new Brainy({ storage: { type: 'filesystem', path: './data' } })
await brain.init()
// that's the entire configuration — on every machine, at every scale
It observes available RAM and picks in-memory / compressed / on-disk operation, widens its search with corpus size, shares the box fairly with sibling instances, and grows its id space to ~51B entities. Same binary, same files — from a laptop to a 128 GB server, it simply uses what it finds.
How Adaptive DiskANN works · ADR-002: why 100% Rust
Streaming inserts that never freeze
Writes absorb instantly and flush to small immutable segments in O(new-data) — seconds at any corpus size, not hours of reindexing. Index maintenance runs off-thread; consolidation is rare, background, and never blocks a read or a write.
// keep writing at any corpus size — reads stay live throughout
for (const doc of firehose) await brain.add(doc)
await brain.find({ query: 'still answering' }) // never waits on a rebuild
A brain that grows fast never hits a rebuild wall.
Time travel
Point-in-time queries across vectors, graph, and metadata together — plus speculative transactions. No other vector database ships this.
const lastWeek = await brain.asOf(Date.now() - 7 * 86_400_000)
await lastWeek.find({ query: 'what did we know then?' }) // full query surface, past state
Cold start = warm
Every index is mmap-durable — the files are the state. A restart serves identical results from the first query, with no rebuild and no warm-up phase (measured: cold-reopen recall matches warm exactly).
Local embeddings, embedded engine
An on-box ML runtime (Candle) — no per-document API fees, no data egress, fully offline-capable. And the whole thing is a library, not a database server: nothing to deploy, monitor, or operate.
Automatic upgrades
Opening an older-format brain triggers a coordinated, observable migration: progress reporting, an automatic pre-upgrade backup, and a guarantee it never serves half-built state or loses a write.
Upgrading from 2.x / brainy 7.x
One box, hundreds of brains — or one brain at billion scale
The same zero-config design serves both extremes. Per-user isolation: run one brain per user or customer — each a physically separate database (own files, own indexes; no shared store, no cross-tenant query surface to secure). Every brain sizes itself from observed RAM ÷ active brains, a resource manager rebalances budgets at runtime, and mmap paging means idle tenants cost almost nothing — hundreds of isolated brains fit one commodity box. Or scale one up: the identical engine takes a single brain to billions of entities on that same box. No sharding tier, no "multi-tenant edition" — one design, both shapes.
Scaling: sizing, tenants, limits
Measured, not promised
SIFT benchmarks on commodity-class hardware; reproducible via scripts/verify-*.mjs; methodology + honesty notes in docs/comparison.md.
| Scale | Recall@10 | Median latency |
|---|---|---|
| 1M | 0.9942 | 0.31 ms |
| 10M | 0.9647 | 1.33 ms |
| 100M | 0.9559 | ~7 ms — one box, at the published DiskANN billion-scale operating point |
| 1B | in validation | measured run in progress; labeled projected until it lands |
Cold-reopen recall matches warm exactly (measured). The write path holds flat RSS from 100k → 1M entities (measured). Billion-scale claims stay labeled until the 1B run completes — that's the house rule.
Sovereign by construction
This is one of the promises, and here it is structural. Everything runs on your hardware, in your process: search, storage, and embedding generation (the on-box ML runtime means documents never leave the machine, even to be vectorized). There is no telemetry — none. Not opt-out, not opt-in: license keys verify offline, nothing in the engine ever calls out, and a test in the suite fails if that ever changes. Air-gapped deployments aren't a mode; they're just deployments. And point-in-time queries give you an audit dimension most databases can't: what did the system know, and when?
Licensing that never locks your data
Start free on Open Brainy. When you outgrow it, npm install @soulcraft/brainy — nothing else changes. In the other direction: no key, an invalid key, or one whose coverage has closed for a given build means @soulcraft/brainy refuses to open, loudly, naming the cure — it does not step down and run unaccelerated. Your data is never locked, because it never needed this package in the first place: Open Brainy reads and writes the identical store format with no key at all, so moving back is npm install @soulcraftlabs/brainy against the same directory, not an export/import migration. There is no kill switch, and we will never build one. Pricing is flat and yearly, sized by your organization — never by your data, never metered, never monthly. And when a license lapses, every version released while it was valid keeps running at full native speed, forever: you renew for the future, not to keep what you already have. Keys and terms: soulcraft.com/account; the full text ships in this package's LICENSE.
Requirements
- Node.js ≥ 22 (Bun ≥ 1.1 as a runtime) · TypeScript-native, ESM
- Local filesystem storage (mmap requires real files); the engine is self-contained — nothing else installs
- 32 GB RAM serves ~1B entities; 64 GB recommended — see docs/scaling.md
Learn more
| Topic | Doc |
|---|---|
| What brainy is | docs/overview.md |
| How Adaptive DiskANN works | docs/diskann.md · ADR-002: why 100% Rust |
| Benchmarks + methodology | docs/performance.md · docs/comparison.md · docs/verification-report.md |
| Scaling: sizing, tenants, limits | docs/scaling.md · docs/billion-scale.md · docs/deployment-limits.md |
| Durability + snapshots | docs/snapshot-safety.md |
| Time travel | ADR-003: semantic time travel |
| Memory, guardrails, coordination | docs/memory.md · docs/guardrails.md · docs/accords.md |
| Reaching the engine from outside your process | docs/serve.md · docs/mcp.md |
| Upgrading from 2.x / brainy 7.x | docs/migration-3.0.md |
The open-core promise
Every accelerated path has a working JavaScript default in Open Brainy (MIT) — a separate, always-available install, not a mode this package steps down into. You upgrade for speed, not capability — and you can move to Open Brainy at any time with zero migration, because Brainy works on Open Brainy's files, not its own. Your data is never hostage to a subscription.
Support
- Product & licensing — brainy@soulcraft.com for questions about brainy, licensing, or your subscription.
- Security — security@soulcraft.com for vulnerabilities. Report privately first; we practice coordinated disclosure and will work with you on timing and credit.
Documentation · Platform · The promise · Open Brainy (MIT) · Support
Dependencies
Dependencies
| ID | Version |
|---|---|
| @msgpack/msgpack | ^3.1.2 |
| boxen | ^8.0.1 |
| chalk | ^5.3.0 |
| chardet | ^2.0.0 |
| cli-table3 | ^0.6.5 |
| csv-parse | ^6.1.0 |
| js-yaml | ^4.1.0 |
| mammoth | ^1.11.0 |
| mime | ^4.1.0 |
| ora | ^8.2.0 |
| pdfjs-dist | ^4.0.379 |
| prompts | ^2.4.2 |
| roaring-wasm | ^1.1.0 |
| undici | ^7.29.1 |
| xlsx | ^0.18.5 |
Development dependencies
| ID | Version |
|---|---|
| @napi-rs/cli | ^3.0.0 |
| @types/js-yaml | ^4.0.9 |
| @types/node | ^22.0.0 |
| pg | ^8.21.0 |
| tsx | ^4.21.0 |
| typescript | ^5.9.3 |
| vitest | ^3.2.4 |
Optional dependencies
| ID | Version |
|---|---|
| @soulcraft/brainy-model-ms-marco-minilm-l12-v2 | 13.0.3 |
| @soulcraft/brainy-serve-linux-x64-gnu | 13.0.3 |