@soulcraft/brainy 0.54.7 → 0.56.0

package/README.md

@@ -1,49 +1,27 @@
+# 🧠⚛️ Brainy - Lightning-Fast Vector + Graph Database with AI Intelligence
+
 <div align="center">
-<img src="./brainy.png" alt="Brainy Logo" width="200"/>
-<br/><br/>
 
-[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+![Brainy Logo](brainy.png)
+
+[![npm version](https://badge.fury.io/js/%40soulcraft%2Fbrainy.svg)](https://badge.fury.io/js/%40soulcraft%2Fbrainy)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D24.4.1-brightgreen.svg)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.4.5-blue.svg)](https://www.typescriptlang.org/)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 
-**The world's only true Vector + Graph database - unified semantic search and knowledge graphs**
+**The world's only true Vector + Graph database with built-in AI intelligence**  
+**Sub-millisecond queries across millions of vectors + billions of relationships**
 
 </div>
 
----
+## The Problem: Three Databases for One Search
 
-# The Search Problem Every Developer Faces
+**"I need semantic search, relationship traversal, AND metadata filtering - that means 3+ databases"**
 
-**"I need to find similar content, explore relationships, AND filter by metadata - but that means juggling 3+ databases"**
+❌ **Current Reality**: Pinecone + Neo4j + Elasticsearch + Custom Sync = Slow, expensive, complex  
+✅ **Brainy Reality**: One blazing-fast database. One API. Everything in sync.
 
-❌ **Current Reality**: Pinecone + Neo4j + Elasticsearch + Custom Sync Logic  
-✅ **Brainy Reality**: One database. One API. All three search types.
-
-## 🔥 The Power of Three-in-One Search
-
-```javascript
-// This ONE query does what used to require 3 databases:
-const results = await brainy.search("AI startups in healthcare", 10, {
-  // 🔍 Vector: Semantic similarity 
-  includeVerbs: true,
-  
-  // 🔗 Graph: Relationship traversal
-  verbTypes: ["invests_in", "partners_with"],
-  
-  // 📊 Faceted: MongoDB-style filtering  
-  metadata: {
-    industry: "healthcare",
-    funding: { $gte: 1000000 },
-    stage: { $in: ["Series A", "Series B"] }
-  }
-})
-// Returns: Companies similar to your query + their relationships + matching your criteria
-```
-
-**Three search paradigms. One lightning-fast query. Zero complexity.**
-
-## 🚀 Install & Go
+## 🚀 Quick Start: 8 Lines to Production
 
 ```bash
 npm install @soulcraft/brainy
@@ -52,550 +30,229 @@ npm install @soulcraft/brainy
 ```javascript
 import { BrainyData } from '@soulcraft/brainy'
 
-const brainy = new BrainyData()  // Auto-detects your environment
-await brainy.init()              // Auto-configures everything
+const brainy = new BrainyData()  // Auto-detects environment
+await brainy.init()              // Zero configuration
 
 // Add data 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")
 
-// Search across all dimensions
+// One query, three search paradigms
 const results = await brainy.search("AI language models", 5, {
-  metadata: { funding: { $gte: 10000000 } },
-  includeVerbs: true
-})
+  metadata: { funding: { $gte: 10000000 } },  // MongoDB-style filtering
+  includeVerbs: true                           // Graph relationships
+})  // Semantic vector search
 ```
 
-**That's it. You just built a knowledge graph with semantic search and faceted filtering in 8 lines.**
-
-## ⚙️ Configuration Options
+**That's it. You just built a knowledge graph with semantic search in 8 lines.**
 
-Brainy works great with **zero configuration**, but you can customize it for your specific needs:
+## 🎯 Key Features: Why Developers Choose Brainy
 
-### 🚀 Quick Start (Recommended)
-```javascript
-const brainy = new BrainyData()  // Auto-detects everything
-await brainy.init()              // Zero config needed
+### ⚡ Blazing Performance at Scale
 ```
-
-### 🎯 Specialized Configurations
-
-#### Writer Service with Deduplication
-Perfect for high-throughput data ingestion with smart caching:
-```javascript
-const brainy = new BrainyData({
-  writeOnly: true,        // Skip search index loading
-  allowDirectReads: true  // Enable ID-based lookups for deduplication
-})
-// ✅ Can: add(), get(), has(), exists(), getMetadata(), getBatch()
-// ❌ Cannot: search(), similar(), query() (saves memory & startup time)
+Vector Search (1M embeddings):     2-8ms p95 latency
+Graph Traversal (100M relations):  1-3ms p95 latency  
+Combined Vector+Graph+Filter:      5-15ms p95 latency
+Throughput:                        10K+ queries/second
 ```
 
-#### Pure Writer Service
-For maximum performance data ingestion only:
-```javascript
-const brainy = new BrainyData({
-  writeOnly: true,         // No search capabilities
-  allowDirectReads: false  // No read operations at all
-})
-// ✅ Can: add(), addBatch(), relate()
-// ❌ Cannot: Any read operations (fastest startup)
-```
+### 🌍 Write Once, Run Anywhere
+- **Same code** works in React, Vue, Angular, Node.js, Edge Workers
+- **Auto-detects** environment and optimizes automatically
+- **Zero config** - no setup files, no tuning parameters
 
-#### Read-Only Service
-For search-only applications with immutable data:
-```javascript
-const brainy = new BrainyData({
-  readOnly: true,    // Block all write operations
-  frozen: true       // Block statistics updates and optimizations
-})
-// ✅ Can: All search operations
-// ❌ Cannot: add(), update(), delete()
-```
+### 🧠 Built-in AI Intelligence (FREE)
+- **Neural Import**: AI understands your data structure automatically
+- **Entity Detection**: Identifies people, companies, locations
+- **Relationship Mapping**: Discovers connections between entities
+- **Chat Interface**: Talk to your data naturally (v0.56+)
 
-#### Custom Storage & Performance
-```javascript
-const brainy = new BrainyData({
-  // Storage options
-  storage: {
-    type: 's3',                    // 's3', 'memory', 'filesystem'
-    requestPersistentStorage: true, // Browser: request persistent storage
-    s3Storage: {
-      bucketName: 'my-vectors',
-      region: 'us-east-1'
-    }
-  },
-  
-  // Performance tuning
-  hnsw: {
-    maxConnections: 16,      // Higher = better search quality
-    efConstruction: 200,     // Higher = better index quality
-    useOptimized: true       // Enable disk-based storage
-  },
-  
-  // Embedding customization
-  embeddingFunction: myCustomEmbedder,
-  distanceFunction: 'euclidean'  // 'cosine', 'euclidean', 'manhattan'
-})
-```
+---
 
-#### Distributed Services
-```javascript
-// Microservice A (Writer)
-const writerService = new BrainyData({
-  writeOnly: true,
-  allowDirectReads: true,  // For deduplication
-  defaultService: 'data-ingestion'
-})
+# 🎆 NEW: Talk to Your Data with Brainy Chat!
 
-// Microservice B (Reader) 
-const readerService = new BrainyData({
-  readOnly: true,
-  defaultService: 'search-api'
-})
+```javascript
+import { BrainyChat } from '@soulcraft/brainy'
 
-// Full-featured service
-const hybridService = new BrainyData({
-  writeOnly: false,  // Can read and write
-  defaultService: 'full-stack-app'
-})
+const chat = new BrainyChat(brainy)  // That's it!
+const answer = await chat.ask("What patterns do you see in customer behavior?")
+// → Works instantly with zero config!
 ```
 
-### 🔧 All Configuration Options
+**One line. Zero complexity. Optional LLM for smarter responses.**  
+[📖 **Learn More About Brainy Chat**](BRAINY-CHAT.md)
 
-<details>
-<summary>Click to see complete configuration reference</summary>
+## 🔥 The Power of Three-in-One Search
 
 ```javascript
-const brainy = new BrainyData({
-  // === Operation Modes ===
-  writeOnly?: boolean              // Disable search operations, enable fast ingestion
-  allowDirectReads?: boolean       // Enable ID lookups in writeOnly mode
-  readOnly?: boolean              // Disable write operations
-  frozen?: boolean                // Disable all optimizations and statistics
-  lazyLoadInReadOnlyMode?: boolean // Load index on-demand
-  
-  // === Storage Configuration ===
-  storage?: {
-    type?: 'auto' | 'memory' | 'filesystem' | 's3' | 'opfs'
-    requestPersistentStorage?: boolean  // Browser persistent storage
-    
-    // Cloud storage options
-    s3Storage?: {
-      bucketName: string
-      region?: string
-      accessKeyId?: string
-      secretAccessKey?: string
-    },
-    
-    r2Storage?: { /* Cloudflare R2 options */ },
-    gcsStorage?: { /* Google Cloud Storage options */ }
-  },
-  
-  // === Performance Tuning ===
-  hnsw?: {
-    maxConnections?: number        // Default: 16
-    efConstruction?: number        // Default: 200  
-    efSearch?: number             // Default: 50
-    useOptimized?: boolean        // Default: true
-    useDiskBasedIndex?: boolean   // Default: auto-detected
-  },
-  
-  // === Embedding & Distance ===
-  embeddingFunction?: EmbeddingFunction
-  distanceFunction?: 'cosine' | 'euclidean' | 'manhattan'
-  
-  // === Service Identity ===
-  defaultService?: string          // Default service name for operations
+// This ONE query does what used to require 3 databases:
+const results = await brainy.search("AI startups in healthcare", 10, {
+  // 🔍 Vector: Semantic similarity 
+  includeVerbs: true,
   
-  // === Advanced Options ===
-  logging?: {
-    verbose?: boolean             // Enable detailed logging
-  },
+  // 🔗 Graph: Relationship traversal
+  verbTypes: ["invests_in", "partners_with"],
   
-  timeouts?: {
-    embedding?: number            // Embedding timeout (ms)
-    search?: number              // Search timeout (ms)
+  // 📊 Faceted: MongoDB-style filtering  
+  metadata: {
+    industry: "healthcare",
+    funding: { $gte: 1000000 },
+    stage: { $in: ["Series A", "Series B"] }
   }
 })
+// Returns: Companies similar to your query + their relationships + matching your criteria
 ```
 
-</details>
-
-## 🔥 MAJOR UPDATES: What's New in v0.51, v0.49 & v0.48
-
-### 🎯 **v0.51: Revolutionary Developer Experience** 
-
-**Problem-focused approach that gets you productive in seconds!**
+## 🌍 Works Everywhere - Same Code
 
-- ✅ **Problem-Solution Narrative** - Immediately understand why Brainy exists
-- ✅ **8-Line Quickstart** - Three search types in one simple demo  
-- ✅ **Streamlined Documentation** - Focus on what matters most
-- ✅ **Clear Positioning** - The only true Vector + Graph database
+**Write once, run anywhere.** Brainy auto-detects your environment:
 
-### 🎯 **v0.49: Filter Discovery & Performance Improvements**
+| Environment | Storage | Optimization |
+|-------------|---------|-------------|
+| 🌐 Browser | OPFS | Web Workers, Memory Cache |
+| 🟢 Node.js | FileSystem / S3 | Worker Threads, Clustering |
+| ⚡ Serverless | S3 / Memory | Cold Start Optimization |
+| 🔥 Edge | Memory / KV | Minimal Footprint |
 
-**Discover available filters and scale to millions of items!**
+<details>
+<summary>🔧 <strong>Advanced Configuration Options</strong></summary>
 
 ```javascript
-// Discover what filters are available - O(1) field lookup
-const categories = await brainy.getFilterValues('category')
-// Returns: ['electronics', 'books', 'clothing', ...]
-
-const fields = await brainy.getFilterFields()  // O(1) operation
-// Returns: ['category', 'price', 'brand', 'rating', ...]
-```
-
-- ✅ **Filter Discovery API**: O(1) field discovery for instant filter UI generation
-- ✅ **Improved Performance**: Removed deprecated methods, now uses pagination everywhere
-- ✅ **Better Scalability**: Hybrid indexing with O(1) field access scales to millions
-- ✅ **Smart Caching**: LRU cache for frequently accessed filters
-- ✅ **Zero Configuration**: Everything auto-optimizes based on usage patterns
-
-### 🚀 **v0.48: MongoDB-Style Metadata Filtering**
+// High-throughput writer
+const writer = new BrainyData({
+  writeOnly: true,
+  allowDirectReads: true  // For deduplication
+})
 
-**Powerful querying with familiar syntax - filter DURING search for maximum performance!**
+// Read-only search service
+const reader = new BrainyData({
+  readOnly: true,
+  frozen: true  // No stats updates
+})
 
-```javascript
-const results = await brainy.search("wireless headphones", 10, {
-  metadata: {
-    category: { $in: ["electronics", "audio"] },
-    price: { $lte: 200 },
-    rating: { $gte: 4.0 },
-    brand: { $ne: "Generic" }
+// Custom storage
+const custom = new BrainyData({
+  storage: {
+    type: 's3',
+    s3Storage: { bucketName: 'my-vectors' }
+  },
+  hnsw: {
+    maxConnections: 32  // Higher quality
   }
 })
 ```
 
-- ✅ **15+ MongoDB Operators**: `$gt`, `$in`, `$regex`, `$and`, `$or`, `$includes`, etc.
-- ✅ **Automatic Indexing**: Zero configuration, maximum performance
-- ✅ **Nested Fields**: Use dot notation for complex objects
-- ✅ **100% Backward Compatible**: Your existing code works unchanged
-
-### ⚡ **v0.46: Transformers.js Migration**
-
-**Replaced TensorFlow.js for better performance and true offline operation!**
+</details>
 
-- ✅ **95% Smaller Package**: 643 kB vs 12.5 MB
-- ✅ **84% Smaller Models**: 87 MB vs 525 MB models
-- ✅ **True Offline**: Zero network calls after initial download
-- ✅ **5x Fewer Dependencies**: Clean tree, no peer dependency issues
-- ✅ **Same API**: Drop-in replacement, existing code works unchanged
+## 🎮 Cortex CLI - Command Center for Everything
 
-### 🚀 Why Developers Love Brainy
+```bash
+# Talk to your data
+cortex chat "What patterns do you see?"
 
-- **🧠 Zero-to-Smart™** - No config files, no tuning parameters, no DevOps headaches. Brainy auto-detects your environment and optimizes itself
-- **🌍 True Write-Once, Run-Anywhere** - Same code runs in Angular, React, Vue, Node.js, Deno, Bun, serverless, edge workers, and web workers with automatic environment detection
-- **⚡ Scary Fast** - Handles millions of vectors with sub-millisecond search. GPU acceleration for embeddings, optimized CPU for distance calculations
-- **🎯 Self-Learning** - Like having a database that goes to the gym. Gets faster and smarter the more you use it
-- **🔮 AI-First Design** - Built for the age of embeddings, RAG, and semantic search. Your LLMs will thank you
-- **🎮 Actually Fun to Use** - Clean API, great DX, and it does the heavy lifting so you can build cool stuff
+# AI-powered data import
+cortex neural import data.csv --confidence 0.8
 
-### 🚀 NEW: Ultra-Fast Search Performance + Auto-Configuration
+# Real-time monitoring
+cortex monitor --dashboard
 
-**Your searches just got 100x faster AND Brainy now configures itself!** Advanced performance with zero setup:
+# Start premium trials
+cortex license trial notion
+```
 
-- **🤖 Intelligent Auto-Configuration** - Detects environment and usage patterns, optimizes automatically
-- **⚡ Smart Result Caching** - Repeated queries return in <1ms with automatic cache invalidation
-- **📄 Cursor-Based Pagination** - Navigate millions of results with constant O(k) performance
-- **🔄 Real-Time Data Sync** - Cache automatically updates when data changes, even in distributed scenarios
-- **📊 Performance Monitoring** - Built-in hit rate and memory usage tracking with adaptive optimization
-- **🎯 Zero Breaking Changes** - All existing code works unchanged, just faster and smarter
+[📖 **Full Cortex Documentation**](/docs/cortex.md)
 
-## 🏆 Why Brainy Wins
+## ⚙️ Configuration (Optional)
 
-- 🧠 **Triple Search Power** - Vector + Graph + Faceted filtering in one query
-- 🌍 **Runs Everywhere** - Same code: React, Node.js, serverless, edge  
-- ⚡ **Zero Config** - Auto-detects environment, optimizes itself
-- 🔄 **Always Synced** - No data consistency nightmares between systems
-- 📦 **Truly Offline** - Works without internet after initial setup
-- 🔒 **Your Data** - Run locally, in browser, or your own cloud
+Brainy works with **zero configuration**, but you can customize
 
-## 🔮 Coming Soon
 
-- **🤖 MCP Integration** - Let Claude, GPT, and other AI models query your data directly
-- **⚡ LLM Generation** - Built-in content generation powered by your knowledge graph  
-- **🌊 Real-time Sync** - Live updates across distributed instances
+## 🆚 Why Not Just Use...?
 
-## 🎨 Build Amazing Things
+### vs. Multiple Databases
+❌ **Pinecone + Neo4j + Elasticsearch** - 3 databases, sync nightmares, 3x the cost  
+✅ **Brainy** - One database, always synced, built-in intelligence
 
-**🤖 AI Chat Applications** - Build ChatGPT-like apps with long-term memory and context awareness  
-**🔍 Semantic Search Engines** - Search by meaning, not keywords. Find "that thing that's like a cat but bigger" → returns "tiger"  
-**🎯 Recommendation Engines** - "Users who liked this also liked..." but actually good  
-**🧬 Knowledge Graphs** - Connect everything to everything. Wikipedia meets Neo4j meets magic  
-**👁️ Computer Vision Apps** - Store and search image embeddings. "Find all photos with dogs wearing hats"  
-**🎵 Music Discovery** - Find songs that "feel" similar. Spotify's Discover Weekly in your app  
-**📚 Smart Documentation** - Docs that answer questions. "How do I deploy to production?" → relevant guides  
-**🛡️ Fraud Detection** - Find patterns humans can't see. Anomaly detection on steroids  
-**🌐 Real-Time Collaboration** - Sync vector data across devices. Figma for AI data  
-**🏥 Medical Diagnosis Tools** - Match symptoms to conditions using embedding similarity
+### vs. Cloud-Only Vector DBs
+❌ **Pinecone/Weaviate/Qdrant** - Vendor lock-in, expensive, cloud-only  
+✅ **Brainy** - Run anywhere, your data stays yours, cost-effective
 
-## 🌍 Works Everywhere - Same Code
+### vs. Graph DBs with "Vector Features"
+❌ **Neo4j + vector plugin** - Bolt-on solution, not native, limited  
+✅ **Brainy** - Native vector+graph architecture from the ground up
 
-**Write once, run anywhere.** Brainy auto-detects your environment and optimizes automatically:
+## 💎 Premium Features (Optional)
 
-### 🌐 Browser Frameworks (React, Angular, Vue)
+**Core Brainy is FREE forever. Premium features for enterprise needs:**
 
-```javascript
-import { BrainyData } from '@soulcraft/brainy'
+### 🔗 Enterprise Connectors (14-day trials)
+- **Notion** ($49/mo) - Bidirectional workspace sync
+- **Salesforce** ($99/mo) - CRM integration
+- **Slack** ($49/mo) - Team collaboration
+- **Asana** ($44/mo) - Project management
 
-// SAME CODE in React, Angular, Vue, Svelte, etc.
-const brainy = new BrainyData()
-await brainy.init()  // Auto-uses OPFS in browsers
+```bash
+cortex license trial notion  # Start free trial
+```
 
-// Add entities and relationships
-const john = await brainy.add("John is a software engineer", { type: "person" })
-const jane = await brainy.add("Jane is a data scientist", { type: "person" })
-const ai = await brainy.add("AI Project", { type: "project" })
+**No vendor lock-in. Your data stays yours.**
 
-await brainy.relate(john, ai, "works_on")
-await brainy.relate(jane, ai, "leads")
+## 🎨 What You Can Build
 
-// Search by meaning
-const engineers = await brainy.search("software developers", 5)
+- **🤖 AI Chat Applications** - ChatGPT-like apps with long-term memory
+- **🔍 Semantic Search** - Search by meaning, not keywords
+- **🎯 Recommendation Engines** - "Users who liked this also liked..." 
+- **🧬 Knowledge Graphs** - Connect everything to everything
+- **🛡️ Fraud Detection** - Find patterns humans can't see
+- **📚 Smart Documentation** - Docs that answer questions
 
-// Traverse relationships
-const team = await brainy.getVerbsByTarget(ai)  // Who works on AI Project?
-```
 
 <details>
-<summary>📦 <strong>Full React Component Example</strong></summary>
+<summary>📦 <strong>Framework Examples</strong></summary>
 
+### React
 ```jsx
 import { BrainyData } from '@soulcraft/brainy'
-import { useEffect, useState } from 'react'
-
-function Search() {
-  const [brainy, setBrainy] = useState(null)
-  const [results, setResults] = useState([])
-
-  useEffect(() => {
-    const init = async () => {
-      const db = new BrainyData()
-      await db.init()
-      // Add your data...
-      setBrainy(db)
-    }
-    init()
-  }, [])
 
+function App() {
+  const [brainy] = useState(() => new BrainyData())
+  useEffect(() => brainy.init(), [])
+  
   const search = async (query) => {
-    const results = await brainy?.search(query, 5) || []
-    setResults(results)
+    return await brainy.search(query, 10)
   }
-
-  return <input onChange={(e) => search(e.target.value)} placeholder="Search..." />
 }
 ```
 
-</details>
-
-<details>
-<summary>📦 <strong>Full Angular Component Example</strong></summary>
+### Vue 3
+```vue
+<script setup>
+  const brainy = new BrainyData()
+  await brainy.init()
+</script>
+```
 
+### Angular
 ```typescript
-import { Component, signal, OnInit } from '@angular/core'
-import { BrainyData } from '@soulcraft/brainy'
-
-@Component({
-  selector: 'app-search',
-  template: `<input (input)="search($event.target.value)" placeholder="Search...">`
-})
-export class SearchComponent implements OnInit {
+@Component({})
+export class AppComponent {
   brainy = new BrainyData()
-
   async ngOnInit() {
     await this.brainy.init()
-    // Add your data...
-  }
-
-  async search(query: string) {
-    const results = await this.brainy.search(query, 5)
-    // Display results...
   }
 }
 ```
 
-</details>
-
-<details>
-<summary>📦 <strong>Full Vue Example</strong></summary>
-
-```vue
-<script setup>
-  import { BrainyData } from '@soulcraft/brainy'
-  import { ref, onMounted } from 'vue'
-
-  const brainy = ref(null)
-  const results = ref([])
-
-  onMounted(async () => {
-    const db = new BrainyData()
-    await db.init()
-    // Add your data...
-    brainy.value = db
-  })
-
-  const search = async (query) => {
-    const results = await brainy.value?.search(query, 5) || []
-    setResults(results)
-  }
-</script>
-
-<template>
-  <input @input="search($event.target.value)" placeholder="Search..." />
-</template>
-```
-
-</details>
-
-### 🟢 Node.js / Serverless / Edge
-
+### Node.js
 ```javascript
-import { BrainyData } from '@soulcraft/brainy'
-
-// SAME CODE works in Node.js, Vercel, Netlify, Cloudflare Workers, Deno, Bun
 const brainy = new BrainyData()
-await brainy.init()  // Auto-detects environment and optimizes
-
-// Add entities and relationships
-await brainy.add("Python is great for data science", { type: "fact" })
-await brainy.add("JavaScript rules the web", { type: "fact" })
-
-// Search by meaning
-const results = await brainy.search("programming languages", 5)
-
-// Optional: Production with S3/R2 storage (auto-detected in cloud environments)
-const productionBrainy = new BrainyData({
-  storage: {
-    s3Storage: { bucketName: process.env.BUCKET_NAME }
-  }
-})
-```
-
-**That's it! Same code, everywhere. Zero-to-Smart™**
-
-Brainy automatically detects and optimizes for your environment:
-
-| Environment | Storage | Optimization |
-|-------------|---------|-------------|
-| 🌐 Browser | OPFS | Web Workers, Memory Cache |
-| 🟢 Node.js | FileSystem / S3 | Worker Threads, Clustering |
-| ⚡ Serverless | S3 / Memory | Cold Start Optimization |
-| 🔥 Edge | Memory / KV | Minimal Footprint |
-
-## 🌐 Distributed Mode (NEW!)
-
-**Scale horizontally with zero configuration!** Brainy now supports distributed deployments with automatic coordination:
-
-- **🌐 Multi-Instance Coordination** - Multiple readers and writers working in harmony
-- **🏷️ Smart Domain Detection** - Automatically categorizes data (medical, legal, product, etc.)
-- **📊 Real-Time Health Monitoring** - Track performance across all instances
-- **🔄 Automatic Role Optimization** - Readers optimize for cache, writers for throughput
-- **🗂️ Intelligent Partitioning** - Hash-based partitioning for perfect load distribution
-
-```javascript
-// Writer Instance - Ingests data from multiple sources
-const writer = new BrainyData({
-  storage: { s3Storage: { bucketName: 'my-bucket' } },
-  distributed: { role: 'writer' }  // Explicit role for safety
-})
-
-// Reader Instance - Optimized for search queries
-const reader = new BrainyData({
-  storage: { s3Storage: { bucketName: 'my-bucket' } },
-  distributed: { role: 'reader' }  // 80% memory for cache
-})
-
-// Data automatically gets domain tags
-await writer.add("Patient shows symptoms of...", {
-  diagnosis: "flu"  // Auto-tagged as 'medical' domain
-})
-
-// Domain-aware search across all partitions
-const results = await reader.search("medical symptoms", 10, {
-  filter: { domain: 'medical' }  // Only search medical data
-})
-
-// Monitor health across all instances
-const health = reader.getHealthStatus()
-console.log(`Instance ${health.instanceId}: ${health.status}`)
-```
-
-### 🐳 NEW: Zero-Config Docker Deployment
-
-**Deploy to any cloud with embedded models - no runtime downloads needed!**
-
-```dockerfile
-# One line extracts models automatically during build
-RUN npm run download-models
-
-# Deploy anywhere: Google Cloud, AWS, Azure, Cloudflare, etc.
-```
-
-- **⚡ 7x Faster Cold Starts** - Models embedded in container, no downloads
-- **🌐 Universal Cloud Support** - Same Dockerfile works everywhere  
-- **🔒 Offline Ready** - No external dependencies at runtime
-- **📦 Zero Configuration** - Automatic model detection and loading
-
-```javascript
-// Zero configuration - everything optimized automatically!
-const brainy = new BrainyData()  // Auto-detects environment & optimizes
 await brainy.init()
-
-// Caching happens automatically - no setup needed!
-const results1 = await brainy.search('query', 10)  // ~50ms first time
-const results2 = await brainy.search('query', 10)  // <1ms cached hit!
-
-// Advanced pagination works instantly
-const page1 = await brainy.searchWithCursor('query', 100)
-const page2 = await brainy.searchWithCursor('query', 100, {
-  cursor: page1.cursor  // Constant time, no matter how deep!
-})
-
-// Monitor auto-optimized performance
-const stats = brainy.getCacheStats()
-console.log(`Auto-tuned cache hit rate: ${(stats.search.hitRate * 100).toFixed(1)}%`)
 ```
 
-## 🎭 Key Features
-
-### Core Capabilities
-
-- **Vector Search** - Find semantically similar content using embeddings
-- **MongoDB-Style Metadata Filtering** 🆕 - Advanced filtering with `$gt`, `$in`, `$regex`, `$and`, `$or` operators
-- **Graph Relationships** - Connect data with meaningful relationships
-- **JSON Document Search** - Search within specific fields with prioritization
-- **Distributed Mode** - Scale horizontally with automatic coordination between instances
-- **Real-Time Syncing** - WebSocket and WebRTC for distributed instances
-- **Streaming Pipeline** - Process data in real-time as it flows through
-- **Model Control Protocol** - Let AI models access your data
-
-### Developer Experience
-
-- **TypeScript Support** - Fully typed API with generics
-- **Extensible Augmentations** - Customize and extend functionality
-- **REST API** - Web service wrapper for HTTP endpoints
-- **Auto-Complete** - IntelliSense for all APIs and types
-
-## 🆚 Why Not Just Use...?
-
-### vs. Multiple Databases
-❌ **Pinecone + Neo4j + Elasticsearch** - 3 databases, sync nightmares, 3x the cost  
-✅ **Brainy** - One database, always synced, built-in intelligence
+</details>
 
-### vs. Traditional Solutions  
-❌ **PostgreSQL + pgvector + extensions** - Complex setup, performance issues  
-✅ **Brainy** - Zero config, purpose-built for AI, works everywhere
 
-### vs. Cloud-Only Vector DBs
-❌ **Pinecone/Weaviate/Qdrant** - Vendor lock-in, expensive, cloud-only  
-✅ **Brainy** - Run anywhere, your data stays yours, cost-effective
-
-### vs. Graph Databases with "Vector Features"
-❌ **Neo4j + vector plugin** - Bolt-on solution, not native, limited  
-✅ **Brainy** - Native vector+graph architecture from the ground up
 
 ## 📦 Advanced Features
 
@@ -605,229 +262,77 @@ console.log(`Auto-tuned cache hit rate: ${(stats.search.hitRate * 100).toFixed(1
 ```javascript
 const results = await brainy.search("machine learning", 10, {
   metadata: {
-    // Comparison operators
     price: { $gte: 100, $lte: 1000 },
-    category: { $in: ["AI", "ML", "Data"] },
+    category: { $in: ["AI", "ML"] },
     rating: { $gt: 4.5 },
-    
-    // Logical operators  
-    $and: [
-      { status: "active" },
-      { verified: true }
-    ],
-    
-    // Text operators
-    description: { $regex: "neural.*network", $options: "i" },
-    
-    // Array operators
     tags: { $includes: "tensorflow" }
   }
 })
 ```
 
-**15+ operators supported**: `$gt`, `$gte`, `$lt`, `$lte`, `$eq`, `$ne`, `$in`, `$nin`, `$and`, `$or`, `$not`, `$regex`, `$includes`, `$exists`, `$size`
+**15+ operators**: `$gt`, `$in`, `$regex`, `$and`, `$or`, etc.
 
 </details>
 
 <details>
-<summary>🔗 <strong>Graph Relationships & Traversal</strong></summary>
+<summary>🔗 <strong>Graph Relationships</strong></summary>
 
 ```javascript
-// Create entities and relationships
 const company = await brainy.add("OpenAI", { type: "company" })
 const product = await brainy.add("GPT-4", { type: "product" })
-const person = await brainy.add("Sam Altman", { type: "person" })
-
-// Create meaningful relationships
 await brainy.relate(company, product, "develops")
-await brainy.relate(person, company, "leads")
-await brainy.relate(product, person, "created_by")
-
-// Traverse relationships
-const products = await brainy.getVerbsBySource(company) // What OpenAI develops
-const leaders = await brainy.getVerbsByTarget(company)  // Who leads OpenAI
-const connections = await brainy.findSimilar(product, { 
-  relationType: "develops" 
-})
-
-// Search with relationship context
-const results = await brainy.search("AI models", 10, {
-  includeVerbs: true,
-  verbTypes: ["develops", "created_by"],
-  searchConnectedNouns: true
-})
-```
-
-</details>
-
-<details>
-<summary>🌐 <strong>Universal Storage & Deployment</strong></summary>
 
-```javascript
-// Development: File system
-const dev = new BrainyData({ 
-  storage: { fileSystem: { path: './data' } } 
-})
-
-// Production: S3/R2  
-const prod = new BrainyData({
-  storage: { s3Storage: { bucketName: 'my-vectors' } }
-})
-
-// Browser: OPFS
-const browser = new BrainyData() // Auto-detects OPFS
-
-// Edge: Memory
-const edge = new BrainyData({
-  storage: { memory: {} }
-})
-
-// Redis: High performance  
-const redis = new BrainyData({
-  storage: { redis: { connectionString: 'redis://...' } }
-})
+const products = await brainy.getVerbsBySource(company)
 ```
 
-**Extend with any storage**: MongoDB, PostgreSQL, DynamoDB - [see storage adapters guide](docs/api-reference/storage-adapters.md)
-
 </details>
 
 <details>
-<summary>🐳 <strong>Docker & Cloud Deployment</strong></summary>
+<summary>🐳 <strong>Docker Deployment</strong></summary>
 
 ```dockerfile
-# Production-ready Dockerfile
-FROM node:24-slim AS builder
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci
-COPY . .
-RUN npm run download-models  # Embed models for offline operation
-RUN npm run build
-
-FROM node:24-slim AS production  
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci --only=production
-COPY --from=builder /app/dist ./dist
-COPY --from=builder /app/models ./models  # Offline models included
-CMD ["node", "dist/server.js"]
+FROM node:24-slim
+RUN npm run download-models  # Embed models
+CMD ["node", "server.js"]
 ```
 
-Deploy to: Google Cloud Run, AWS Lambda/ECS, Azure Container Instances, Cloudflare Workers, Railway, Render, Vercel, anywhere Docker runs.
+Deploy anywhere: AWS, GCP, Azure, Cloudflare
 
 </details>
 
-## 🚀 Getting Started in 30 Seconds
 
-**The same Brainy code works everywhere - React, Vue, Angular, Node.js, Serverless, Edge Workers.**
+## 📚 Documentation
 
-```javascript
-// This EXACT code works in ALL environments
-import { BrainyData } from '@soulcraft/brainy'
-
-const brainy = new BrainyData()
-await brainy.init()
+- [Quick Start](docs/getting-started/)
+- [API Reference](docs/api-reference/)
+- [Examples](docs/examples/)
+- [Cortex CLI](docs/cortex.md)
+- [Performance Guide](docs/optimization-guides/)
 
-// Add nouns (entities)
-const openai = await brainy.add("OpenAI", { type: "company" })
-const gpt4 = await brainy.add("GPT-4", { type: "product" })
+## ❓ Does Brainy Impact Performance?
 
-// Add verbs (relationships)
-await brainy.relate(openai, gpt4, "develops")
+**NO - Brainy actually IMPROVES performance:**
 
-// Vector search + Graph traversal
-const similar = await brainy.search("AI companies", 5)
-const products = await brainy.getVerbsBySource(openai)
-```
+✅ **Zero runtime overhead** - Premium features are lazy-loaded only when used  
+✅ **Smaller than alternatives** - 643KB vs 12.5MB for TensorFlow.js  
+✅ **Built-in caching** - 95%+ cache hit rates reduce compute  
+✅ **Automatic optimization** - Gets faster as it learns your patterns  
+✅ **No network calls** - Works completely offline after setup
 
-<details>
-<summary>🔍 <strong>See Framework Examples</strong></summary>
-
-### React
-
-```jsx
-function App() {
-  const [brainy] = useState(() => new BrainyData())
-  useEffect(() => brainy.init(), [])
-
-  const search = async (query) => {
-    return await brainy.search(query, 10)
-  }
-  // Same API as above
-}
-```
-
-### Vue 3
-
-```vue
-<script setup>
-  const brainy = new BrainyData()
-  await brainy.init()
-  // Same API as above
-</script>
-```
-
-### Angular
-
-```typescript
-@Component({})
-export class AppComponent {
-  brainy = new BrainyData()
-
-  async ngOnInit() {
-    await this.brainy.init()
-    // Same API as above
-  }
-}
-```
-
-### Node.js / Deno / Bun
-
-```javascript
-const brainy = new BrainyData()
-await brainy.init()
-// Same API as above
-```
-
-</details>
-
-### 🌍 Framework-First, Runs Everywhere
-
-**Brainy automatically detects your environment and optimizes everything:**
-
-| Environment     | Storage         | Optimization               |
-|-----------------|-----------------|----------------------------|
-| 🌐 Browser      | OPFS            | Web Workers, Memory Cache  |
-| 🟢 Node.js      | FileSystem / S3 | Worker Threads, Clustering |
-| ⚡ Serverless    | S3 / Memory     | Cold Start Optimization    |
-| 🔥 Edge Workers | Memory / KV     | Minimal Footprint          |
-| 🦕 Deno/Bun     | FileSystem / S3 | Native Performance         |
-
-## 📚 Documentation & Resources
-
-- **[🚀 Quick Start Guide](docs/getting-started/)** - Get up and running in minutes
-- **[📖 API Reference](docs/api-reference/)** - Complete method documentation  
-- **[💡 Examples](docs/examples/)** - Real-world usage patterns
-- **[⚡ Performance Guide](docs/optimization-guides/)** - Scale to millions of vectors
-- **[🔧 Storage Adapters](docs/api-reference/storage-adapters.md)** - Universal storage compatibility
+**The augmentation system and premium features are 100% optional and have ZERO impact unless explicitly activated.**
 
 ## 🤝 Contributing
 
-We welcome contributions! Please see:
-
-- [Contributing Guidelines](CONTRIBUTING.md)
-- [Developer Documentation](docs/development/DEVELOPERS.md)
-- [Code of Conduct](CODE_OF_CONDUCT.md)
+We welcome contributions! See [Contributing Guidelines](CONTRIBUTING.md)
 
 ## 📄 License
 
-[MIT](LICENSE)
+[MIT](LICENSE) - Core Brainy is FREE forever
 
 ---
 
 <div align="center">
-<strong>Ready to build the future of search? Get started with Brainy today!</strong>
+<strong>Ready to build the future of search?</strong>
 
-**[Get Started →](docs/getting-started/) | [View Examples →](docs/examples/) | [Join Community →](https://github.com/soulcraft-research/brainy/discussions)**
+**[Get Started →](docs/getting-started/) | [Examples →](docs/examples/) | [Discord →](https://discord.gg/brainy)**
 </div>