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 9 core methods:

# Install the latest release candidate
npm install @soulcraft/brainy@rc

import { BrainyData, NounType, VerbType } from '@soulcraft/brainy'

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

// 🎯 THE 9 UNIFIED METHODS:
await brain.add("Smart data addition")           // 1. Smart addition
await brain.search("smart data", 10)             // 2. Vector search
await brain.import(["data1", "data2"])          // 3. Bulk import
await brain.addNoun("John Doe", NounType.Person) // 4. Typed entities
await brain.addVerb(id1, id2, VerbType.CreatedBy) // 5. Relationships
await brain.update(id1, "Updated data")         // 6. Smart updates
await brain.delete(id)                          // 7. Soft delete
brain.augment(myAugmentation)                   // 8. Add capabilities
await brain.export({ format: 'json' })          // 9. Export data

✨ What's New in 1.0:

• 🔥 40+ methods consolidated → 9 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 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

// Before: Learning 10+ different database APIs
pinecone.upsert(), neo4j.run(), elasticsearch.search()
supabase.insert(), mongodb.find(), redis.set()

// After: 9 methods handle EVERYTHING
brain.add(), brain.search(), brain.import()
brain.addNoun(), brain.addVerb(), brain.update()
brain.delete(), brain.augment(), brain.export()

🤯 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

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

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

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

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

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

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

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

Try Brainy instantly in your browser. No signup. No credit card.

⚡ Quick Start (60 Seconds)

Open Source (Local Storage)

npm install @soulcraft/brainy

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)

# 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

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 Brain Cloud subscription)
brain.register(new AIMemory())
brain.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)

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 (Coming Soon!)

// 🚧 FUTURE: Community augmentations will be available soon!
// These are examples of what the community could build:

// Example: Sentiment Analysis (not yet available)
// npm install brainy-sentiment
// brain.register(new SentimentAnalyzer())

// Example: Translation (not yet available)  
// npm install brainy-translate
// brain.register(new Translator())

Ideas for Community Augmentations: Want to build one of these? We'll help promote it!

• 🎭 Sentiment Analysis - Analyze emotional tone
• 🌍 Translation - Multi-language support
• 📧 Email Parser - Extract structured data from emails
• 🔗 URL Extractor - Find and validate URLs
• 📊 Data Visualizer - Generate charts from data
• 🎨 Image Understanding - Analyze image content

Be the First! Create an augmentation and we'll feature it here. See how to build augmentations →

☁️ Brain Cloud (Optional Add-On)

🌟 Brainy works perfectly without this! Brain Cloud adds team features:

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

brain.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:

// 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 - Multiple interactive demos showcasing Brainy's capabilities

☁️ Brain Cloud (Managed Service)

For teams that want zero-ops:

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

import { IAugmentation } from '@soulcraft/brainy'

export class MovieRecommender implements IAugmentation {
  name = 'movie-recommender'
  type = 'cognition' // sense|conduit|cognition|memory
  description = 'AI-powered movie recommendations'
  enabled = true
  
  async processRawData(data: any) {
    // Your recommendation logic
    const movies = await this.analyzePreferences(data)
    
    return {
      success: true,
      data: {
        recommendations: movies,
        confidence: 0.95
      }
    }
  }
}

// Register with Brainy
const brain = new BrainyData()
brain.register(new MovieRecommender())

Share with the community:

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

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

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

// 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: 9 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
• 🧩 Extensible: Augment with custom capabilities
• 📤 Portable: Export in any format (json, csv, graph)
• ⚡ 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 - Get up and running in 60 seconds
• Installation - Detailed installation instructions
• Architecture Overview - Design principles and philosophy

Core Documentation

• API Reference - Complete API documentation
• Augmentation Guide - Build your own augmentations
• CLI Reference - Command-line interface
• All Documentation - Browse all docs

Guides

• Search & Metadata - Advanced search
• Performance Optimization - Scale Brainy
• Production Deployment - Deploy to production
• Contributing Guidelines - 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
• 🐦 Twitter Updates
• 📧 Email Support
• 🎓 Video Tutorials

📈 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

---

🧠⚛️ Give Your Data a Brain Upgrade

Get Started • Examples • API Docs • Discord

⭐ Star us on GitHub to support open source AI! ⭐

Created and maintained by SoulCraft • 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.