@soulcraft/brainy
v7.15.5TypeScript
Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. Stage 3 CANONICAL: 42 nouns × 127 verbs covering 96-97% of all human knowledge.
ai-databasevector-databasegraph-databasefield-filteringtriple-intelligencehnswembeddingssemantic-searchmachine-learningartificial-intelligence
791/weekUpdated 6 days agoMITUnpacked: 97.8 MB
Published by Brainy Contributors
npm install @soulcraft/brainyBrainy
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:
$3
→ Full Documentation ⭐ Most developers start here ⭐
- Interactive API reference with examples
- Quick start guides and tutorials
- Copy-paste ready code snippets
- This is your primary resource
$3
→ Keep reading below for demos, architecture, and use cases
$3
→ Jump to Why Revolutionary or 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
$3
`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 has every method with examples.
---
Entity Extraction (NEW in v5.7.6)
Extract entities from text with AI-powered classification:
`javascript
import { Brainy, NounType } from '@soulcraft/brainy'
const brain = new Brainy()
await brain.init()
// Extract all entities
const entities = await brain.extractEntities('John Smith founded Acme Corp in New York')
// Returns:
// [
// { text: 'John Smith', type: NounType.Person, confidence: 0.95 },
// { text: 'Acme Corp', type: NounType.Organization, confidence: 0.92 },
// { text: 'New York', type: NounType.Location, confidence: 0.88 }
// ]
// Extract with filters
const people = await brain.extractEntities(resume, {
types: [NounType.Person],
confidence: 0.8
})
// Advanced: Direct access to extractors
import { SmartExtractor } from '@soulcraft/brainy'
const extractor = new SmartExtractor(brain, { minConfidence: 0.7 })
const result = await extractor.extract('CEO', {
formatContext: { format: 'excel', columnHeader: 'Title' }
})
`
Features:
- 🎯 4-Signal Ensemble - ExactMatch (40%) + Embedding (35%) + Pattern (20%) + Context (5%)
- 📊 Format Intelligence - Adapts to Excel, CSV, PDF, YAML, DOCX, JSON, Markdown
- ⚡ Fast - ~15-20ms per extraction with LRU caching
- 🌍 42 Types - Person, Organization, Location, Document, and 38 more
→ Neural Extraction Guide | Import Preview Mode
---
From Prototype to Planet Scale
The same API. Zero rewrites. Any scale.
$3
`
javascript
const brain = new Brainy() // Zero config, starts in memory
await brain.init()
`
Perfect for: Hackathons, side projects, prototyping, learning$3
javascript
const brain = new Brainy({
storage: { type: 'filesystem', path: './data', compression: true }
})
`
Scale: Thousands to hundreds of thousands • Performance: <5ms queries
→ Production Service Architecture — Singleton patterns, caching, and scaling for Bun/Node.js services$3
javascript
const brain = new Brainy({
storage: { type: 's3', s3Storage: { bucketName: 'my-kb', region: 'us-east-1' } },
hnsw: { typeAware: true }
})
`
Scale: Millions of entities • Performance: <10ms queries (measured at 1M scale)$3
javascript
const brain = new Brainy({
storage: { type: 'gcs', gcsStorage: { bucketName: 'global-kb' } },
hnsw: { typeAware: true, M: 32, efConstruction: 400 }
})
`
Scale: PROJECTED billion+ (extrapolated from 10M tests, not tested at 1B)
Cost: $138k/year → $6k/year with intelligent tiering (96% savings)→ Capacity Planning Guide | Cost Optimization
$3
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
$3
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.
$3
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:
- Finance:
- Manufacturing:
- Education:
- YOUR domain → Your types + relationships = Your knowledge graph$3
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.
$3
Clone your entire database in <100ms. Track every entity change. 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' })
// Switch to experimental branch to make it active
await brain.checkout('test-migration')
// Time-travel: Query database at any past commit (read-only)
const commits = await brain.getHistory({ limit: 10 })
const snapshot = await brain.asOf(commits[5].id)
const pastResults = await snapshot.find({ query: 'historical data' })
await snapshot.close()
// Entity versioning: Track changes to individual entities (v5.3.0+)
const userId = await brain.add({ type: 'user', data: { name: 'Alice' } })
await brain.versions.save(userId, { tag: 'v1.0', description: 'Initial profile' })
await brain.update(userId, { data: { name: 'Alice Smith', role: 'admin' } })
await brain.versions.save(userId, { tag: 'v2.0', description: 'Added role' })
// Compare versions or restore previous state
const diff = await brain.versions.compare(userId, 1, 2) // See what changed
await brain.versions.restore(userId, 1) // Restore v1.0
`Database-level version control (v5.0.0):
- ✅
- Instant clone in <100ms
- ✅ merge() - Merge with conflict resolution
- ✅ commit() - Snapshot state
- ✅ asOf() - Time-travel queries (query at any commit)
- ✅ getHistory() - View commit history
- ✅ checkout(), listBranches() - Full branch management
- ✅ CLI support for all featuresEntity-level version control (v5.3.0):
- ✅
versions.save() - Save entity snapshots with tags
- ✅ versions.restore() - Restore previous versions
- ✅ versions.compare() - Diff between versions
- ✅ versions.list() - View version history
- ✅ Automatic deduplication (content-addressable storage)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, time-travel debugging, audit trails, document versioning, compliance tracking
---
What Can You Build?
If your app needs to remember, understand, or connect information — Brainy makes it trivial.
$3
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
$3
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
$3
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
$3
Corporate memory that never forgets. Track every customer interaction, product evolution, and business relationship.Examples: CRM systems, product catalogs, customer intelligence, institutional knowledge
$3
NPCs that remember. Characters that persist across stories. Worlds that evolve based on real relationships.Examples: Game worlds, interactive fiction, educational platforms, creative tools
$3
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
$3
`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
$3
Automatically combines text (keyword) and semantic (vector) search for optimal results:
javascript
// Just works - no configuration needed
const results = await brain.find({ query: 'David Smith' })
// Finds exact text matches AND semantically similar content// Override when needed
await brain.find({ query: 'exact match', searchMode: 'text' }) // Text only
await brain.find({ query: 'AI concepts', searchMode: 'semantic' }) // Semantic only
await brain.find({ query: 'hybrid', hybridAlpha: 0.3 }) // Custom weighting
// Highlight structured content (v7.8.0) — plain text, JSON, HTML, Markdown
const highlights = await brain.highlight({
query: 'warrior',
text: entity.data // Auto-detects TipTap, Slate, Lexical, HTML, Markdown
})
// Each highlight has: text, score, position, matchType, contentCategory
`$3
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 → | Common Patterns → | Neural Extraction →
$3
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')
`$3
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 → | Next.js → | Vue →
---
Storage — From Memory to Planet-Scale
$3
javascript
const brain = new Brainy() // Memory storage, zero config
`$3
javascript
const brain = new Brainy({
storage: { type: 'filesystem', path: './data', compression: true }
})
// 60-80% space savings with gzip
`$3
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 → | AWS Cost Optimization → | GCS → | Azure →
---
Production Features
$3
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 →
$3
- 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()
`$3
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
`$3
Install
for Rust-powered native acceleration: SIMD distance calculations, native metadata/graph indexes, CRoaring bitmaps, and Candle ML embeddings.`bash
npm install @soulcraft/cortex
`typescript
const brain = new Brainy({
plugins: ['@soulcraft/cortex']
})
await brain.init()
// [brainy] Plugin activated: @soulcraft/cortex
`Plugins are opt-in — brainy never auto-imports packages unless you list them in
.---
Benchmarks
| Operation | Performance | Memory | Notes |
|-----------|-------------|--------|-------|
| Initialize | 450ms | 24MB | Measured |
| Add entity | 12ms | +0.1MB | Measured |
| Vector search (1K) | 3ms | - | Measured |
| Metadata filter (10K) | 0.8ms | - | Measured |
| Bulk import (1K) | 2.3s | +8MB | Measured |
| 10M entities | 5.8ms | 12GB | Measured |
| 1B entities | ~18ms | ~50GB | PROJECTED (extrapolated from 10M) |
---
🧠 Deep Dive: How Brainy Actually Works
Want to understand the magic under the hood?
$3
Understand how vector search, graph relationships, and document filtering work together in one unified query:📖 Triple Intelligence Architecture →
📖 Natural Language Guide →
📖 API Reference: find() →
$3
Learn about our indexing architecture with measured performance optimizations:📖 Data Storage Architecture →
📖 Architecture Overview →
$3
Understand how the same code scales from prototype to billions of entities:📖 Capacity Planning →
📖 Cloud Deployment Guide →
$3
Explore the mathematical foundation: 42 nouns × 127 verbs = Stage 3 CANONICAL taxonomy:---
CLI Tools
`bash
npm install -g brainybrainy 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 ⭐
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
---
$3
1. 📖 Complete API Reference ⭐ START HERE ⭐
- Your primary resource for building with Brainy
- Every method documented with working examples
2. Filter & Query Syntax Guide
- Complete reference for operators, compound filters, and optimization tips
3. Natural Language Queries
- Master the
method and Triple Intelligence queries4. v4.0.0 Migration Guide
- Upgrading from v3 (100% backward compatible)
$3
- Triple Intelligence Architecture — How vector + graph + document work together
- Noun-Verb Taxonomy — The universal type system (42 nouns × 127 verbs)
- Transactions — Atomic operations with automatic rollback
- Architecture Overview — System design and components
- Data Storage Architecture — Type-aware indexing and HNSW
$3
- Cloud Deployment Guide — Deploy to AWS, GCS, Azure
- Capacity Planning — Memory, storage, and scaling to billions
- Cost Optimization: AWS S3 | GCS | Azure | Cloudflare R2
$3
- Framework Integration Guide — React, Vue, Angular, Svelte
- Next.js Integration
- Vue.js Integration
$3
- VFS Quick Start — Build file explorers that never crash
- VFS Core Documentation
- Semantic VFS Guide — AI-powered file navigation
- Neural Extraction API
$3
- Import Anything Guide — 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 → | Migration Guide → (100% backward compatible)
---
Requirements
> Deprecation Notice: Browser support (OPFS storage, Web Workers, WASM embeddings) is deprecated in v7.10.0 and will be removed in v8.0.0. Brainy v8+ will be server-only (Node.js >= 22, Bun >= 1.3.0). Migrate browser deployments to a server-side API.
Bun 1.0+ (recommended) or Node.js 22 LTS
`bash
Bun (recommended - best performance, single-binary deployment)
bun install @soulcraft/brainyNode.js (fully supported)
npm install @soulcraft/brainy
`> Why Bun? Brainy's Candle WASM engine works seamlessly with
---
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 →
---
Enterprise & Support
🏢 Brain Cloud — Managed Brainy with team sync, persistent memory, and enterprise connectors.
Visit soulcraft.com for more information.
💖 Support Development:
- ⭐ Star us on GitHub
- 💝 Sponsor via GitHub Sponsors
- 🐛 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 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™