[](LICENSE)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](CONTRIBUTING.md)
**A powerful graph & vector data platform for AI applications across any environment**
## ๐ฅ MAJOR UPDATE: TensorFlow.js โ Transformers.js Migration (v0.46+)
**We've completely replaced TensorFlow.js with Transformers.js for better performance and true offline operation!**
### Why We Made This Change
**The Honest Truth About TensorFlow.js:**
- ๐ฆ **Massive Package Size**: 12.5MB+ packages with complex dependency trees
- ๐ **Hidden Network Calls**: Even "local" models triggered fetch() calls internally
- ๐ **Dependency Hell**: Constant `--legacy-peer-deps` issues with Node.js updates
- ๐ง **Maintenance Burden**: 47+ dependencies to keep compatible across environments
- ๐พ **Huge Models**: 525MB Universal Sentence Encoder models
### What You Get Now
- โ **95% Smaller Package**: 643 kB vs 12.5 MB (and it actually works better!)
- โ **84% Smaller Models**: 87 MB vs 525 MB all-MiniLM-L6-v2 vs USE
- โ **True Offline Operation**: Zero network calls after initial model download
- โ **5x Fewer Dependencies**: Clean dependency tree, no more peer dep issues
- โ **Same API**: Drop-in replacement - your existing code just works
- โ **Better Performance**: ONNX Runtime is faster than TensorFlow.js in most cases
### Migration (It's Automatic!)
```javascript
// Your existing code works unchanged!
import { BrainyData } from '@soulcraft/brainy'
const db = new BrainyData({
embedding: { type: 'transformer' } // Now uses Transformers.js automatically
})
// Dimensions changed from 512 โ 384 (handled automatically)
```
**For Docker/Production or No Egress:**
```dockerfile
RUN npm install @soulcraft/brainy
RUN npm run download-models # Download during build for offline production
```
---
## โจ What is Brainy?
Imagine a database that thinks like you do - connecting ideas, finding patterns, and getting smarter over time. Brainy
is the **AI-native database** that brings vector search and knowledge graphs together in one powerful, ridiculously
easy-to-use package.
### ๐ NEW: Distributed Mode (v0.38+)
**Scale horizontally with zero configuration!** Brainy now supports distributed deployments with automatic coordination:
- **๐ Multi-Instance Coordination** - Multiple readers and writers working in harmony
- **๐ท๏ธ Smart Domain Detection** - Automatically categorizes data (medical, legal, product, etc.)
- **๐ Real-Time Health Monitoring** - Track performance across all instances
- **๐ Automatic Role Optimization** - Readers optimize for cache, writers for throughput
- **๐๏ธ Intelligent Partitioning** - Hash-based partitioning for perfect load distribution
### ๐ Why Developers Love Brainy
- **๐ง Zero-to-Smartโข** - No config files, no tuning parameters, no DevOps headaches. Brainy auto-detects your
environment and optimizes itself
- **๐ True Write-Once, Run-Anywhere** - Same code runs in Angular, React, Vue, Node.js, Deno, Bun, serverless, edge
workers, and web workers with automatic environment detection
- **โก Scary Fast** - Handles millions of vectors with sub-millisecond search. GPU acceleration for embeddings, optimized CPU for distance calculations
- **๐ฏ Self-Learning** - Like having a database that goes to the gym. Gets faster and smarter the more you use it
- **๐ฎ AI-First Design** - Built for the age of embeddings, RAG, and semantic search. Your LLMs will thank you
- **๐ฎ Actually Fun to Use** - Clean API, great DX, and it does the heavy lifting so you can build cool stuff
### ๐ NEW: Ultra-Fast Search Performance + Auto-Configuration
**Your searches just got 100x faster AND Brainy now configures itself!** Advanced performance with zero setup:
- **๐ค Intelligent Auto-Configuration** - Detects environment and usage patterns, optimizes automatically
- **โก Smart Result Caching** - Repeated queries return in <1ms with automatic cache invalidation
- **๐ Cursor-Based Pagination** - Navigate millions of results with constant O(k) performance
- **๐ Real-Time Data Sync** - Cache automatically updates when data changes, even in distributed scenarios
- **๐ Performance Monitoring** - Built-in hit rate and memory usage tracking with adaptive optimization
- **๐ฏ Zero Breaking Changes** - All existing code works unchanged, just faster and smarter
## ๐ฆ Get Started in 30 Seconds
```bash
npm install @soulcraft/brainy
```
```javascript
import { BrainyData } from '@soulcraft/brainy'
const brainy = new BrainyData()
await brainy.init() // Auto-detects your environment
// Add some data
await brainy.add("The quick brown fox jumps over the lazy dog")
await brainy.add("A fast fox leaps over a sleeping dog")
await brainy.add("Cats are independent and mysterious animals")
// Vector search finds similar content
const results = await brainy.search("speedy animals jumping", 2)
console.log(results) // Finds the fox sentences!
```
**๐ฏ That's it!** You just built semantic search in 4 lines. Works in Angular, React, Vue, Node.js, browsers,
serverless - everywhere.
## ๐ The Magic: Vector + Graph Database
**Most databases do one thing.** Brainy does both vector similarity AND graph relationships:
```javascript
// Add entities with relationships
const companyId = await brainy.addNoun("OpenAI creates powerful AI models", "company")
const productId = await brainy.addNoun("GPT-4 is a large language model", "product")
// Connect them with relationships
await brainy.addVerb(companyId, productId, undefined, { type: "develops" })
// Now you can do BOTH:
const similar = await brainy.search("AI language models") // Vector similarity
const products = await brainy.getVerbsByType("develops") // Graph traversal
```
**Why this matters:** Find content by meaning AND follow relationships. It's like having PostgreSQL and Pinecone working
together seamlessly.
### ๐ Want More Power?
- **Advanced graph traversal** - Complex relationship queries and multi-hop searches
- **Distributed clustering** - Scale across multiple instances with automatic coordination
- **Real-time syncing** - WebSocket and WebRTC for live data updates
- **Custom augmentations** - Extend Brainy with your own functionality
*[See full API documentation below](#-installation) for advanced features*
## ๐จ Build Amazing Things
**๐ค AI Chat Applications** - Build ChatGPT-like apps with long-term memory and context awareness
**๐ Semantic Search Engines** - Search by meaning, not keywords. Find "that thing that's like a cat but bigger" โ
returns "tiger"
**๐ฏ Recommendation Engines** - "Users who liked this also liked..." but actually good
**๐งฌ Knowledge Graphs** - Connect everything to everything. Wikipedia meets Neo4j meets magic
**๐๏ธ Computer Vision Apps** - Store and search image embeddings. "Find all photos with dogs wearing hats"
**๐ต Music Discovery** - Find songs that "feel" similar. Spotify's Discover Weekly in your app
**๐ Smart Documentation** - Docs that answer questions. "How do I deploy to production?" โ relevant guides
**๐ก๏ธ Fraud Detection** - Find patterns humans can't see. Anomaly detection on steroids
**๐ Real-Time Collaboration** - Sync vector data across devices. Figma for AI data
**๐ฅ Medical Diagnosis Tools** - Match symptoms to conditions using embedding similarity
## ๐ Write-Once, Run-Anywhere Quick Start
Brainy uses the same code across all environments with automatic detection. **Framework-optimized** for the best
developer experience. Choose your environment:
### ๐ ฐ๏ธ Angular (Latest)
```bash
npm install @soulcraft/brainy
```
```typescript
import { Component, signal, OnInit } from '@angular/core'
import { BrainyData } from '@soulcraft/brainy'
@Component({
selector: 'app-search',
template: `