David Snelling
478fa176f2
The legacy backup/import/export/stats facade (src/api/DataAPI.ts) drifted from the modern entity shape and every job it did now has a first-class surface. Delete it and brain.data(), and rewire the CLI: - data-stats → brain.stats() (full BrainyStats report: per-type breakdowns, indexed fields, index health, storage backend, writer lock, version) - clean → brain.clear() - export → alias of snapshot; a db.persist() snapshot is the full-fidelity export format (open with Brainy.load, load wholesale with brainy restore); external data ingestion remains brainy import (UniversalImportAPI) Rewiring clean onto brain.clear() exposed two real bugs, both fixed: - clear() left this.graphIndex undefined forever — any graph-touching call afterwards (relate, getNeighbors, stats) crashed. clear() now re-resolves the graph index exactly as init() does and re-wires the shared UUID↔int resolver, and re-resolves the metadata index with the same provider fallback as init(). - storage.clear() reset the legacy totals but not the per-type/subtype count rollups or id→type caches, so stats() reported phantom counts for deleted entities. Both adapters now delegate derived-state reset to reloadDerivedState(), the same path restore-from-snapshot uses. One-shot CLI commands (data-stats, clean, snapshot/export, restore, history, generation) now close the brain and exit explicitly — global cache timers otherwise keep the process alive holding the writer lock. Verified: build clean, 1383/1383 unit tests, 24/24 db-mvcc integration, plus an end-to-end CLI smoke (add → data-stats → export → clean → data-stats). |
||
|---|---|---|
| .. | ||
| api | ||
| architecture | ||
| augmentations | ||
| concepts | ||
| features | ||
| guides | ||
| operations | ||
| vfs | ||
| ADR-001-generational-mvcc.md | ||
| BATCHING.md | ||
| CREATING-AUGMENTATIONS.md | ||
| DATA_MODEL.md | ||
| DEVELOPER_LEARNING_PATH.md | ||
| eli5.md | ||
| EXTENDING_STORAGE.md | ||
| FIND_SYSTEM.md | ||
| MIGRATION-V3-TO-V4.md | ||
| neural-extraction.md | ||
| PERFORMANCE.md | ||
| PLUGINS.md | ||
| PRODUCTION_SERVICE_ARCHITECTURE.md | ||
| QUERY_OPERATORS.md | ||
| README.md | ||
| RELEASE-GUIDE.md | ||
| SCALING.md | ||
| STAGE3-CANONICAL-TAXONOMY.md | ||
| transactions.md | ||
| troubleshooting.md | ||
| universal-display-augmentation.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 & Augmentations
| Document | Description |
|---|---|
| Plugins | Plugin system overview |
| Creating Augmentations | Build custom plugins |
| Augmentations Reference | Full augmentation API |
| Augmentations Developer Guide | Plugin development guide |
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.