brainy/docs/guides/getting-started.md

Getting Started with Brainy

This guide will help you get up and running with Brainy, the multi-dimensional AI database that combines vector similarity, graph relationships, and metadata filtering.

Installation

npm install brainy

Basic Setup

Simple Initialization

import { BrainyData } from 'brainy'

// Create a new Brainy instance with defaults
const brain = new BrainyData()

// Initialize (downloads models if needed)
await brain.init()

// You're ready to go!

Custom Configuration

const brain = new BrainyData({
  // Storage configuration
  storage: {
    type: 'filesystem',  // or 's3', 'opfs', 'memory'
    path: './my-data'
  },
  
  // Vector configuration
  vectors: {
    dimensions: 384,
    model: 'all-MiniLM-L6-v2'
  },
  
  // Performance tuning
  cache: {
    enabled: true,
    maxSize: 1000
  }
})

await brain.init()

Your First Operations

Adding Data

// Add entities (nouns) with automatic embedding generation
const id = await brain.addNoun("The quick brown fox jumps over the lazy dog", {
  category: "demo",
  timestamp: Date.now()
})

console.log(`Added noun with ID: ${id}`)

// Add relationships (verbs) between entities
const sourceId = await brain.addNoun("John Smith")
const targetId = await brain.addNoun("TechCorp")
await brain.addVerb(sourceId, targetId, "works_at", {
  position: "Engineer",
  since: "2024"
})

Searching

// Simple semantic search
const results = await brain.search("fast animals")

results.forEach(result => {
  console.log(`Found: ${result.content} (score: ${result.score})`)
})

Advanced Queries with find()

// Natural language queries - Brainy understands intent!
const results = await brain.find("show me technology articles about AI from 2023")
// Automatically interprets: topic, category, and time range

// Structured queries with vector similarity and metadata filtering
const structured = await brain.find({
  like: "artificial intelligence",
  where: {
    category: "technology",
    year: { $gte: 2023 }
  },
  limit: 10
})

// Complex natural language with multiple filters
const complex = await brain.find("financial reports from Q3 2024 with revenue over 1M")
// Automatically extracts: document type, date range, numeric filters

Common Use Cases

1. Semantic Search Engine

// Index documents
const documents = [
  { title: "Introduction to AI", content: "AI is transforming..." },
  { title: "Machine Learning Basics", content: "ML algorithms..." },
  { title: "Deep Learning", content: "Neural networks..." }
]

for (const doc of documents) {
  await brain.addNoun(doc.content, {
    title: doc.title,
    type: "document"
  })
}

// Search semantically
const results = await brain.search("how do neural networks work")

2. Recommendation System

// Add user interactions as nouns
const interactionId = await brain.addNoun("user viewed product", {
  userId: "user123",
  productId: "product456",
  action: "view",
  timestamp: Date.now()
})

// Create relationships between users and products
const userId = await brain.addNoun("user123")
const productId = await brain.addNoun("product456")
await brain.addVerb(userId, productId, "viewed", {
  timestamp: Date.now()
})

// Natural language query for recommendations
const recommendations = await brain.find("products similar to what user123 viewed recently")

// Or structured query for similar users
const similar = await brain.find({
  like: "user123 interests",
  where: { action: "view" },
  limit: 5
})

3. Knowledge Graph

// Add entities (nouns) to the knowledge graph
const personId = await brain.addNoun("John Smith, Software Engineer", {
  type: "person",
  role: "engineer"
})

const companyId = await brain.addNoun("TechCorp, Innovation Leader", {
  type: "company",
  industry: "technology"
})

// Create relationship
await brain.addVerb(personId, companyId, "works_at", {
  since: "2020",
  position: "Senior Engineer"
})

// Natural language query for relationships
const colleagues = await brain.find("people who work at TechCorp")

// Or structured query for specific relationships
const results = await brain.find({
  connected: {
    from: personId,
    type: "works_at"
  }
})

4. Real-time Data Processing

// Configure for streaming
const brain = new BrainyData({
  augmentations: [
    new EntityRegistryAugmentation(),  // Deduplication
    new BatchProcessingAugmentation({ batchSize: 100 })  // Batching
  ]
})

// Process streaming data
async function processStream(item) {
  // Entity registry prevents duplicate nouns
  const id = await brain.addNoun(item.content, {
    externalId: item.id,
    timestamp: item.timestamp
  })
  
  // Real-time natural language queries
  if (item.urgent) {
    const related = await brain.find(`urgent items similar to ${item.content}`)
    // Process related items...
  }
}

Storage Options

Development (Memory)

const brain = new BrainyData({
  storage: { type: 'memory' }
})
// Fast, temporary, perfect for testing

Production (FileSystem)

const brain = new BrainyData({
  storage: {
    type: 'filesystem',
    path: '/var/lib/brainy'
  }
})
// Persistent, efficient, server-ready

Cloud (S3)

const brain = new BrainyData({
  storage: {
    type: 's3',
    bucket: 'my-brainy-data',
    region: 'us-east-1'
  }
})
// Scalable, distributed, cloud-native

Browser (OPFS)

const brain = new BrainyData({
  storage: { type: 'opfs' }
})
// Browser-native, persistent, offline-capable

Performance Tips

1. Use Batch Operations

// Good - batch operations for nouns
const items = ["item1", "item2", "item3"]
for (const item of items) {
  await brain.addNoun(item, { batch: true })
}

// Create relationships efficiently
const relationships = [
  { source: id1, target: id2, type: "related" },
  { source: id2, target: id3, type: "similar" }
]
for (const rel of relationships) {
  await brain.addVerb(rel.source, rel.target, rel.type)
}

2. Enable Caching

const brain = new BrainyData({
  cache: {
    enabled: true,
    maxSize: 1000,
    ttl: 300000  // 5 minutes
  }
})

3. Use Appropriate Limits

// Always specify reasonable limits
const results = await brain.search("query", {
  limit: 20  // Don't fetch more than needed
})

4. Index Frequently Queried Fields

const brain = new BrainyData({
  indexedFields: ['category', 'userId', 'timestamp']
})

Error Handling

try {
  await brain.addNoun("content", metadata)
} catch (error) {
  if (error.code === 'STORAGE_FULL') {
    console.error('Storage is full')
  } else if (error.code === 'INVALID_INPUT') {
    console.error('Invalid input:', error.message)
  } else {
    console.error('Unexpected error:', error)
  }
}

Next Steps

• Architecture Overview - Understand the system design
• Triple Intelligence - Advanced query capabilities
• API Reference - Complete API documentation
• Examples - More code examples

Getting Help

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Examples: Check the /examples directory