Cortex

What is Cortex?

Cortex replaces Brainy's JavaScript internals with native Rust implementations. Same API, same data, dramatically faster.

Install it, add it to your plugins config, and Brainy uses Rust for distance calculations, embeddings, metadata queries, graph operations, and more.

npm install @soulcraft/brainy @soulcraft/cortex

import Brainy from '@soulcraft/brainy'

const brain = new Brainy({
  plugins: ['@soulcraft/cortex']
})
await brain.init()
// [brainy] Plugin activated: @soulcraft/cortex

// Verify what's accelerated
const diag = brain.diagnostics()
console.log(diag.providers)
// { distance: { source: 'plugin' }, embeddings: { source: 'plugin' }, ... }

Why Cortex?

Brainy works great on its own with pure JavaScript and WASM. Cortex is for when you need more:

• SIMD distance calculations — every vector comparison gets faster
• Native ML inference — Candle engine replaces WASM embeddings, with CPU, CUDA, and Metal support
• Rust metadata engine — queries and mutations run in Rust with CRoaring bitmaps
• Native graph index — 4 LSM-trees with verb tracking, all in Rust
• Batch embeddings — single Rust forward pass for bulk operations
• Zero-copy storage — mmap-backed SSTables for disk-heavy workloads

Brainy's plugin system means cortex acceleration flows through every operation — add(), find(), update(), delete(), similar(), VFS path resolution, neural APIs, and everything in between.

What Gets Accelerated

| Subsystem | What Cortex Provides | Impact | |-----------|---------------------|--------| | HNSW index | Rust graph engine with SIMD distance, Arc-based COW | Core vector search | | Distance | SIMD cosine, euclidean, manhattan, dot product | Every vector comparison | | Embeddings | Candle ML engine (CPU/CUDA/Metal) | No WASM compilation, GPU support | | Batch embeddings | Single forward pass for multiple texts | Bulk import and reindex | | Cache | Rust eviction engine with JS data storage | Memory management | | Metadata index | Rust query/mutation engine with CRoaring | Faster filtering and type queries | | Graph adjacency | 4 LSM-trees with verb tracking | Faster relationship operations | | Entity ID mapper | Rust O(1) HashMap for UUID-integer mapping | Bitmap index operations | | Vector quantization | SIMD SQ8/SQ4 distance on compressed vectors | 4-8x memory reduction | | Product quantization | Native PQ codebook training and ADC | 16-32x compression | | Graph compression | Delta-varint encoded connections | 2-3x smaller graph storage | | Roaring bitmaps | CRoaring bindings | Faster set operations | | Msgpack | Native encode/decode | Faster serialization | | Storage | MmapFileSystemStorage with zero-copy SSTables | Faster disk I/O | | Compaction | Graph-aware BFS/HNSW traversal ordering | Better disk locality |

Getting Started

1. Install

npm install @soulcraft/brainy @soulcraft/cortex

2. Set up your license

# Environment variable
export SOULCRAFT_LICENSE=sc_cortex_<your-key>

# Or license file
echo "sc_cortex_<your-key>" > ~/.soulcraft/license

License validation is offline — no network calls, no telemetry.

3. Enable cortex in your Brainy config

import Brainy from '@soulcraft/brainy'

const brain = new Brainy({
  storage: { type: 'filesystem', rootDirectory: './data' },
  plugins: ['@soulcraft/cortex']
})
await brain.init()
// [brainy] Plugin activated: @soulcraft/cortex
// [brainy] Providers: 10/10 native (@soulcraft/cortex)

4. Verify in production

Use requireProviders() to fail fast if cortex isn't providing expected acceleration:

brain.requireProviders(['distance', 'embeddings', 'metadataIndex', 'graphIndex'])

Or inspect the full picture with diagnostics:

console.log(brain.diagnostics())

MmapFileSystemStorage

Cortex includes a storage adapter with mmap-backed binary blob support:

const brain = new Brainy({
  storage: { type: 'mmap-filesystem', rootDirectory: './data' }
})

Zero-copy access to LSM-tree SSTables — useful for large graph datasets where disk I/O is the bottleneck.

Platform Support

| Platform | Architecture | Status | |----------|-------------|--------| | Linux | x64 (glibc) | Supported | | Linux | arm64 (glibc) | Supported | | macOS | arm64 (Apple Silicon) | Supported | | macOS | x64 (Intel) | Supported | | Windows | x64 | Supported |

Requirements

• @soulcraft/brainy >= 7.15.4
• Node.js >= 22 or Bun >= 1.3.0

Direct Native Access

For advanced use cases, access the Rust bindings directly:

import { loadNativeModule, isNativeAvailable } from '@soulcraft/cortex'

if (isNativeAvailable()) {
  const native = loadNativeModule()
  const distance = native.cosineDistance(vectorA, vectorB)
}

Learn More

• Product info and licensing
• Brainy documentation
• Brainy on GitHub
• Plugin development guide

License

Commercial. See LICENSE for details.