Cloud Run cold starts taking 139 seconds due to 90MB WASM file with
embedded 87MB model weights. WASM compilation scales with file size.
Solution: Split into 2.4MB WASM (code only) + external model files.
- WASM compile: 139,000ms → 6-8ms
- Model load: N/A → 30-115ms
- Total init: 139,000ms → 136-240ms
New modelLoader.ts handles all environments:
- Node.js: fs.readFile()
- Bun: Bun.file()
- Bun --compile: auto-embedded assets
- Browser: fetch()
Zero config - same API, npm package includes model files.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove unused model.type validation that caused Workshop error
- Remove model config from BrainyConfig type (never used)
- Simplify modelAutoConfig.ts (always Q8 WASM)
- Clean up zeroConfig.ts model references
This fixes the "Invalid model type: balanced" error and removes
unnecessary configuration options that did nothing.
CRITICAL BUG FIX: TypeAwareStorage metadata race condition
Problem:
- saveNoun() called before saveNounMetadata()
- TypeAwareStorage couldn't determine entity type (not cached yet)
- Defaulted to 'thing' and saved to wrong storage path
- Later saveNounMetadata() saved to correct path
- Noun and metadata in different locations = entity not found
Impact:
- Broke VFS file operations completely
- Broke brain.get(), brain.relate(), brain.find()
- All metadata-dependent features failed
- Workshop team completely blocked
Solution:
- Reversed save order: saveNounMetadata() FIRST, then saveNoun()
- Type now cached before saveNoun() needs it
- Both saved to correct type-aware paths
Additional Fixes:
- Make baseStorage.initializeCOW() public (was protected)
- Remove enableCOW config option (cleanup)
- COW auto-init temporarily disabled (deadlock issue)
Known Limitations (v5.0.1):
- Fork API exists but COW requires manual init
- Will be zero-config in v5.1.0
Fixes: Workshop Bug Report (VFS metadata missing)
CRITICAL FIX: VFS bug that persisted through v4.5.1-v4.7.4 is NOW FIXED.
Root Cause:
- Storage adapters were not properly extracting standard fields from metadata
- This caused getVerbsBySource_internal() to return 0 relationships despite relationships existing
- VFS PathResolver couldn't navigate directory structure
Solution - Metadata Architecture Refactoring:
1. Move standard fields to top-level of HNSWNounWithMetadata and HNSWVerbWithMetadata
- type, createdAt, updatedAt, confidence, weight, service, data, createdBy
2. Update all 9 storage adapters to extract standard fields from metadata on load
3. Maintain backward compatibility at storage layer (metadata files unchanged)
Changes:
- src/coreTypes.ts: Update HNSWNounWithMetadata and HNSWVerbWithMetadata interfaces
- Add top-level standard fields
- Change data type from unknown to Record<string, any>
- Add confidence field to GraphVerb
- src/storage/baseStorage.ts: Add type cast pattern for standard field extraction
- src/storage/adapters/*.ts: Fix all 9 adapters (memoryStorage, fileSystemStorage, gcsStorage,
s3CompatibleStorage, r2Storage, opfsStorage, azureBlobStorage, typeAwareStorageAdapter)
- Extract standard fields from metadata on load
- Place at top-level of returned entities
- src/api/DataAPI.ts: Read fields from top-level instead of metadata
- src/graph/graphAdjacencyIndex.ts: Convert HNSWVerbWithMetadata to GraphVerb format
- src/utils/metadataIndex.ts: Fix typo (metadata → entityOrMetadata)
- src/types/brainy.types.ts: Add createdBy field to AddParams
- src/types/graphTypes.ts: Add service field to GraphVerb
Test Results:
✅ VFS bug FIXED - vfs.readdir('/') now returns files (was returning empty array)
✅ getVerbsBySource_internal() now returns relationships correctly
✅ Build succeeds with ZERO compilation errors
✅ 95.7% of tests pass (954/997)
Breaking Changes:
- None - backward compatibility maintained at storage layer
Version: 4.8.0
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Remove includeVFS parameter and broken isVFS filtering logic
- Add excludeVFS parameter for optional VFS entity filtering
- VFS entities now part of knowledge graph by default
- Enable O(1) graph adjacency optimizations for VFS operations
- Update all VFS projections and PathResolver
- Add comprehensive VFS visibility documentation
This fixes the bug where VFS operations returned empty results due to
operator object mismatch in storage adapters. VFS relationships now use
proper graph traversal without metadata filtering.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add production-scale sorting support with orderBy/order parameters:
- Sort by any field including createdAt, updatedAt, timestamps
- Works in both metadata-only and vector+metadata query paths
- O(k) memory complexity where k = filtered results
Fix timestamp sorting precision issue:
- Load actual timestamp values from entity metadata for sorting
- Avoids 1-minute bucketing precision loss
- Maintains bucketing for efficient range queries
Fix range query operators:
- Normalize min/max bounds before comparison with bucketed index
- Ensures gte, lte, gt, lt work correctly with timestamps
Standardize operator syntax:
- Canonical: eq, ne, gt, gte, lt, lte, in, between, contains, exists
- Deprecate: is, isNot, greaterEqual, lessEqual (remove in v5.0.0)
- Maintain backward compatibility with aliases
Test results: All sorting and range query tests pass, no regressions
CRITICAL BUG FIX - VFS Files Were Completely Invisible
Workshop Team Issue:
- Import created 569 VFS files
- vfs.readdir('/') returned 0 items
- VFS was 100% unusable
Root Cause:
v4.4.0 added includeVFS to brain.find() but FORGOT brain.getRelations().
PathResolver.getChildren() calls getRelations() to find VFS relationships,
but those were being excluded by default - making ALL VFS files invisible!
Fix:
1. Add includeVFS parameter to GetRelationsParams interface
2. Wire includeVFS filtering in brain.getRelations()
- Excludes VFS relationships by default (metadata.isVFS != true)
- Include them when includeVFS: true
3. Update VFS to mark all relationships with metadata: { isVFS: true }
- 7 relate() calls updated in VirtualFileSystem.ts
4. Update PathResolver to use includeVFS: true
- resolveChild() line 200
- getChildren() line 229
Impact:
- VFS is now fully functional again
- Consistent with v4.4.0 architecture (VFS separate from knowledge graph)
- All APIs now have includeVFS where needed
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add real-time progress reporting throughout the entire import pipeline
with a standardized API that works across all supported formats.
Workshop Team Feature Request:
- Eliminates "0% complete" hangs during AI extraction
- Shows continuous progress with entities/sec, throughput, ETA
- Reports contextual messages ("Processing page 5 of 23")
- Standardized progress API for CSV, PDF, Excel, JSON, Markdown, YAML, DOCX
Core Changes:
- Add FormatHandlerProgressHooks interface for extensible progress
- Wire up all 3 binary format handlers (CSV, PDF, Excel) with 7+ progress points
- Wire up all 4 text format importers (JSON, Markdown, YAML, DOCX)
- Add ImportProgress interface with stage, message, counts, throughput, ETA
- ImportCoordinator normalizes all format progress to standard interface
CLI Improvements:
- Import command now uses brain.import() directly with full progress
- Add --include-vfs flag to find command (v4.4.0 compatibility)
- Add --confidence and --weight options to add command
Documentation:
- docs/guides/standard-import-progress.md - Universal API guide
- docs/guides/import-progress-implementation.md - Developer guide
- docs/guides/import-progress-examples.md - Practical examples
- JSDoc on brain.import() with universal handler examples
Result: ONE progress handler works for ALL 7 formats with zero format-specific code!
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add confidence and weight properties to Entity interface and flatten Result fields to top level for improved developer experience and API consistency.
Breaking Changes: None (all changes are backward compatible)
Phase 2 - Entity Confidence & Weight:
- Add confidence (type classification certainty) and weight (entity importance) to Entity interface
- Add confidence/weight parameters to AddParams and UpdateParams
- Update convertNounToEntity() to extract confidence/weight from storage
- Update add() and update() methods to preserve confidence/weight in metadata
- Enable developers to specify and access entity confidence/weight scores
Phase 3 - Result Field Flattening:
- Flatten commonly-used entity fields (type, metadata, data, confidence, weight) to Result top level
- Add createResult() helper for consistent Result construction
- Update all find() code paths to use createResult()
- Enable direct access: result.metadata instead of result.entity.metadata
- Preserve full entity in result.entity for backward compatibility
VFS Fix (from previous work):
- Fix VFSStructureGenerator to use brain.vfs() cached instance instead of creating separate instance
- Improve VFS error messages with step-by-step guidance
- Update examples to show correct vfs.init() usage
- Add comprehensive VFS import verification tests
Documentation Updates:
- Update API_REFERENCE.md with confidence/weight examples and flattened Result documentation
- Enhance JSDoc for add(), get(), find(), similar() with v4.3.0 examples
- Document Result structure changes and backward compatibility
- Add migration examples showing both old and new access patterns
Tests:
- Add 16 comprehensive tests for Entity confidence/weight exposure
- Add tests for Result field flattening
- Add tests for backward compatibility
- All tests passing (16/16)
API Consistency:
- Entity: direct access to confidence/weight
- Result: flattened fields + nested entity (both work)
- Relation: already had confidence/weight (consistent)
- VFS: inherits from Entity (automatic)
Files Changed:
- src/types/brainy.types.ts - Updated Entity, AddParams, UpdateParams, Result interfaces
- src/brainy.ts - Updated implementation and JSDoc for all affected methods
- tests/integration/entity-confidence-weight.test.ts - 16 comprehensive tests
- docs/API_REFERENCE.md - Updated with v4.3.0 examples
- src/importers/VFSStructureGenerator.ts - VFS fix
- src/vfs/VirtualFileSystem.ts - Improved error messages
- examples/unified-import-example.ts - Added vfs.init() example
- tests/integration/vfs-*-verification.test.ts - VFS verification tests
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
**Problem**: brain.getRelations() returned empty array when called without
parameters, making 524 imported relationships inaccessible for Workshop team.
**Root Cause**: Method only queried storage when `from` or `to` parameters
were provided. Without params, it returned empty array.
**Solution**:
- Add support for "get all" via storage.getVerbs() when no from/to provided
- Add string ID shorthand: getRelations(id) → getRelations({ from: id })
- Default limit: 100 (matching storage layer pattern)
- Production safety: warn for >10k queries without filters
- Fix broken improvedNeuralAPI.ts calls (getVerbsForNoun → getRelations)
- Fix property bugs: verb.target → verb.to, verb.verb → verb.type
**Testing**:
- 14 new integration tests covering all query patterns
- All critical tests passing (25/25)
- Backward compatible - no breaking changes
**Impact**: Resolves Workshop bug where imported relationships were invisible
- Change default storage from 'memory' to 'auto' for smart environment detection
- Add 'auto' support to storage type validation and TypeScript types
- Browser: auto-selects OPFS → memory fallback
- Node.js: auto-selects filesystem → memory fallback
- Cloud: auto-detects S3/GCS/R2 → disk → memory fallback
- Eliminates need for manual storage configuration in most cases
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Fix FileSystemStorage counting non-existent files in totalCount
- Add safety check in BaseStorage to prevent hasMore:true with empty items
- Ensure pagination terminates correctly even with corrupted storage state
- Add incremental sorted index updates during CRUD operations for consistent <5ms range queries
- Implement parallel search optimization with vector, metadata, and graph intelligence fusion
- Fix metadata-only query handling to properly return results without vector search
- Fix NLP recursive call issue by using embed() instead of add()
- Add cardinality tracking for smart index optimization
- Store entity data in metadata for proper retrieval
- Add comprehensive performance documentation
This improves query performance from O(n) to O(log n) for range queries
and ensures consistent fast performance without lazy loading delays.
