@soulcraft/brainy (11.2.2)
Installation
@soulcraft:registry=npm install @soulcraft/brainy@11.2.2"@soulcraft/brainy": "11.2.2"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 breaks your app
Start free on Open Brainy. When you outgrow it, npm install @soulcraft/brainy — nothing else changes. And in the other direction: no key, or an expired one, means Brainy steps aside loudly and you're running the open reference engines on the same files. 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 Open Brainy reference engine installs automatically as a dependency
- 32 GB RAM serves ~1B entities; 64 GB recommended — see docs/scaling.md
Learn more
| Topic | Doc |
|---|---|
| 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 |
| 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). You upgrade for speed, not capability — and you can downgrade 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 |
| 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 |