David Snelling
bd39b71fbf
BREAKING CHANGES: - CLI command renamed from 'cortex' to 'brainy' - Neural Import renamed to Cortex augmentation - Class CortexSenseAugmentation (was NeuralImportSenseAugmentation) Benefits: - npx @soulcraft/brainy now works automatically - Better conceptual clarity: Cortex = AI intelligence layer - Cleaner architecture: CLI = brainy, AI = Cortex, DB = BrainyData
338 lines
No EOL
9.3 KiB
Markdown
338 lines
No EOL
9.3 KiB
Markdown
# 🧠⚛️ Brainy - Lightning-Fast Vector + Graph Database with AI Intelligence
|
|
|
|
<div align="center">
|
|
|
|
|
|
|
|
[](https://badge.fury.io/js/%40soulcraft%2Fbrainy)
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](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**
|
|
|
|
</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)
|
|
- **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!
|
|
|
|
```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>
|
|
|
|
## 🎮 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
|
|
|
|
|
|
<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/)
|
|
- [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.**
|
|
|
|
## 🤝 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> |