# Brainy
[](https://www.npmjs.com/package/@soulcraft/brainy)
[](https://www.npmjs.com/package/@soulcraft/brainy)
[](LICENSE)
[](https://www.typescriptlang.org/)
## The Knowledge Operating System
**Every piece of knowledge in your application โ living, connected, and intelligent.**
Stop fighting with vector databases, graph databases, and document stores. Stop stitching together Pinecone + Neo4j + MongoDB. **Brainy does all three, in one elegant API, from prototype to planet-scale.**
```javascript
const brain = new Brainy()
await brain.init()
// That's it. You now have semantic search, graph relationships,
// and document filtering. Zero configuration. Just works.
```
**Built by developers who were tired of:**
- Spending weeks configuring embeddings, indexes, and schemas
- Choosing between vector similarity OR graph relationships OR metadata filtering
- Rewriting everything when you need to scale from 1,000 to 1,000,000,000 entities
**Brainy makes the impossible simple: All three paradigms. One API. Any scale.**
---
## ๐ Choose Your Path
**New to Brainy? Pick your starting point:**
### ๐ Path 1: I want to build something NOW
**โ [Complete API Reference](docs/api/README.md)** โญ **Most developers start here** โญ
- Every method documented with examples
- Quick start in 60 seconds
- 1,870 lines of copy-paste ready code
- **This is your primary resource**
### ๐ง Path 2: I want to understand the big picture first
**โ Keep reading below** for demos, architecture, and use cases
### ๐ Path 3: I'm evaluating database options
**โ Jump to [Why Revolutionary](#why-brainy-is-revolutionary)** or **[Benchmarks](#benchmarks)**
---
## See It In Action
**30 seconds to understand why Brainy is different:**
```javascript
import { Brainy, NounType, VerbType } from '@soulcraft/brainy'
const brain = new Brainy()
await brain.init()
// Add knowledge with context
const reactId = await brain.add({
data: "React is a JavaScript library for building user interfaces",
type: NounType.Concept,
metadata: { category: "frontend", year: 2013 }
})
const nextId = await brain.add({
data: "Next.js framework for React with server-side rendering",
type: NounType.Concept,
metadata: { category: "framework", year: 2016 }
})
// Create relationships
await brain.relate({ from: nextId, to: reactId, type: VerbType.BuiltOn })
// NOW THE MAGIC: Query with natural language
const results = await brain.find({
query: "modern frontend frameworks", // ๐ Vector similarity
where: { year: { greaterThan: 2015 } }, // ๐ Document filtering
connected: { to: reactId, depth: 2 } // ๐ธ๏ธ Graph traversal
})
// ALL THREE PARADIGMS. ONE QUERY. 10ms response time.
```
**This is impossible with traditional databases.** Brainy makes it trivial.
---
## Quick Start
```bash
npm install @soulcraft/brainy
```
### Your First Knowledge Graph (60 seconds)
```javascript
import { Brainy, NounType, VerbType } from '@soulcraft/brainy'
const brain = new Brainy()
await brain.init()
// Add knowledge
const jsId = await brain.add({
data: "JavaScript is a programming language",
type: NounType.Concept,
metadata: { category: "language", year: 1995 }
})
const nodeId = await brain.add({
data: "Node.js runtime environment",
type: NounType.Concept,
metadata: { category: "runtime", year: 2009 }
})
// Create relationships
await brain.relate({ from: nodeId, to: jsId, type: VerbType.Executes })
// Query with Triple Intelligence
const results = await brain.find({
query: "JavaScript", // ๐ Vector
where: { category: "language" }, // ๐ Document
connected: { from: nodeId, depth: 1 } // ๐ธ๏ธ Graph
})
```
**Done.** No configuration. No complexity. Production-ready from day one.
**โ Ready to dive deeper? [Complete API Documentation](docs/api/README.md)** has every method with examples.
---
## From Prototype to Planet Scale
**The same API. Zero rewrites. Any scale.**
### ๐ค Individual Developer โ Weekend Prototype
```javascript
const brain = new Brainy() // Zero config, starts in memory
await brain.init()
```
**Perfect for:** Hackathons, side projects, prototyping, learning
### ๐ฅ Small Team โ Production MVP
```javascript
const brain = new Brainy({
storage: { type: 'filesystem', path: './data', compression: true }
})
```
**Scale:** Thousands to hundreds of thousands โข **Performance:** <5ms queries
### ๐ข Growing Company โ Multi-Million Scale
```javascript
const brain = new Brainy({
storage: { type: 's3', s3Storage: { bucketName: 'my-kb', region: 'us-east-1' } },
hnsw: { typeAware: true } // 87% memory reduction
})
```
**Scale:** Millions of entities โข **Performance:** <10ms queries, 12GB @ 10M entities
### ๐ Enterprise โ Billion+ Scale
```javascript
const brain = new Brainy({
storage: { type: 'gcs', gcsStorage: { bucketName: 'global-kb' } },
hnsw: { typeAware: true, M: 32, efConstruction: 400 }
})
```
**Scale:** Billions (tested @ 1B+) โข **Performance:** 18ms queries, 50GB memory
**Cost:** $138k/year โ $6k/year with intelligent tiering (96% savings)
**โ [Capacity Planning Guide](docs/operations/capacity-planning.md)** | **[Cost Optimization](docs/operations/)**
### ๐ฏ The Point
**Start simple. Scale infinitely. Never rewrite.**
Most systems make you choose: Simple (SQLite) OR Scalable (Kubernetes + 7 databases).
**Brainy gives you both.** Starts simple as SQLite. Scales like Google.
---
## Why Brainy Is Revolutionary
### ๐ง **Triple Intelligenceโข** โ The Impossible Made Possible
**The world's first to unify three database paradigms in ONE API:**
| What You Get | Like Having | But Unified |
|-------------|-------------|-------------|
| ๐ **Vector Search** | Pinecone, Weaviate | Find by meaning |
| ๐ธ๏ธ **Graph Relationships** | Neo4j, ArangoDB | Navigate connections |
| ๐ **Document Filtering** | MongoDB, Elasticsearch | Query metadata |
**Every other system makes you choose.** Brainy does all three together.
**Why this matters:** Your data isn't just vectors or just documents or just graphs. It's all three at once. A research paper is semantically similar to other papers (vector), written by an author (graph), and published in 2023 (document). **Brainy is the only system that understands this.**
### ๐ฏ **42 Noun Types ร 127 Verb Types = Universal Protocol**
Model **any domain** with mathematical completeness:
```
42 Nouns ร 127 Verbs ร โ Metadata = 5,334+ base combinations
Stage 3 CANONICAL: 96-97% coverage of all human knowledge
```
**Real-world expressiveness:**
- Healthcare: `Patient โ diagnoses โ Condition`
- Finance: `Account โ transfers โ Transaction`
- Manufacturing: `Product โ assembles โ Component`
- Education: `Student โ completes โ Course`
- **YOUR domain** โ Your types + relationships = Your knowledge graph
[โ See the Mathematical Proof](docs/architecture/noun-verb-taxonomy.md)
### โก **Zero Configuration Philosophy**
**We hate configuration files. So we eliminated them.**
```javascript
const brain = new Brainy() // Auto-detects everything
await brain.init() // Optimizes for your environment
```
Brainy automatically:
- Detects optimal storage (memory/filesystem/cloud)
- Configures memory based on available RAM
- Optimizes for containers (Docker/K8s)
- Tunes indexes for your data patterns
- Manages embedding models and caching
**You write business logic. Brainy handles infrastructure.**
### ๐ **Instant Forkโข** โ Git for Databases (v5.0.0)
**Clone your entire database in <100ms. Merge back when ready. Full Git-style workflow.**
```javascript
// Fork instantly - Snowflake-style copy-on-write
const experiment = await brain.fork('test-migration')
// Make changes safely in isolation
await experiment.add({ type: 'user', data: { name: 'Test User' } })
await experiment.updateAll({ /* migration logic */ })
// Commit your work
await experiment.commit({ message: 'Add test user', author: 'dev@example.com' })
// Merge back to main with conflict resolution
const result = await brain.merge('test-migration', 'main', {
strategy: 'last-write-wins'
})
console.log(result) // { added: 1, modified: 0, conflicts: 0 }
```
**NEW in v5.0.0:**
- โ
`fork()` - Instant clone in <100ms
- โ
`merge()` - Merge with conflict resolution
- โ
`commit()` - Snapshot state
- โ
`getHistory()` - View commit history
- โ
`checkout()`, `listBranches()` - Full branch management
- โ
CLI support for all features
**How it works:** Snowflake-style COW shares HNSW index structures, copying only modified nodes (10-20% memory overhead).
**Perfect for:** Safe migrations, A/B testing, feature branches, distributed development
[โ See Full Documentation](docs/features/instant-fork.md)
---
## What Can You Build?
**If your app needs to remember, understand, or connect information โ Brainy makes it trivial.**
### ๐ค **AI Agents with Perfect Memory**
Give your AI unlimited context that persists forever. Not just chat history โ true understanding of relationships, evolution, and meaning over time.
**Examples:** Personal assistants, code assistants, conversational AI, research agents
### ๐ **Living Documentation & Knowledge Bases**
Documentation that understands itself. Auto-links related concepts, detects outdated information, finds connections across your entire knowledge base.
**Examples:** Internal wikis, research platforms, smart documentation, learning systems
### ๐ **Semantic Search at Any Scale**
Find by meaning, not keywords. Search codebases, research papers, customer data, or media libraries with natural language.
**Examples:** Code search, research platforms, content discovery, recommendation engines
### ๐ข **Enterprise Knowledge Management**
Corporate memory that never forgets. Track every customer interaction, product evolution, and business relationship.
**Examples:** CRM systems, product catalogs, customer intelligence, institutional knowledge
### ๐ฎ **Rich Interactive Experiences**
NPCs that remember. Characters that persist across stories. Worlds that evolve based on real relationships.
**Examples:** Game worlds, interactive fiction, educational platforms, creative tools
### ๐จ **Content & Media Platforms**
Every asset knows its relationships. Intelligent tagging, similarity-based discovery, and relationship-aware management.
**Examples:** DAM systems, media libraries, writing assistants, content management
**The pattern:** Knowledge that needs to live, connect, and evolve. That's what Brainy was built for.
---
## Core Features
### ๐ง **Natural Language Queries**
```javascript
// Ask naturally - Brainy understands
await brain.find("recent React components with tests")
await brain.find("JavaScript libraries similar to Vue")
// Or use structured Triple Intelligence queries
await brain.find({
query: "React",
where: { type: "library", year: { greaterThan: 2020 } },
connected: { to: "JavaScript", depth: 2 }
})
```
**โ [See all query methods in API Reference](docs/api/README.md#search--query)**
### ๐ **Virtual Filesystem** โ Intelligent File Management
Build file explorers and IDEs that never crash:
```javascript
const vfs = brain.vfs()
// Tree-aware operations prevent infinite recursion
const tree = await vfs.getTreeStructure('/projects', { maxDepth: 3 })
// Semantic file search
const reactFiles = await vfs.search('React components with hooks')
```
**[๐ VFS Quick Start โ](docs/vfs/QUICK_START.md)** | **[Common Patterns โ](docs/vfs/COMMON_PATTERNS.md)** | **[Neural Extraction โ](docs/vfs/NEURAL_EXTRACTION.md)**
### ๐ **Import Anything** โ CSV, Excel, PDF, URLs
```javascript
await brain.import('customers.csv') // Auto-detects everything
await brain.import('sales-data.xlsx', { excelSheets: ['Q1', 'Q2'] })
await brain.import('research-paper.pdf', { pdfExtractTables: true })
await brain.import('https://api.example.com/data.json')
```
**[๐ Complete Import Guide โ](docs/guides/import-anything.md)**
### ๐ง **Neural API** โ Advanced Semantic Analysis
```javascript
// Clustering, similarity, outlier detection, visualization
const clusters = await brain.neural.clusters({ algorithm: 'kmeans' })
const similarity = await brain.neural.similar('item1', 'item2')
const outliers = await brain.neural.outliers(0.3)
const vizData = await brain.neural.visualize({ maxNodes: 100 })
```
---
## Framework Integration
**Works with any modern framework.** React, Vue, Angular, Svelte, Solid.js โ your choice.
```javascript
// React
const [brain] = useState(() => new Brainy())
useEffect(() => { brain.init() }, [])
// Vue
async mounted() { this.brain = await new Brainy().init() }
// Angular
@Injectable() export class BrainyService { brain = new Brainy() }
```
**Supports:** All bundlers (Webpack, Vite, Rollup) โข SSR/SSG โข Edge runtimes โข Browser/Node.js
**[๐ Framework Integration Guide โ](docs/guides/framework-integration.md)** | **[Next.js โ](docs/guides/nextjs-integration.md)** | **[Vue โ](docs/guides/vue-integration.md)**
---
## Storage โ From Memory to Planet-Scale
### Development โ Just Works
```javascript
const brain = new Brainy() // Memory storage, zero config
```
### Production โ Persistence with Compression
```javascript
const brain = new Brainy({
storage: { type: 'filesystem', path: './data', compression: true }
})
// 60-80% space savings with gzip
```
### Cloud โ AWS, GCS, Azure, Cloudflare R2
```javascript
// AWS S3 / Cloudflare R2
const brain = new Brainy({
storage: {
type: 's3',
s3Storage: {
bucketName: 'my-knowledge-base',
region: 'us-east-1'
}
}
})
// Enable Intelligent-Tiering: 96% cost savings
await brain.storage.enableIntelligentTiering('entities/', 'auto-tier')
```
**Cost optimization at scale:**
| Scale | Standard | With Intelligent Tiering | Annual Savings |
|-------|----------|--------------------------|----------------|
| 5TB | $1,380 | $59 | $1,321 (96%) |
| 50TB | $13,800 | $594 | $13,206 (96%) |
| 500TB | $138,000 | $5,940 | $132,060 (96%) |
**[๐ Cloud Storage Guide โ](docs/deployment/CLOUD_DEPLOYMENT_GUIDE.md)** | **[AWS Cost Optimization โ](docs/operations/cost-optimization-aws-s3.md)** | **[GCS โ](docs/operations/cost-optimization-gcs.md)** | **[Azure โ](docs/operations/cost-optimization-azure.md)**
---
## Production Features
### ๐ฏ Type-Aware HNSW Indexing
Efficient type-based organization for large-scale deployments:
- **Type-based queries:** Faster via directory structure (measured at 1K-1M scale)
- **Type count tracking:** 284 bytes (Uint32Array, measured)
- **Billion-scale projections:** NOT tested at 1B entities (extrapolated from 1M)
```javascript
const brain = new Brainy({ hnsw: { typeAware: true } })
```
**[๐ How Type-Aware Indexing Works โ](docs/architecture/data-storage-architecture.md)**
### โก Enterprise-Ready Operations (v4.0.0)
- **Batch operations** with retry logic (1000x faster deletes)
- **Gzip compression** (60-80% space savings)
- **OPFS quota monitoring** (browser storage)
- **Metadata/Vector separation** (billion-entity scalability)
- **Circuit breakers & backpressure** (enterprise reliability)
```javascript
// Batch operations
await brain.storage.batchDelete(keys, { maxRetries: 3 })
// Monitor storage
const status = await brain.storage.getStorageStatus()
```
### ๐ Adaptive Memory Management
Auto-scales 2GB โ 128GB+ based on environment:
- Container-aware (Docker/K8s cgroups)
- Environment-optimized (dev/staging/production)
- Built-in cache monitoring with tuning recommendations
```javascript
const stats = brain.getCacheStats() // Performance insights
```
**[๐ Capacity Planning Guide โ](docs/operations/capacity-planning.md)**
---
## Benchmarks
| Operation | Performance | Memory |
|-----------|-------------|--------|
| Initialize | 450ms | 24MB |
| Add entity | 12ms | +0.1MB |
| Vector search (1K) | 3ms | - |
| Metadata filter (10K) | 0.8ms | - |
| Bulk import (1K) | 2.3s | +8MB |
| **10M entities** | **5.8ms** | **12GB** |
| **1B entities** | **18ms** | **50GB** |
---
## ๐ง Deep Dive: How Brainy Actually Works
**Want to understand the magic under the hood?**
### ๐ Triple Intelligence & find() API
Understand how vector search, graph relationships, and document filtering work together in one unified query:
**[๐ Triple Intelligence Architecture โ](docs/architecture/triple-intelligence.md)**
**[๐ Natural Language Guide โ](docs/guides/natural-language.md)**
**[๐ API Reference: find() โ](docs/api/README.md)**
### ๐๏ธ Type-Aware Indexing & HNSW
Learn about our indexing architecture with measured performance optimizations:
**[๐ Data Storage Architecture โ](docs/architecture/data-storage-architecture.md)**
**[๐ Architecture Overview โ](docs/architecture/overview.md)**
### ๐ Scaling: Individual โ Planet
Understand how the same code scales from prototype to billions of entities:
**[๐ Capacity Planning โ](docs/operations/capacity-planning.md)**
**[๐ Cloud Deployment Guide โ](docs/deployment/CLOUD_DEPLOYMENT_GUIDE.md)**
### ๐ฏ The Universal Type System
Explore the mathematical foundation: 42 nouns ร 127 verbs = Stage 3 CANONICAL taxonomy:
**[๐ Noun-Verb Taxonomy โ](docs/architecture/noun-verb-taxonomy.md)**
---
## CLI Tools
```bash
npm install -g brainy
brainy add "JavaScript is awesome" --metadata '{"type":"opinion"}'
brainy find "awesome programming languages"
brainy search "programming"
```
47 commands available, including storage management, imports, and neural operations.
---
## ๐ Complete Documentation
**For most developers:** Start with the **[Complete API Reference](docs/api/README.md)** โญ
This comprehensive guide includes:
- โ
Every method with parameters, returns, and examples
- โ
Quick start in 60 seconds
- โ
Core CRUD โ Advanced features (branching, versioning, time-travel)
- โ
TypeScript types and patterns
- โ
1,870 lines of copy-paste ready code
---
### ๐ฏ Essential Reading (Start Here)
1. **[๐ Complete API Reference](docs/api/README.md)** โญ **START HERE** โญ
- Your primary resource for building with Brainy
- Every method documented with working examples
2. **[Natural Language Queries](docs/guides/natural-language.md)**
- Master the `find()` method and Triple Intelligence queries
3. **[v4.0.0 Migration Guide](docs/MIGRATION-V3-TO-V4.md)**
- Upgrading from v3 (100% backward compatible)
### ๐ง Core Concepts & Architecture
- **[Triple Intelligence Architecture](docs/architecture/triple-intelligence.md)** โ How vector + graph + document work together
- **[Noun-Verb Taxonomy](docs/architecture/noun-verb-taxonomy.md)** โ The universal type system (42 nouns ร 127 verbs)
- **[Architecture Overview](docs/architecture/overview.md)** โ System design and components
- **[Data Storage Architecture](docs/architecture/data-storage-architecture.md)** โ Type-aware indexing and HNSW
### โ๏ธ Production & Operations
- **[Cloud Deployment Guide](docs/deployment/CLOUD_DEPLOYMENT_GUIDE.md)** โ Deploy to AWS, GCS, Azure
- **[Capacity Planning](docs/operations/capacity-planning.md)** โ Memory, storage, and scaling to billions
- **Cost Optimization:** **[AWS S3](docs/operations/cost-optimization-aws-s3.md)** | **[GCS](docs/operations/cost-optimization-gcs.md)** | **[Azure](docs/operations/cost-optimization-azure.md)** | **[Cloudflare R2](docs/operations/cost-optimization-cloudflare-r2.md)**
### ๐ Framework Integration
- **[Framework Integration Guide](docs/guides/framework-integration.md)** โ React, Vue, Angular, Svelte
- **[Next.js Integration](docs/guides/nextjs-integration.md)**
- **[Vue.js Integration](docs/guides/vue-integration.md)**
### ๐ณ Virtual Filesystem (VFS)
- **[VFS Quick Start](docs/vfs/QUICK_START.md)** โ Build file explorers that never crash
- **[VFS Core Documentation](docs/vfs/VFS_CORE.md)**
- **[Semantic VFS Guide](docs/vfs/SEMANTIC_VFS.md)** โ AI-powered file navigation
- **[Neural Extraction API](docs/vfs/NEURAL_EXTRACTION.md)**
### ๐ฆ Data Import & Processing
- **[Import Anything Guide](docs/guides/import-anything.md)** โ CSV, Excel, PDF, URLs with auto-detection
---
## What's New in v4.0.0
**Enterprise-scale cost optimization and performance improvements:**
- ๐ฏ **96% cloud storage cost savings** with intelligent tiering (AWS, GCS, Azure)
- โก **1000x faster batch deletions** (533 entities/sec vs 0.5/sec)
- ๐ฆ **60-80% compression** with gzip (FileSystem storage)
- ๐ **Enhanced metadata/vector separation** for billion-scale deployments
**[๐ Full v4.0.0 Changelog โ](CHANGELOG.md)** | **[Migration Guide โ](docs/MIGRATION-V3-TO-V4.md)** (100% backward compatible)
---
## Requirements
**Node.js 22 LTS** (recommended) or **Node.js 20 LTS**
```bash
nvm use # We provide .nvmrc
```
---
## Why Brainy Exists
**The Vision:** Traditional systems force you to choose between vector databases, graph databases, and document stores. You need all three, but combining them is complex and fragile.
**Brainy solved the impossible:** One API. All three paradigms. Any scale.
Like HTTP standardized web communication, **Brainy standardizes knowledge representation.** One protocol that any AI model understands. One system that scales from prototype to planet.
**[๐ Read the Mathematical Proof โ](docs/architecture/noun-verb-taxonomy.md)**
---
## Enterprise & Support
**๐ข Brain Cloud** โ Managed Brainy with team sync, persistent memory, and enterprise connectors.
Visit **[soulcraft.com](https://soulcraft.com)** for more information.
**๐ Support Development:**
- โญ Star us on **[GitHub](https://github.com/soulcraftlabs/brainy)**
- ๐ Sponsor via **[GitHub Sponsors](https://github.com/sponsors/soulcraftlabs)**
- ๐ Report issues and contribute code
- ๐ฃ Share with your team and community
**Brainy is 100% free and open source.** No paywalls, no premium tiers, no feature gates.
---
## Contributing
We welcome contributions! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for guidelines.
---
## License
MIT ยฉ Brainy Contributors
---
Built with โค๏ธ by the Brainy community
The Knowledge Operating System
From prototype to planet-scale โข Zero configuration โข Triple Intelligenceโข