[](LICENSE)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](CONTRIBUTING.md)
**A powerful graph & vector data platform for AI applications across any environment**
## โจ 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.
### ๐ Why Developers Love Brainy
- **๐ง It Just Worksโข** - 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 React, Angular, Vue, Node.js, Deno, Bun, serverless, edge workers, and even vanilla HTML
- **โก Scary Fast** - Handles millions of vectors with sub-millisecond search. Built-in GPU acceleration when available
- **๐ฏ 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
## ๐ Quick Start (30 seconds!)
### Node.js TLDR
```bash
# Install
npm install brainy
# Use it
```
```javascript
import { createAutoBrainy, NounType, VerbType } from 'brainy'
const brainy = createAutoBrainy()
// Add data with Nouns (entities)
const catId = await brainy.add("Siamese cats are elegant and vocal", {
noun: NounType.Thing,
breed: "Siamese",
category: "animal"
})
const ownerId = await brainy.add("John loves his pets", {
noun: NounType.Person,
name: "John Smith"
})
// Connect with Verbs (relationships)
await brainy.addVerb(ownerId, catId, {
verb: VerbType.Owns,
since: "2020-01-01"
})
// Search by meaning
const results = await brainy.searchText("feline companions", 5)
// Search JSON documents by specific fields
const docs = await brainy.searchDocuments("Siamese", {
fields: ['breed', 'category'], // Search these fields
weights: { breed: 2.0 }, // Prioritize breed matches
limit: 10
})
// Find relationships
const johnsPets = await brainy.getVerbsBySource(ownerId, VerbType.Owns)
```
That's it! No config, no setup, it just worksโข
## ๐ญ Key Features
### Core Capabilities
- **Vector Search** - Find semantically similar content using embeddings
- **Graph Relationships** - Connect data with meaningful relationships
- **JSON Document Search** - Search within specific fields with prioritization
- **Real-Time Syncing** - WebSocket and WebRTC for distributed instances
- **Streaming Pipeline** - Process data in real-time as it flows through
- **Model Control Protocol** - Let AI models access your data
### Smart Optimizations
- **Auto-Configuration** - Detects environment and optimizes automatically
- **Adaptive Learning** - Gets smarter with usage, optimizes itself over time
- **Intelligent Partitioning** - Semantic clustering with auto-tuning
- **Multi-Level Caching** - Hot/warm/cold caching with predictive prefetching
- **Memory Optimization** - 75% reduction with compression for large datasets
### Developer Experience
- **TypeScript Support** - Fully typed API with generics
- **Extensible Augmentations** - Customize and extend functionality
- **REST API** - Web service wrapper for HTTP endpoints
- **Auto-Complete** - IntelliSense for all APIs and types
## ๐ฆ Installation
### Main Package
```bash
npm install brainy
```
### Optional: Offline Models Package
```bash
npm install @soulcraft/brainy-models
```
The `@soulcraft/brainy-models` package provides **offline access** to the Universal Sentence Encoder model, eliminating network dependencies and ensuring consistent performance. Perfect for:
- **Air-gapped environments** - No internet? No problem
- **Consistent performance** - No network latency or throttling
- **Privacy-focused apps** - Keep everything local
- **High-reliability systems** - No external dependencies
```javascript
import { createAutoBrainy } from 'brainy'
import { BundledUniversalSentenceEncoder } from '@soulcraft/brainy-models'
// Use the bundled model for offline operation
const brainy = createAutoBrainy({
embeddingModel: BundledUniversalSentenceEncoder
})
```
## ๐จ 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
## ๐งฌ The Power of Nouns & Verbs
Brainy uses a **graph-based data model** that mirrors how humans think - with **Nouns** (entities) connected by **Verbs** (relationships). This isn't just vectors in a void; it's structured, meaningful data.
### ๐ Nouns (What Things Are)
Nouns are your entities - the "things" in your data. Each noun has:
- A unique ID
- A vector representation (for similarity search)
- A type (Person, Document, Concept, etc.)
- Custom metadata
**Available Noun Types:**
| Category | Types | Use For |
|----------|-------|---------|
| **Core Entities** | `Person`, `Organization`, `Location`, `Thing`, `Concept`, `Event` | People, companies, places, objects, ideas, happenings |
| **Digital Content** | `Document`, `Media`, `File`, `Message`, `Content` | PDFs, images, videos, emails, posts, generic content |
| **Collections** | `Collection`, `Dataset` | Groups of items, structured data sets |
| **Business** | `Product`, `Service`, `User`, `Task`, `Project` | E-commerce, SaaS, project management |
| **Descriptive** | `Process`, `State`, `Role` | Workflows, conditions, responsibilities |
### ๐ Verbs (How Things Connect)
Verbs are your relationships - they give meaning to connections. Not just "these vectors are similar" but "this OWNS that" or "this CAUSES that".
**Available Verb Types:**
| Category | Types | Examples |
|----------|-------|----------|
| **Core** | `RelatedTo`, `Contains`, `PartOf`, `LocatedAt`, `References` | Generic relations, containment, location |
| **Temporal** | `Precedes`, `Succeeds`, `Causes`, `DependsOn`, `Requires` | Time sequences, causality, dependencies |
| **Creation** | `Creates`, `Transforms`, `Becomes`, `Modifies`, `Consumes` | Creation, change, consumption |
| **Ownership** | `Owns`, `AttributedTo`, `CreatedBy`, `BelongsTo` | Ownership, authorship, belonging |
| **Social** | `MemberOf`, `WorksWith`, `FriendOf`, `Follows`, `Likes`, `ReportsTo` | Social networks, organizations |
| **Functional** | `Describes`, `Implements`, `Validates`, `Triggers`, `Serves` | Functions, implementations, services |
### ๐ก Why This Matters
```javascript
// Traditional vector DB: Just similarity
const similar = await vectorDB.search(embedding, 10)
// Result: [vector1, vector2, ...] - What do these mean? ๐คท
// Brainy: Similarity + Meaning + Relationships
const catId = await brainy.add("Siamese cat", {
noun: NounType.Thing,
breed: "Siamese"
})
const ownerId = await brainy.add("John Smith", {
noun: NounType.Person
})
await brainy.addVerb(ownerId, catId, {
verb: VerbType.Owns,
since: "2020-01-01"
})
// Now you can search with context!
const johnsPets = await brainy.getVerbsBySource(ownerId, VerbType.Owns)
const catOwners = await brainy.getVerbsByTarget(catId, VerbType.Owns)
```
## ๐ค Why Choose Brainy?
### vs. Traditional Databases
โ **PostgreSQL with pgvector** - Requires complex setup, tuning, and DevOps expertise
โ **Brainy** - Zero config, auto-optimizes, works everywhere from browser to cloud
### vs. Vector Databases
โ **Pinecone/Weaviate/Qdrant** - Cloud-only, expensive, vendor lock-in
โ **Brainy** - Run locally, in browser, or cloud. Your choice, your data
### vs. Graph Databases
โ **Neo4j** - Great for graphs, no vector support
โ **Brainy** - Vectors + graphs in one. Best of both worlds
### vs. DIY Solutions
โ **Building your own** - Months of work, optimization nightmares
โ **Brainy** - Production-ready in 30 seconds
## ๐ Getting Started in 30 Seconds
### React
```jsx
import { createAutoBrainy } from 'brainy'
import { useEffect, useState } from 'react'
function SemanticSearch() {
const [brainy] = useState(() => createAutoBrainy())
const [results, setResults] = useState([])
const search = async (query) => {
const items = await brainy.searchText(query, 10)
setResults(items)
}
return (
search(e.target.value)}
placeholder="Search by meaning..." />
)
}
```
### Angular
```typescript
import { Component, OnInit } from '@angular/core'
import { createAutoBrainy } from 'brainy'
@Component({
selector: 'app-search',
template: `
