Brainy

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.

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 ⭐ 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 or Benchmarks

---

See It In Action

30 seconds to understand why Brainy is different:

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

npm install @soulcraft/brainy

Your First Knowledge Graph (60 seconds)

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:

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.

👤 Individual Developer → Weekend Prototype

const brain = new Brainy()  // Zero config, starts in memory
await brain.init()

Perfect for: Hackathons, side projects, prototyping, learning

👥 Small Team → Production MVP

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

🏢 Growing Company → Multi-Million Scale

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

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 | Cost Optimization

🎯 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

⚡ Zero Configuration Philosophy

We hate configuration files. So we eliminated them.

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.

🚀 Git-Style Version Control — Database & Entity Level (v5.0.0+)

Clone your entire database in <100ms. Track every entity change. Full Git-style workflow.

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

• ✅ fork() - 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 features

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

→ See Full Documentation

---

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

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

🌐 Virtual Filesystem — Intelligent File Management

Build file explorers and IDEs that never crash:

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 →

🚀 Import Anything — CSV, Excel, PDF, URLs

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 →

🧠 Neural API — Advanced Semantic Analysis

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

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

Development → Just Works

const brain = new Brainy()  // Memory storage, zero config

Production → Persistence with Compression

const brain = new Brainy({
  storage: { type: 'filesystem', path: './data', compression: true }
})
// 60-80% space savings with gzip

Cloud → AWS, GCS, Azure, Cloudflare R2

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

🎯 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)

const brain = new Brainy({ hnsw: { typeAware: true } })

📖 How Type-Aware Indexing Works →

⚡ 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)

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

const stats = brain.getCacheStats()  // Performance insights

📖 Capacity Planning Guide →

---

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 → 📖 Natural Language Guide → 📖 API Reference: find() →

🗂️ Type-Aware Indexing & HNSW

Learn about our indexing architecture with measured performance optimizations:

📖 Data Storage Architecture → 📖 Architecture Overview →

📈 Scaling: Individual → Planet

Understand how the same code scales from prototype to billions of entities:

📖 Capacity Planning → 📖 Cloud Deployment Guide →

🎯 The Universal Type System

Explore the mathematical foundation: 42 nouns × 127 verbs = Stage 3 CANONICAL taxonomy:

📖 Noun-Verb Taxonomy →

---

CLI Tools

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 ⭐

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 ⭐ 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 find() method and Triple Intelligence queries

4. v4.0.0 Migration Guide

   • Upgrading from v3 (100% backward compatible)

🧠 Core Concepts & Architecture

• 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

☁️ Production & Operations

• Cloud Deployment Guide — Deploy to AWS, GCS, Azure
• Capacity Planning — Memory, storage, and scaling to billions
• Cost Optimization: AWS S3 | GCS | Azure | Cloudflare R2

🌐 Framework Integration

• Framework Integration Guide — React, Vue, Angular, Svelte
• Next.js Integration
• Vue.js Integration

🌳 Virtual Filesystem (VFS)

• VFS Quick Start — Build file explorers that never crash
• VFS Core Documentation
• Semantic VFS Guide — AI-powered file navigation
• Neural Extraction API

📦 Data Import & Processing

• 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

Bun 1.0+ (recommended) or Node.js 22 LTS

# Bun (recommended - best performance, single-binary deployment)
bun install @soulcraft/brainy

# Node.js (fully supported)
npm install @soulcraft/brainy

Why Bun? Brainy's Candle WASM engine works seamlessly with bun --compile for standalone binary deployment. No external model files, no runtime downloads.

---

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™