David Snelling
e5feae4104
Historical Db values (now()/asOf() pins that history has moved past) now serve the COMPLETE query surface - vector/hybrid search, graph traversal, cursor pagination, and aggregation - by materializing ephemeral in-memory indexes over the exact at-generation record set. The historical-query throw is gone; NotYetSupportedAtHistoricalGenerationError is deleted. Materializer (Brainy.materializeAtGeneration): - Copies the at-G record set (live bytes for ids untouched since the pin, immutable before-images otherwise) into a fresh MemoryStorage; a final reconciliation pass under the commit mutex makes the copy exact even when transactions commit mid-build. - Opens a read-only Brainy over the copy: init rebuilds the metadata and graph-adjacency indexes from the records; the vector index is built by inserting every at-G vector (the at-G HNSW graph never existed on disk, so there is nothing to restore). Host embedder and aggregate definitions are shared - no second model load, aggregates backfill at-G values. - Cost is the documented contract: O(n at G) time and memory, ONCE per Db (handle cached; freed by release(), with a FinalizationRegistry backstop that also closes leaked readers). A native VersionedIndexProvider serves the same reads from retained segments with no rebuild. Db routing (src/db/db.ts): metadata-level find()/related() keep the free record path; index-only dimensions (query/vector/near/connected/cursor/ aggregate/includeRelations/non-metadata modes) route to the cached materialization; unsupported where-operators on the record path re-route there too instead of erroring. Speculative with() overlays keep the one honest boundary - SpeculativeOverlayError (overlay entities carry no embeddings, so index reads over them would be silently incomplete); metadata find()/get()/filter related() work on overlays. UpdateParams.vector contract now honored: an explicit pre-computed vector applies directly (with dimension validation) in update() and transact update ops, re-indexing HNSW - previously it was silently ignored unless data also changed. GraphAdjacencyIndex: adjacency now derives from the two verb-id LSM trees filtered through the live-verb tombstone set (entity->entity edge trees deleted - they carried no verb ids, so removeVerb could never tombstone them and traversal served stale neighbors forever). Neighbor reads batch- load live verbs via the unified cache; addVerb seeds the cache. Proofs (tests/integration/db-mvcc.test.ts, 24 green): historical vector search finds old vector placement including since-deleted entities; historical graph traversal walks the old wiring after a rewire; historical aggregation computes at-G group values; asOf() pins get the same surface; the materialization builds once per Db and release() closes the ephemeral reader (it refuses reads afterwards); overlays throw the documented error. ADR-001 updated to the no-throws historical model. |
||
|---|---|---|
| .. | ||
| 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 |
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 |
| 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.