brainy/docs/README.md

Brainy Documentation

The multi-dimensional AI database with Triple Intelligence — vector search, graph traversal, and metadata filtering in one unified API.

Quick Start

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

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

// Add entities — data is embedded for semantic search, metadata is indexed for filtering
const id = await brain.add({
  data: 'Revolutionary AI Breakthrough',
  type: NounType.Document,
  metadata: { category: 'technology', rating: 4.8 }
})

// Search with Triple Intelligence
const results = await brain.find({
  query: 'artificial intelligence',              // Semantic search (on data)
  where: { rating: { greaterThan: 4.0 } },       // Metadata filter
  connected: { from: authorId, depth: 2 }         // Graph traversal
})

---

Core Documentation

Document	Description
API Reference	Complete API documentation — start here
Data Model	Entity structure, data vs metadata, storage fields
Query Operators	All BFO operators with examples and indexed/in-memory matrix
Find System	Natural language find() and hybrid search details
Consistency Model	The Db API guarantees — snapshot isolation, atomic transactions, time travel

---

Architecture

Document	Description
Architecture Overview	High-level system design
Triple Intelligence	Vector + Graph + Metadata unified query
Noun-Verb Taxonomy	42 nouns + 127 verbs type system
Stage 3 Canonical Taxonomy	Complete type reference
Storage Architecture	Storage adapters and optimization
Index Architecture	Vector, Graph, and Metadata indexing
Zero Configuration	Auto-adapts to any environment

---

Virtual Filesystem (VFS)

Document	Description
VFS Quick Start	Get started in 30 seconds
VFS Core	Core concepts and architecture
VFS API Guide	Complete VFS API reference
Common Patterns	VFS usage patterns

See vfs/ for the complete VFS documentation set.

---

Guides

Document	Description
Import Anything	CSV, Excel, PDF, URL imports
Snapshots & Time Travel	Backups, restore, what-if analysis, audit trails
Natural Language	Query in plain English
Neural API	AI-powered features
Enterprise for Everyone	No limits, no tiers
Framework Integration	React, Vue, Angular, Svelte

---

Storage & Deployment

Document	Description
Storage Architecture	Filesystem and memory adapters, on-disk artifact layout, operator-layer backup
Extending Storage	Create custom storage adapters
Capacity Planning	Scale to millions of entities

---

Plugins

Document	Description
Plugins	Plugin system overview — providers, plugins config, brain.use()

---

Performance & Scaling

Document	Description
Performance	Optimization techniques
Scaling	Scale to billions of entities
Batching	Batch operations guide

---

Migration & Reference

Document	Description
v3 to v4 Migration	Upgrade guide
Release Guide	How to release new versions
Production Architecture	Ops reference

---

Internal

Document	Description
Audit Report	Feature audit
Honest Status	Actual implementation status

---

License

Brainy is MIT licensed. See LICENSE for details.