Major refactor of metadata indexing system for production scalability:
Performance improvements:
- 630x file reduction: 560,000 flat files → 89 chunk files
- O(1) exact match queries with bloom filters (1% false positive rate)
- O(log n) range queries with zone maps (ClickHouse-inspired)
- Adaptive chunking: ~50 values per chunk optimizes I/O
Technical changes:
- NEW: src/utils/metadataIndexChunking.ts
- BloomFilter: Probabilistic membership testing (FNV-1a + DJB2)
- SparseIndex: Directory of chunks with metadata
- ChunkManager: Handles chunk CRUD operations
- AdaptiveChunkingStrategy: Field-specific optimization
- ZoneMap: Min/max tracking for range query optimization
- REFACTORED: src/utils/metadataIndex.ts
- Removed indexCache (flat file entry cache)
- Removed dirtyEntries (flat file dirty tracking)
- Removed sortedIndices (sorted index for range queries)
- Removed 13 obsolete methods (sorted index operations, flat file I/O)
- Simplified flush() to only flush field indexes
- All fields now use chunked sparse indexing exclusively
- UPDATED: docs/architecture/index-architecture.md
- Documented new chunked sparse index architecture
- Added bloom filter and zone map explanations
- Updated query algorithm examples
- Added v3.42.0 version history
Benefits:
- Single code path (no more dual flat file + chunks)
- Immediate chunk flushing (no dirty tracking needed)
- Better I/O patterns (chunk-based instead of per-value files)
- Production-ready for billions of entities
- Zero breaking changes to public API
All tests passing. Ready for production.
Add detailed documentation explaining Brainy's 4-index architecture:
- MetadataIndex: inverted indexing with temporal bucketing (v3.41.0)
- HNSWIndex: hierarchical vector similarity search
- GraphAdjacencyIndex: O(1) bidirectional relationship traversal
- DeletedItemsIndex: soft-delete tracking
Includes explanation of UnifiedCache for coordinated memory management
across all indexes, integration patterns, performance characteristics,
and best practices for developers.
Updated overview.md to reference the new index architecture documentation.
Critical fix for GCS/S3 native storage adapters crashing on metadata index keys.
Problem:
- GCS and S3 adapters crashed with "Invalid UUID format" errors
- System keys like __metadata_field_index__status are NOT UUIDs
- Adapters incorrectly tried to shard all metadata keys as UUIDs
Solution:
- Move sharding/routing logic from adapters to BaseStorage class
- Add analyzeKey() method to detect system keys vs entity UUIDs
- System keys route to _system/ directory (no sharding)
- Entity UUIDs route to sharded directories (256 shards)
- All adapters now implement 4 primitive operations:
* writeObjectToPath(path, data)
* readObjectFromPath(path)
* deleteObjectFromPath(path)
* listObjectsUnderPath(prefix)
Benefits:
- Impossible for future adapters to repeat this mistake
- Zero breaking changes, full backward compatibility
- No data migration required
- Cleaner architecture with better separation of concerns
Updated adapters: GcsStorage, S3CompatibleStorage, OPFSStorage,
FileSystemStorage, MemoryStorage
Added: docs/architecture/data-storage-architecture.md
Updated: README.md with architecture docs link
- Removed ImportManager class and exports (use brain.import() instead)
- Fixed all documentation: getStatistics() → getStats()
- Updated 41 files across codebase for consistency
- Removed ImportManager section from API docs
- Added v3.30.0 migration guide to CHANGELOG
Co-Authored-By: Claude <noreply@anthropic.com>
- Fixed imports in examples/tests/ to use correct Brainy import
- Fixed imports in tests/benchmarks/ to use correct paths
- Updated bin/brainy-interactive.js to use Brainy instead of BrainyData
- Corrected documentation references throughout codebase
- Removed duplicate imports in benchmark files
- All files now consistently use 'Brainy' class from dist/index.js
- Add @deprecated JSDoc tags to TypeScript definitions
- Update all documentation examples to use modern add() and relate() API
- Preserve batch operations (addNouns, addVerbs) as they remain current
- Mark deprecated methods in both source and compiled definitions
Migration guide:
- addNoun(data, type, metadata) → add(data, { nounType: type, ...metadata })
- addVerb(source, target, type, metadata) → relate(source, target, type, metadata)
- Add user-friendly SCALING.md explaining Enterprise for Everyone
- Document zero-config philosophy and auto-discovery
- Explain storage adapter patterns and coordination strategies
- Add real-world examples and best practices
- Create technical deep-dive on distributed storage architecture
- Document how different storage backends work together
- Explain coordination strategies for shared vs isolated storage
✨ ONE universal import method for everything
- Auto-detects files, URLs, and raw data
- Intelligent noun/verb type matching using embeddings
- Support for JSON, CSV, YAML, and text formats
- Zero configuration required
🧠 Intelligent Type Matching
- Uses semantic embeddings to match 31 noun types
- Automatically detects 40 verb relationship types
- Confidence scores for type predictions
- Caching for improved performance
📦 Import Manager
- Centralized import logic with lazy loading
- Integrates NeuralImportAugmentation for AI processing
- Proper CSV parsing with quote handling
- Basic YAML support
🎯 Simplified API
- brain.import() - ONE method that handles everything
- Auto-detection of URLs and file paths
- Backwards compatible with existing code
- Clean, modern, delightful developer experience
📚 Documentation
- Comprehensive import guide in docs/guides/import-anything.md
- Examples for every format and use case
- Philosophy of simplicity and zero config
✅ Tests
- Full unit test coverage for import functionality
- Type matching tests for all 31 nouns and 40 verbs
- Tests for CSV, YAML, JSON, and text formats
BREAKING CHANGES: None - fully backward compatible
- Position Brainy as the Universal Knowledge Protocol with Triple Intelligence
- Document all 24 noun types and 40 verb types with industry examples
- Add verb relationship examples to demonstrate graph capabilities
- Emphasize infinite expressiveness and universal interoperability
- Show how standardized types enable tool and AI model compatibility
- Version 2.0.2
