@soulcraft/cortex

bun add @soulcraft/cortex    # or: npm install @soulcraft/cortex

soulcraft.com/docs · Pricing · Benchmarks · Comparison

Brainy handles your knowledge graph. Cortex makes it fast.

When performance matters — at scale, in production, with large embedding models — Cortex automatically swaps in compiled Rust implementations for distance calculations, HNSW graph search, metadata filtering, and embeddings. No code changes. No configuration changes. Add the package and it activates.

Quick Start

bun add @soulcraft/brainy @soulcraft/cortex

import { Brainy, NounType } from '@soulcraft/brainy'

const brain = new Brainy({
  storage: { type: 'filesystem', rootDirectory: './data' },
  plugins: ['@soulcraft/cortex']
})
await brain.init()
// [brainy] Plugin activated: @soulcraft/cortex
// All native providers registered — same API, Rust speed.

await brain.add({ data: 'Native Rust SIMD acceleration', type: NounType.Concept })
const results = await brain.find({ query: 'fast vector search' })

Activate your license

Free tier activates automatically — no key needed. For Pro/Enterprise:

1. Get your activation code from soulcraft.com/account
2. Run in your project directory:

npx @soulcraft/cortex activate CX-XXXX-XXXX

This creates a .soulcraft.json in your project — commit it to your repository and it works everywhere (dev, staging, prod, Docker, CI).

Other CLI commands:

npx cortex status       # show license info
npx cortex deactivate   # remove license
npx cortex help         # all commands

License validation runs locally in Rust — no network calls at startup. Get a key at soulcraft.com/pricing.

What Gets Accelerated

Every provider listed here is a drop-in replacement — Brainy's plugin system wires them in automatically based on your license tier.

| Subsystem | What Cortex Provides | |-----------|---------------------| | SIMD distance | Float32 cosine; SQ8 uint8 cosine (82× faster); SQ4 nibble-packed | | HNSW graph engine | Rust graph with SIMD distance and Arc-based copy-on-write nodes | | Embeddings | Candle ML runtime — in-process, no Python sidecar, no HTTP roundtrip. CPU and Apple Metal | | Batch embeddings | Single Rust forward pass for bulk import and reindex | | Metadata index | Rust query/mutation engine with CRoaring bitmap indexes | | Graph adjacency | 4 LSM-trees with typed verb tracking | | Entity ID mapper | O(1) UUID ↔ integer Rust HashMap | | Vector quantization | SQ8 (4× memory), SQ4 (8× memory), Product Quantization (16–32×) | | Graph compression | Delta-varint encoded connection lists | | Roaring bitmaps | CRoaring bindings — binary-compatible with roaring-wasm | | Msgpack | Native encode/decode | | mmap storage | Zero-copy SSTable reads via memory-mapped files | | Aggregation engine | Incremental updates with Rayon parallel rebuild | | Compaction | Graph-aware BFS and HNSW traversal ordering for disk locality |

Performance

All numbers measured with vitest bench on Linux x64.

Distance Calculations — 384-dimensional vectors (all-MiniLM-L6-v2)

| Operation | Throughput | Latency | vs full-precision | |-----------|----------:|--------:|:-----------------:| | cosineDistance (float32) | 45,965 ops/s | 21.8 μs | baseline | | cosineDistanceSq8 (quantized) | 3,715,855 ops/s | 0.27 μs | 81× | | cosineDistanceSq8Batch (1K vectors) | 2,142 ops/s | 467 μs | 28× | | cosineDistanceBatch (float32, 1K) | 77 ops/s | 13.0 ms | — | | quantizeSq8 (encode 384-dim) | 74,020 ops/s | 13.5 μs | — |

Quantize once at index time. Get 81× faster distances at every query.

Aggregation Engine

| Operation | Throughput | Latency | |-----------|----------:|--------:| | incrementalUpdate (1K entities, 3 metrics) | 809 ops/s | 1.2 ms | | rebuildAggregate (10K entities, 5 groups) | 475 ops/s | 2.1 ms | | rebuildAggregate (100K entities, Rayon) | 66 ops/s | 15.2 ms | | queryAggregate (1K groups, sort + paginate) | 986 ops/s | 1.0 ms |

Serialization

| Operation | Throughput | Latency | |-----------|----------:|--------:| | msgpackEncode (1K entities) | 235 ops/s | 4.3 ms | | msgpackDecode (1K entities) | 355 ops/s | 2.8 ms | | RoaringBitmap32.serialize (10K elements) | 361,258 ops/s | 2.8 μs | | RoaringBitmap32.deserialize (10K elements) | 548,714 ops/s | 1.8 μs | | encodeConnections (1K lists) | 913 ops/s | 1.1 ms | | decodeConnections (1K lists) | 1,078 ops/s | 928 μs |

Full breakdown: docs/performance.md · Side-by-side comparison: docs/comparison.md

Free Tier vs Pro

| Feature | Free | Pro / Enterprise | |---------|:----:|:----------------:| | mmap-enhanced filesystem storage | ✓ | ✓ | | SIMD distance (float32, SQ8, SQ4) | — | ✓ | | Native HNSW graph engine | — | ✓ | | Vector quantization (SQ8, SQ4, PQ) | — | ✓ | | Candle ML embeddings (CPU / Metal) | — | ✓ | | Native metadata index (CRoaring) | — | ✓ | | Graph adjacency index (4 LSM-trees) | — | ✓ | | Entity ID mapper (O(1) UUID ↔ int) | — | ✓ | | CRoaring bitmap bindings | — | ✓ | | Native msgpack encode/decode | — | ✓ | | Incremental aggregation engine | — | ✓ | | Graph-aware BFS compaction | — | ✓ |

Free tier activates automatically with no key. Pro/Enterprise require a license key — see soulcraft.com/pricing.

Verify Activation

Check which providers are active after brain.init():

const diag = brain.diagnostics()
console.log(diag.providers)
// {
//   distance:      { source: 'plugin' },
//   hnsw:          { source: 'plugin' },
//   embeddings:    { source: 'plugin' },
//   metadataIndex: { source: 'plugin' },
//   ...
// }

Require specific providers in production — fail fast if something isn't native:

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

License & Subscription

Cortex uses a subscription license with offline validation. Your key is an Ed25519-signed JWT verified entirely in Rust at process start — no network call required. A background heartbeat runs once every 24 hours to check subscription status.

Graceful Degradation

Cortex never hard-blocks your process on a lapsed license. If your subscription lapses:

1. A warning appears on the next process start
2. A 14-day grace period begins
3. After the grace period, Cortex silently degrades to free tier — storage keeps working, compute acceleration pauses

[cortex] Subscription canceled. Renew at soulcraft.com/account. Grace period: 12 days remaining.

Renew at any time during the grace period to restore compute acceleration instantly on the next startup.

Key Source

Cortex reads .soulcraft.json from the project root (process.cwd()):

{ "cortex": "CX-7F3A-9B2D" }

On first use, short codes are exchanged for a JWT via soulcraft.com/api/license/exchange and cached in memory for the process lifetime. The file itself is never rewritten — each cold start re-exchanges if needed.

Run npx @soulcraft/cortex activate CX-XXXX-XXXX to create this file.

Platform Support

Pre-built binaries ship inside the npm package. No compile step needed.

| Platform | Architecture | Binary Included | |----------|-------------|:---------------:| | Linux | x64 (glibc 2.17+) | ✓ | | Linux | arm64 (glibc) | ✓ | | macOS | arm64 (Apple Silicon) | ✓ | | macOS | x64 (Intel) | ✓ | | Windows | x64 | ✓ |

GPU / CUDA acceleration is available for Enterprise customers. Contact us to discuss your requirements.

Troubleshooting

| Symptom | Likely cause | Fix | |---------|-------------|-----| | [cortex] missing sc_cortex_ prefix | .soulcraft.json contains wrong key or non-cortex key | Re-run npx @soulcraft/cortex activate CX-XXXX-XXXX | | [cortex] license expired | Key is past its expiry date | Renew at soulcraft.com/account | | [cortex] invalid signature | Key was truncated or corrupted | Re-activate: npx @soulcraft/cortex activate CX-XXXX-XXXX | | [cortex] invalid product: workshop | Workshop key used for Cortex | Keys are product-specific — get a Cortex key at soulcraft.com/account | | [cortex] native module unavailable | Native binary not found for current platform | Check platform table above | | Compute providers inactive, no warning | No key set — free tier is active | Run npx @soulcraft/cortex activate CX-XXXX-XXXX | | [cortex] License lapsed. Compute acceleration disabled. | Grace period expired | Renew at soulcraft.com/account | | [cortex] License suspended. Contact support. | Account suspended | Open a ticket at soulcraft.com/issues |

Direct Native Access

For advanced use cases — custom pipelines, tooling, benchmarks — access the Rust bindings directly without Brainy:

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

if (isNativeAvailable()) {
  const native = loadNativeModule()
  const dist = native.cosineDistance(vectorA, vectorB)
  const encoded = native.msgpackEncode(data)
}

Requirements

• Bun 1.0+ (recommended) or Node.js 22 LTS
• @soulcraft/brainy >= 7.15.4

bun add @soulcraft/brainy @soulcraft/cortex    # Bun — best performance
npm install @soulcraft/brainy @soulcraft/cortex # Node.js — fully supported

Learn More

• Brainy documentation — Full Brainy API reference
• Plugin system — How Brainy plugins work
• Performance benchmarks — Full benchmark table with methodology
• Brainy vs Cortex comparison — Side-by-side feature and speed comparison
• soulcraft.com/pricing — Pro and Enterprise plans

License

Commercial — soulcraft.com/pricing

Free tier (mmap storage) is available without a license key. Pro and Enterprise tiers require a paid subscription.