brainy/README.md

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

The world's only true Vector + Graph database with built-in AI intelligence
Sub-millisecond queries across millions of vectors + billions of relationships

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

npm install @soulcraft/brainy

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!

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

🔥 The Power of Three-in-One Search

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

🔧 Advanced Configuration Options

// 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
  }
})

🎮 Cortex CLI - Command Center for Everything

# 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

⚙️ 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

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

📦 Framework Examples

React

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

<script setup>
  const brainy = new BrainyData()
  await brainy.init()
</script>

Angular

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

Node.js

const brainy = new BrainyData()
await brainy.init()

📦 Advanced Features

🔧 MongoDB-Style Metadata Filtering

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.

🔗 Graph Relationships

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)

🐳 Docker Deployment

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

Deploy anywhere: AWS, GCP, Azure, Cloudflare

📚 Documentation

• Quick Start
• API Reference
• Examples
• Cortex CLI
• Performance Guide

❓ 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

📄 License

MIT - Core Brainy is FREE forever

---

Ready to build the future of search?

Get Started → | Examples → | Discord →