[](https://badge.fury.io/js/%40soulcraft%2Fbrainy)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
# 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 AMAZING BRAINY: See It In Action!
```javascript
import { BrainyData } from '@soulcraft/brainy'
// ๐งช 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'
// It's alive! (No config needed)
const brainy = new BrainyData()
await brainy.init()
// Feed your brain some data
await brainy.add("Tesla", { type: "company", sector: "automotive" })
await brainy.add("SpaceX", { type: "company", sector: "aerospace" })
// 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" }
})
```
## ๐ NEW! Talk to Your Data with Brainy Chat
```javascript
import { BrainyChat } from '@soulcraft/brainy'
const chat = new BrainyChat(brainy) // Your data becomes conversational!
const answer = await chat.ask("What patterns do you see in customer behavior?")
// โ AI-powered insights from your knowledge graph!
```
**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
**One line. Zero complexity. Optional LLM for genius-level responses.**
[๐ **Learn More About Brainy Chat**](BRAINY-CHAT.md)
## ๐ฎ 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
// 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",
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
const reader = new BrainyData({
readOnly: true,
frozen: true // Maximum performance
})
// Custom storage backend
const custom = new BrainyData({
storage: {
type: 's3',
s3Storage: {
bucketName: 'my-brain',
region: 'us-east-1'
}
}
})
```
### ๐ Framework Integration Examples
๐ฆ See Framework Examples
#### React
```jsx
import { BrainyData } from '@soulcraft/brainy'
function App() {
const [brainy] = useState(() => new BrainyData())
useEffect(() => {
brainy.init()
}, [])
const search = async (query) => {
return await brainy.search(query, 10)
}
return
}
```
#### Vue 3
```vue
```
#### Angular
```typescript
@Injectable({ providedIn: 'root' })
export class BrainyService {
private brainy = new BrainyData()
async init() {
await this.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"]
```
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
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
// 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
[MIT](LICENSE) - Core Brainy is FREE forever
---
## ๐ง 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*