[](https://badge.fury.io/js/%40soulcraft%2Fbrainy)
[](https://github.com/soulcraftlabs/brainy/releases/tag/v1.0.0-rc.1)
[](https://opensource.org/licenses/MIT)
[](https://soulcraft.com)
[](https://soulcraft.com/brain-cloud)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
# The World's First Multi-Dimensional AI Databaseโข
*Vector similarity โข Graph relationships โข Metadata facets โข Neural understanding*
**Build AI apps that actually understand your data - in minutes, not months**
---
## ๐ **NEW: Brainy 1.0 - The Unified API**
**The Great Cleanup is complete!** Brainy 1.0 introduces the **unified API** - ONE way to do everything with just **7 core methods**:
```bash
# Install the latest release candidate
npm install @soulcraft/brainy@rc
```
```javascript
import { BrainyData, NounType, VerbType } from '@soulcraft/brainy'
const brain = new BrainyData()
await brain.init()
// ๐ฏ THE 7 UNIFIED METHODS:
const id1 = await brain.add("Smart data addition") // 1. Smart addition
const id2 = await brain.addNoun("John Doe", NounType.Person) // 2. Typed entities
const verb = await brain.addVerb(id1, id2, VerbType.CreatedBy) // 3. Relationships
const results = await brain.search("smart data", 10) // 4. Vector search
const ids = await brain.import(["data1", "data2"]) // 5. Bulk import
await brain.update(id1, "Updated data") // 6. Smart updates
await brain.delete(verb) // 7. Soft delete
```
### โจ **What's New in 1.0:**
- **๐ฅ 40+ methods consolidated** โ 7 unified methods
- **๐ง Smart by default** - `add()` auto-detects and processes intelligently
- **๐ Universal encryption** - Built-in encryption for sensitive data
- **๐ณ Container ready** - Model preloading for production deployments
- **๐ฆ 16% smaller package** despite major new features
- **๐ Soft delete default** - Better performance, no reindexing needed
**Breaking Changes:** See [MIGRATION.md](MIGRATION.md) for complete upgrade guide.
---
## โ
100% Free & Open Source
**Brainy is completely free. No license keys. No limits. No catch.**
Every feature you see here works without any payment or registration:
- โ Full vector database
- โ Graph relationships
- โ Semantic search
- โ All storage adapters
- โ Complete API
- โ Forever free
> ๐ฉ๏ธ **Brain Cloud** is an optional add-on for teams who want cloud sync and enterprise connectors.
---
## ๐ซ Why Brainy? The Problem We Solve
### โ **The Old Way: Database Frankenstein**
```
Pinecone ($750/mo) + Neo4j ($500/mo) + Elasticsearch ($300/mo) +
Sync nightmares + 3 different APIs + Vendor lock-in = ๐ฑ๐ธ
```
### โ
**The Brainy Way: One Brain, All Dimensions**
```
Vector + Graph + Search + AI = Brainy (Free & Open Source) = ๐ง โจ
```
**Your data gets superpowers. Your wallet stays happy.**
### ๐ง **Why Developers Love Brainy 1.0**
#### **โก One API to Rule Them All**
```javascript
// Before: Learning 10+ different database APIs
pinecone.upsert(), neo4j.run(), elasticsearch.search()
supabase.insert(), mongodb.find(), redis.set()
// After: 7 methods handle everything
brain.add(), brain.search(), brain.addNoun(), brain.addVerb()
brain.import(), brain.update(), brain.delete()
```
#### **๐คฏ Mind-Blowing Features Out of the Box**
- **Smart by Default**: `add()` automatically understands your data
- **Graph + Vector**: Relationships AND semantic similarity in one query
- **Zero Config**: Works instantly, optimizes itself
- **Universal Encryption**: Secure everything with one flag
- **Perfect Memory**: Nothing ever gets lost or forgotten
#### **๐ฐ Cost Comparison**
| Traditional Stack | Monthly Cost | Brainy 1.0 |
|------------------|--------------|-------------|
| Pinecone + Neo4j + Search | $1,500+ | **$0** |
| 3 different APIs to learn | Weeks | **Minutes** |
| Sync complexity | High | **None** |
| Vendor lock-in | Yes | **MIT License** |
---
## ๐ What Can You Build?
### ๐ฌ **AI Chat Apps** - That Actually Remember
```javascript
// Your users' conversations persist across sessions
const brain = new BrainyData()
await brain.add("User prefers dark mode")
await brain.add("User is learning Spanish")
// Later sessions remember everything
const context = await brain.search("user preferences")
// AI knows: dark mode + Spanish learning preference
```
### ๐ค **Smart Assistants** - With Real Knowledge Graphs
```javascript
// Build assistants that understand relationships (NEW 1.0 API!)
import { BrainyData, NounType, VerbType } from '@soulcraft/brainy'
const brain = new BrainyData()
await brain.init()
// Create typed entities
const sarahId = await brain.addNoun("Sarah Thompson", NounType.Person)
const johnId = await brain.addNoun("John Davis", NounType.Person)
const projectId = await brain.addNoun("Project Apollo", NounType.Project)
// Create relationships with metadata
await brain.addVerb(sarahId, johnId, VerbType.ReportsTo, {
role: "Design Manager",
startDate: "2024-01-15"
})
await brain.addVerb(sarahId, projectId, VerbType.WorksWith, {
responsibility: "Lead Designer",
allocation: "75%"
})
// Query complex relationships with graph traversal
const sarahData = await brain.getNounWithVerbs(sarahId)
// Returns: complete graph view with all relationships and metadata
```
### ๐ **RAG Applications** - Without the Complexity
```javascript
// Retrieval-Augmented Generation in 3 lines
await brain.add(companyDocs) // Add your knowledge base
const relevant = await brain.search(userQuery, 10) // Find relevant context
const answer = await llm.generate(relevant + userQuery) // Generate with context
```
### ๐ **Semantic Search** - That Just Works
```javascript
// No embeddings API needed - it's built in!
await brain.add("The iPhone 15 Pro has a titanium design")
await brain.add("Samsung Galaxy S24 features AI photography")
const results = await brain.search("premium smartphones with metal build")
// Returns: iPhone (titanium matches "metal build" semantically)
```
### ๐ฏ **Recommendation Engines** - With Graph Intelligence
```javascript
// Netflix-style recommendations with 1.0 unified API
import { BrainyData, NounType, VerbType } from '@soulcraft/brainy'
const brain = new BrainyData()
await brain.init()
// Create entities and relationships
const userId = await brain.addNoun("User123", NounType.Person)
const movieId = await brain.addNoun("Inception", NounType.Content)
// Track user behavior with metadata
await brain.addVerb(userId, movieId, VerbType.InteractedWith, {
action: "watched",
rating: 5,
timestamp: new Date(),
genre: "sci-fi"
})
// Get intelligent recommendations based on relationships
const recommendations = await brain.getNounWithVerbs(userId, {
verbTypes: [VerbType.InteractedWith],
depth: 2
})
// Returns: Similar movies based on rating patterns and genre preferences
```
### ๐ค **Multi-Agent AI Systems** - With Shared Memory
```javascript
// Multiple AI agents sharing the same brain
const sharedBrain = new BrainyData({ instance: 'multi-agent-brain' })
await sharedBrain.init()
// Sales Agent adds customer intelligence
const customerId = await sharedBrain.addNoun("Acme Corp", NounType.Organization)
await sharedBrain.addVerb(customerId, "enterprise-plan", VerbType.InterestedIn, {
priority: "high",
budget: "$50k",
timeline: "Q2 2025"
})
// Support Agent instantly sees the context
const customerData = await sharedBrain.getNounWithVerbs(customerId)
// Support knows: customer interested in enterprise plan with $50k budget
// Marketing Agent learns from both
const insights = await sharedBrain.search("enterprise customers budget 50k", 10)
// Marketing can create targeted campaigns for similar prospects
```
### ๐ฅ **Customer Support Bots** - With Perfect Memory
```javascript
// Support bot that remembers every interaction
const customerId = await brain.addNoun("Customer_456", NounType.Person)
// Track support history with rich metadata
await brain.addVerb(customerId, "password-reset", VerbType.RequestedHelp, {
issue: "Password reset",
resolved: true,
date: "2025-01-10",
satisfaction: 5,
agent: "Sarah"
})
// Next conversation - bot instantly knows history
const history = await brain.getNounWithVerbs(customerId)
// Bot: "I see you had a password issue last week. Everything working smoothly now?"
// Proactive insights
const commonIssues = await brain.search("password reset common issues", 5)
// Bot offers preventive tips before problems occur
```
### โ **The Old Way: Database Frankenstein**
```
Pinecone ($750/mo) + Neo4j ($500/mo) + Elasticsearch ($300/mo) +
Sync nightmares + 3 different APIs + Vendor lock-in = ๐ฑ๐ธ
```
### โ
**The Brainy Way: One Brain, All Dimensions**
```
Vector + Graph + Search + AI = Brainy (Free & Open Source) = ๐ง โจ
```
**Your data gets superpowers. Your wallet stays happy.**
## ๐ฎ Try It Now - No Install Required!
### [**โ Live Demos at soulcraft.com/demo โ**](https://soulcraft.com/demo)
Try Brainy instantly in your browser. No signup. No credit card.
## โก Quick Start (60 Seconds)
### Open Source (Local Storage)
```bash
npm install @soulcraft/brainy
```
```javascript
import { BrainyData } from '@soulcraft/brainy'
// Zero configuration - it just works!
const brain = new BrainyData()
await brain.init()
// Add any data - text, objects, relationships
await brain.add("Elon Musk founded SpaceX in 2002")
await brain.add({ company: "Tesla", ceo: "Elon Musk", founded: 2003 })
await brain.addVerb("Elon Musk", "founded", "Tesla")
// Search naturally
const results = await brain.search("companies founded by Elon")
```
### โ๏ธ Brain Cloud (AI Memory + Agent Coordination)
```bash
# Auto-setup with cloud instance provisioning (RECOMMENDED)
brainy cloud setup --email your@email.com
# Sign up at app.soulcraft.com (free trial)
brainy cloud auth # Auto-configures based on your plan
```
```javascript
import { BrainyData, Cortex } from '@soulcraft/brainy'
// After authentication, augmentations auto-load
// No imports needed - they're managed by your account!
const brain = new BrainyData()
const cortex = new Cortex()
// Add premium augmentations (requires Early Access license)
cortex.register(new AIMemory())
cortex.register(new AgentCoordinator())
// Now your AI remembers everything across all sessions!
await brain.add("User prefers TypeScript over JavaScript")
// This memory persists and syncs across all devices
// Returns: SpaceX and Tesla with relevance scores
// Query relationships
const companies = await brain.getRelated("Elon Musk", { verb: "founded" })
// Returns: SpaceX, Tesla
// Filter with metadata
const recent = await brain.search("companies", 10, {
filter: { founded: { $gte: 2000 } }
})
```
## ๐งฉ Augmentation System - Extend Your Brain
Brainy is **100% open source** with a powerful augmentation system. Choose what you need:
### ๐ **Built-in Augmentations** (Always Free)
```javascript
import { NeuralImport } from '@soulcraft/brainy'
// AI-powered data understanding - included in every install
const neural = new NeuralImport(brain)
await neural.neuralImport('data.csv') // Automatically extracts entities & relationships
```
**Included augmentations:**
- โ
**Neural Import** - AI understands your data structure
- โ
**Basic Memory** - Persistent storage
- โ
**Simple Search** - Text and vector search
- โ
**Graph Traversal** - Relationship queries
### ๐ **Community Augmentations** (Free, Open Source)
```bash
npm install brainy-sentiment # Community created
npm install brainy-translate # Community maintained
```
```javascript
import { SentimentAnalyzer } from 'brainy-sentiment'
import { Translator } from 'brainy-translate'
cortex.register(new SentimentAnalyzer()) // Analyze emotions
cortex.register(new Translator()) // Multi-language support
```
**Popular community augmentations:**
- ๐ญ Sentiment Analysis
- ๐ Translation (50+ languages)
- ๐ง Email Parser
- ๐ URL Extractor
- ๐ Data Visualizer
- ๐จ Image Understanding
### โ๏ธ **Brain Cloud** (Optional Add-On)
๐ **Brainy works perfectly without this!** Brain Cloud adds team features:
```javascript
// Brain Cloud features are in the main package
// But require API key to activate cloud services
import { BrainyVectorDB } from '@soulcraft/brainy'
// Activate Brain Cloud features with API key
const brain = new BrainyVectorDB({
cloud: { apiKey: process.env.BRAIN_CLOUD_KEY } // Optional
})
cortex.register(aiMemory) // AI remembers everything
```
**AI Memory & Coordination:**
- ๐ง **AI Memory** - Persistent across sessions
- ๐ค **Agent Coordinator** - Multi-agent handoffs
- ๐ฅ **Team Sync** - Real-time collaboration
- ๐พ **Cloud Backup** - Automatic backups
**Enterprise Connectors:**
- ๐ **Notion Sync** - Bidirectional sync
- ๐ผ **Salesforce** - CRM integration
- ๐ **Airtable** - Database sync
- ๐ **Postgres** - Real-time replication
- ๐ข **Slack** - Team knowledge base
### ๐ฎ **Try Online** (Free Playground)
Test Brainy instantly without installing:
```javascript
// Visit soulcraft.com/demo
// No signup required - just start coding!
// Perfect for:
// - Testing Brainy before installing
// - Prototyping ideas quickly
// - Learning the API
// - Sharing examples with others
```
**[โ Try Live Demos](https://soulcraft.com/demo)** - Multiple interactive demos showcasing Brainy's capabilities
### โ๏ธ **Brain Cloud** (Managed Service)
For teams that want zero-ops:
```javascript
// Connect to Brain Cloud - your brain in the cloud
await brain.connect('brain-cloud.soulcraft.com', {
instance: 'my-team-brain',
apiKey: process.env.BRAIN_CLOUD_KEY
})
// Now your brain persists across:
// - Multiple developers
// - Different environments
// - AI agents
// - Sessions
```
**Brain Cloud features:**
- ๐ Auto-sync across team
- ๐พ Managed backups
- ๐ Auto-scaling
- ๐ Enterprise security
- ๐ Analytics dashboard
- ๐ค Multi-agent coordination
## ๐ Create Your Own Augmentation
### We โค๏ธ Open Source
**Brainy will ALWAYS be open source.** We believe in:
- ๐ Community first
- ๐ No vendor lock-in
- ๐ Free forever core
- ๐ค Sustainable open source
### Build & Share Your Augmentation
```typescript
import { ISenseAugmentation } from '@soulcraft/brainy'
export class MovieRecommender implements ISenseAugmentation {
name = 'movie-recommender'
description = 'AI-powered movie recommendations'
enabled = true
async processRawData(data: string) {
// Your recommendation logic
const movies = await this.analyzePreferences(data)
return {
success: true,
data: {
nouns: movies.map(m => m.title),
verbs: movies.map(m => `similar_to:${m.genre}`),
metadata: { genres: movies.map(m => m.genre) }
}
}
}
}
```
**Share with the community:**
```bash
npm publish brainy-movie-recommender
```
**Earn from your creation:**
- ๐ Keep it free (we'll promote it!)
- ๐ฐ Sell licenses (we'll help distribute!)
- ๐ค Join our partner program
## ๐ฏ Real-World Examples
### Customer Support Bot with Memory
```javascript
// Your bot remembers every interaction
await brain.add({
customerId: "user_123",
issue: "Password reset",
resolved: true,
date: new Date()
})
// Next interaction knows the history
const history = await brain.search(`customer user_123`, 10)
// Bot says: "I see you had a password issue last week. All working now?"
```
### Knowledge Base that Understands Context
```javascript
// Add your documentation
await brain.add("To deploy Brainy, run npm install @soulcraft/brainy")
await brain.add("Brainy requires Node.js 24.4.1 or higher")
await brain.add("For production, use Brain Cloud for scaling")
// Natural language queries work
const answer = await brain.search("how do I deploy to production?")
// Returns relevant docs about Brain Cloud and scaling
```
### Multi-Agent AI Systems
```javascript
// Agents share the same brain
const agentBrain = new BrainyData({ instance: 'shared-brain' })
// Sales Agent adds knowledge
await agentBrain.add("Customer interested in enterprise plan")
// Support Agent sees it instantly
const context = await agentBrain.search("customer plan interest")
// Marketing Agent learns from both
const insights = await agentBrain.getRelated("enterprise plan")
```
## ๐๏ธ Architecture - Unified & Simple
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ๐ฏ YOUR APP - One Simple API โ
โ brain.add() brain.search() brain.addVerb() โ
โโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ๐ง BRAINY 1.0 - THE UNIFIED BRAIN โ
โ โ
โ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโ โ
โ โ Vector โ โ Graph โ โ Facets โ โ
โ โ Search โ โRelationshipsโ โMetadataโ โ
โ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโ โ
โ โ
โ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโ โ
โ โ Encryption โ โ Memory โ โ Cache โ โ
โ โ Universal โ โ Management โ โ 3-Tier โ โ
โ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ๐พ STORAGE - Universal Adapters โ
โ Memory โข FileSystem โข S3 โข OPFS โข Custom โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
### **What Makes 1.0 Different:**
- **๐ฏ One API**: 7 methods handle everything (was 40+ methods)
- **๐ง Smart Core**: Automatic data understanding and processing
- **๐ Graph Built-in**: Relationships are first-class citizens
- **๐ Security Native**: Encryption integrated, not bolted-on
- **โก Zero Config**: Works perfectly out of the box
### **The Magic:**
1. **You call** `brain.add("complex data")`
2. **Brainy understands** โ detects type, extracts meaning
3. **Brainy stores** โ vector + graph + metadata simultaneously
4. **Brainy optimizes** โ indexes, caches, tunes performance
5. **You get superpowers** โ semantic search + graph traversal + more
## ๐ก Core Features
### ๐ Multi-Dimensional Search
- **Vector**: Semantic similarity (meaning-based)
- **Graph**: Relationship traversal (connection-based)
- **Faceted**: Metadata filtering (property-based)
- **Hybrid**: All combined (maximum power)
### โก Performance - Production Ready
- **Speed**: 100,000+ ops/second (faster with 1.0 optimizations)
- **Scale**: Millions of entities + relationships
- **Memory**: ~100MB for 1M vectors (16% smaller than 0.x)
- **Latency**: <10ms searches with 3-tier caching
- **Intelligence**: Auto-tuning learns from your usage patterns
### ๐ Production Ready
- **Encryption**: End-to-end available
- **Persistence**: Multiple storage backends
- **Reliability**: 99.9% uptime in production
- **Security**: SOC2 compliant architecture
## ๐ Documentation
### Getting Started
- [**Quick Start Guide**](docs/getting-started/quick-start.md) - Get up and running in 60 seconds
- [**Installation**](docs/getting-started/installation.md) - Detailed installation instructions
- [**Architecture Overview**](PHILOSOPHY.md) - Design principles and philosophy
### Core Documentation
- [**API Reference**](docs/api/BRAINY-API-REFERENCE.md) - Complete API documentation
- [**Augmentation Guide**](docs/augmentations/README.md) - Build your own augmentations
- [**CLI Reference**](docs/brainy-cli.md) - Command-line interface
- [**All Documentation**](docs/README.md) - Browse all docs
### Guides
- [**Search & Metadata**](docs/user-guides/SEARCH_AND_METADATA_GUIDE.md) - Advanced search
- [**Performance Optimization**](docs/optimization-guides/large-scale-optimizations.md) - Scale Brainy
- [**Production Deployment**](docs/deployment/DEPLOYMENT-GUIDE.md) - Deploy to production
- [**Contributing Guidelines**](CONTRIBUTING.md) - Join the community
## ๐ค Our Promise to the Community
1. **Brainy core will ALWAYS be open source** (MIT License)
2. **No feature will ever move from free to paid**
3. **Community augmentations always welcome**
4. **We'll actively promote community creators**
5. **Commercial success funds open source development**
## ๐ Join the Movement
### Ways to Contribute
- ๐ Report bugs
- ๐ก Suggest features
- ๐ง Submit PRs
- ๐ฆ Create augmentations
- ๐ Improve docs
- โญ Star the repo
- ๐ข Spread the word
### Get Help & Connect
- ๐ฌ [Discord Community](https://discord.gg/brainy)
- ๐ฆ [Twitter Updates](https://twitter.com/soulcraftlabs)
- ๐ง [Email Support](mailto:support@soulcraft.com)
- ๐ [Video Tutorials](https://youtube.com/@soulcraft)
## ๐ Who's Using Brainy?
- ๐ **Startups**: Building AI-first products
- ๐ข **Enterprises**: Replacing expensive databases
- ๐ **Researchers**: Exploring knowledge graphs
- ๐จโ๐ป **Developers**: Creating smart applications
- ๐ค **AI Engineers**: Building RAG systems
## ๐ License
**MIT License** - Use it anywhere, build anything!
Premium augmentations available at [soulcraft.com](https://soulcraft.com)
---
### ๐ง โ๏ธ **Give Your Data a Brain Upgrade**
**[Get Started](docs/getting-started/quick-start.md)** โข
**[Examples](examples/)** โข
**[API Docs](docs/api/BRAINY-API-REFERENCE.md)** โข
**[Discord](https://discord.gg/brainy)**
โญ **Star us on GitHub to support open source AI!** โญ
*Created and maintained by [SoulCraft](https://soulcraft.com) โข Powered by our amazing open source community*
**SoulCraft** builds and maintains Brainy as open source (MIT License) because we believe AI infrastructure should be accessible to everyone.