David Snelling 35b9d7ef43 refactor(8.0)!: remove orphaned zero-config subsystem + dead cloud/progressive-init storage vestige

The old config-generation subsystem (src/config/ + autoConfiguration.ts) was
superseded during the 8.0 rework and never wired into init(): it emitted settings
for a partitioning subsystem that no longer exists and probed deleted cloud env
vars. The live zero-config path is inline — recall preset → HNSW knobs, storage
auto-detect, auto persistMode, container-memory-aware cache sizing.

The storage progressive-init / cloud-detection cluster was equally dead after the
cloud adapters were dropped: isCloudStorage() is permanently false (no overriders),
scheduleBackgroundInit/runBackgroundInit were never called (the latter an empty
body), initMode was never assigned, and Brainy.isFullyInitialized()/
awaitBackgroundInit() were always-trivial with zero callers. scheduleCountPersist()
collapses to its only-ever-taken immediate write-through path.

Removed:
- src/config/{index,zeroConfig,storageAutoConfig,modelAutoConfig,sharedConfigManager}.ts
- src/utils/autoConfiguration.ts + the inert BrainyZeroConfig export
- Brainy.isFullyInitialized()/awaitBackgroundInit() (+ BrainyInterface decls)
- InitMode type, isCloudStorage/detectCloudEnvironment/resolveInitMode,
  scheduleBackgroundInit/runBackgroundInit/ensureValidatedForWrite and their state
- Dead cloud env-var probes (K_SERVICE/K_REVISION/AWS_LAMBDA_FUNCTION_NAME/
  FUNCTIONS_TARGET/AZURE_FUNCTIONS_ENVIRONMENT)

Kept (verified live): production-detection logging (environment.ts), container-
memory cache sizing (memoryDetection/paramValidation), on-disk hash bucketing
(sharding.ts).

Docs: scrubbed deleted-subsystem references (JS quantization knobs, cloud/OPFS
adapters, partitioning, old zero-config API) across 14 files; deleted two wholly-
obsolete feature docs (complete-feature-list, v3-features); rewrote
architecture/zero-config for 8.0.

~3,700 LOC removed. Build clean; 1392 unit + 24 db-mvcc green.

2026-06-15 11:11:21 -07:00

3.3 KiB

Raw Blame History

title

slug

public

Quick Start

Get Brainy running in under a minute.

1. Install

npm install @soulcraft/brainy

2. Initialize

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

const brain = new Brainy()
await brain.init()

That's it. Brainy auto-configures storage, loads the embedding model, and builds the indexes.

3. Add Knowledge

// Text is automatically embedded into 384-dim vectors
const reactId: string = await brain.add({
  data: 'React is a JavaScript library for building user interfaces',
  type: NounType.Concept,
  subtype: 'library',                                  // Sub-classification within Concept
  metadata: { category: 'frontend', year: 2013 }
})

const nextId: string = await brain.add({
  data: 'Next.js framework for React with server-side rendering',
  type: NounType.Concept,
  subtype: 'framework',
  metadata: { category: 'framework', year: 2016 }
})

type is one of Brainy's 42 stable NounTypes. subtype is your free-form sub-classification within that type — flat string, no hierarchy, indexed on the fast path. See Subtypes & Facets for the full guide.

4. Create Relationships

// Typed graph relationships
await brain.relate({
  from: nextId,
  to: reactId,
  type: VerbType.BuiltOn
})

5. Query with Triple Intelligence

import type { FindResult } from '@soulcraft/brainy'

// All three search paradigms in one call
const results: FindResult[] = await brain.find({
  query: 'modern frontend frameworks',    // Vector similarity search
  where: { year: { greaterThan: 2015 } }, // Metadata filtering
  connected: { to: reactId, depth: 2 }   // Graph traversal
})

console.log(results[0].data)   // 'Next.js framework for React...'
console.log(results[0].score)  // 0.94

What Just Happened

Every entity you add() lives in three indexes simultaneously:

Index	What it stores	Query with
Vector	384-dim embedding of `data`	`find({ query: '...' })`
Metadata	All `metadata` fields	`find({ where: { ... } })`
Graph	Typed relationships from `relate()`	`find({ connected: { ... } })`

find() queries all three in parallel and fuses the results.

Natural Language Queries

Brainy understands 220+ natural language patterns:

// These all work without any configuration
await brain.find({ query: 'recent documents about machine learning' })
await brain.find({ query: 'articles created this week' })
await brain.find({ query: 'people who work at Anthropic' })

Next Steps

Triple Intelligence — understand how the query engine works
The Find System — advanced queries, operators, and graph traversal
API Reference — complete method documentation
Storage Adapters — filesystem, memory

3.3 KiB Raw Blame History