brainy/docs/architecture/PERFORMANCE_ANALYSIS.md

Brainy Performance Analysis & Optimization

Current Issues Found

1. ❌ CRITICAL: notEquals Operator is O(n)

// PROBLEM: Gets ALL items to filter
case 'notEquals':
  const allItemIds = await this.getAllIds() // O(n) - TERRIBLE!

2. ❌ Soft Delete Performance

• Every query adds deleted: { notEquals: true }
• This makes EVERY query O(n) instead of O(log n)

3. ❌ exists Operator is Inefficient

case 'exists':
  // Scans all cache entries - O(n)
  for (const [key, entry] of this.indexCache.entries()) {
    if (entry.field === field) {
      entry.ids.forEach(id => allIds.add(id))
    }
  }

4. ⚠️ Query Optimizer Not Smart Enough

• isSelectiveFilter() needs to understand which filters are fast
• Should prioritize O(1) and O(log n) operations

Performance Characteristics

✅ Fast Operations (Keep These)

Operation	Complexity	Example
Vector Search (HNSW)	O(log n)	like: "query"
Exact Match	O(1)	where: { status: "active" }
Deleted Filter (NEW)	O(1)	where: { deleted: false }
Range Query (sorted)	O(log n)	where: { year: { gt: 2000 } }
Graph Traversal	O(k)	connected: { from: id }

❌ Slow Operations (Need Fixing)

Operation	Current	Should Be	Fix
notEquals	O(n)	O(1) or O(log n)	Use complement index
exists	O(n)	O(1)	Maintain field existence bitmap
noneOf	O(n)	O(k)	Use set operations

Optimized Architecture

Solution 1: Positive Indexing for Soft Delete ✅

// Instead of: deleted !== true (O(n))
// Use: deleted === false (O(1))
where: { deleted: false }

// Ensure all items have deleted field
if (!metadata.deleted) metadata.deleted = false

Solution 2: Complement Indices for notEquals

class MetadataIndexManager {
  // For common notEquals queries, maintain complement sets
  private complementIndices: Map<string, Set<string>> = new Map()
  
  // Example: Track non-deleted items separately
  private activeItems: Set<string> = new Set()
  private deletedItems: Set<string> = new Set()
}

Solution 3: Field Existence Bitmap

class FieldExistenceIndex {
  private fieldBitmaps: Map<string, BitSet> = new Map()
  
  hasField(id: string, field: string): boolean {
    return this.fieldBitmaps.get(field)?.has(id) ?? false
  }
}

Query Execution Strategy

Progressive Search (When Metadata is Selective)

1. Field Filter (O(1) or O(log n)) → Small candidate set
2. Vector Search within candidates (O(k log k))
3. Fusion if needed

Parallel Search (When Nothing is Selective)

1. Vector Search (O(log n)) → Top K results
2. Graph Traversal (O(m)) → Connected items  
3. Field Filter (O(1)) → Metadata matches
4. Fusion: Intersection or Union

Implementation Priority

1. DONE ✅ Fix soft delete to use deleted: false
2. TODO 🔧 Optimize notEquals for common fields
3. TODO 🔧 Add field existence index
4. TODO 🔧 Improve query optimizer intelligence
5. TODO 🔧 Add query explain mode for debugging

Performance Targets

• Vector search: < 10ms for 1M items
• Metadata filter: < 1ms for exact match
• Combined query: < 20ms for complex queries
• Soft delete overhead: < 0.1ms (O(1))