diff --git a/README.md b/README.md
index 2b4b68a5..7ca6f963 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,3 @@
-# ๐ง โ๏ธ Brainy - Lightning-Fast Vector + Graph Database with AI Intelligence
-
@@ -9,91 +7,263 @@
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
-**The world's only true Vector + Graph database with built-in AI intelligence**
-**Sub-millisecond queries across millions of vectors + billions of relationships**
+# BRAINY: The Brain in a Jar Databaseโข
+
+**The world's only Vector + Graph + AI database and realtime data platform**
+
+*Zero-to-Smartโข technology that thinks so you don't have to*
-## The Problem: Three Databases for One Search
+---
-**"I need semantic search, relationship traversal, AND metadata filtering - that means 3+ databases"**
+## ๐ THE AMAZING BRAINY: See It In Action!
-โ **Current Reality**: Pinecone + Neo4j + Elasticsearch + Custom Sync = Slow, expensive, complex
-โ
**Brainy Reality**: One blazing-fast database. One API. Everything in sync.
+```javascript
+import { BrainyData } from '@soulcraft/brainy'
-## ๐ Quick Start: 8 Lines to Production
+// ๐งช Initialize your brain-in-a-jar
+const brainy = new BrainyData() // Zero config - it's ALIVE!
+await brainy.init()
+
+// ๐ฌ 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.**
+
+## ๐ซ WHY BRAINY? The Problem We Solve
+
+### โ The Old Way: Database Frankenstein
+
+```
+Pinecone ($$$) + Neo4j ($$$) + Elasticsearch ($$$) + Sync Hell = ๐ฑ
+```
+
+### โ
The Brainy Way: One Smart Brain
+
+```
+Vector Search + Graph Relations + Metadata Filtering + AI Intelligence = ๐ง โจ
+```
+
+**Your data gets a brain upgrade. No assembly required.**
+
+## โก QUICK & EASY: From Zero to Smart in 60 Seconds
+
+### Installation
```bash
npm install @soulcraft/brainy
```
+### Your First Brainy App
+
```javascript
import { BrainyData } from '@soulcraft/brainy'
-const brainy = new BrainyData() // Auto-detects environment
-await brainy.init() // Zero configuration
+// It's alive! (No config needed)
+const brainy = new BrainyData()
+await brainy.init()
-// 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")
+// Feed your brain some data
+await brainy.add("Tesla", { type: "company", sector: "automotive" })
+await brainy.add("SpaceX", { type: "company", sector: "aerospace" })
-// One query, three search paradigms
-const results = await brainy.search("AI language models", 5, {
- metadata: { funding: { $gte: 10000000 } }, // MongoDB-style filtering
- includeVerbs: true // Graph relationships
-}) // Semantic vector search
+// Ask it questions (semantic search)
+const similar = await brainy.search("electric vehicles")
+
+// Use relationships (graph database)
+await brainy.relate("Tesla", "SpaceX", "shares_founder_with")
+
+// Filter like MongoDB (faceted search)
+const results = await brainy.search("innovation", {
+ metadata: { sector: "automotive" }
+})
```
-**That's it. You just built a knowledge graph with semantic search in 8 lines.**
-
-## ๐ฏ Key Features: Why Developers Choose Brainy
-
-### โก Blazing Performance at Scale
-```
-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
-```
-
-### ๐ 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
-
-### ๐ง Built-in AI Intelligence (FREE)
-- **Cortex Augmentation**: 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+)
-
----
-
-# ๐ NEW: Talk to Your Data with Brainy Chat!
+## ๐ NEW! Talk to Your Data with Brainy Chat
```javascript
import { BrainyChat } from '@soulcraft/brainy'
-const chat = new BrainyChat(brainy) // That's it!
+const chat = new BrainyChat(brainy) // Your data becomes conversational!
const answer = await chat.ask("What patterns do you see in customer behavior?")
-// โ Works instantly with zero config!
+// โ AI-powered insights from your knowledge graph!
```
-**One line. Zero complexity. Optional LLM for smarter responses.**
+**One line. Zero complexity. Optional LLM for genius-level responses.**
[๐ **Learn More About Brainy Chat**](BRAINY-CHAT.md)
-## ๐ฅ The Power of Three-in-One Search
+## ๐ฎ 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
-// This ONE query does what used to require 3 databases:
+// Enable Cortex Intelligence during import
+const brainy = new BrainyData({
+ cortex: {
+ enabled: true,
+ autoDetect: true // Automatically identify entities & relationships
+ }
+})
+
+// Import with understanding
+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)!**
+
+## ๐ NEW! Augmentation Pipeline - Plug in Superpowers
+
+**8 types of augmentations to enhance your brain:**
+
+```javascript
+// Add augmentations like installing apps on your brain
+brainy.augment({
+ type: 'PERCEPTION', // Visual/pattern recognition
+ handler: myPerceptor
+})
+
+brainy.augment({
+ type: 'COGNITION', // Deep thinking & analysis
+ handler: myThinker
+})
+
+// Premium augmentations (coming soon!)
+brainy.augment({
+ type: 'NOTION_SYNC', // Bi-directional Notion sync
+ license: 'premium'
+})
+```
+
+**Augmentation Types:**
+
+- ๐ฏ **SENSE** - Input processing
+- ๐ง **MEMORY** - Long-term storage
+- ๐ญ **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
+// This ONE query replaces THREE 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",
@@ -101,225 +271,290 @@ const results = await brainy.search("AI startups in healthcare", 10, {
stage: { $in: ["Series A", "Series B"] }
}
})
-// Returns: Companies similar to your query + their relationships + matching your criteria
```
-## ๐ Works Everywhere - Same Code
+### ๐ง Self-Learning & Auto-Optimization
-**Write once, run anywhere.** Brainy auto-detects your environment:
+**Brainy gets smarter the more you use it:**
-| 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 |
+- Auto-indexes frequently searched fields
+- Learns query patterns for faster responses
+- Optimizes storage based on access patterns
+- Self-configures for your environment
-
-๐ง Advanced Configuration Options
+## ๐ญ ADVANCED FEATURES: For Mad Scientists
+
+### ๐ฌ MongoDB-Style Query Operators
```javascript
-// High-throughput writer
+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 service
+// Read-only search cluster
const reader = new BrainyData({
readOnly: true,
- frozen: true // No stats updates
+ frozen: true // Maximum performance
})
-// Custom storage
+// Custom storage backend
const custom = new BrainyData({
storage: {
type: 's3',
- s3Storage: { bucketName: 'my-vectors' }
- },
- hnsw: {
- maxConnections: 32 // Higher quality
+ s3Storage: {
+ bucketName: 'my-brain',
+ region: 'us-east-1'
+ }
}
})
```
-
-
-## ๐ฎ Brainy CLI - Command Center for Everything
-
-```bash
-# Talk to your data
-brainy chat "What patterns do you see?"
-
-# AI-powered data import
-brainy import data.csv --cortex --confidence 0.8
-
-# Real-time monitoring
-brainy monitor --dashboard
-
-# Start premium trials
-brainy license trial notion
-```
-
-[๐ **Full CLI Documentation**](/docs/brainy-cli.md)
-
-## โ๏ธ Configuration (Optional)
-
-Brainy works with **zero configuration**, but you can customize
-
-
-## ๐ 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
-
-### 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 DBs with "Vector Features"
-โ **Neo4j + vector plugin** - Bolt-on solution, not native, limited
-โ
**Brainy** - Native vector+graph architecture from the ground up
-
-## ๐ Premium Features (Optional)
-
-**Core Brainy is FREE forever. Premium features for enterprise needs:**
-
-### ๐ 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
-
-```bash
-brainy license trial notion # Start free trial
-```
-
-**No vendor lock-in. Your data stays yours.**
-
-## ๐จ What You Can Build
-
-- **๐ค 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
-
+### ๐ Framework Integration Examples
-๐ฆ Framework Examples
+๐ฆ See Framework Examples
+
+#### React
-### React
```jsx
import { BrainyData } from '@soulcraft/brainy'
function App() {
const [brainy] = useState(() => new BrainyData())
- useEffect(() => brainy.init(), [])
-
+
+ useEffect(() => {
+ brainy.init()
+ }, [])
+
const search = async (query) => {
return await brainy.search(query, 10)
}
+
+ return
}
```
-### Vue 3
+#### Vue 3
+
```vue
+
```
-### Angular
+#### Angular
+
```typescript
-@Component({})
-export class AppComponent {
- brainy = new BrainyData()
- async ngOnInit() {
+
+@Injectable({ providedIn: 'root' })
+export class BrainyService {
+ private brainy = new BrainyData()
+
+ async init() {
await this.brainy.init()
}
-}
-```
-### Node.js
-```javascript
-const brainy = new BrainyData()
-await brainy.init()
+ search(query: string) {
+ return this.brainy.search(query, 10)
+ }
+}
```
+### ๐ณ 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"]
+```
-## ๐ฆ Advanced Features
+Deploy to AWS, GCP, Azure, Cloudflare Workers, anywhere!
-
-๐ง MongoDB-Style Metadata Filtering
+## ๐ 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
+brainy augment trial notion # Start 14-day free trial
+```
+
+## ๐จ What You Can Build
+
+**The only limit is your imagination:**
+
+- **๐ค AI Assistants** - ChatGPT with perfect memory
+- **๐ Semantic Search** - Find by meaning, not keywords
+- **๐ฏ Recommendation Engines** - Netflix-level suggestions
+- **๐งฌ Knowledge Graphs** - Wikipedia meets Neo4j
+- **๐๏ธ Computer Vision** - Search images by content
+- **๐ต Music Discovery** - Spotify's algorithm in your app
+- **๐ Smart Documentation** - Self-answering docs
+- **๐ก๏ธ Fraud Detection** - Pattern recognition on steroids
+- **๐ Real-time Collaboration** - Multiplayer knowledge bases
+- **๐ฅ Medical Diagnosis** - Symptom matching with AI
+
+## ๐ Complete Documentation
+
+### Getting Started
+
+- [**Quick Start Guide**](docs/getting-started/) - Up and running in 5 minutes
+- [**Installation**](docs/getting-started/installation.md) - All environments covered
+- [**Basic Concepts**](docs/getting-started/concepts.md) - Understand the brain
+
+### Core Features
+
+- [**API Reference**](docs/api-reference/) - Every method documented
+- [**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
+
+- [**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
+
+- [**Example Apps**](docs/examples/) - Full applications
+- [**Code Recipes**](docs/examples/recipes.md) - Common patterns
+- [**Video Tutorials**](docs/tutorials/) - Visual learning
+
+## ๐ Why Not Just Use...?
+
+### vs. Multiple Databases
+
+โ **Pinecone + Neo4j + Elasticsearch** = 3x cost, sync nightmares, 3 APIs
+โ
**Brainy** = One database, always synced, one simple API
+
+### 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
-const results = await brainy.search("machine learning", 10, {
- metadata: {
- price: { $gte: 100, $lte: 1000 },
- category: { $in: ["AI", "ML"] },
- rating: { $gt: 4.5 },
- tags: { $includes: "tensorflow" }
+// 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
}
})
```
-**15+ operators**: `$gt`, `$in`, `$regex`, `$and`, `$or`, etc.
-
-
-
-
-๐ Graph Relationships
+**Scale Out (Horizontal)**
```javascript
-const company = await brainy.add("OpenAI", { type: "company" })
-const product = await brainy.add("GPT-4", { type: "product" })
-await brainy.relate(company, product, "develops")
+// 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' })
+}
-const products = await brainy.getVerbsBySource(company)
+// Or use read/write separation
+const writer = new BrainyData({ writeOnly: true })
+const readers = [/* multiple read replicas */]
```
-
+### ๐๏ธ Architecture That Scales
-
-๐ณ Docker Deployment
+โ
**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
-```dockerfile
-FROM node:24-slim
-RUN npm run download-models # Embed models
-CMD ["node", "server.js"]
-```
+## ๐ธ Recent Updates
-Deploy anywhere: AWS, GCP, Azure, Cloudflare
+### ๐ฏ 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
-## ๐ Documentation
-
-- [Quick Start](docs/getting-started/)
-- [API Reference](docs/api-reference/)
-- [Examples](docs/examples/)
-- [Brainy CLI](docs/brainy-cli.md)
-- [Performance Guide](docs/optimization-guides/)
-
-## โ Does Brainy Impact Performance?
-
-**NO - Brainy actually IMPROVES performance:**
-
-โ
**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
-
-**The augmentation system and premium features are 100% optional and have ZERO impact unless explicitly activated.**
+- 95% package size reduction
+- MongoDB query operators
+- Filter discovery API
+- Transformers.js migration
+- True offline operation
## ๐ค Contributing
@@ -332,7 +567,14 @@ We welcome contributions! See [Contributing Guidelines](CONTRIBUTING.md)
---
-Ready to build the future of search?
-**[Get Started โ](docs/getting-started/) | [Examples โ](docs/examples/) | [Discord โ](https://discord.gg/brainy)**
-
\ No newline at end of file
+## ๐ง Ready to Give Your Data a Brain?
+
+**[Get Started โ](docs/getting-started/) | [Examples โ](docs/examples/)**
+
+*Zero-to-Smartโข - Because your data deserves a brain upgrade*
+
+**Built with โค๏ธ by [Soulcraft Research](https://soulcraft.com)**
+*Powered by the BXL9000โข Cognitive Engine*
+
+