BREAKING CHANGE: System metadata location changed from 'index/' to '_system/' directory
- Rename INDEX_DIR to SYSTEM_DIR following database conventions
- Implement dual-read/write strategy for zero-downtime migration
- Add automatic migration from old to new location on first access
- Support mixed service versions sharing S3/cloud storage
- Add 30-day grace period for gradual rollout (configurable)
- Store distributed config alongside statistics in _system folder
- Add comprehensive migration guide and documentation
Migration features:
- Read from both locations (new first, fallback to old)
- Write to both during migration period
- Automatic data migration when found only in old location
- Services can update independently without coordination
- Full backward compatibility for production deployments
The change improves clarity ('_system' better represents system metadata than 'index')
and follows standard database conventions (MongoDB's _system, PostgreSQL's pg_*).
- Remove Rollup bundling in favor of direct TypeScript compilation
- Move from bundled models to dynamic model loading with configurable paths
- Add Docker deployment examples and documentation
- Implement robust model loader with fallback mechanisms
- Update storage adapters for better cross-environment compatibility
- Add comprehensive tests for model loading and package installation
- Simplify package.json scripts and remove complex build configurations
- Clean up deprecated demo files and old bundling scripts
BREAKING CHANGE: Models are no longer bundled with the package. They are now loaded dynamically from CDN or custom paths.
Add @soulcraft/brainy-models as optional dependency for zero-config offline reliability. Enhance robustModelLoader with hierarchical loading strategy (local → online → fail). Add comprehensive production deployment documentation and update README with clear benefits.
This solves critical production issues where Universal Sentence Encoder fails to load in Docker/Cloud Run environments due to network timeouts or blocked URLs. The solution provides 100% offline reliability while maintaining backward compatibility and requires no code changes from users.
- Fix deprecated getAllNodes() warnings by using getNodesWithPagination() in S3 adapter
- Add getNounsWithPagination() method to S3CompatibleStorage for proper pagination support
- Create optimizedS3Search module for efficient pagination and filtering
- Update baseStorage to properly detect pagination support in adapters
- Add comprehensive documentation for performance and logging fixes
- Ensure backward compatibility with existing code
This resolves the following warnings in dependent projects:
- "getAllNodes() is deprecated and will be removed in a future version"
- "Storage adapter does not support pagination, falling back to loading all nouns"
- "Only returning the first 1000 nodes. There are more nodes available"
- Add complete PERFORMANCE_FEATURES.md with auto-configuration guide
- Document intelligent cache system with 100x performance improvements
- Add cursor-based pagination and real-time sync documentation
- Include distributed storage considerations and best practices
- Update README.md with performance highlights and auto-config features
- Replace "It Just Works™" with trademark-friendly "Zero-to-Smart™"
- Fix storage configuration examples for consistency
- All tests passing with zero breaking changes
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implements Phase 1 and Phase 2 of distributed enhancements for horizontal scaling:
Phase 1 - Zero-Config Distributed Mode:
- Add DistributedConfigManager for shared S3 configuration coordination
- Implement explicit role configuration (reader/writer/hybrid) for safety
- Add instance registration with heartbeat and health monitoring
- Create hash-based partitioner for deterministic data distribution
Phase 2 - Intelligent Data Management:
- Add DomainDetector for automatic data categorization (medical, legal, product, etc.)
- Implement domain-aware search filtering for improved relevance
- Create role-based operational modes with specific optimizations
- Add HealthMonitor for comprehensive metrics tracking
Key Features:
- Multi-writer support with consistent hash partitioning
- Reader instances optimize for 80% cache utilization
- Writer instances optimize for batched writes
- Automatic domain detection and tagging
- Real-time health monitoring across all instances
- Cross-platform crypto utilities for browser compatibility
Safety Improvements:
- Require explicit role configuration (no automatic assignment)
- Validate role compatibility on startup
- Track instance health and performance metrics
Testing:
- Add comprehensive test suite for distributed features
- All 25 distributed tests passing
- Fixed domain filtering in search functionality
Documentation:
- Update README with distributed mode highlights
- Add examples showing reader/writer setup
- Document new capabilities and benefits
🤖 Generated with Claude Code
https://claude.ai/code
Co-Authored-By: Claude <noreply@anthropic.com>
- Replace complex 8-enhancement proposal with simpler 3-phase approach
- Switch from semantic to hash-based partitioning for multi-writer scenarios
- Introduce zero-config distributed mode with automatic role detection
- Add shared JSON config coordination instead of complex locking mechanisms
- Focus on minimal user burden with progressive disclosure for advanced features
- Phase 1: Foundation with shared config and hash partitioning (3-4 days)
- Phase 2: Optimizations for caching and domain metadata (2-3 days)
- Phase 3: Optional advanced features for write-heavy workloads (3-4 days)
Enhanced the claude-commit tool with comprehensive safety features and
deployed them across all projects:
Safety improvements:
- Added mandatory review warning with visual indicators
- Implemented double confirmation before committing
- Added regenerate option for new commit messages
- Shows edited messages for review after modifications
- Added configuration file creation in setup script
- Created ~/.claude-commit.conf for user preferences
Deployment updates:
- Updated setup.sh with embedded safety features
- Copied enhanced script to github-package
- Copied enhanced script to bluesky-package
- Copied enhanced script to scout-search
- Updated dotfiles version for portability
Documentation:
- Updated CLAUDE.md with clear commit workflow for Claude Code
- Documented review-approve-commit-push process
- Added instructions for multi-machine consistency
These changes ensure consistent safety features across all projects
and machines, with mandatory review before any commit operation.
Added comprehensive safety features to prevent accidental commits and ensure
user review of all generated commit messages:
Safety enhancements:
- Added mandatory review warning with clear visual indicators
- Implemented double confirmation for all commit operations
- Added option to regenerate commit message if not satisfied
- Shows edited message for review after modifications
- Added explicit "no auto-push" reminders after commits
- Created ~/.claude-commit.conf for safety preferences
Documentation updates:
- Updated CLAUDE.md with clear commit workflow for Claude Code
- Added safety features section to tool documentation
- Clarified that manual review is always required
- Documented the review-approve-commit-push workflow
These changes ensure users always have full control over commit messages
and prevent accidental commits or pushes without explicit approval.
Implemented a comprehensive AI-powered commit message generator using Claude that:
- Automatically generates Conventional Commit formatted messages
- Analyzes git diff to create context-aware commit messages
- Works globally across all git repositories with 'git cc' command
- Supports multi-computer setup through portable dotfiles
Major changes:
- Added global claude-commit script with git aliases (git cc, git smart-commit)
- Created organized documentation in docs/tools/claude-commit/
- Included portable dotfiles structure for easy multi-machine deployment
- Updated README with TLDR Node.js quickstart section featuring all Brainy capabilities
- Moved documentation section to bottom of README for better flow
- Added CLAUDE.md with project-specific instructions for Claude Code
The tool eliminates manual commit message writing by leveraging AI to understand
code changes and generate properly formatted, meaningful commit messages that
follow the Conventional Commits specification.
- Enhanced key features section with new optimizations
- Introduced a dedicated section for large-scale performance optimizations
- Added detailed auto-configuration setup instructions
- Included performance benchmarks and core optimization systems
- Created a new document for comprehensive large-scale optimizations
- **Documentation Removal**:
- Deleted `brainy_architecture_diagram.md` and `brainy_architecture_visual.md`:
- Removed outdated architecture descriptions, diagrams, and structured content no longer in use.
- **Purpose**:
- Clean up legacy documentation to reduce confusion and ensure only the latest and most accurate resources are available for developers and stakeholders.
- **Documentation Additions**:
- Created `brainy_architecture_diagram.md` to detail Brainy's architecture using diagrams and structured descriptions:
- Added overviews of the system, core architecture, and augmentation pipeline.
- Defined data models, graph structures, storage architecture, and performance optimizations.
- Explained vector search engine design, HNSW index structure, and usage flow examples.
- Developed `brainy_architecture_visual.md` to complement the architecture with visual aids in Mermaid.js:
- Provided detailed flowcharts, mind maps, and sequence diagrams for system components and data flow.
- **Purpose**:
- Provide in-depth technical insights into Brainy's architecture for developers and stakeholders.
- Enhance understanding of the system's core design principles with easy-to-follow diagrams and examples.
- **Documentation**:
- Added a detailed explanation in `model-management.md` for resolving `"format"` field compatibility issues in TensorFlow.js.
- Introduced a dual-layer protection approach to mitigate errors like `RangeError: byte length of Float32Array should be a multiple of 4`.
- **Scripts**:
- Removed the redundant `release:minor` script entry from `package.json`.
- Enhanced `_deploy` script consistency.
- **Protection Mechanisms**:
- Updated `download-full-models.js` to inject a missing `"format"` field during downloads.
- Enhanced `RobustModelLoader` to validate and restore the `"format"` field automatically at runtime, ensuring persistence and compatibility
- Deleted the following obsolete files:
- `CHANGES.md`, `changes-summary.md`, `CHANGES_SUMMARY.md`: Contained redundant or outdated change logs and implementation summaries.
- `COMPATIBILITY.md`: Detailed compatibility behavior no longer relevant after environment detection updates.
- `fix-documentation.md`: Addressed a resolved issue regarding `process.memoryUsage` errors in testing.
- `DIMENSION_MISMATCH_SUMMARY.md`: Provided a legacy summary of resolved embedding dimension mismatch issues.
- `demo.md`: Documented an outdated demo process for testing Brainy features.
- `CONCURRENCY_IMPLEMENTATION_SUMMARY.md`: Summarized already-documented concurrency features.
- `IMPLEMENTATION_SUMMARY.md`: Detailed an obsolete implementation of optional model bundling.
- Purpose:
- Streamline and declutter archive by removing redundant or outdated documentation.
- Align repository with current feature set and documentation standards.
- Introduced new documentation files under `docs/`:
- `model-bundling-analysis.md`: Provides detailed analysis of current, bundled, hybrid, and dynamic model loading approaches, including pros, cons, and recommendations.
- `model-management.md`: Explains how Brainy manages Universal Sentence Encoder models, including setup, usage, and troubleshooting.
- `optional-model-bundling.md`: Details the `@soulcraft/brainy-models` package for offline reliability with pre-bundled models.
- Added `src/utils/robustModelLoader.ts`:
- Implements enhanced model loading with retry mechanisms, timeout handling, fallback URLs, and optional local model bundling.
- Supports Node.js and browser environments with exponential backoff logic.
- Key Updates:
- **Hybrid Loading Strategy**: Recommended for balancing reliability and flexibility via hybrid online/offline mechanisms.
- **Enhanced Fallback Scenarios**: Robust loader improves network-dependent reliability for embedding workflows.
- **Offline Reliability Support**: Optional model bundling eliminates dependency on external services, supporting air-gapped and edge environments.
**Purpose**: Introduce a hybrid model loading approach with robust options for
- Added `cache-configuration.md` under `docs/guides`:
- Detailed multi-level cache system (hot, warm, cold) overview.
- Explained new adaptive tuning capabilities:
- Memory-based adjustments across Node.js, Browser, and Worker environments.
- Dynamic sizing for read-heavy/write-heavy workloads.
- Environment-specific configurations for optimal caching.
- Included best practices for large datasets, memory-constrained and read-only environments.
- Added monitoring and advanced manual tuning instructions.
- Modified `cacheManager.ts`:
- Introduced `environmentConfig` for tailored per-environment cache settings.
- Enhanced auto-tuning with support for dynamic memory detection and cache hit/miss ratio.
- Added fine-grained tuning for eviction thresholds, TTLs, and batch sizes based on workload characteristics.
- Improved adaptive tuning with async memory detection and detailed cache statistics tracking.
**Purpose**: Provide developers with detailed guidance and dynamic tools for optimizing Brainy's cache system, ensuring better performance across diverse environments and workloads.
- Created `service-identification.md` in `docs/guides`:
- Detailed guidelines on how services should identify themselves within Brainy.
- Documented two identification methods: default service initialization and operation-specific service naming.
- Included service name conventions and common examples (`github`, `reddit`, `default`).
- Described benefits of proper service identification:
- Enhanced statistics tracking and JSON field discovery by service.
- Provided best practices for consistent and descriptive service naming.
- Explained internal implementation details, such as `getServiceName` usage and statistic tracking.
**Purpose**: Help users properly identify services to enable statistics tracking, field discovery, and improved data management in Brainy.
- Added support for field-specific and prioritized searches in `brainyData`:
- Introduced `searchField` option to enable targeted field-level searches.
- Implemented `priorityFields` option for weighted vectorization and query relevance.
- Developed utilities in `jsonProcessing.ts` and `fieldNameTracking.ts`:
- `extractTextFromJson` for text extraction with customizable depth and field prioritization.
- `extractFieldFromJson` to target specific fields in JSON documents.
- `prepareJsonForVectorization` for optimized JSON vectorization.
- Enhanced management of field names and mappings:
- Integrated `trackFieldNames` to associate fields with their services.
- Supported cross-service consistency through `standardFieldMappings`.
- Updated documentation:
- Added detailed guides for JSON search enhancements and HNSW limitations.
- Extended usage examples in `README.md` and `json-search-test.js`.
- Verified improvements with comprehensive tests:
- Created unit and integration tests demonstrating search behavior improvements.
- Addressed previous TypeScript errors related to search parameters.
**Purpose**: Improve search accuracy and usability when working with complex JSON documents by enabling field-specific searches and enhancing contextual relevance.
- Deleted `CHANGES.md`, `CHANGES_SUMMARY.md`, `CONCURRENCY_ANALYSIS.md`, `CONCURRENCY_IMPLEMENTATION_SUMMARY.md`, and related developer documentation files.
- Removed redundant or legacy content no longer aligned with the current codebase and workflows.
- Updated repository to reflect streamlined documentation approach, reducing clutter and improving maintainability.
**Purpose**: Simplify and declutter repository by removing obsolete documentation files, ensuring it remains focused and relevant.
- Introduced `test-fallback-function.js` and `test-fallback-simple.js` to validate `executeInThread` fallback functionality with both named and anonymous compute-intensive functions.
- Added `test-tensorflow-textencoder.js` for TensorFlow.js and TextEncoder tests in a Node.js environment.
- Created `test-tensorflow-textencoder.html` for browser-based TensorFlow.js and TextEncoder tests.
- Implemented cross-environment test support in `cli-package/src/test-tensorflow-textencoder.ts` for CLI functionality.
- Enhanced `src/utils/embedding.ts`, `textEncoding.ts`, and `brainy-wrapper.js` to include updated global `TextEncoder` and `TextDecoder` utilities for compatibility and worker improvements.
- Standardized and expanded utility methods in `PlatformNode` for broader support, including `isFloat32Array` and `isTypedArray` checks.
- Updated Node.js requirement to `>= 24.4.0` across documentation and configuration files for compatibility improvements.
This update introduces comprehensive testing for fallback mechanisms, TensorFlow.js, and TextEncoder across multiple environments, ensuring robustness and compatibility.
- Updated version to `0.10.0` in `README.md`, `cli-package/package.json`, and `src/utils/version.ts`.
- Removed `CHANGELOG.md` from the root and `cli-package`, as GitHub auto-generates release notes.
- Refactored `brainy-wrapper.js` to simplify utility methods (`isFloat32Array` and `isTypedArray`) by moving them to instance-level definitions.
- Standardized Node.js version requirement to `>= 24.3.0` across documentation and configuration files.
- Improved `textEncoding.ts` by introducing a unified `Platform` class for cross-environment compatibility (Node.js and browser).
- Restructured scripts:
- Replaced outdated commands (e.g., `test-cli` -> `test:cli` and `test-all` -> `test:all`) for consistency.
- Removed changelog updates from `scripts/create-github-release.js` as part of simplification.
- Enhanced `patch-textencoder.js` to also patch `worker.js` for both `TextEncoder` and `TextDecoder`.
This release improves compatibility with Node.js 24, simplifies the deployment/changelog process, and refines text encoding and worker functionalities.
- Updated version to `0.9.30` in `package.json`, `cli-package/package.json`, `src/utils/version.ts`, and `README.md`.
- Synced `@soulcraft/brainy` dependency version to `0.9.30` for CLI package consistency.
- Modified npm version badge in `README.md` to reflect the new version.
- Added detailed publishing instructions in `docs/publishing-cli.md` to guide users on publishing both, main, or CLI packages.
- Introduced new npm scripts `publish:cli` and `build:cli` for streamlined package-specific operations.
This update ensures cohesive versioning, provides clearer publishing guidelines, and improves maintainability with new build/publish scripts.
- Added a new `@soulcraft/brainy-cli` package to provide a dedicated CLI interface for the Brainy database.
- Implemented a CLI wrapper script (`cli-wrapper.js`) to manage global package execution and version handling.
- Introduced `scripts/publish-cli.js` to automate synchronized publishing of the main package and CLI, ensuring version consistency.
- Created documentation for CLI usage and publishing workflow (`publishing-cli.md`).
- Updated `package.json` to include CLI-related build and deploy scripts.
- Adjusted `README.md` to document the CLI package, usage instructions, and build separation.
This feature introduces a standalone CLI package, improves deployment automation, and enhances documentation to align with the updated architecture.
