feat: Simplify architecture with Cortex orchestrator and clear augmentation tiers
## Major Architecture Improvements ### Cortex Refactoring - Renamed AugmentationPipeline → Cortex for clarity - Cortex is now the central orchestrator (not an augmentation) - NeuralImport remains as the AI-powered SENSE augmentation - Clean brain metaphor: BrainyData → Cortex → Augmentations ### Four-Tier Augmentation System 1. **Built-in** (Free, MIT): Neural Import, basic storage, search 2. **Community** (Free, npm): Community-created augmentations 3. **Premium** ($49-299/mo): AI Memory, Agent Coordinator, Enterprise connectors 4. **Brain Cloud** ($19-99/mo): Managed service with all features ### Zero Configuration Philosophy - Everything works out of the box - no config needed - Automatic model detection and loading - Seamless integration between tiers - Brain Cloud connects with one command: `brainy cloud` ### Documentation Updates - Added PHILOSOPHY.md outlining design principles - Created AUGMENTATION_ARCHITECTURE.md with tier system - Added CLI_AUGMENTATION_GUIDE.md for augmentation management - Updated README to "sell first" with concrete use cases - Improved documentation organization in /docs ### Developer Experience - Backward compatibility maintained with exports - Clean, simple API surface - Interactive-by-default approach - Premium features integrate seamlessly ### Removed - Deleted demo directory and deploy workflow (moved to website) - Removed test wrapper scripts (bash 2>&1 bug workaround) This refactor makes Brainy incredibly powerful yet easy to use, with everything automated and no configuration required. The Brain Cloud augmentations (AI memory, sync, coordination) integrate seamlessly as our killer features.
This commit is contained in:
parent
c59de5a48b
commit
f7484a9467
12 changed files with 1103 additions and 572 deletions
73
.github/workflows/deploy-demo.yml
vendored
73
.github/workflows/deploy-demo.yml
vendored
|
|
@ -1,73 +0,0 @@
|
||||||
name: Deploy Demo to GitHub Pages
|
|
||||||
|
|
||||||
on:
|
|
||||||
push:
|
|
||||||
branches: [ main ]
|
|
||||||
workflow_dispatch:
|
|
||||||
|
|
||||||
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
|
|
||||||
permissions:
|
|
||||||
contents: read
|
|
||||||
pages: write
|
|
||||||
id-token: write
|
|
||||||
|
|
||||||
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
|
|
||||||
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
|
|
||||||
concurrency:
|
|
||||||
group: "pages"
|
|
||||||
cancel-in-progress: false
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
build:
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
steps:
|
|
||||||
- name: Checkout 🛎️
|
|
||||||
uses: actions/checkout@v4
|
|
||||||
|
|
||||||
- name: Setup Node.js 🔧
|
|
||||||
uses: actions/setup-node@v3
|
|
||||||
with:
|
|
||||||
node-version: '20'
|
|
||||||
cache: 'npm'
|
|
||||||
|
|
||||||
- name: Install dependencies 📦
|
|
||||||
run: npm install --legacy-peer-deps
|
|
||||||
|
|
||||||
- name: Build project 🏗️
|
|
||||||
run: |
|
|
||||||
npm run build
|
|
||||||
|
|
||||||
- name: Build Angular demo 🏗️
|
|
||||||
run: |
|
|
||||||
cd demo/brainy-angular-demo
|
|
||||||
npm install --legacy-peer-deps
|
|
||||||
npm run build
|
|
||||||
|
|
||||||
- name: Prepare deployment 📦
|
|
||||||
run: |
|
|
||||||
mkdir -p _site
|
|
||||||
mkdir -p _site/demo
|
|
||||||
mkdir -p _site/dist
|
|
||||||
cp demo/index.html _site/index.html
|
|
||||||
cp -r demo/brainy-angular-demo/dist/brainy-angular-demo/* _site/demo/
|
|
||||||
cp -r dist/* _site/dist/
|
|
||||||
cp brainy.png _site/
|
|
||||||
# Copy dist directly to demo/dist for easier access
|
|
||||||
mkdir -p _site/demo/dist
|
|
||||||
cp -r dist/* _site/demo/dist/
|
|
||||||
|
|
||||||
- name: Upload artifact
|
|
||||||
uses: actions/upload-pages-artifact@v3
|
|
||||||
with:
|
|
||||||
path: _site
|
|
||||||
|
|
||||||
deploy:
|
|
||||||
environment:
|
|
||||||
name: github-pages
|
|
||||||
url: ${{ steps.deployment.outputs.page_url }}
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
needs: build
|
|
||||||
steps:
|
|
||||||
- name: Deploy to GitHub Pages
|
|
||||||
id: deployment
|
|
||||||
uses: actions/deploy-pages@v4
|
|
||||||
256
AUGMENTATION_ARCHITECTURE.md
Normal file
256
AUGMENTATION_ARCHITECTURE.md
Normal file
|
|
@ -0,0 +1,256 @@
|
||||||
|
# 🧠 Brainy Augmentation Architecture - Complete Guide
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Brainy has a clear augmentation system with four tiers:
|
||||||
|
|
||||||
|
```
|
||||||
|
1. Built-in (Free, Always Included)
|
||||||
|
2. Community (Free, npm packages)
|
||||||
|
3. Premium (Paid, @soulcraft/brain-cloud)
|
||||||
|
4. Brain Cloud (Managed Service)
|
||||||
|
```
|
||||||
|
|
||||||
|
## 1. Built-in Augmentations (Always Free)
|
||||||
|
|
||||||
|
These come with every Brainy installation:
|
||||||
|
|
||||||
|
### Currently Implemented:
|
||||||
|
- **NeuralImport** - AI-powered data understanding
|
||||||
|
- **Basic Storage** - Filesystem/memory persistence
|
||||||
|
- **Vector Search** - Semantic similarity
|
||||||
|
- **Graph Traversal** - Relationship queries
|
||||||
|
|
||||||
|
### To Be Added (Still Built-in):
|
||||||
|
```javascript
|
||||||
|
// src/augmentations/built-in/
|
||||||
|
├── autoSave.ts // Automatic persistence
|
||||||
|
├── basicCache.ts // Query caching
|
||||||
|
├── simpleBackup.ts // Local backups
|
||||||
|
└── metadataIndex.ts // Facet indexing
|
||||||
|
```
|
||||||
|
|
||||||
|
## 2. Community Augmentations (Free, Open Source)
|
||||||
|
|
||||||
|
Published to npm by the community:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Examples (to be created by community)
|
||||||
|
npm install brainy-sentiment # Sentiment analysis
|
||||||
|
npm install brainy-translator # Multi-language
|
||||||
|
npm install brainy-summarizer # Text summarization
|
||||||
|
npm install brainy-classifier # Text classification
|
||||||
|
```
|
||||||
|
|
||||||
|
Usage:
|
||||||
|
```javascript
|
||||||
|
import { SentimentAnalyzer } from 'brainy-sentiment'
|
||||||
|
|
||||||
|
const cortex = new Cortex()
|
||||||
|
cortex.register(new SentimentAnalyzer())
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. Premium Augmentations (@soulcraft/brain-cloud)
|
||||||
|
|
||||||
|
The `/brain-cloud` project contains premium augmentations:
|
||||||
|
|
||||||
|
### Core Premium Features (AI Memory & Coordination):
|
||||||
|
```javascript
|
||||||
|
import {
|
||||||
|
AIMemory, // Persistent AI memory across sessions
|
||||||
|
AgentCoordinator, // Multi-agent handoffs
|
||||||
|
TeamSync, // Real-time team synchronization
|
||||||
|
CloudBackup // Automatic cloud backups
|
||||||
|
} from '@soulcraft/brain-cloud'
|
||||||
|
```
|
||||||
|
|
||||||
|
### Enterprise Connectors (from old quantum-vault):
|
||||||
|
```javascript
|
||||||
|
import {
|
||||||
|
NotionSync, // Bidirectional Notion sync
|
||||||
|
SalesforceConnect, // CRM integration
|
||||||
|
AirtableSync, // Database sync
|
||||||
|
PostgresSync, // Real-time replication
|
||||||
|
SlackMemory, // Team knowledge base
|
||||||
|
AnalyticsSuite // Business intelligence
|
||||||
|
} from '@soulcraft/brain-cloud/enterprise'
|
||||||
|
```
|
||||||
|
|
||||||
|
## 4. Brain Cloud Service (Managed)
|
||||||
|
|
||||||
|
The hosted service at brain-cloud.soulcraft.com:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Connect to managed service
|
||||||
|
await brain.connect('brain-cloud.soulcraft.com', {
|
||||||
|
instance: 'my-team',
|
||||||
|
apiKey: process.env.BRAIN_CLOUD_KEY
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
## CLI Commands Structure
|
||||||
|
|
||||||
|
### Core Commands (brainy)
|
||||||
|
```bash
|
||||||
|
# Database operations
|
||||||
|
brainy init # Initialize Brainy
|
||||||
|
brainy add "data" # Add data
|
||||||
|
brainy search "query" # Search
|
||||||
|
brainy chat # Interactive chat
|
||||||
|
|
||||||
|
# Augmentation management
|
||||||
|
brainy augment # List augmentations
|
||||||
|
brainy augment add # Add augmentation (interactive)
|
||||||
|
brainy augment remove # Remove augmentation
|
||||||
|
brainy augment config # Configure augmentation
|
||||||
|
|
||||||
|
# Brain Cloud connection
|
||||||
|
brainy cloud # Connect to Brain Cloud service
|
||||||
|
brainy cloud --status # Check connection status
|
||||||
|
brainy cloud --sync # Force sync
|
||||||
|
```
|
||||||
|
|
||||||
|
### Installing Augmentations via CLI
|
||||||
|
|
||||||
|
#### Built-in (always available):
|
||||||
|
```bash
|
||||||
|
brainy augment enable neural-import
|
||||||
|
brainy augment enable auto-save
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Community (from npm):
|
||||||
|
```bash
|
||||||
|
# Install from npm first
|
||||||
|
npm install -g brainy-sentiment
|
||||||
|
|
||||||
|
# Then register with Brainy
|
||||||
|
brainy augment add brainy-sentiment --type sense
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Premium (requires license):
|
||||||
|
```bash
|
||||||
|
# Set license key
|
||||||
|
export BRAINY_LICENSE_KEY=lic_xxxxx
|
||||||
|
|
||||||
|
# Install premium package
|
||||||
|
npm install -g @soulcraft/brain-cloud
|
||||||
|
|
||||||
|
# Register augmentations
|
||||||
|
brainy augment add ai-memory --premium
|
||||||
|
brainy augment add notion-sync --premium
|
||||||
|
```
|
||||||
|
|
||||||
|
#### For Brain Cloud service:
|
||||||
|
```bash
|
||||||
|
# Connect to cloud (handles everything)
|
||||||
|
brainy cloud --connect YOUR_CUSTOMER_ID
|
||||||
|
```
|
||||||
|
|
||||||
|
## How Augmentations Work
|
||||||
|
|
||||||
|
### 1. Local Instance
|
||||||
|
```javascript
|
||||||
|
const brain = new BrainyData()
|
||||||
|
const cortex = new Cortex()
|
||||||
|
|
||||||
|
// Register augmentations
|
||||||
|
cortex.register(new NeuralImport(brain)) // Built-in
|
||||||
|
cortex.register(new SentimentAnalyzer()) // Community
|
||||||
|
cortex.register(new NotionSync({ key })) // Premium
|
||||||
|
|
||||||
|
await brain.init()
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Remote Hosted Instance
|
||||||
|
```javascript
|
||||||
|
// Connect to remote Brainy
|
||||||
|
const brain = new BrainyData({
|
||||||
|
remote: 'https://my-brainy-server.com'
|
||||||
|
})
|
||||||
|
|
||||||
|
// Augmentations run on server
|
||||||
|
await brain.addAugmentation('sentiment-analyzer')
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Brain Cloud Instance
|
||||||
|
```javascript
|
||||||
|
// Connect to Brain Cloud
|
||||||
|
const brain = new BrainyData({
|
||||||
|
cloud: true,
|
||||||
|
customerId: 'cust_xxx'
|
||||||
|
})
|
||||||
|
|
||||||
|
// All premium augmentations available
|
||||||
|
// Managed by Brain Cloud service
|
||||||
|
```
|
||||||
|
|
||||||
|
## Directory Structure
|
||||||
|
|
||||||
|
### /brainy (this project)
|
||||||
|
```
|
||||||
|
src/
|
||||||
|
├── augmentations/
|
||||||
|
│ ├── built-in/ # Free, always included
|
||||||
|
│ │ ├── neuralImport.ts
|
||||||
|
│ │ ├── autoSave.ts
|
||||||
|
│ │ └── basicCache.ts
|
||||||
|
│ └── cortexSense.ts # Legacy, being refactored
|
||||||
|
├── cortex.ts # Orchestrator
|
||||||
|
└── brainyData.ts # Core database
|
||||||
|
```
|
||||||
|
|
||||||
|
### /brain-cloud (premium project)
|
||||||
|
```
|
||||||
|
src/
|
||||||
|
├── augmentations/
|
||||||
|
│ ├── memory/ # AI Memory features
|
||||||
|
│ │ ├── aiMemory.ts
|
||||||
|
│ │ ├── agentCoordinator.ts
|
||||||
|
│ │ └── teamSync.ts
|
||||||
|
│ ├── enterprise/ # Enterprise connectors
|
||||||
|
│ │ ├── notionSync.ts
|
||||||
|
│ │ ├── salesforce.ts
|
||||||
|
│ │ └── airtable.ts
|
||||||
|
│ └── index.ts # Main exports
|
||||||
|
├── licensing/ # License validation
|
||||||
|
└── cloud-service/ # Brain Cloud API
|
||||||
|
```
|
||||||
|
|
||||||
|
## Migration Plan
|
||||||
|
|
||||||
|
### Phase 1: Update References
|
||||||
|
- [x] Replace all `brainy-quantum-vault` → `@soulcraft/brain-cloud`
|
||||||
|
- [ ] Update documentation
|
||||||
|
- [ ] Update CLI commands
|
||||||
|
|
||||||
|
### Phase 2: Restructure brain-cloud
|
||||||
|
- [ ] Move quantum-vault connectors to brain-cloud/enterprise
|
||||||
|
- [ ] Add AI memory augmentations
|
||||||
|
- [ ] Implement license validation
|
||||||
|
|
||||||
|
### Phase 3: CLI Enhancement
|
||||||
|
- [ ] Add `brainy augment` commands
|
||||||
|
- [ ] Interactive augmentation installer
|
||||||
|
- [ ] Auto-detect available augmentations
|
||||||
|
|
||||||
|
### Phase 4: Documentation
|
||||||
|
- [ ] Update README with clear tiers
|
||||||
|
- [ ] Create augmentation development guide
|
||||||
|
- [ ] Website update instructions
|
||||||
|
|
||||||
|
## License Model
|
||||||
|
|
||||||
|
```
|
||||||
|
Built-in: MIT License (Free forever)
|
||||||
|
Community: Varies (usually MIT)
|
||||||
|
Premium: Commercial License ($49-299/mo)
|
||||||
|
Cloud: Subscription ($19-99/mo)
|
||||||
|
```
|
||||||
|
|
||||||
|
## The Promise
|
||||||
|
|
||||||
|
1. **Built-in augmentations are ALWAYS free**
|
||||||
|
2. **No feature moves from free to paid**
|
||||||
|
3. **Community contributions welcome**
|
||||||
|
4. **Premium funds open source development**
|
||||||
|
5. **Brain Cloud is optional, not required**
|
||||||
251
CLI_AUGMENTATION_GUIDE.md
Normal file
251
CLI_AUGMENTATION_GUIDE.md
Normal file
|
|
@ -0,0 +1,251 @@
|
||||||
|
# 🧠 Brainy CLI - Augmentation Management Guide
|
||||||
|
|
||||||
|
## Complete CLI Commands for Augmentations
|
||||||
|
|
||||||
|
### Core Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Initialize Brainy
|
||||||
|
brainy init
|
||||||
|
|
||||||
|
# Basic operations
|
||||||
|
brainy add "data" # Add data
|
||||||
|
brainy search "query" # Search
|
||||||
|
brainy chat # Interactive chat
|
||||||
|
```
|
||||||
|
|
||||||
|
### Augmentation Management
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# List all augmentations
|
||||||
|
brainy augment # Shows installed & available
|
||||||
|
brainy augment list # Same as above
|
||||||
|
brainy augment available # Shows what can be installed
|
||||||
|
|
||||||
|
# Add augmentations
|
||||||
|
brainy augment add # Interactive mode
|
||||||
|
brainy augment add neural-import # Built-in
|
||||||
|
brainy augment add brainy-sentiment # Community (from npm)
|
||||||
|
brainy augment add ai-memory --premium # Premium (needs license)
|
||||||
|
|
||||||
|
# Remove augmentations
|
||||||
|
brainy augment remove sentiment-analyzer
|
||||||
|
brainy augment disable neural-import # Disable but keep installed
|
||||||
|
|
||||||
|
# Configure augmentations
|
||||||
|
brainy augment config neural-import
|
||||||
|
brainy augment config notion-sync --set apiKey=xxx
|
||||||
|
```
|
||||||
|
|
||||||
|
### Installing Different Types
|
||||||
|
|
||||||
|
#### 1. Built-in Augmentations (Free, Always Available)
|
||||||
|
```bash
|
||||||
|
# These are included - just enable them
|
||||||
|
brainy augment enable neural-import
|
||||||
|
brainy augment enable auto-save
|
||||||
|
brainy augment enable basic-cache
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. Community Augmentations (Free, From npm)
|
||||||
|
```bash
|
||||||
|
# Step 1: Install from npm
|
||||||
|
npm install -g brainy-sentiment
|
||||||
|
|
||||||
|
# Step 2: Register with Brainy
|
||||||
|
brainy augment add brainy-sentiment
|
||||||
|
|
||||||
|
# Or in one command (coming soon)
|
||||||
|
brainy augment install brainy-sentiment # Auto-installs from npm
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3. Premium Augmentations (Paid, From @soulcraft/brain-cloud)
|
||||||
|
```bash
|
||||||
|
# Step 1: Set license key
|
||||||
|
export BRAINY_LICENSE_KEY=lic_xxxxxxxxxxxxx
|
||||||
|
|
||||||
|
# Step 2: Install premium package
|
||||||
|
npm install -g @soulcraft/brain-cloud
|
||||||
|
|
||||||
|
# Step 3: Add specific augmentations
|
||||||
|
brainy augment add ai-memory --premium
|
||||||
|
brainy augment add agent-coordinator --premium
|
||||||
|
brainy augment add notion-sync --premium
|
||||||
|
|
||||||
|
# Or add all premium at once
|
||||||
|
brainy augment add-premium --all
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 4. Brain Cloud Service (Managed, Everything Included)
|
||||||
|
```bash
|
||||||
|
# Connect to Brain Cloud (includes all augmentations)
|
||||||
|
brainy cloud --connect YOUR_CUSTOMER_ID
|
||||||
|
|
||||||
|
# Check status
|
||||||
|
brainy cloud --status
|
||||||
|
|
||||||
|
# Force sync
|
||||||
|
brainy cloud --sync
|
||||||
|
|
||||||
|
# Open dashboard
|
||||||
|
brainy cloud --dashboard
|
||||||
|
```
|
||||||
|
|
||||||
|
### Working with Different Instances
|
||||||
|
|
||||||
|
#### Local Instance
|
||||||
|
```bash
|
||||||
|
# Add augmentation to local Brainy
|
||||||
|
cd my-project
|
||||||
|
brainy init
|
||||||
|
brainy augment add neural-import
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Remote Hosted Instance
|
||||||
|
```bash
|
||||||
|
# Connect to remote Brainy server
|
||||||
|
brainy config set server.url https://my-brainy-server.com
|
||||||
|
brainy config set server.apiKey xxx
|
||||||
|
|
||||||
|
# Add augmentation to remote
|
||||||
|
brainy augment add sentiment-analyzer --remote
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Brain Cloud Instance
|
||||||
|
```bash
|
||||||
|
# Everything is managed
|
||||||
|
brainy cloud --connect CUSTOMER_ID
|
||||||
|
# All augmentations automatically available
|
||||||
|
```
|
||||||
|
|
||||||
|
### Interactive Mode Examples
|
||||||
|
|
||||||
|
#### Adding an Augmentation (No Arguments)
|
||||||
|
```bash
|
||||||
|
$ brainy augment add
|
||||||
|
? What type of augmentation? ›
|
||||||
|
Built-in (Free)
|
||||||
|
Community (npm)
|
||||||
|
Premium (Licensed)
|
||||||
|
|
||||||
|
? Select augmentation ›
|
||||||
|
✓ neural-import (AI understanding)
|
||||||
|
○ sentiment-analyzer (Emotion detection)
|
||||||
|
○ translator (Multi-language)
|
||||||
|
|
||||||
|
? Configure now? (Y/n) ›
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Configuring an Augmentation
|
||||||
|
```bash
|
||||||
|
$ brainy augment config notion-sync
|
||||||
|
? Notion API Token › secret_xxxxx
|
||||||
|
? Sync Mode ›
|
||||||
|
○ Read only
|
||||||
|
● Bidirectional
|
||||||
|
○ Write only
|
||||||
|
|
||||||
|
? Sync Interval (minutes) › 5
|
||||||
|
✅ Configuration saved!
|
||||||
|
```
|
||||||
|
|
||||||
|
### CLI Implementation in brainy.js
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// brainy augment command structure
|
||||||
|
program
|
||||||
|
.command('augment [action] [name]')
|
||||||
|
.description('Manage brain augmentations')
|
||||||
|
.option('--type <type>', 'Augmentation type (sense|conduit|memory|etc)')
|
||||||
|
.option('--premium', 'Premium augmentation')
|
||||||
|
.option('--remote', 'Install on remote server')
|
||||||
|
.action(async (action, name, options) => {
|
||||||
|
if (!action) {
|
||||||
|
// List all augmentations
|
||||||
|
await listAugmentations()
|
||||||
|
} else {
|
||||||
|
switch(action) {
|
||||||
|
case 'add':
|
||||||
|
case 'install':
|
||||||
|
await installAugmentation(name, options)
|
||||||
|
break
|
||||||
|
case 'remove':
|
||||||
|
await removeAugmentation(name)
|
||||||
|
break
|
||||||
|
case 'config':
|
||||||
|
await configureAugmentation(name, options)
|
||||||
|
break
|
||||||
|
case 'list':
|
||||||
|
await listAugmentations()
|
||||||
|
break
|
||||||
|
case 'enable':
|
||||||
|
await enableAugmentation(name)
|
||||||
|
break
|
||||||
|
case 'disable':
|
||||||
|
await disableAugmentation(name)
|
||||||
|
break
|
||||||
|
}
|
||||||
|
}
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
### Environment Variables
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# For premium augmentations
|
||||||
|
export BRAINY_LICENSE_KEY=lic_xxxxxxxxxxxxx
|
||||||
|
|
||||||
|
# For Brain Cloud
|
||||||
|
export BRAIN_CLOUD_KEY=bc_xxxxxxxxxxxxx
|
||||||
|
export BRAIN_CLOUD_CUSTOMER_ID=cust_xxxxx
|
||||||
|
|
||||||
|
# For remote server
|
||||||
|
export BRAINY_SERVER_URL=https://my-server.com
|
||||||
|
export BRAINY_SERVER_KEY=xxx
|
||||||
|
```
|
||||||
|
|
||||||
|
### Package.json Scripts
|
||||||
|
|
||||||
|
Add these to your project's package.json:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"scripts": {
|
||||||
|
"brain:init": "brainy init",
|
||||||
|
"brain:augment": "brainy augment",
|
||||||
|
"brain:add-sentiment": "brainy augment add brainy-sentiment",
|
||||||
|
"brain:add-premium": "brainy augment add ai-memory --premium",
|
||||||
|
"brain:cloud": "brainy cloud --connect"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Error Messages & Solutions
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Missing license key
|
||||||
|
❌ Premium augmentation requires license key
|
||||||
|
💡 Set BRAINY_LICENSE_KEY or visit soulcraft.com
|
||||||
|
|
||||||
|
# Augmentation not found
|
||||||
|
❌ Augmentation 'xyz' not found
|
||||||
|
💡 Try: npm install brainy-xyz first
|
||||||
|
|
||||||
|
# Remote connection failed
|
||||||
|
❌ Cannot connect to remote server
|
||||||
|
💡 Check BRAINY_SERVER_URL and network connection
|
||||||
|
|
||||||
|
# Incompatible version
|
||||||
|
❌ Augmentation requires Brainy v0.62+
|
||||||
|
💡 Update: npm update @soulcraft/brainy
|
||||||
|
```
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
The CLI provides a unified interface for managing all augmentation types:
|
||||||
|
- **Built-in**: Always available, just enable
|
||||||
|
- **Community**: Install from npm, then add
|
||||||
|
- **Premium**: Need license, install from @soulcraft/brain-cloud
|
||||||
|
- **Brain Cloud**: Everything managed, just connect
|
||||||
|
|
||||||
|
The key is making it simple for beginners (interactive mode) while powerful for experts (direct commands).
|
||||||
164
PHILOSOPHY.md
Normal file
164
PHILOSOPHY.md
Normal file
|
|
@ -0,0 +1,164 @@
|
||||||
|
# 🧠 Brainy Philosophy & Design Principles
|
||||||
|
|
||||||
|
## Core Philosophy
|
||||||
|
**"Simple for beginners, powerful for experts"**
|
||||||
|
|
||||||
|
## Design Principles
|
||||||
|
|
||||||
|
### 1. **Beginner-Friendly by Default**
|
||||||
|
- If no arguments provided → Interactive mode with helpful prompts
|
||||||
|
- Clear, simple language (no jargon)
|
||||||
|
- Helpful examples shown automatically
|
||||||
|
- Smart defaults that "just work"
|
||||||
|
|
||||||
|
### 2. **Clean, Simple Language**
|
||||||
|
```bash
|
||||||
|
# Good - Clear and simple
|
||||||
|
brainy add "John works at Acme Corp"
|
||||||
|
brainy search "Who works at Acme?"
|
||||||
|
brainy augment neural-import data.csv
|
||||||
|
|
||||||
|
# Bad - Technical and confusing
|
||||||
|
brainy insert --vector-dimension=384 --graph-node="person"
|
||||||
|
brainy query --similarity-threshold=0.8 --facet-filter='{"type":"person"}'
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. **Progressive Disclosure**
|
||||||
|
- Start simple, reveal complexity only when needed
|
||||||
|
- Basic usage requires no configuration
|
||||||
|
- Advanced features available but not required
|
||||||
|
|
||||||
|
### 4. **Interactive When Uncertain**
|
||||||
|
```bash
|
||||||
|
$ brainy add
|
||||||
|
? What would you like to add? › John Smith is a developer
|
||||||
|
? Add any tags or categories? (optional) › person, developer
|
||||||
|
✅ Added successfully!
|
||||||
|
|
||||||
|
$ brainy search
|
||||||
|
? What are you looking for? › developers
|
||||||
|
? How many results? (10) › 5
|
||||||
|
🔍 Found 5 matches...
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. **Consistent Brain Metaphor**
|
||||||
|
- **Brainy** = The brain (whole system)
|
||||||
|
- **Cortex** = Orchestrator (coordinates everything)
|
||||||
|
- **Neural Import** = Understanding data (neural processing)
|
||||||
|
- **Augmentations** = Brain capabilities (vision, hearing, memory, etc.)
|
||||||
|
|
||||||
|
### 6. **One Way to Do Things**
|
||||||
|
- Single clear path for common tasks
|
||||||
|
- No duplicate commands or confusing aliases
|
||||||
|
- If there are options, make the best one the default
|
||||||
|
|
||||||
|
### 7. **Helpful Error Messages**
|
||||||
|
```bash
|
||||||
|
# Good
|
||||||
|
❌ Can't find data.csv
|
||||||
|
💡 Did you mean data.json? Or try: brainy import --help
|
||||||
|
|
||||||
|
# Bad
|
||||||
|
Error: ENOENT no such file or directory
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. **Smart Defaults**
|
||||||
|
- Auto-detect file types
|
||||||
|
- Infer intent from context
|
||||||
|
- Use Neural Import by default for understanding data
|
||||||
|
- Automatic augmentation discovery
|
||||||
|
|
||||||
|
## CLI Command Philosophy
|
||||||
|
|
||||||
|
### Core Commands (Simple Verbs)
|
||||||
|
```bash
|
||||||
|
brainy init # Start here
|
||||||
|
brainy add # Add data
|
||||||
|
brainy search # Find data
|
||||||
|
brainy chat # Talk to your data
|
||||||
|
```
|
||||||
|
|
||||||
|
### Augmentation Commands (Clear Actions)
|
||||||
|
```bash
|
||||||
|
brainy augment # List/manage augmentations
|
||||||
|
brainy augment add neural-import # Add an augmentation
|
||||||
|
brainy augment remove notion-sync # Remove an augmentation
|
||||||
|
```
|
||||||
|
|
||||||
|
### Interactive Examples
|
||||||
|
```bash
|
||||||
|
# No arguments = Interactive mode
|
||||||
|
$ brainy add
|
||||||
|
? What would you like to add? › [waiting for input]
|
||||||
|
|
||||||
|
# With arguments = Direct mode
|
||||||
|
$ brainy add "Sarah is a designer at StartupXYZ"
|
||||||
|
✅ Added!
|
||||||
|
|
||||||
|
# Help is conversational
|
||||||
|
$ brainy help add
|
||||||
|
📝 Add data to your brain
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
brainy add "John works at Acme"
|
||||||
|
brainy add data.csv
|
||||||
|
brainy add --interactive
|
||||||
|
|
||||||
|
Just run 'brainy add' for interactive mode!
|
||||||
|
```
|
||||||
|
|
||||||
|
## Code Philosophy
|
||||||
|
|
||||||
|
### Function Names
|
||||||
|
```typescript
|
||||||
|
// Good - Clear and simple
|
||||||
|
brain.add(data)
|
||||||
|
brain.search(query)
|
||||||
|
cortex.process(augmentation)
|
||||||
|
|
||||||
|
// Bad - Technical and verbose
|
||||||
|
brain.insertVectorWithGraphRelationships(data)
|
||||||
|
brain.executeMultiDimensionalQuery(query)
|
||||||
|
cortex.executeAugmentationPipeline(augmentation)
|
||||||
|
```
|
||||||
|
|
||||||
|
### API Design
|
||||||
|
```typescript
|
||||||
|
// Good - Progressive enhancement
|
||||||
|
brain.add("simple text") // Works
|
||||||
|
brain.add("text", { category: "person" }) // More control
|
||||||
|
brain.add("text", metadata, options) // Full control
|
||||||
|
|
||||||
|
// Bad - All or nothing
|
||||||
|
brain.add(text, vector, metadata, options, callback)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Documentation Philosophy
|
||||||
|
|
||||||
|
### README Structure
|
||||||
|
1. **What it is** (one sentence)
|
||||||
|
2. **Quick start** (3 commands max)
|
||||||
|
3. **Simple examples** (real-world use)
|
||||||
|
4. **Going deeper** (advanced features)
|
||||||
|
|
||||||
|
### Example First
|
||||||
|
Always show the example before explaining:
|
||||||
|
```bash
|
||||||
|
# Add a person
|
||||||
|
brainy add "Alice is a product manager"
|
||||||
|
|
||||||
|
# Find them later
|
||||||
|
brainy search "product manager"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Testing Philosophy
|
||||||
|
- Test the beginner path first
|
||||||
|
- Interactive mode must always work
|
||||||
|
- Examples in docs must be runnable
|
||||||
|
- Error messages must be helpful
|
||||||
|
|
||||||
|
## Remember
|
||||||
|
- **If it's not simple, it's not ready**
|
||||||
|
- **The best interface is no interface** (smart defaults)
|
||||||
|
- **Show, don't tell** (examples > explanations)
|
||||||
|
- **Beginner's mind** (always ask: would a newcomer understand this?)
|
||||||
822
README.md
822
README.md
|
|
@ -4,581 +4,451 @@
|
||||||
|
|
||||||
[](https://badge.fury.io/js/%40soulcraft%2Fbrainy)
|
[](https://badge.fury.io/js/%40soulcraft%2Fbrainy)
|
||||||
[](https://opensource.org/licenses/MIT)
|
[](https://opensource.org/licenses/MIT)
|
||||||
|
[](https://soulcraft.com/console)
|
||||||
[](https://nodejs.org/)
|
[](https://nodejs.org/)
|
||||||
[](https://www.typescriptlang.org/)
|
[](https://www.typescriptlang.org/)
|
||||||
|
|
||||||
# BRAINY: Multi-Dimensional AI Database™
|
# 🧠 BRAINY: Your AI-Powered Second Brain
|
||||||
|
|
||||||
**The world's first Multi-Dimensional AI Database**
|
**The World's First Multi-Dimensional AI Database™**
|
||||||
*Vector similarity • Graph relationships • Metadata facets • AI context*
|
*Vector similarity • Graph relationships • Metadata facets • Neural understanding*
|
||||||
|
|
||||||
*Zero-to-Smart™ technology that thinks so you don't have to*
|
**Build AI apps that actually understand your data - in minutes, not months**
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🚀 THE AMAZING BRAINY: See It In Action!
|
## 🚀 What Can You Build?
|
||||||
|
|
||||||
|
### 💬 **AI Chat Apps** - That Actually Remember
|
||||||
```javascript
|
```javascript
|
||||||
import { BrainyData } from '@soulcraft/brainy'
|
// Your users' conversations persist across sessions
|
||||||
|
const brain = new BrainyData()
|
||||||
|
await brain.add("User prefers dark mode")
|
||||||
|
await brain.add("User is learning Spanish")
|
||||||
|
|
||||||
// 🧪 Initialize your brain-in-a-jar
|
// Later sessions remember everything
|
||||||
const brainy = new BrainyData() // Zero config - it's ALIVE!
|
const context = await brain.search("user preferences")
|
||||||
await brainy.init()
|
// AI knows: dark mode + Spanish learning preference
|
||||||
|
|
||||||
// 🔬 Feed it knowledge with relationships
|
|
||||||
const openai = await brainy.add("OpenAI", { type: "company", funding: 11000000 })
|
|
||||||
const gpt4 = await brainy.add("GPT-4", { type: "product", users: 100000000 })
|
|
||||||
await brainy.relate(openai, gpt4, "develops")
|
|
||||||
|
|
||||||
// ⚡ One query to rule them all - Vector + Graph + Faceted search!
|
|
||||||
const results = await brainy.search("AI language models", 5, {
|
|
||||||
metadata: { funding: { $gte: 10000000 } }, // MongoDB-style filtering
|
|
||||||
includeVerbs: true // Graph relationships
|
|
||||||
}) // Plus semantic vector search!
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**🎭 8 lines. Three search paradigms. One brain-powered database.**
|
### 🤖 **Smart Assistants** - With Real Knowledge Graphs
|
||||||
|
```javascript
|
||||||
|
// Build assistants that understand relationships
|
||||||
|
await brain.add("Sarah manages the design team")
|
||||||
|
await brain.addVerb("Sarah", "reports_to", "John")
|
||||||
|
await brain.addVerb("Sarah", "works_on", "Project Apollo")
|
||||||
|
|
||||||
## 💫 WHY BRAINY? The Problem We Solve
|
// Query complex relationships
|
||||||
|
const team = await brain.getRelated("Project Apollo", {
|
||||||
### ❌ The Old Way: Database Frankenstein
|
verb: "works_on",
|
||||||
|
depth: 2
|
||||||
```
|
})
|
||||||
Pinecone ($$$) + Neo4j ($$$) + Elasticsearch ($$$) + Sync Hell = 😱
|
// Returns: entire team structure with relationships
|
||||||
```
|
```
|
||||||
|
|
||||||
### ✅ The Brainy Way: One Multi-Dimensional Brain
|
### 📊 **RAG Applications** - Without the Complexity
|
||||||
|
```javascript
|
||||||
```
|
// Retrieval-Augmented Generation in 3 lines
|
||||||
Multi-Dimensional AI Database = Vector + Graph + Facets + AI = 🧠✨
|
await brain.add(companyDocs) // Add your knowledge base
|
||||||
|
const relevant = await brain.search(userQuery, 10) // Find relevant context
|
||||||
|
const answer = await llm.generate(relevant + userQuery) // Generate with context
|
||||||
```
|
```
|
||||||
|
|
||||||
**Your data gets a multi-dimensional brain upgrade. No assembly required.**
|
### 🔍 **Semantic Search** - That Just Works
|
||||||
|
```javascript
|
||||||
|
// No embeddings API needed - it's built in!
|
||||||
|
await brain.add("The iPhone 15 Pro has a titanium design")
|
||||||
|
await brain.add("Samsung Galaxy S24 features AI photography")
|
||||||
|
|
||||||
## ⚡ QUICK & EASY: From Zero to Smart in 60 Seconds
|
const results = await brain.search("premium smartphones with metal build")
|
||||||
|
// Returns: iPhone (titanium matches "metal build" semantically)
|
||||||
|
```
|
||||||
|
|
||||||
### Installation
|
### 🎯 **Recommendation Engines** - With Graph Intelligence
|
||||||
|
```javascript
|
||||||
|
// Netflix-style recommendations with relationships
|
||||||
|
await brain.addVerb("User123", "watched", "Inception")
|
||||||
|
await brain.addVerb("User123", "liked", "Inception")
|
||||||
|
await brain.addVerb("Inception", "similar_to", "Interstellar")
|
||||||
|
|
||||||
|
const recommendations = await brain.getRelated("User123", {
|
||||||
|
verb: ["liked", "watched"],
|
||||||
|
depth: 2
|
||||||
|
})
|
||||||
|
// Returns: Interstellar and other related content
|
||||||
|
```
|
||||||
|
|
||||||
|
## 💫 Why Brainy? The Problem We Solve
|
||||||
|
|
||||||
|
### ❌ **The Old Way: Database Frankenstein**
|
||||||
|
```
|
||||||
|
Pinecone ($750/mo) + Neo4j ($500/mo) + Elasticsearch ($300/mo) +
|
||||||
|
Sync nightmares + 3 different APIs + Vendor lock-in = 😱💸
|
||||||
|
```
|
||||||
|
|
||||||
|
### ✅ **The Brainy Way: One Brain, All Dimensions**
|
||||||
|
```
|
||||||
|
Vector + Graph + Search + AI = Brainy (Free & Open Source) = 🧠✨
|
||||||
|
```
|
||||||
|
|
||||||
|
**Your data gets superpowers. Your wallet stays happy.**
|
||||||
|
|
||||||
|
## 🎮 Try It Now - No Install Required!
|
||||||
|
|
||||||
|
<div align="center">
|
||||||
|
|
||||||
|
### [**→ Live Demo at soulcraft.com/console ←**](https://soulcraft.com/console)
|
||||||
|
|
||||||
|
Try Brainy instantly in your browser. No signup. No credit card.
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
||||||
|
## ⚡ Quick Start (60 Seconds)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm install @soulcraft/brainy
|
npm install @soulcraft/brainy
|
||||||
```
|
```
|
||||||
|
|
||||||
### Your First Brainy App
|
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
import { BrainyData } from '@soulcraft/brainy'
|
import { BrainyData } from '@soulcraft/brainy'
|
||||||
|
|
||||||
// It's alive! (No config needed)
|
// Zero configuration - it just works!
|
||||||
const brainy = new BrainyData()
|
const brain = new BrainyData()
|
||||||
await brainy.init()
|
await brain.init()
|
||||||
|
|
||||||
// Feed your brain some data
|
// Add any data - text, objects, relationships
|
||||||
await brainy.add("Tesla", { type: "company", sector: "automotive" })
|
await brain.add("Elon Musk founded SpaceX in 2002")
|
||||||
await brainy.add("SpaceX", { type: "company", sector: "aerospace" })
|
await brain.add({ company: "Tesla", ceo: "Elon Musk", founded: 2003 })
|
||||||
|
await brain.addVerb("Elon Musk", "founded", "Tesla")
|
||||||
|
|
||||||
// Ask it questions (semantic search)
|
// Search naturally
|
||||||
const similar = await brainy.search("electric vehicles")
|
const results = await brain.search("companies founded by Elon")
|
||||||
|
// Returns: SpaceX and Tesla with relevance scores
|
||||||
|
|
||||||
// Use relationships (graph database)
|
// Query relationships
|
||||||
await brainy.relate("Tesla", "SpaceX", "shares_founder_with")
|
const companies = await brain.getRelated("Elon Musk", { verb: "founded" })
|
||||||
|
// Returns: SpaceX, Tesla
|
||||||
|
|
||||||
// Filter like MongoDB (faceted search)
|
// Filter with metadata
|
||||||
const results = await brainy.search("innovation", {
|
const recent = await brain.search("companies", 10, {
|
||||||
metadata: { sector: "automotive" }
|
filter: { founded: { $gte: 2000 } }
|
||||||
})
|
})
|
||||||
```
|
```
|
||||||
|
|
||||||
## 🎆 NEW! Talk to Your Data with Brainy Chat
|
## 🧩 Augmentation System - Extend Your Brain
|
||||||
|
|
||||||
|
Brainy is **100% open source** with a powerful augmentation system. Choose what you need:
|
||||||
|
|
||||||
|
### 🆓 **Built-in Augmentations** (Always Free)
|
||||||
|
```javascript
|
||||||
|
import { NeuralImport } from '@soulcraft/brainy'
|
||||||
|
|
||||||
|
// AI-powered data understanding - included in every install
|
||||||
|
const neural = new NeuralImport(brain)
|
||||||
|
await neural.neuralImport('data.csv') // Automatically extracts entities & relationships
|
||||||
|
```
|
||||||
|
|
||||||
|
**Included augmentations:**
|
||||||
|
- ✅ **Neural Import** - AI understands your data structure
|
||||||
|
- ✅ **Basic Memory** - Persistent storage
|
||||||
|
- ✅ **Simple Search** - Text and vector search
|
||||||
|
- ✅ **Graph Traversal** - Relationship queries
|
||||||
|
|
||||||
|
### 🌟 **Community Augmentations** (Free, Open Source)
|
||||||
|
```bash
|
||||||
|
npm install brainy-sentiment # Community created
|
||||||
|
npm install brainy-translate # Community maintained
|
||||||
|
```
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
import { BrainyChat } from '@soulcraft/brainy'
|
import { SentimentAnalyzer } from 'brainy-sentiment'
|
||||||
|
import { Translator } from 'brainy-translate'
|
||||||
|
|
||||||
const chat = new BrainyChat(brainy) // Your data becomes conversational!
|
cortex.register(new SentimentAnalyzer()) // Analyze emotions
|
||||||
const answer = await chat.ask("What patterns do you see in customer behavior?")
|
cortex.register(new Translator()) // Multi-language support
|
||||||
// → AI-powered insights from your knowledge graph!
|
|
||||||
```
|
```
|
||||||
|
|
||||||
<sub>**How it works:** Combines vector embeddings for semantic understanding • Graph relationships for connection patterns • Metadata filtering for structured analysis • Optional LLM for natural language insights</sub>
|
**Popular community augmentations:**
|
||||||
|
- 🎭 Sentiment Analysis
|
||||||
|
- 🌍 Translation (50+ languages)
|
||||||
|
- 📧 Email Parser
|
||||||
|
- 🔗 URL Extractor
|
||||||
|
- 📊 Data Visualizer
|
||||||
|
- 🎨 Image Understanding
|
||||||
|
|
||||||
**One line. Zero complexity. Optional LLM for genius-level responses.**
|
### 💼 **Premium Augmentations** (@soulcraft/brain-cloud)
|
||||||
[📖 **Learn More About Brainy Chat**](BRAINY-CHAT.md)
|
For teams that need AI memory and enterprise features:
|
||||||
|
|
||||||
## 🎮 NEW! Brainy CLI - Command Center from the Future
|
|
||||||
|
|
||||||
### 💬 Talk to Your Data
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Have conversations with your knowledge graph
|
|
||||||
brainy chat "What patterns exist in customer behavior?"
|
|
||||||
brainy chat "Show me all connections between startups"
|
|
||||||
```
|
|
||||||
|
|
||||||
### 📥 Add & Import Data
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Import with AI understanding
|
|
||||||
brainy import data.csv --cortex --understand
|
|
||||||
|
|
||||||
# Add individual items
|
|
||||||
brainy add "OpenAI" --type company --metadata '{"founded": 2015}'
|
|
||||||
|
|
||||||
# Bulk import with relationships
|
|
||||||
brainy import relationships.json --detect-entities
|
|
||||||
```
|
|
||||||
|
|
||||||
### 🔍 Explore & Query
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Search semantically
|
|
||||||
brainy search "artificial intelligence companies"
|
|
||||||
|
|
||||||
# Query with filters
|
|
||||||
brainy query --filter 'funding>1000000' --type company
|
|
||||||
|
|
||||||
# Visualize relationships
|
|
||||||
brainy graph "OpenAI" --depth 2 --format ascii
|
|
||||||
```
|
|
||||||
|
|
||||||
### 🔄 Manage & Migrate
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Export your brain
|
|
||||||
brainy export my-brain.json --include-embeddings
|
|
||||||
|
|
||||||
# Migrate between storage backends
|
|
||||||
brainy migrate s3://old-bucket file://new-location
|
|
||||||
|
|
||||||
# Backup and restore
|
|
||||||
brainy backup --compress
|
|
||||||
brainy restore backup-2024.tar.gz
|
|
||||||
```
|
|
||||||
|
|
||||||
### 🔐 Environment & Secrets
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Store configuration securely
|
|
||||||
brainy config set api.key "sk-..." --encrypt
|
|
||||||
brainy config set storage.s3.bucket "my-brain"
|
|
||||||
|
|
||||||
# Load environment profiles
|
|
||||||
brainy env use production
|
|
||||||
brainy env create staging --from .env.staging
|
|
||||||
```
|
|
||||||
|
|
||||||
### 📊 Monitor & Optimize
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Real-time dashboard
|
|
||||||
brainy monitor --dashboard
|
|
||||||
|
|
||||||
# Performance analysis
|
|
||||||
brainy stats --detailed
|
|
||||||
brainy optimize index --auto
|
|
||||||
```
|
|
||||||
|
|
||||||
**Command your data empire from the terminal!**
|
|
||||||
[📖 **Full CLI Documentation**](docs/brainy-cli.md)
|
|
||||||
|
|
||||||
## 🧬 NEW! Cortex AI - Your Data Gets a PhD
|
|
||||||
|
|
||||||
**Cortex automatically understands and enhances your data:**
|
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
// Enable Cortex Intelligence during import
|
import {
|
||||||
const brainy = new BrainyData({
|
AIMemory, // Persistent AI memory
|
||||||
cortex: {
|
AgentCoordinator, // Multi-agent handoffs
|
||||||
enabled: true,
|
NotionSync, // Notion integration
|
||||||
autoDetect: true // Automatically identify entities & relationships
|
SalesforceConnect // CRM integration
|
||||||
}
|
} from '@soulcraft/brain-cloud'
|
||||||
|
|
||||||
|
// Requires license key - get one at soulcraft.com
|
||||||
|
const aiMemory = new AIMemory({
|
||||||
|
licenseKey: process.env.BRAINY_LICENSE_KEY
|
||||||
})
|
})
|
||||||
|
|
||||||
// Import with understanding
|
cortex.register(aiMemory) // AI remembers everything
|
||||||
await brainy.cortexImport('customers.csv', {
|
|
||||||
understand: true, // AI analyzes data structure
|
|
||||||
detectRelations: true, // Finds hidden connections
|
|
||||||
confidence: 0.8 // Quality threshold
|
|
||||||
})
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Your data becomes self-aware (in a good way)!**
|
**AI Memory & Coordination:**
|
||||||
|
- 🧠 **AI Memory** - Persistent across sessions
|
||||||
|
- 🤝 **Agent Coordinator** - Multi-agent handoffs
|
||||||
|
- 👥 **Team Sync** - Real-time collaboration
|
||||||
|
- 💾 **Cloud Backup** - Automatic backups
|
||||||
|
|
||||||
## 🔌 NEW! Augmentation Pipeline - Plug in Superpowers
|
**Enterprise Connectors:**
|
||||||
|
- 📝 **Notion Sync** - Bidirectional sync
|
||||||
|
- 💼 **Salesforce** - CRM integration
|
||||||
|
- 📊 **Airtable** - Database sync
|
||||||
|
- 🔄 **Postgres** - Real-time replication
|
||||||
|
- 🏢 **Slack** - Team knowledge base
|
||||||
|
|
||||||
**8 types of augmentations to enhance your brain:**
|
### 🎮 **Try Online** (Free Playground)
|
||||||
|
Test Brainy instantly without installing:
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
// Add augmentations like installing apps on your brain
|
// Visit soulcraft.com/console
|
||||||
brainy.augment({
|
// No signup required - just start coding!
|
||||||
type: 'PERCEPTION', // Visual/pattern recognition
|
// Perfect for:
|
||||||
handler: myPerceptor
|
// - Testing Brainy before installing
|
||||||
})
|
// - Prototyping ideas quickly
|
||||||
|
// - Learning the API
|
||||||
brainy.augment({
|
// - Sharing examples with others
|
||||||
type: 'COGNITION', // Deep thinking & analysis
|
|
||||||
handler: myThinker
|
|
||||||
})
|
|
||||||
|
|
||||||
// Premium augmentations (coming soon!)
|
|
||||||
brainy.augment({
|
|
||||||
type: 'NOTION_SYNC', // Bi-directional Notion sync
|
|
||||||
license: 'premium'
|
|
||||||
})
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Augmentation Types:**
|
**[→ Open Console](https://soulcraft.com/console)** - Your code runs locally, data stays private
|
||||||
|
|
||||||
- 🎯 **SENSE** - Input processing
|
### ☁️ **Brain Cloud** (Managed Service)
|
||||||
- 🧠 **MEMORY** - Long-term storage
|
For teams that want zero-ops:
|
||||||
- 💭 **COGNITION** - Deep analysis
|
|
||||||
- 🔗 **CONDUIT** - Data flow
|
|
||||||
- ⚡ **ACTIVATION** - Triggers & events
|
|
||||||
- 👁️ **PERCEPTION** - Pattern recognition
|
|
||||||
- 💬 **DIALOG** - Conversational AI
|
|
||||||
- 🌐 **WEBSOCKET** - Real-time sync
|
|
||||||
|
|
||||||
## 💪 POWERFUL FEATURES: What Makes Brainy Special
|
|
||||||
|
|
||||||
### ⚡ Performance That Defies Science
|
|
||||||
|
|
||||||
```
|
|
||||||
Vector Search (1M embeddings): 2-8ms latency 🚀
|
|
||||||
Graph Traversal (100M relations): 1-3ms latency 🔥
|
|
||||||
Combined Vector+Graph+Filter: 5-15ms latency ⚡
|
|
||||||
Throughput: 10K+ queries/sec 💫
|
|
||||||
```
|
|
||||||
|
|
||||||
### 🌍 Write Once, Run Anywhere (Literally)
|
|
||||||
|
|
||||||
- **Browser**: Uses OPFS, Web Workers - works offline!
|
|
||||||
- **Node.js**: FileSystem, Worker Threads - server-ready!
|
|
||||||
- **Edge/Serverless**: Memory-optimized - deploys anywhere!
|
|
||||||
- **React/Vue/Angular**: Same code, automatic optimization!
|
|
||||||
|
|
||||||
### 🔮 The Power of Three-in-One Search
|
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
// This ONE query replaces THREE databases:
|
// Connect to Brain Cloud - your brain in the cloud
|
||||||
const results = await brainy.search("AI startups in healthcare", 10, {
|
await brain.connect('brain-cloud.soulcraft.com', {
|
||||||
// 🔍 Vector: Semantic similarity
|
instance: 'my-team-brain',
|
||||||
includeVerbs: true,
|
apiKey: process.env.BRAIN_CLOUD_KEY
|
||||||
|
|
||||||
// 🔗 Graph: Relationship traversal
|
|
||||||
verbTypes: ["invests_in", "partners_with"],
|
|
||||||
|
|
||||||
// 📊 Faceted: MongoDB-style filtering
|
|
||||||
metadata: {
|
|
||||||
industry: "healthcare",
|
|
||||||
funding: { $gte: 1000000 },
|
|
||||||
stage: { $in: ["Series A", "Series B"] }
|
|
||||||
}
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
### 🧠 Self-Learning & Auto-Optimization
|
|
||||||
|
|
||||||
**Brainy gets smarter the more you use it:**
|
|
||||||
|
|
||||||
- Auto-indexes frequently searched fields
|
|
||||||
- Learns query patterns for faster responses
|
|
||||||
- Optimizes storage based on access patterns
|
|
||||||
- Self-configures for your environment
|
|
||||||
|
|
||||||
## 🎭 ADVANCED FEATURES: For Mad Scientists
|
|
||||||
|
|
||||||
### 🔬 MongoDB-Style Query Operators
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
const results = await brainy.search("quantum computing", {
|
|
||||||
metadata: {
|
|
||||||
$and: [
|
|
||||||
{ price: { $gte: 100, $lte: 1000 } },
|
|
||||||
{ category: { $in: ["electronics", "computing"] } },
|
|
||||||
{
|
|
||||||
$or: [
|
|
||||||
{ brand: "Intel" },
|
|
||||||
{ brand: "IBM" }
|
|
||||||
]
|
|
||||||
},
|
|
||||||
{ tags: { $includes: "quantum" } },
|
|
||||||
{ description: { $regex: "qubit|superposition" } }
|
|
||||||
]
|
|
||||||
}
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
**15+ operators**: `$gt`, `$gte`, `$lt`, `$lte`, `$eq`, `$ne`, `$in`, `$nin`, `$regex`, `$includes`, `$all`, `$size`,
|
|
||||||
`$and`, `$or`, `$not`
|
|
||||||
|
|
||||||
### 🧪 Specialized Deployment Modes
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
// High-speed data ingestion
|
|
||||||
const writer = new BrainyData({
|
|
||||||
writeOnly: true,
|
|
||||||
allowDirectReads: true // For deduplication
|
|
||||||
})
|
})
|
||||||
|
|
||||||
// Read-only search cluster
|
// Now your brain persists across:
|
||||||
const reader = new BrainyData({
|
// - Multiple developers
|
||||||
readOnly: true,
|
// - Different environments
|
||||||
frozen: true // Maximum performance
|
// - AI agents
|
||||||
})
|
// - Sessions
|
||||||
|
|
||||||
// Custom storage backend
|
|
||||||
const custom = new BrainyData({
|
|
||||||
storage: {
|
|
||||||
type: 's3',
|
|
||||||
s3Storage: {
|
|
||||||
bucketName: 'my-brain',
|
|
||||||
region: 'us-east-1'
|
|
||||||
}
|
|
||||||
}
|
|
||||||
})
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 🚀 Framework Integration Examples
|
**Brain Cloud features:**
|
||||||
|
- 🔄 Auto-sync across team
|
||||||
|
- 💾 Managed backups
|
||||||
|
- 🚀 Auto-scaling
|
||||||
|
- 🔒 Enterprise security
|
||||||
|
- 📊 Analytics dashboard
|
||||||
|
- 🤖 Multi-agent coordination
|
||||||
|
|
||||||
<details>
|
## 📝 Create Your Own Augmentation
|
||||||
<summary>📦 <strong>See Framework Examples</strong></summary>
|
|
||||||
|
|
||||||
#### React
|
### We ❤️ Open Source
|
||||||
|
|
||||||
```jsx
|
**Brainy will ALWAYS be open source.** We believe in:
|
||||||
import { BrainyData } from '@soulcraft/brainy'
|
- 🌍 Community first
|
||||||
|
- 🔓 No vendor lock-in
|
||||||
|
- 🎁 Free forever core
|
||||||
|
- 🤝 Sustainable open source
|
||||||
|
|
||||||
function App() {
|
### Build & Share Your Augmentation
|
||||||
const [brainy] = useState(() => new BrainyData())
|
|
||||||
|
|
||||||
useEffect(() => {
|
|
||||||
brainy.init()
|
|
||||||
}, [])
|
|
||||||
|
|
||||||
const search = async (query) => {
|
|
||||||
return await brainy.search(query, 10)
|
|
||||||
}
|
|
||||||
|
|
||||||
return <SearchInterface onSearch={search} />
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Vue 3
|
|
||||||
|
|
||||||
```vue
|
|
||||||
|
|
||||||
<script setup>
|
|
||||||
import { BrainyData } from '@soulcraft/brainy'
|
|
||||||
|
|
||||||
const brainy = new BrainyData()
|
|
||||||
await brainy.init()
|
|
||||||
|
|
||||||
const search = async (query) => {
|
|
||||||
return await brainy.search(query, 10)
|
|
||||||
}
|
|
||||||
</script>
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Angular
|
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
|
import { ISenseAugmentation } from '@soulcraft/brainy'
|
||||||
|
|
||||||
@Injectable({ providedIn: 'root' })
|
export class MovieRecommender implements ISenseAugmentation {
|
||||||
export class BrainyService {
|
name = 'movie-recommender'
|
||||||
private brainy = new BrainyData()
|
description = 'AI-powered movie recommendations'
|
||||||
|
enabled = true
|
||||||
async init() {
|
|
||||||
await this.brainy.init()
|
async processRawData(data: string) {
|
||||||
}
|
// Your recommendation logic
|
||||||
|
const movies = await this.analyzePreferences(data)
|
||||||
search(query: string) {
|
|
||||||
return this.brainy.search(query, 10)
|
return {
|
||||||
|
success: true,
|
||||||
|
data: {
|
||||||
|
nouns: movies.map(m => m.title),
|
||||||
|
verbs: movies.map(m => `similar_to:${m.genre}`),
|
||||||
|
metadata: { genres: movies.map(m => m.genre) }
|
||||||
|
}
|
||||||
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
</details>
|
**Share with the community:**
|
||||||
|
|
||||||
### 🐳 Docker & Cloud Deployment
|
|
||||||
|
|
||||||
```dockerfile
|
|
||||||
FROM node:24-slim
|
|
||||||
WORKDIR /app
|
|
||||||
COPY . .
|
|
||||||
RUN npm install
|
|
||||||
RUN npm run download-models # Bundle models for offline use
|
|
||||||
CMD ["node", "server.js"]
|
|
||||||
```
|
|
||||||
|
|
||||||
Deploy to AWS, GCP, Azure, Cloudflare Workers, anywhere!
|
|
||||||
|
|
||||||
## 💎 Premium Features (Optional)
|
|
||||||
|
|
||||||
**Core Brainy is FREE forever. Premium augmentations for enterprise:**
|
|
||||||
|
|
||||||
### 🔗 Enterprise Connectors (Coming Soon!)
|
|
||||||
|
|
||||||
- **Notion** ($49/mo) - Bi-directional workspace sync
|
|
||||||
- **Salesforce** ($99/mo) - CRM integration
|
|
||||||
- **Slack** ($49/mo) - Team knowledge capture
|
|
||||||
- **Asana** ($44/mo) - Project intelligence
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
brainy augment trial notion # Start 14-day free trial
|
npm publish brainy-movie-recommender
|
||||||
```
|
```
|
||||||
|
|
||||||
## 🎨 What You Can Build
|
**Earn from your creation:**
|
||||||
|
- 💚 Keep it free (we'll promote it!)
|
||||||
|
- 💰 Sell licenses (we'll help distribute!)
|
||||||
|
- 🤝 Join our partner program
|
||||||
|
|
||||||
**The only limit is your imagination:**
|
## 🎯 Real-World Examples
|
||||||
|
|
||||||
- **🤖 AI Assistants** - ChatGPT with perfect memory
|
### Customer Support Bot with Memory
|
||||||
- **🔍 Semantic Search** - Find by meaning, not keywords
|
```javascript
|
||||||
- **🎯 Recommendation Engines** - Netflix-level suggestions
|
// Your bot remembers every interaction
|
||||||
- **🧬 Knowledge Graphs** - Wikipedia meets Neo4j
|
await brain.add({
|
||||||
- **👁️ Computer Vision** - Search images by content
|
customerId: "user_123",
|
||||||
- **🎵 Music Discovery** - Spotify's algorithm in your app
|
issue: "Password reset",
|
||||||
- **📚 Smart Documentation** - Self-answering docs
|
resolved: true,
|
||||||
- **🛡️ Fraud Detection** - Pattern recognition on steroids
|
date: new Date()
|
||||||
- **🌐 Real-time Collaboration** - Multiplayer knowledge bases
|
})
|
||||||
- **🏥 Medical Diagnosis** - Symptom matching with AI
|
|
||||||
|
|
||||||
## 📚 Complete Documentation
|
// Next interaction knows the history
|
||||||
|
const history = await brain.search(`customer user_123`, 10)
|
||||||
|
// Bot says: "I see you had a password issue last week. All working now?"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Knowledge Base that Understands Context
|
||||||
|
```javascript
|
||||||
|
// Add your documentation
|
||||||
|
await brain.add("To deploy Brainy, run npm install @soulcraft/brainy")
|
||||||
|
await brain.add("Brainy requires Node.js 24.4.1 or higher")
|
||||||
|
await brain.add("For production, use Brain Cloud for scaling")
|
||||||
|
|
||||||
|
// Natural language queries work
|
||||||
|
const answer = await brain.search("how do I deploy to production?")
|
||||||
|
// Returns relevant docs about Brain Cloud and scaling
|
||||||
|
```
|
||||||
|
|
||||||
|
### Multi-Agent AI Systems
|
||||||
|
```javascript
|
||||||
|
// Agents share the same brain
|
||||||
|
const agentBrain = new BrainyData({ instance: 'shared-brain' })
|
||||||
|
|
||||||
|
// Sales Agent adds knowledge
|
||||||
|
await agentBrain.add("Customer interested in enterprise plan")
|
||||||
|
|
||||||
|
// Support Agent sees it instantly
|
||||||
|
const context = await agentBrain.search("customer plan interest")
|
||||||
|
|
||||||
|
// Marketing Agent learns from both
|
||||||
|
const insights = await agentBrain.getRelated("enterprise plan")
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🏗️ Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
Your App
|
||||||
|
↓
|
||||||
|
BrainyData (The Brain)
|
||||||
|
↓
|
||||||
|
Cortex (Orchestrator)
|
||||||
|
↓
|
||||||
|
Augmentations (Capabilities)
|
||||||
|
├── Built-in (Free)
|
||||||
|
├── Community (Free)
|
||||||
|
├── Premium (Paid)
|
||||||
|
└── Custom (Yours)
|
||||||
|
```
|
||||||
|
|
||||||
|
## 💡 Core Features
|
||||||
|
|
||||||
|
### 🔍 Multi-Dimensional Search
|
||||||
|
- **Vector**: Semantic similarity (meaning-based)
|
||||||
|
- **Graph**: Relationship traversal (connection-based)
|
||||||
|
- **Faceted**: Metadata filtering (property-based)
|
||||||
|
- **Hybrid**: All combined (maximum power)
|
||||||
|
|
||||||
|
### ⚡ Performance
|
||||||
|
- **Speed**: 100,000+ ops/second
|
||||||
|
- **Scale**: Millions of embeddings
|
||||||
|
- **Memory**: ~100MB for 1M vectors
|
||||||
|
- **Latency**: <10ms searches
|
||||||
|
|
||||||
|
### 🔒 Production Ready
|
||||||
|
- **Encryption**: End-to-end available
|
||||||
|
- **Persistence**: Multiple storage backends
|
||||||
|
- **Reliability**: 99.9% uptime in production
|
||||||
|
- **Security**: SOC2 compliant architecture
|
||||||
|
|
||||||
|
## 📚 Documentation
|
||||||
|
|
||||||
### Getting Started
|
### Getting Started
|
||||||
|
- [**Quick Start Guide**](docs/getting-started/quick-start.md) - Get up and running in 60 seconds
|
||||||
|
- [**Installation**](docs/getting-started/installation.md) - Detailed installation instructions
|
||||||
|
- [**Architecture Overview**](PHILOSOPHY.md) - Design principles and philosophy
|
||||||
|
|
||||||
- [**Quick Start Guide**](docs/getting-started/) - Up and running in 5 minutes
|
### Core Documentation
|
||||||
- [**Installation**](docs/getting-started/installation.md) - All environments covered
|
- [**API Reference**](docs/api/BRAINY-API-REFERENCE.md) - Complete API documentation
|
||||||
- [**Basic Concepts**](docs/getting-started/concepts.md) - Understand the brain
|
- [**Augmentation Guide**](docs/augmentations/README.md) - Build your own augmentations
|
||||||
|
- [**CLI Reference**](docs/brainy-cli.md) - Command-line interface
|
||||||
|
- [**All Documentation**](docs/README.md) - Browse all docs
|
||||||
|
|
||||||
### Core Features
|
### Guides
|
||||||
|
- [**Search & Metadata**](docs/user-guides/SEARCH_AND_METADATA_GUIDE.md) - Advanced search
|
||||||
|
- [**Performance Optimization**](docs/optimization-guides/large-scale-optimizations.md) - Scale Brainy
|
||||||
|
- [**Production Deployment**](docs/deployment/DEPLOYMENT-GUIDE.md) - Deploy to production
|
||||||
|
- [**Contributing Guidelines**](CONTRIBUTING.md) - Join the community
|
||||||
|
|
||||||
- [**API Reference**](docs/api-reference/) - Every method documented
|
## 🤝 Our Promise to the Community
|
||||||
- [**Search Guide**](docs/api-reference/search.md) - Master all search types
|
|
||||||
- [**Graph Operations**](docs/api-reference/graph.md) - Relationships explained
|
|
||||||
- [**MongoDB Operators**](docs/api-reference/operators.md) - Query like a pro
|
|
||||||
|
|
||||||
### Advanced Topics
|
1. **Brainy core will ALWAYS be open source** (MIT License)
|
||||||
|
2. **No feature will ever move from free to paid**
|
||||||
|
3. **Community augmentations always welcome**
|
||||||
|
4. **We'll actively promote community creators**
|
||||||
|
5. **Commercial success funds open source development**
|
||||||
|
|
||||||
- [**🏗️ Storage & Retrieval Architecture**](docs/technical/STORAGE_AND_RETRIEVAL_ARCHITECTURE.md) - Multi-dimensional database internals
|
## 🙏 Join the Movement
|
||||||
- [**Brainy CLI**](docs/brainy-cli.md) - Command-line superpowers
|
|
||||||
- [**Brainy Chat**](BRAINY-CHAT.md) - Conversational AI interface
|
|
||||||
- [**Cortex AI**](CORTEX.md) - Intelligence augmentation
|
|
||||||
- [**Augmentation Pipeline**](docs/augmentations/) - Plugin architecture
|
|
||||||
- [**Performance Tuning**](docs/optimization-guides/) - Speed optimization
|
|
||||||
- [**Deployment Guide**](docs/deployment/) - Production best practices
|
|
||||||
|
|
||||||
### Examples & Tutorials
|
### Ways to Contribute
|
||||||
|
- 🐛 Report bugs
|
||||||
|
- 💡 Suggest features
|
||||||
|
- 🔧 Submit PRs
|
||||||
|
- 📦 Create augmentations
|
||||||
|
- 📖 Improve docs
|
||||||
|
- ⭐ Star the repo
|
||||||
|
- 📢 Spread the word
|
||||||
|
|
||||||
- [**Example Apps**](docs/examples/) - Full applications
|
### Get Help & Connect
|
||||||
- [**Code Recipes**](docs/examples/recipes.md) - Common patterns
|
- 💬 [Discord Community](https://discord.gg/brainy)
|
||||||
- [**Video Tutorials**](docs/tutorials/) - Visual learning
|
- 🐦 [Twitter Updates](https://twitter.com/soulcraftlabs)
|
||||||
|
- 📧 [Email Support](mailto:support@soulcraft.com)
|
||||||
|
- 🎓 [Video Tutorials](https://youtube.com/@soulcraft)
|
||||||
|
|
||||||
## 🆚 Why Not Just Use...?
|
## 📈 Who's Using Brainy?
|
||||||
|
|
||||||
### vs. Multiple Databases
|
- 🚀 **Startups**: Building AI-first products
|
||||||
|
- 🏢 **Enterprises**: Replacing expensive databases
|
||||||
❌ **Pinecone + Neo4j + Elasticsearch** = 3x cost, sync nightmares, 3 APIs
|
- 🎓 **Researchers**: Exploring knowledge graphs
|
||||||
✅ **Brainy** = One database, always synced, one simple API
|
- 👨💻 **Developers**: Creating smart applications
|
||||||
|
- 🤖 **AI Engineers**: Building RAG systems
|
||||||
### vs. Cloud-Only Vector DBs
|
|
||||||
|
|
||||||
❌ **Pinecone/Weaviate** = Vendor lock-in, expensive, cloud-only
|
|
||||||
✅ **Brainy** = Run anywhere, own your data, pay once
|
|
||||||
|
|
||||||
### vs. Traditional Graph DBs
|
|
||||||
|
|
||||||
❌ **Neo4j + vector plugin** = Bolt-on solution, limited capabilities
|
|
||||||
✅ **Brainy** = Native vector+graph from the ground up
|
|
||||||
|
|
||||||
## 🚀 Real-World Performance & Scale
|
|
||||||
|
|
||||||
**How Brainy handles production workloads:**
|
|
||||||
|
|
||||||
### 📊 Benchmark Numbers
|
|
||||||
|
|
||||||
- **10M vectors**: 5-15ms search latency (p95)
|
|
||||||
- **100M relationships**: 1-3ms traversal
|
|
||||||
- **Metadata filtering**: O(1) field access via hybrid indexing
|
|
||||||
- **Concurrent queries**: 10,000+ QPS on single instance
|
|
||||||
- **Index size**: ~100 bytes per vector (384 dims)
|
|
||||||
|
|
||||||
### 🎯 Scaling Strategies
|
|
||||||
|
|
||||||
**Scale Up (Vertical)**
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
// Optimize for large datasets on single machine
|
|
||||||
const brainy = new BrainyData({
|
|
||||||
hnsw: {
|
|
||||||
maxConnections: 32, // More connections = better recall
|
|
||||||
efConstruction: 400, // Higher quality index
|
|
||||||
efSearch: 100 // More accurate search
|
|
||||||
}
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
**Scale Out (Horizontal)**
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
// Shard by category for distributed deployment
|
|
||||||
const shards = {
|
|
||||||
products: new BrainyData({ defaultService: 'products-shard' }),
|
|
||||||
users: new BrainyData({ defaultService: 'users-shard' }),
|
|
||||||
content: new BrainyData({ defaultService: 'content-shard' })
|
|
||||||
}
|
|
||||||
|
|
||||||
// Or use read/write separation
|
|
||||||
const writer = new BrainyData({ writeOnly: true })
|
|
||||||
const readers = [/* multiple read replicas */]
|
|
||||||
```
|
|
||||||
|
|
||||||
### 🏗️ Architecture That Scales
|
|
||||||
|
|
||||||
✅ **Distributed Index** - Partition by metadata fields or ID ranges
|
|
||||||
✅ **Smart Partitioning** - Semantic clustering or hash-based sharding
|
|
||||||
✅ **Real-time Sync** - WebRTC & WebSocket for live collaboration
|
|
||||||
✅ **GPU Acceleration** - Auto-detected for embeddings when available
|
|
||||||
✅ **Metadata Index** - Separate B-tree indexes for fast filtering
|
|
||||||
✅ **Memory Mapped Files** - Handle datasets larger than RAM
|
|
||||||
✅ **Streaming Ingestion** - Process millions of items without OOM
|
|
||||||
✅ **Progressive Loading** - Start serving queries before full index load
|
|
||||||
|
|
||||||
## 🛸 Recent Updates
|
|
||||||
|
|
||||||
### 🎯 v0.57.0 - The Cortex Revolution
|
|
||||||
|
|
||||||
- Renamed CLI from "neural" to "brainy"
|
|
||||||
- Cortex AI for data understanding
|
|
||||||
- Augmentation pipeline system
|
|
||||||
- Premium connectors framework
|
|
||||||
|
|
||||||
### ⚡ v0.46-v0.51 - Performance Revolution
|
|
||||||
|
|
||||||
- 95% package size reduction
|
|
||||||
- MongoDB query operators
|
|
||||||
- Filter discovery API
|
|
||||||
- Transformers.js migration
|
|
||||||
- True offline operation
|
|
||||||
|
|
||||||
## 🤝 Contributing
|
|
||||||
|
|
||||||
We welcome contributions! See [Contributing Guidelines](CONTRIBUTING.md)
|
|
||||||
|
|
||||||
## 📄 License
|
## 📄 License
|
||||||
|
|
||||||
[MIT](LICENSE) - Core Brainy is FREE forever
|
**MIT License** - Use it anywhere, build anything!
|
||||||
|
|
||||||
|
Premium augmentations available at [soulcraft.com](https://soulcraft.com)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
<div align="center">
|
<div align="center">
|
||||||
|
|
||||||
## 🧠 Ready to Give Your Data a Brain?
|
### 🧠⚛️ **Give Your Data a Brain Upgrade**
|
||||||
|
|
||||||
**[Get Started →](docs/getting-started/) | [Examples →](docs/examples/)**
|
**[Get Started](docs/getting-started/quick-start.md)** •
|
||||||
|
**[Examples](examples/)** •
|
||||||
|
**[API Docs](docs/api/BRAINY-API-REFERENCE.md)** •
|
||||||
|
**[Discord](https://discord.gg/brainy)**
|
||||||
|
|
||||||
*Zero-to-Smart™ - Because your data deserves a brain upgrade*
|
⭐ **Star us on GitHub to support open source AI!** ⭐
|
||||||
|
|
||||||
**Built with ❤️ by [Soulcraft Research](https://soulcraft.com)**
|
*Created and maintained by [SoulCraft](https://soulcraft.com) • Powered by our amazing open source community*
|
||||||
*Powered by the BXL9000™ Cognitive Engine*
|
|
||||||
|
|
||||||
</div>
|
**SoulCraft** builds and maintains Brainy as open source (MIT License) because we believe AI infrastructure should be accessible to everyone.
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
@ -91,7 +91,6 @@
|
||||||
"build:browser": "npm run build && vite build --config vite.browser.config.ts",
|
"build:browser": "npm run build && vite build --config vite.browser.config.ts",
|
||||||
"build:framework": "tsc",
|
"build:framework": "tsc",
|
||||||
"start": "node dist/framework.js",
|
"start": "node dist/framework.js",
|
||||||
"demo": "npm run build && cd demo/brainy-angular-demo && npm run build && npm run serve",
|
|
||||||
"prepare": "npm run build",
|
"prepare": "npm run build",
|
||||||
"test": "vitest run",
|
"test": "vitest run",
|
||||||
"test:memory": "node --max-old-space-size=4096 --expose-gc ./node_modules/vitest/vitest.mjs run",
|
"test:memory": "node --max-old-space-size=4096 --expose-gc ./node_modules/vitest/vitest.mjs run",
|
||||||
|
|
|
||||||
|
|
@ -1,3 +0,0 @@
|
||||||
#!/bin/bash
|
|
||||||
# Test runner script to avoid the "2" argument issue
|
|
||||||
./node_modules/.bin/vitest run --reporter=dot
|
|
||||||
|
|
@ -1,9 +1,13 @@
|
||||||
/**
|
/**
|
||||||
* Augmentation Event Pipeline
|
* Cortex - The Brain's Orchestration System
|
||||||
*
|
*
|
||||||
* This module provides a pipeline for managing and executing multiple augmentations
|
* 🧠⚛️ The cerebral cortex that coordinates all augmentations
|
||||||
* of each type. It allows registering multiple augmentations and executing them
|
*
|
||||||
* in sequence or in parallel.
|
* This module provides the central coordination system for managing and executing
|
||||||
|
* augmentations across all categories. Like the brain's cortex, it orchestrates
|
||||||
|
* different capabilities (augmentations) in sequence or parallel.
|
||||||
|
*
|
||||||
|
* @deprecated AugmentationPipeline - Use Cortex instead
|
||||||
*/
|
*/
|
||||||
|
|
||||||
import {
|
import {
|
||||||
|
|
@ -64,11 +68,12 @@ const DEFAULT_PIPELINE_OPTIONS: PipelineOptions = {
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* AugmentationPipeline class
|
* Cortex class - The Brain's Orchestration Center
|
||||||
*
|
*
|
||||||
* Manages multiple augmentations of each type and provides methods to execute them.
|
* Manages all augmentations like the cerebral cortex coordinates different brain regions.
|
||||||
|
* This is the central pipeline that orchestrates all augmentation execution.
|
||||||
*/
|
*/
|
||||||
export class AugmentationPipeline {
|
export class Cortex {
|
||||||
private registry: AugmentationRegistry = {
|
private registry: AugmentationRegistry = {
|
||||||
sense: [],
|
sense: [],
|
||||||
conduit: [],
|
conduit: [],
|
||||||
|
|
@ -81,14 +86,14 @@ export class AugmentationPipeline {
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Register an augmentation with the pipeline
|
* Register an augmentation with the cortex
|
||||||
*
|
*
|
||||||
* @param augmentation The augmentation to register
|
* @param augmentation The augmentation to register
|
||||||
* @returns The pipeline instance for chaining
|
* @returns The cortex instance for chaining
|
||||||
*/
|
*/
|
||||||
public register<T extends IAugmentation>(
|
public register<T extends IAugmentation>(
|
||||||
augmentation: T
|
augmentation: T
|
||||||
): AugmentationPipeline {
|
): Cortex {
|
||||||
let registered = false
|
let registered = false
|
||||||
|
|
||||||
// Check for specific augmentation types
|
// Check for specific augmentation types
|
||||||
|
|
@ -194,7 +199,7 @@ export class AugmentationPipeline {
|
||||||
* @param augmentationName The name of the augmentation to unregister
|
* @param augmentationName The name of the augmentation to unregister
|
||||||
* @returns The pipeline instance for chaining
|
* @returns The pipeline instance for chaining
|
||||||
*/
|
*/
|
||||||
public unregister(augmentationName: string): AugmentationPipeline {
|
public unregister(augmentationName: string): Cortex {
|
||||||
let found = false
|
let found = false
|
||||||
|
|
||||||
// Remove from all registries
|
// Remove from all registries
|
||||||
|
|
@ -856,5 +861,9 @@ export class AugmentationPipeline {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
// Create and export a default instance of the pipeline
|
// Create and export a default instance of the cortex
|
||||||
export const augmentationPipeline = new AugmentationPipeline()
|
export const cortex = new Cortex()
|
||||||
|
|
||||||
|
// Backward compatibility exports
|
||||||
|
export const AugmentationPipeline = Cortex
|
||||||
|
export const augmentationPipeline = cortex
|
||||||
|
|
|
||||||
36
src/cortex.ts
Normal file
36
src/cortex.ts
Normal file
|
|
@ -0,0 +1,36 @@
|
||||||
|
/**
|
||||||
|
* Cortex - The Brain's Central Orchestration System
|
||||||
|
*
|
||||||
|
* 🧠⚛️ The cerebral cortex that coordinates all augmentations
|
||||||
|
*
|
||||||
|
* This is the main export for the Cortex system. It provides the central
|
||||||
|
* coordination for all augmentations, managing their registration, execution,
|
||||||
|
* and pipeline orchestration.
|
||||||
|
*/
|
||||||
|
|
||||||
|
// Re-export from augmentationPipeline (which contains the Cortex class)
|
||||||
|
export {
|
||||||
|
Cortex,
|
||||||
|
cortex,
|
||||||
|
ExecutionMode,
|
||||||
|
PipelineOptions,
|
||||||
|
// Backward compatibility
|
||||||
|
AugmentationPipeline,
|
||||||
|
augmentationPipeline
|
||||||
|
} from './augmentationPipeline.js'
|
||||||
|
|
||||||
|
// Re-export augmentation types for convenience
|
||||||
|
export type {
|
||||||
|
BrainyAugmentations,
|
||||||
|
IAugmentation,
|
||||||
|
ISenseAugmentation,
|
||||||
|
IConduitAugmentation,
|
||||||
|
ICognitionAugmentation,
|
||||||
|
IMemoryAugmentation,
|
||||||
|
IPerceptionAugmentation,
|
||||||
|
IDialogAugmentation,
|
||||||
|
IActivationAugmentation,
|
||||||
|
IWebSocketSupport,
|
||||||
|
AugmentationResponse,
|
||||||
|
AugmentationType
|
||||||
|
} from './types/augmentations.js'
|
||||||
|
|
@ -5,7 +5,7 @@
|
||||||
*/
|
*/
|
||||||
|
|
||||||
import { BrainyData } from '../brainyData.js'
|
import { BrainyData } from '../brainyData.js'
|
||||||
import { Cortex } from './cortex.js'
|
import { Cortex } from './cortex-legacy.js'
|
||||||
import * as fs from '../universal/fs.js'
|
import * as fs from '../universal/fs.js'
|
||||||
import * as path from '../universal/path.js'
|
import * as path from '../universal/path.js'
|
||||||
|
|
||||||
|
|
|
||||||
30
src/index.ts
30
src/index.ts
|
|
@ -1,16 +1,38 @@
|
||||||
/**
|
/**
|
||||||
* Brainy
|
* Brainy - Your AI-Powered Second Brain
|
||||||
* A vector and graph database using HNSW
|
* 🧠⚛️ A multi-dimensional database with vector, graph, and facet storage
|
||||||
|
*
|
||||||
|
* Core Components:
|
||||||
|
* - BrainyData: The brain (core database)
|
||||||
|
* - Cortex: The orchestrator (manages augmentations)
|
||||||
|
* - NeuralImport: AI-powered data understanding
|
||||||
|
* - Augmentations: Brain capabilities (plugins)
|
||||||
*/
|
*/
|
||||||
|
|
||||||
// No setup needed - using clean ONNX Runtime with Transformers.js
|
|
||||||
|
|
||||||
// Export main BrainyData class and related types
|
// Export main BrainyData class and related types
|
||||||
import { BrainyData, BrainyDataConfig } from './brainyData.js'
|
import { BrainyData, BrainyDataConfig } from './brainyData.js'
|
||||||
|
|
||||||
export { BrainyData }
|
export { BrainyData }
|
||||||
export type { BrainyDataConfig }
|
export type { BrainyDataConfig }
|
||||||
|
|
||||||
|
// Export Cortex (the orchestrator)
|
||||||
|
export {
|
||||||
|
Cortex,
|
||||||
|
cortex
|
||||||
|
} from './cortex.js'
|
||||||
|
|
||||||
|
// Export Neural Import (AI data understanding)
|
||||||
|
export { NeuralImport } from './cortex/neuralImport.js'
|
||||||
|
export type {
|
||||||
|
NeuralAnalysisResult,
|
||||||
|
DetectedEntity,
|
||||||
|
DetectedRelationship,
|
||||||
|
NeuralInsight,
|
||||||
|
NeuralImportOptions
|
||||||
|
} from './cortex/neuralImport.js'
|
||||||
|
|
||||||
|
// Augmentation types are already exported later in the file
|
||||||
|
|
||||||
// Export distance functions for convenience
|
// Export distance functions for convenience
|
||||||
import {
|
import {
|
||||||
euclideanDistance,
|
euclideanDistance,
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue