brainy/README.md

# 🧠⚛️ Brainy - Lightning-Fast Vector + Graph Database with AI Intelligence

<div align="center">

![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/)

**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

**"I need semantic search, relationship traversal, AND metadata filtering - that means 3+ databases"**

❌ **Current Reality**: Pinecone + Neo4j + Elasticsearch + Custom Sync = Slow, expensive, complex  
✅ **Brainy Reality**: One blazing-fast database. One API. Everything in sync.

## 🚀 Quick Start: 8 Lines to Production

```bash
npm install @soulcraft/brainy
```

```javascript
import { BrainyData } from '@soulcraft/brainy'

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")

// 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
```

**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)
- **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+)

---

# 🎆 NEW: Talk to Your Data with Brainy Chat!

```javascript
import { BrainyChat } from '@soulcraft/brainy'

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!
```

**One line. Zero complexity. Optional LLM for smarter responses.**  
[📖 **Learn More About Brainy Chat**](BRAINY-CHAT.md)

## 🔥 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
```

## 🌍 Works Everywhere - Same Code

**Write once, run anywhere.** Brainy auto-detects 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 |

<details>
<summary>🔧 <strong>Advanced Configuration Options</strong></summary>

```javascript
// High-throughput writer
const writer = new BrainyData({
  writeOnly: true,
  allowDirectReads: true  // For deduplication
})

// Read-only search service
const reader = new BrainyData({
  readOnly: true,
  frozen: true  // No stats updates
})

// Custom storage
const custom = new BrainyData({
  storage: {
    type: 's3',
    s3Storage: { bucketName: 'my-vectors' }
  },
  hnsw: {
    maxConnections: 32  // Higher quality
  }
})
```

</details>

## 🎮 Cortex CLI - Command Center for Everything

```bash
# Talk to your data
cortex chat "What patterns do you see?"

# AI-powered data import
cortex neural import data.csv --confidence 0.8

# Real-time monitoring
cortex monitor --dashboard

# Start premium trials
cortex license trial notion
```

[📖 **Full Cortex Documentation**](/docs/cortex.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
cortex 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


<details>
<summary>📦 <strong>Framework Examples</strong></summary>

### 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)
  }
}
```

### Vue 3
```vue
<script setup>
  const brainy = new BrainyData()
  await brainy.init()
</script>
```

### Angular
```typescript
@Component({})
export class AppComponent {
  brainy = new BrainyData()
  async ngOnInit() {
    await this.brainy.init()
  }
}
```

### Node.js
```javascript
const brainy = new BrainyData()
await brainy.init()
```

</details>



## 📦 Advanced Features

<details>
<summary>🔧 <strong>MongoDB-Style Metadata Filtering</strong></summary>

```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" }
  }
})
```

**15+ operators**: `$gt`, `$in`, `$regex`, `$and`, `$or`, etc.

</details>

<details>
<summary>🔗 <strong>Graph Relationships</strong></summary>

```javascript
const company = await brainy.add("OpenAI", { type: "company" })
const product = await brainy.add("GPT-4", { type: "product" })
await brainy.relate(company, product, "develops")

const products = await brainy.getVerbsBySource(company)
```

</details>

<details>
<summary>🐳 <strong>Docker Deployment</strong></summary>

```dockerfile
FROM node:24-slim
RUN npm run download-models  # Embed models
CMD ["node", "server.js"]
```

Deploy anywhere: AWS, GCP, Azure, Cloudflare

</details>


## 📚 Documentation

- [Quick Start](docs/getting-started/)
- [API Reference](docs/api-reference/)
- [Examples](docs/examples/)
- [Cortex CLI](docs/cortex.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.**

## 🤝 Contributing

We welcome contributions! See [Contributing Guidelines](CONTRIBUTING.md)

## 📄 License

[MIT](LICENSE) - Core Brainy is FREE forever

---

<div align="center">
<strong>Ready to build the future of search?</strong>

**[Get Started →](docs/getting-started/) | [Examples →](docs/examples/) | [Discord →](https://discord.gg/brainy)**
</div>