Installation

Brainy is one install: the database, its native engine, and the reference engine underneath it arrive together.

npm install @soulcraft/brainy    # or: bun add @soulcraft/brainyBASH

@soulcraft/brainy is published on the Soulcraft registry. Point npm's scope at it once per machine (or per project in .npmrc):

npm config set @soulcraft:registry https://source.soulcraft.com/api/packages/soulcraftlabs/npm/BASH

(Internal Soulcraft fleet hosts point the same scope at a private registry path instead, authenticated with a forge token — customers always use the public path above.)

Requirements

• Node.js ≥ 22, or Bun ≥ 1.1 · TypeScript-native, ESM

• A local filesystem for the store (mmap requires real files)

• 32 GB RAM serves ~1B entities; far less serves far more brains — see Scaling

The license key

A valid key turns on native acceleration. One key, two places it can live — the engine checks them in this order:

# 1. The environment (CI, containers, secret managers):
export BRAINY_LICENSE=sc_brainy_...

# 2. Or the machine file (workstations; one key per machine):
mkdir -p ~/.config/soulcraft
echo "$KEY" > ~/.config/soulcraft/brainy-license && chmod 600 ~/.config/soulcraft/brainy-licenseBASH

Keys come from soulcraft.com/account and verify offline — nothing phones home, ever. Without a key an install does not keep serving: the engine refuses to open, loudly, with REFUSED — no Brainy license found, naming the two places it looked and the way out. Your data is never locked — Open Brainy, the MIT reference engine, reads and writes the same store format with no key at all.

Verify

import { Brainy } from '@soulcraft/brainy'

const brain = new Brainy({ storage: { type: 'filesystem', path: './data' } })
await brain.init() // look for: engine: native — core 12/12TYPESCRIPT

If activation prints anything other than core 12/12, the message names exactly what to fix — a missing key, an unbuilt binary, or a deliberate engine: 'reference' opt-in.

Your data lives in files you own, in an open format with an MIT reader. Installing Brainy never changes who holds your data: you do.