David Snelling 0bf88e2518 Update documentation and CLI with Brain Cloud service clarifications

- Updated BRAINY_VS_BRAIN_CLOUD.md with clearer service integration examples
- Improved documentation showing Brain Cloud is a service, not a package
- Enhanced CLI messaging for better user understanding

2025-08-12 09:03:36 -07:00

5.4 KiB

Raw Blame History

🧠 Brainy vs ☁️ Brain Cloud - Clear Separation

Core Philosophy

Brainy is FREE FOREVER. Brain Cloud is optional premium.

🧠 Brainy (100% Free Open Source)

What's Included (Everything You Need!)

✅ Full Vector Database

HNSW indexing
Semantic search
Metadata filtering
Graph relationships
Batch operations
All distance metrics

✅ Storage Options

FileSystem (Node.js)
IndexedDB (Browser)
S3 (with your AWS account)
Memory
Custom adapters

✅ All Core Features

Embeddings (local models)
Augmentation pipeline
Statistics & monitoring
Import/Export
CLI tools
Full API

Code Example - Brainy Core

// NO LICENSE NEEDED - JUST WORKS!
import { BrainyVectorDB } from '@brainy/vector-db'

const brain = new BrainyVectorDB()
await brain.add('Hello world', { category: 'greeting' })
const results = await brain.search('hi there')
// Full functionality, no limits, no license!

What You CAN'T Do (Without Brain Cloud)

❌ Sync across devices ❌ Team collaboration ❌ Managed cloud hosting ❌ Enterprise connectors (Notion, Salesforce) ❌ Multi-agent coordination ❌ Automatic backups to cloud

☁️ Brain Cloud (Optional Premium Service)

What It Is

A managed service that adds cloud capabilities to Brainy. Think of it like GitHub vs Git - Brainy is Git (free tool), Brain Cloud is GitHub (paid service).

Premium Features

🌟 Cloud Sync

Your brain in the cloud
Access from anywhere
Automatic backups

🌟 Team Features

Share knowledge bases
Real-time collaboration
Access controls

🌟 Enterprise Connectors

// These auto-load with Brain Cloud subscription after 'brainy cloud auth'
// No manual imports needed - managed service handles everything!

// Just use augmentations - they're automatically available
await brainy.connectNotion({
  // Your Notion credentials only - no Brain Cloud API keys needed
  notionToken: process.env.NOTION_TOKEN
})

🌟 AI Memory

Persistent across sessions
Multi-agent coordination
Context sharing

Code Example - Brain Cloud

// Everything is in one package
import { BrainyVectorDB } from '@soulcraft/brainy'        // Free core
// Cloud features are in same package, activated by API key

const brain = new BrainyVectorDB()  // Works without cloud!

// Optional: Add cloud sync
const cloud = new CloudSync({
  apiKey: process.env.BRAIN_CLOUD_KEY  // Only if you want cloud
})
brain.enableCloud(cloud)  // Optional enhancement

File Organization

Core Brainy (This Repo)

brainy/
├── src/
│   ├── brainyData.ts        # Core (FREE)
│   ├── hnsw/                # Core (FREE)
│   ├── storage/             # Core (FREE)
│   ├── augmentations/       # Core (FREE)
│   └── cli/
│       ├── basic.ts         # Core commands (FREE)
│       └── cloud.ts         # Cloud commands (points to Brain Cloud)

Brain Cloud (Service, not a package)

Brain Cloud is a managed service that auto-loads augmentations
based on your subscription when you run `brainy cloud auth`.
No manual package installation required!

CLI Commands

Free Commands (Core Brainy)

brainy init                  # Setup local database
brainy add <text>            # Add data
brainy search <query>        # Search
brainy export                # Export data
brainy import                # Import data
brainy stats                 # View statistics

Premium Commands (Brain Cloud)

brainy cloud setup           # Setup cloud sync (requires key)
brainy cloud sync            # Sync with cloud
brainy cloud connect notion  # Connect Notion (premium)

Configuration

Brainy Core (No Config Needed!)

// Just works - no environment variables, no config files
const brain = new BrainyVectorDB()

Brain Cloud (Optional Config)

// Only if using Brain Cloud features
const cloud = new CloudSync({
  apiKey: 'bc_xxxxx',  // Get from soulcraft.com
  region: 'us-east-1'
})

Documentation Structure

README.md Structure

# Brainy - Free Vector Database

## Quick Start (Free, No Setup)
[Simple examples that just work]

## Core Features (All Free)
[Everything included in open source]

## Brain Cloud (Optional Premium)
[Clearly marked as optional add-on]

Migration Rules

✅ DO

Keep Brainy 100% functional without any keys
Put Brain Cloud features in separate package
Clearly mark premium features as optional
Use "Brain Cloud" not "premium" or "paid"

❌ DON'T

Check for license in core Brainy
Require environment variables for basic use
Mix cloud features with core documentation
Make it seem like license is needed

User Journey

New User (Free)

npm install @brainy/vector-db
Start coding immediately
Full functionality
Discovers Brain Cloud later (if needed)

Enterprise User (Paid)

Uses Brainy locally first
Decides they need cloud sync
Signs up for Brain Cloud at app.soulcraft.com
brainy cloud auth (auto-configures everything!)
Augmentations automatically available - no code changes needed

Summary

Brainy = SQLite (Free database) Brain Cloud = Supabase (Managed service)

Keep them separate. Brainy should work perfectly without Brain Cloud. Brain Cloud should enhance, not gate, functionality.

5.4 KiB Raw Blame History