David Snelling
90961c5ce9
- Reduce README from 1800+ to ~220 lines for better readability - Focus on features, quick start, and excitement for new users - Remove obsolete references to brainy-cli and brainy-web-service packages - Add clear performance metrics and zero-configuration examples upfront - Move detailed documentation to /docs folder with proper linking - Improve information architecture with better organization and navigation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
221 lines
No EOL
6.5 KiB
Markdown
221 lines
No EOL
6.5 KiB
Markdown
<div align="center">
|
|
<img src="./brainy.png" alt="Brainy Logo" width="200"/>
|
|
<br/><br/>
|
|
|
|
[](LICENSE)
|
|
[](https://nodejs.org/)
|
|
[](https://www.typescriptlang.org/)
|
|
[](CONTRIBUTING.md)
|
|
|
|
**A lightning-fast vector database that runs everywhere - from browsers to servers to edge functions**
|
|
|
|
[Live Demo](https://soulcraft-research.github.io/brainy/demo/index.html) | [Quick Start](#-quick-start) | [Documentation](docs/) | [Examples](examples/)
|
|
|
|
</div>
|
|
|
|
## ✨ Why Brainy?
|
|
|
|
Brainy is a production-ready vector database that **automatically adapts** to your environment. Whether you're building AI applications, recommendation systems, or knowledge graphs, Brainy provides blazing-fast semantic search with zero configuration.
|
|
|
|
### 🚀 Key Features
|
|
|
|
- **⚡ Lightning Fast** - Sub-second search across millions of vectors
|
|
- **🌍 Runs Everywhere** - Browser, Node.js, Deno, Bun, Edge Workers, Containers
|
|
- **🧠 Zero Configuration** - Auto-detects environment and optimizes automatically
|
|
- **📈 Self-Optimizing** - Gets faster the more you use it through adaptive learning
|
|
- **🔄 Graph Relationships** - Connect data with semantic relationships, not just vectors
|
|
- **💾 75% Memory Reduction** - Advanced compression and intelligent caching
|
|
- **🎯 Production Ready** - Battle-tested with comprehensive optimizations
|
|
|
|
### 📊 Performance at Scale
|
|
|
|
| Dataset Size | Search Time | Memory Usage |
|
|
|-------------|-------------|--------------|
|
|
| 10k vectors | ~50ms | Standard |
|
|
| 100k vectors | ~200ms | 30% reduction |
|
|
| 1M+ vectors | ~500ms | 75% reduction |
|
|
|
|
## 🎯 Quick Start
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
npm install @soulcraft/brainy
|
|
```
|
|
|
|
### Zero Configuration Setup
|
|
|
|
```typescript
|
|
import { createAutoBrainy } from '@soulcraft/brainy'
|
|
|
|
// That's it! Everything is auto-configured
|
|
const brainy = createAutoBrainy()
|
|
|
|
// Add data (automatically converted to vectors)
|
|
await brainy.add("Cats are independent pets", {
|
|
category: 'animal',
|
|
type: 'domestic'
|
|
})
|
|
|
|
// Search semantically
|
|
const results = await brainy.searchText("feline companions", 5)
|
|
console.log(results) // Returns similar items with scores
|
|
```
|
|
|
|
### Choose Your Scale
|
|
|
|
```typescript
|
|
import { createQuickBrainy } from '@soulcraft/brainy'
|
|
|
|
// Pick your scale: 'small', 'medium', 'large', 'enterprise'
|
|
const brainy = await createQuickBrainy('large', {
|
|
bucketName: 'my-vector-storage' // Optional S3 storage
|
|
})
|
|
```
|
|
|
|
| Scale | Dataset Size | Best For |
|
|
|-------|-------------|----------|
|
|
| `small` | ≤10k vectors | Development, prototypes |
|
|
| `medium` | ≤100k vectors | Production apps |
|
|
| `large` | ≤1M vectors | Large applications |
|
|
| `enterprise` | ≤10M vectors | Enterprise systems |
|
|
|
|
## 🔥 Core Concepts
|
|
|
|
### Vector + Graph = Knowledge
|
|
|
|
Brainy combines vector similarity with graph relationships:
|
|
|
|
```typescript
|
|
// Add entities (automatically vectorized)
|
|
const catId = await db.add("Cats are independent pets", {
|
|
noun: NounType.Thing,
|
|
category: 'animal'
|
|
})
|
|
|
|
const dogId = await db.add("Dogs are loyal companions", {
|
|
noun: NounType.Thing,
|
|
category: 'animal'
|
|
})
|
|
|
|
// Create relationships
|
|
await db.addVerb(catId, dogId, {
|
|
verb: VerbType.RelatedTo,
|
|
relationship: 'both are pets'
|
|
})
|
|
|
|
// Search returns both similar vectors AND related entities
|
|
const results = await db.searchText("household pets", 5)
|
|
```
|
|
|
|
### Advanced Search Capabilities
|
|
|
|
```typescript
|
|
// Search within JSON document fields
|
|
const results = await db.search("Acme Corp", 10, {
|
|
searchField: "company"
|
|
})
|
|
|
|
// Search by entity type
|
|
const people = await db.searchByNounTypes([NounType.Person], 10)
|
|
|
|
// Batch operations for performance
|
|
const ids = await db.addBatch([
|
|
{ vectorOrData: "First item", metadata: { category: 'A' }},
|
|
{ vectorOrData: "Second item", metadata: { category: 'B' }}
|
|
], { concurrency: 4, batchSize: 50 })
|
|
```
|
|
|
|
## 🏗️ Architecture
|
|
|
|
Brainy uses cutting-edge technologies to deliver exceptional performance:
|
|
|
|
- **HNSW Algorithm** - Hierarchical Navigable Small World for O(log n) search
|
|
- **TensorFlow.js** - Hardware-accelerated embeddings using GPU/WebGL
|
|
- **Multi-tier Storage** - Hot (RAM) → Warm (Fast Storage) → Cold (S3/Disk)
|
|
- **Semantic Partitioning** - Auto-clusters similar vectors for faster retrieval
|
|
- **Adaptive Caching** - Learns your access patterns and optimizes accordingly
|
|
|
|
## 📚 Documentation
|
|
|
|
- **[Getting Started Guide](docs/getting-started/)** - Installation and first steps
|
|
- **[User Guides](docs/user-guides/)** - Advanced usage and best practices
|
|
- **[API Reference](docs/api-reference/)** - Complete method documentation
|
|
- **[Optimization Guide](docs/optimization-guides/large-scale-optimizations.md)** - Scale to millions of vectors
|
|
- **[Examples](examples/)** - Real-world usage examples
|
|
|
|
## 🛠️ Advanced Features
|
|
|
|
### Augmentation Pipeline
|
|
|
|
Extend Brainy with custom data processing:
|
|
|
|
```typescript
|
|
import { createSenseAugmentation, pipeline } from '@soulcraft/brainy'
|
|
|
|
// Create custom augmentation
|
|
const customProcessor = createSenseAugmentation({
|
|
name: 'my-processor',
|
|
processRawData: async (data, type) => {
|
|
// Your custom logic
|
|
return { nouns: [], verbs: [] }
|
|
}
|
|
})
|
|
|
|
// Register and use
|
|
pipeline.register(customProcessor)
|
|
```
|
|
|
|
### Model Control Protocol (MCP)
|
|
|
|
Let AI models interact with your Brainy database:
|
|
|
|
```typescript
|
|
import { BrainyMCPAdapter } from '@soulcraft/brainy'
|
|
|
|
const adapter = new BrainyMCPAdapter(brainy)
|
|
// Now AI models can query and update your database
|
|
```
|
|
|
|
## 🎮 Live Demo
|
|
|
|
**[Try it now!](https://soulcraft-research.github.io/brainy/demo/index.html)**
|
|
|
|
See Brainy in action with our interactive demo showcasing vector search, graph relationships, and cross-environment compatibility.
|
|
|
|
## 🤝 Contributing
|
|
|
|
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md).
|
|
|
|
### Development
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Run tests
|
|
npm test
|
|
|
|
# Build project
|
|
npm run build
|
|
|
|
# Run demo locally
|
|
npm run demo
|
|
```
|
|
|
|
## 📄 License
|
|
|
|
[MIT](LICENSE) - Use it freely in your projects!
|
|
|
|
## 🙏 Acknowledgments
|
|
|
|
Built with ❤️ using:
|
|
- [TensorFlow.js](https://www.tensorflow.org/js) for embeddings
|
|
- [Universal Sentence Encoder](https://tfhub.dev/google/universal-sentence-encoder/4) for text vectorization
|
|
|
|
---
|
|
|
|
<div align="center">
|
|
<b>Ready to build something amazing?</b><br>
|
|
<a href="docs/getting-started/quick-start.md">Get Started →</a>
|
|
</div> |