# RuVector [![Crates.io](https://img.shields.io/crates/v/ruvector-core.svg)](https://crates.io/crates/ruvector-core) [![npm](https://img.shields.io/npm/v/ruvector.svg)](https://www.npmjs.com/package/ruvector) [![npm Downloads](https://img.shields.io/npm/dm/ruvector.svg?label=monthly)](https://www.npmjs.com/package/ruvector) [![HuggingFace](https://img.shields.io/badge/🤗-RuvLTRA_Models-yellow.svg)](https://huggingface.co/ruv/ruvltra) [![ruv.io](https://img.shields.io/badge/ruv.io-website-purple.svg)](https://ruv.io) [![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) **The vector database that gets smarter the more you use it.** ```bash npx ruvector ``` Most vector databases are static—they store embeddings and search them. That's it. RuVector is different: it learns from every query, runs LLMs locally, scales horizontally, and costs nothing to operate. | | Pinecone/Weaviate | RuVector | |---|---|---| | **Search improves over time** | ❌ | ✅ GNN layers learn from usage | | **Run LLMs locally** | ❌ | ✅ ruvllm + RuvLTRA models ($0) | | **Graph queries (Cypher)** | ❌ | ✅ `MATCH (a)-[:SIMILAR]->(b)` | | **Self-learning AI hooks** | ❌ | ✅ Q-learning, HNSW memory | | **Real-time graph updates** | ❌ Rebuild index | ✅ Dynamic min-cut (no rebuild) | | **Horizontal scaling** | 💰 Paid | ✅ Raft consensus, free | | **Works offline** | ❌ | ✅ Browser, edge, embedded | **One package. Everything included:** vector search, graph queries, GNN learning, distributed clustering, local LLMs, 39 attention mechanisms, and WASM support.

📋 See Full Capabilities (14 features)

| # | Capability | What It Does | |---|------------|--------------| | 1 | **Store vectors** | Like any vector DB (embeddings from OpenAI, Cohere, local ONNX) | | 2 | **Query with Cypher** | Graph queries like Neo4j (`MATCH (a)-[:SIMILAR]->(b)`) | | 3 | **The index learns** | GNN layers make search results improve over time | | 4 | **Scale horizontally** | Raft consensus, multi-master replication, auto-sharding | | 5 | **Route AI requests** | Semantic routing + FastGRNN for LLM optimization | | 6 | **Run LLMs locally** | ruvllm with GGUF, Metal/CUDA, save $250+/month on API costs | | 6a | **RuvLTRA models** | Pre-trained GGUF models for routing & embeddings (<10ms, $0) → [HuggingFace](https://huggingface.co/ruv/ruvltra) | | 7 | **Self-learning hooks** | Q-learning, neural patterns, HNSW memory, swarm coordination | | 8 | **Compress automatically** | 2-32x memory reduction with adaptive tiered compression | | 9 | **39 attention mechanisms** | Flash, linear, graph, hyperbolic, mincut-gated (50% compute) | | 10 | **Drop into Postgres** | pgvector-compatible extension with SIMD acceleration | | 11 | **Run anywhere** | Node.js, browser (WASM), edge (rvLite), HTTP server, Rust | | 12 | **Continuous learning** | SONA with LoRA, EWC++, ReasoningBank for runtime adaptation | | 13 | **MCP integration** | Model Context Protocol server for AI assistant tools | | 14 | **Quantum coherence** | ruQu for quantum error correction via dynamic min-cut |

*Think of it as: **Pinecone + Neo4j + PyTorch + llama.cpp + postgres + etcd** — in one Rust package.* --- ### Ecosystem: AI Agent Orchestration RuVector powers two major AI orchestration platforms: | Platform | Purpose | Install | |----------|---------|---------| | [**Claude-Flow**](https://github.com/ruvnet/claude-flow) | Enterprise multi-agent orchestration for Claude Code | `npx @claude-flow/cli@latest` | | [**Agentic-Flow**](https://github.com/ruvnet/agentic-flow) | Standalone AI agent framework (any LLM provider) | `npx agentic-flow@latest` |

Claude-Flow v3 — Turn Claude Code into a collaborative AI team

**54+ specialized agents** working together on complex software engineering tasks: ```bash # Install npx @claude-flow/cli@latest init --wizard # Spawn a swarm npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8 ``` **Key Features:** - **SONA Learning**: Sub-50ms adaptive routing, learns optimal patterns over time - **Queen-led Swarms**: Byzantine fault-tolerant consensus with 5 protocols (Raft, Gossip, CRDT) - **HNSW Memory**: 150x-12,500x faster pattern retrieval via RuVector - **175+ MCP Tools**: Native Model Context Protocol integration - **Cost Optimization**: 3-tier routing extends Claude Code quota by 2.5x - **Security**: AIDefence threat detection (<10ms), prompt injection blocking

Agentic-Flow v2 — Production AI agents for any cloud

**66 self-learning agents** with Claude Agent SDK, deployable to any cloud: ```bash # Install npx agentic-flow@latest # Or with npm npm install agentic-flow ``` **Key Features:** - **SONA Architecture**: <1ms adaptive learning, +55% quality improvement - **Flash Attention**: 2.49x JS speedup, 7.47x with NAPI bindings - **213 MCP Tools**: Swarm management, memory, GitHub integration - **Agent Booster**: 352x faster code editing for simple transforms - **Multi-Provider**: Claude, GPT, Gemini, Cohere, local models with failover - **Graph Reasoning**: GNN query refinement with +12.4% recall improvement

--- ## How the GNN Works Traditional vector search: ``` Query → HNSW Index → Top K Results ``` RuVector with GNN: ``` Query → HNSW Index → GNN Layer → Enhanced Results ↑ │ └──── learns from ─────┘ ``` The GNN layer: 1. Takes your query and its nearest neighbors 2. Applies multi-head attention to weigh which neighbors matter 3. Updates representations based on graph structure 4. Returns better-ranked results Over time, frequently-accessed paths get reinforced, making common queries faster and more accurate. ## Quick Start ### One-Line Install ```bash # Interactive installer - lists all packages npx ruvector install # Or install directly npm install ruvector npx ruvector # Self-learning hooks for Claude Code npx @ruvector/cli hooks init npx @ruvector/cli hooks install # LLM runtime (SONA learning, HNSW memory) npm install @ruvector/ruvllm ``` ### Node.js / Browser ```bash # Install npm install ruvector # Or try instantly npx ruvector ```

📊 Comparison with Other Vector Databases

| Feature | RuVector | Pinecone | Qdrant | Milvus | ChromaDB | |---------|----------|----------|--------|--------|----------| | **Latency (p50)** | **61µs** | ~2ms | ~1ms | ~5ms | ~50ms | | **Memory (1M vec)** | 200MB* | 2GB | 1.5GB | 1GB | 3GB | | **Graph Queries** | ✅ Cypher | ❌ | ❌ | ❌ | ❌ | | **SPARQL/RDF** | ✅ W3C 1.1 | ❌ | ❌ | ❌ | ❌ | | **Hyperedges** | ✅ | ❌ | ❌ | ❌ | ❌ | | **Dynamic Min-Cut** | ✅ n^0.12 | ❌ | ❌ | ❌ | ❌ | | **Self-Learning (GNN)** | ✅ | ❌ | ❌ | ❌ | ❌ | | **Runtime Adaptation (SONA)** | ✅ LoRA+EWC++ | ❌ | ❌ | ❌ | ❌ | | **AI Agent Routing** | ✅ Tiny Dancer | ❌ | ❌ | ❌ | ❌ | | **Attention Mechanisms** | ✅ 39 types | ❌ | ❌ | ❌ | ❌ | | **Hyperbolic Embeddings** | ✅ Poincaré+Lorentz | ❌ | ❌ | ❌ | ❌ | | **Local Embeddings** | ✅ 6 models | ❌ | ❌ | ❌ | ❌ | | **PostgreSQL Extension** | ✅ 77+ functions | ❌ | ❌ | ❌ | ❌ | | **SIMD Optimization** | ✅ AVX-512/NEON | Partial | ✅ | ✅ | ❌ | | **Metadata Filtering** | ✅ | ✅ | ✅ | ✅ | ✅ | | **Sparse Vectors** | ✅ BM25/TF-IDF | ✅ | ✅ | ✅ | ❌ | | **Raft Consensus** | ✅ | ❌ | ✅ | ❌ | ❌ | | **Multi-Master Replication** | ✅ | ❌ | ❌ | ✅ | ❌ | | **Auto-Sharding** | ✅ | ✅ | ✅ | ✅ | ❌ | | **Auto-Compression** | ✅ 2-32x | ❌ | ❌ | ✅ | ❌ | | **Snapshots/Backups** | ✅ | ✅ | ✅ | ✅ | ❌ | | **Browser/WASM** | ✅ | ❌ | ❌ | ❌ | ❌ | | **Standalone Edge DB** | ✅ rvLite | ❌ | ❌ | ❌ | ❌ | | **LLM Runtime** | ✅ ruvllm | ❌ | ❌ | ❌ | ❌ | | **Pre-trained Models** | ✅ RuvLTRA (HF) | ❌ | ❌ | ❌ | ❌ | | **MCP Server** | ✅ mcp-gate | ❌ | ❌ | ❌ | ❌ | | **Self-Learning Hooks** | ✅ Q-learning+Neural+HNSW | ❌ | ❌ | ❌ | ❌ | | **Quantum Coherence** | ✅ ruQu | ❌ | ❌ | ❌ | ❌ | | **MinCut-Gated Attention** | ✅ 50% compute | ❌ | ❌ | ❌ | ❌ | | **FPGA Acceleration** | ✅ | ❌ | ❌ | ❌ | ❌ | | **Local ONNX Embeddings** | ✅ 8+ models | ❌ | ❌ | ❌ | ❌ | | **Differentiable** | ✅ | ❌ | ❌ | ❌ | ❌ | | **Multi-Tenancy** | ✅ Collections | ✅ | ✅ | ✅ | ✅ | | **Open Source** | ✅ MIT | ❌ | ✅ | ✅ | ✅ | *With PQ8 compression. Benchmarks on Apple M2 / Intel i7.

⚡ Core Features & Capabilities

### Core Capabilities | Feature | What It Does | Why It Matters | |---------|--------------|----------------| | **Vector Search** | HNSW index, <0.5ms latency, SIMD acceleration | Fast enough for real-time apps | | **Cypher Queries** | `MATCH`, `WHERE`, `CREATE`, `RETURN` | Familiar Neo4j syntax | | **GNN Layers** | Neural network on index topology | Search improves with usage | | **Hyperedges** | Connect 3+ nodes at once | Model complex relationships | | **Metadata Filtering** | Filter vectors by properties | Combine semantic + structured search | | **Collections** | Namespace isolation, multi-tenancy | Organize vectors by project/user | ### Distributed Systems | Feature | What It Does | Why It Matters | |---------|--------------|----------------| | **Raft Consensus** | Leader election, log replication | Strong consistency for metadata | | **Auto-Sharding** | Consistent hashing, shard migration | Scale to billions of vectors | | **Multi-Master Replication** | Write to any node, conflict resolution | High availability, no SPOF | | **Snapshots** | Point-in-time backups, incremental | Disaster recovery | | **Cluster Metrics** | Prometheus-compatible monitoring | Observability at scale | ```bash cargo add ruvector-raft ruvector-cluster ruvector-replication ``` ### AI & ML | Feature | What It Does | Why It Matters | |---------|--------------|----------------| | **Tensor Compression** | f32→f16→PQ8→PQ4→Binary | 2-32x memory reduction | | **Differentiable Search** | Soft attention k-NN | End-to-end trainable | | **Semantic Router** | Route queries to optimal endpoints | Multi-model AI orchestration | | **Hybrid Routing** | Keyword-first + embedding fallback | **90% accuracy** for agent routing | | **Tiny Dancer** | FastGRNN neural inference | Optimize LLM inference costs | | **Adaptive Routing** | Learn optimal routing strategies | Minimize latency, maximize accuracy | | **SONA** | Two-tier LoRA + EWC++ + ReasoningBank | Runtime learning without retraining | ### Attention Mechanisms (`@ruvector/attention`) | Feature | What It Does | Why It Matters | |---------|--------------|----------------| | **39 Mechanisms** | Dot-product, multi-head, flash, linear, sparse, cross-attention | Cover all transformer and GNN use cases | | **Graph Attention** | RoPE, edge-featured, local-global, neighborhood | Purpose-built for graph neural networks | | **Hyperbolic Attention** | Poincaré ball operations, curved-space math | Better embeddings for hierarchical data | | **SIMD Optimized** | Native Rust with AVX2/NEON acceleration | 2-10x faster than pure JS | | **Streaming & Caching** | Chunk-based processing, KV-cache | Constant memory, 10x faster inference | > **Documentation**: [Attention Module Docs](./crates/ruvector-attention/README.md) #### Core Attention Mechanisms Standard attention layers for sequence modeling and transformers. | Mechanism | Complexity | Memory | Best For | |-----------|------------|--------|----------| | **DotProductAttention** | O(n²) | O(n²) | Basic attention for small-medium sequences | | **MultiHeadAttention** | O(n²·h) | O(n²·h) | BERT, GPT-style transformers | | **FlashAttention** | O(n²) | O(n) | Long sequences with limited GPU memory | | **LinearAttention** | O(n·d) | O(n·d) | 8K+ token sequences, real-time streaming | | **HyperbolicAttention** | O(n²) | O(n²) | Tree-like data: taxonomies, org charts | | **MoEAttention** | O(n·k) | O(n·k) | Large models with sparse expert routing | #### Graph Attention Mechanisms Attention layers designed for graph-structured data and GNNs. | Mechanism | Complexity | Best For | |-----------|------------|----------| | **GraphRoPeAttention** | O(n²) | Position-aware graph transformers | | **EdgeFeaturedAttention** | O(n²·e) | Molecules, knowledge graphs with edge data | | **DualSpaceAttention** | O(n²) | Hybrid flat + hierarchical embeddings | | **LocalGlobalAttention** | O(n·k + n) | 100K+ node graphs, scalable GNNs | #### Specialized Mechanisms Task-specific attention variants for efficiency and multi-modal learning. | Mechanism | Type | Best For | |-----------|------|----------| | **SparseAttention** | Efficiency | Long docs, low-memory inference | | **CrossAttention** | Multi-modal | Image-text, encoder-decoder models | | **NeighborhoodAttention** | Graph | Local message passing in GNNs | | **HierarchicalAttention** | Structure | Multi-level docs (section → paragraph) | #### Hyperbolic Math Functions Operations for Poincaré ball embeddings—curved space that naturally represents hierarchies. | Function | Description | Use Case | |----------|-------------|----------| | `expMap(v, c)` | Map to hyperbolic space | Initialize embeddings | | `logMap(p, c)` | Map to flat space | Compute gradients | | `mobiusAddition(x, y, c)` | Add vectors in curved space | Aggregate features | | `poincareDistance(x, y, c)` | Measure hyperbolic distance | Compute similarity | | `projectToPoincareBall(p, c)` | Ensure valid coordinates | Prevent numerical errors | #### Async & Batch Operations Utilities for high-throughput inference and training optimization. | Operation | Description | Performance | |-----------|-------------|-------------| | `asyncBatchCompute()` | Process batches in parallel | 3-5x faster | | `streamingAttention()` | Process in chunks | Fixed memory usage | | `HardNegativeMiner` | Find hard training examples | Better contrastive learning | | `AttentionCache` | Cache key-value pairs | 10x faster inference | ```bash # Install attention module npm install @ruvector/attention # CLI commands npx ruvector attention list # List all 39 mechanisms npx ruvector attention info flash # Details on FlashAttention npx ruvector attention benchmark # Performance comparison npx ruvector attention compute -t dot -d 128 # Run attention computation npx ruvector attention hyperbolic -a distance -v "[0.1,0.2]" -b "[0.3,0.4]" ```

🚀 Deployment Options

| Feature | What It Does | Why It Matters | |---------|--------------|----------------| | **HTTP/gRPC Server** | REST API, streaming support | Easy integration | | **WASM/Browser** | Full client-side support | Run AI search offline | | **Node.js Bindings** | Native napi-rs bindings | No serialization overhead | | **FFI Bindings** | C-compatible interface | Use from Python, Go, etc. | | **CLI Tools** | Benchmarking, testing, management | DevOps-friendly |

📈 Performance Benchmarks

**Measured results** from [`/bench_results/`](./bench_results/): | Configuration | QPS | p50 Latency | p99 Latency | Recall | |---------------|-----|-------------|-------------|--------| | **ruvector (optimized)** | 1,216 | 0.78ms | 0.78ms | 100% | | **Multi-threaded (16)** | 3,597 | 2.86ms | 8.47ms | 100% | | **ef_search=50** | 674 | 1.35ms | 1.35ms | 100% | | Python baseline | 77 | 11.88ms | 11.88ms | 100% | | Brute force | 12 | 77.76ms | 77.76ms | 100% | *Dataset: 384D, 10K-50K vectors. See full results in [latency_benchmark.md](./bench_results/latency_benchmark.md).* | Operation | Dimensions | Time | Throughput | |-----------|------------|------|------------| | **HNSW Search (k=10)** | 384 | 61µs | 16,400 QPS | | **HNSW Search (k=100)** | 384 | 164µs | 6,100 QPS | | **Cosine Distance** | 1536 | 143ns | 7M ops/sec | | **Dot Product** | 384 | 33ns | 30M ops/sec | | **Batch Distance (1000)** | 384 | 237µs | 4.2M/sec | ### Global Cloud Performance (500M Streams) Production-validated metrics at hyperscale: | Metric | Value | Details | |--------|-------|---------| | **Concurrent Streams** | 500M baseline | Burst capacity to 25B (50x) | | **Global Latency (p50)** | <10ms | Multi-region + CDN edge caching | | **Global Latency (p99)** | <50ms | Cross-continental with failover | | **Availability SLA** | 99.99% | 15 regions, automatic failover | | **Cost per Stream/Month** | $0.0035 | 60% optimized ($1.74M total at 500M) | | **Regions** | 15 global | Americas, EMEA, APAC coverage | | **Throughput per Region** | 100K+ QPS | Adaptive batching enabled | | **Memory Efficiency** | 2-32x compression | Tiered hot/warm/cold storage | | **Index Build Time** | 1M vectors/min | Parallel HNSW construction | | **Replication Lag** | <100ms | Multi-master async replication |

🗜️ Adaptive Compression Tiers

**The architecture adapts to your data.** Hot paths get full precision and maximum compute. Cold paths compress automatically and throttle resources. Recent data stays crystal clear; historical data optimizes itself in the background. Think of it like your computer's memory hierarchy—frequently accessed data lives in fast cache, while older files move to slower, denser storage. RuVector does this automatically for your vectors: | Access Frequency | Format | Compression | What Happens | |-----------------|--------|-------------|--------------| | **Hot** (>80%) | f32 | 1x | Full precision, instant retrieval | | **Warm** (40-80%) | f16 | 2x | Slight compression, imperceptible latency | | **Cool** (10-40%) | PQ8 | 8x | Smart quantization, ~1ms overhead | | **Cold** (1-10%) | PQ4 | 16x | Heavy compression, still fast search | | **Archive** (<1%) | Binary | 32x | Maximum density, batch retrieval | **No configuration needed.** RuVector tracks access patterns and automatically promotes/demotes vectors between tiers. Your hot data stays fast; your cold data shrinks.

💡 Use Cases

**RAG (Retrieval-Augmented Generation)** ```javascript const context = ruvector.search(questionEmbedding, 5); const prompt = `Context: ${context.join('\n')}\n\nQuestion: ${question}`; ``` **Recommendation Systems** ```cypher MATCH (user:User)-[:VIEWED]->(item:Product) MATCH (item)-[:SIMILAR_TO]->(rec:Product) RETURN rec ORDER BY rec.score DESC LIMIT 10 ``` **Knowledge Graphs** ```cypher MATCH (concept:Concept)-[:RELATES_TO*1..3]->(related) RETURN related ```

## Installation | Platform | Command | |----------|---------| | **npm** | `npm install ruvector` | | **npm (SONA)** | `npm install @ruvector/sona` | | **Browser/WASM** | `npm install ruvector-wasm` | | **Rust** | `cargo add ruvector-core ruvector-graph ruvector-gnn` | | **Rust (SONA)** | `cargo add ruvector-sona` | | **Rust (LLM)** | `cargo add ruvllm` |

📖 Documentation

| Topic | Link | |-------|------| | Getting Started | [docs/guides/GETTING_STARTED.md](./docs/guides/GETTING_STARTED.md) | | Cypher Reference | [docs/api/CYPHER_REFERENCE.md](./docs/api/CYPHER_REFERENCE.md) | | GNN Architecture | [docs/gnn/gnn-layer-implementation.md](./docs/gnn/gnn-layer-implementation.md) | | Node.js API | [crates/ruvector-gnn-node/README.md](./crates/ruvector-gnn-node/README.md) | | WASM API | [crates/ruvector-gnn-wasm/README.md](./crates/ruvector-gnn-wasm/README.md) | | Performance Tuning | [docs/optimization/PERFORMANCE_TUNING_GUIDE.md](./docs/optimization/PERFORMANCE_TUNING_GUIDE.md) | | API Reference | [docs/api/](./docs/api/) | ### Architecture Decision Records (ADRs) | ADR | Status | Description | |-----|--------|-------------| | [ADR-001](./docs/adr/ADR-001-ruvector-core-architecture.md) | Accepted | Core architecture design | | [ADR-002](./docs/adr/ADR-002-ruvllm-integration.md) | Accepted | RuvLLM integration | | [ADR-003](./docs/adr/ADR-003-simd-optimization-strategy.md) | Accepted | SIMD optimization strategy | | [ADR-004](./docs/adr/ADR-004-kv-cache-management.md) | Accepted | KV cache management | | [ADR-005](./docs/adr/ADR-005-wasm-runtime-integration.md) | Accepted | WASM runtime integration | | [ADR-006](./docs/adr/ADR-006-memory-management.md) | Accepted | Memory management | | [ADR-007](./docs/adr/ADR-007-security-review-technical-debt.md) | Accepted | Security review | | [ADR-008](./docs/adr/ADR-008-mistral-rs-integration.md) | **New** | Mistral-rs backend integration | | [ADR-009](./docs/adr/ADR-009-structured-output.md) | **New** | Structured output (SOTA) | | [ADR-010](./docs/adr/ADR-010-function-calling.md) | **New** | Function calling (SOTA) | | [ADR-011](./docs/adr/ADR-011-prefix-caching.md) | **New** | Prefix caching (SOTA) | | [ADR-012](./docs/adr/ADR-012-security-remediation.md) | **New** | Security remediation | | [ADR-013](./docs/adr/ADR-013-huggingface-publishing.md) | **New** | HuggingFace publishing |

🦀 Rust Crates (63 Packages)

All crates are published to [crates.io](https://crates.io) under the `ruvector-*` namespace. ### Core Crates | Crate | Description | crates.io | |-------|-------------|-----------| | [ruvector-core](./crates/ruvector-core) | Vector database engine with HNSW indexing | [![crates.io](https://img.shields.io/crates/v/ruvector-core.svg)](https://crates.io/crates/ruvector-core) | | [ruvector-collections](./crates/ruvector-collections) | Collection and namespace management | [![crates.io](https://img.shields.io/crates/v/ruvector-collections.svg)](https://crates.io/crates/ruvector-collections) | | [ruvector-filter](./crates/ruvector-filter) | Vector filtering and metadata queries | [![crates.io](https://img.shields.io/crates/v/ruvector-filter.svg)](https://crates.io/crates/ruvector-filter) | | [ruvector-metrics](./crates/ruvector-metrics) | Performance metrics and monitoring | [![crates.io](https://img.shields.io/crates/v/ruvector-metrics.svg)](https://crates.io/crates/ruvector-metrics) | | [ruvector-snapshot](./crates/ruvector-snapshot) | Snapshot and persistence management | [![crates.io](https://img.shields.io/crates/v/ruvector-snapshot.svg)](https://crates.io/crates/ruvector-snapshot) | ### Graph & GNN | Crate | Description | crates.io | |-------|-------------|-----------| | [ruvector-graph](./crates/ruvector-graph) | Hypergraph database with Neo4j-style Cypher | [![crates.io](https://img.shields.io/crates/v/ruvector-graph.svg)](https://crates.io/crates/ruvector-graph) | | [ruvector-graph-node](./crates/ruvector-graph-node) | Node.js bindings for graph operations | [![crates.io](https://img.shields.io/crates/v/ruvector-graph-node.svg)](https://crates.io/crates/ruvector-graph-node) | | [ruvector-graph-wasm](./crates/ruvector-graph-wasm) | WASM bindings for browser graph queries | [![crates.io](https://img.shields.io/crates/v/ruvector-graph-wasm.svg)](https://crates.io/crates/ruvector-graph-wasm) | | [ruvector-gnn](./crates/ruvector-gnn) | Graph Neural Network layers and training | [![crates.io](https://img.shields.io/crates/v/ruvector-gnn.svg)](https://crates.io/crates/ruvector-gnn) | | [ruvector-gnn-node](./crates/ruvector-gnn-node) | Node.js bindings for GNN inference | [![crates.io](https://img.shields.io/crates/v/ruvector-gnn-node.svg)](https://crates.io/crates/ruvector-gnn-node) | | [ruvector-gnn-wasm](./crates/ruvector-gnn-wasm) | WASM bindings for browser GNN | [![crates.io](https://img.shields.io/crates/v/ruvector-gnn-wasm.svg)](https://crates.io/crates/ruvector-gnn-wasm) | ### Attention Mechanisms | Crate | Description | crates.io | |-------|-------------|-----------| | [ruvector-attention](./crates/ruvector-attention) | 39 attention mechanisms (Flash, Hyperbolic, MoE, Graph) | [![crates.io](https://img.shields.io/crates/v/ruvector-attention.svg)](https://crates.io/crates/ruvector-attention) | | [ruvector-attention-node](./crates/ruvector-attention-node) | Node.js bindings for attention mechanisms | [![crates.io](https://img.shields.io/crates/v/ruvector-attention-node.svg)](https://crates.io/crates/ruvector-attention-node) | | [ruvector-attention-wasm](./crates/ruvector-attention-wasm) | WASM bindings for browser attention | [![crates.io](https://img.shields.io/crates/v/ruvector-attention-wasm.svg)](https://crates.io/crates/ruvector-attention-wasm) | | [ruvector-attention-cli](./crates/ruvector-attention-cli) | CLI for attention testing and benchmarking | [![crates.io](https://img.shields.io/crates/v/ruvector-attention-cli.svg)](https://crates.io/crates/ruvector-attention-cli) | ### LLM Runtime (ruvllm) | Crate | Description | crates.io | |-------|-------------|-----------| | [ruvllm](./crates/ruvllm) | LLM serving runtime with SONA, paged attention, KV cache | [![crates.io](https://img.shields.io/crates/v/ruvllm.svg)](https://crates.io/crates/ruvllm) | | [ruvllm-cli](./crates/ruvllm-cli) | CLI for model inference and benchmarking | [![crates.io](https://img.shields.io/crates/v/ruvllm-cli.svg)](https://crates.io/crates/ruvllm-cli) | | [ruvllm-wasm](./crates/ruvllm-wasm) | WASM bindings for browser LLM inference | [![crates.io](https://img.shields.io/crates/v/ruvllm-wasm.svg)](https://crates.io/crates/ruvllm-wasm) | **Features:** Candle backend, Metal/CUDA acceleration, Apple Neural Engine, GGUF support, SONA learning integration. ```bash cargo add ruvllm --features inference-metal # Mac with Metal cargo add ruvllm --features inference-cuda # NVIDIA GPU ``` **RuvLTRA Models** — Pre-trained GGUF models optimized for Claude Code workflows: | Model | Size | Use Case | Link | |-------|------|----------|------| | ruvltra-claude-code-0.5b-q4_k_m | 398 MB | Agent routing | [HuggingFace](https://huggingface.co/ruv/ruvltra) | | ruvltra-small-0.5b-q4_k_m | 398 MB | Embeddings | [HuggingFace](https://huggingface.co/ruv/ruvltra) | | ruvltra-medium-1.1b-q4_k_m | 800 MB | Classification | [HuggingFace](https://huggingface.co/ruv/ruvltra) | ```bash # Download and use wget https://huggingface.co/ruv/ruvltra/resolve/main/ruvltra-small-0.5b-q4_k_m.gguf ```

🎓 RuvLLM Training & Fine-Tuning Tutorials

#### Hybrid Routing (90% Accuracy) RuvLTRA achieves **90% routing accuracy** using a keyword-first strategy with embedding fallback: ```javascript // Optimal routing: Keywords first, embeddings as tiebreaker function routeTask(task, taskEmbedding, agentEmbeddings) { const keywordScores = getKeywordScores(task); const maxKw = Math.max(...Object.values(keywordScores)); if (maxKw > 0) { const candidates = Object.entries(keywordScores) .filter(([_, score]) => score === maxKw) .map(([agent]) => agent); if (candidates.length === 1) return { agent: candidates[0] }; return pickByEmbedding(candidates, taskEmbedding, agentEmbeddings); } return embeddingSimilarity(taskEmbedding, agentEmbeddings); } ``` Run the benchmark: `node npm/packages/ruvllm/scripts/hybrid-model-compare.js` #### Generate Training Data ```bash # Using CLI (recommended) npx @ruvector/ruvllm train stats # View dataset statistics npx @ruvector/ruvllm train dataset # Export training data npx @ruvector/ruvllm train contrastive # Run full training pipeline # With options npx @ruvector/ruvllm train dataset --output ./my-training npx @ruvector/ruvllm train contrastive --epochs 20 --batch-size 32 --lr 0.0001 ``` **Programmatic API:** ```javascript import { ContrastiveTrainer, generateTrainingDataset, getDatasetStats } from '@ruvector/ruvllm'; const stats = getDatasetStats(); console.log(`${stats.totalExamples} examples, ${stats.agentTypes} agent types`); const trainer = new ContrastiveTrainer({ epochs: 10, margin: 0.5 }); trainer.addTriplet(anchor, anchorEmb, positive, positiveEmb, negative, negativeEmb, true); const result = trainer.train(); trainer.exportTrainingData('./output'); ``` #### Fine-Tune with LoRA ```bash pip install transformers peft datasets accelerate python -m peft.lora_train \ --model_name Qwen/Qwen2.5-0.5B-Instruct \ --dataset ./data/training/routing-examples.jsonl \ --output_dir ./ruvltra-routing-lora \ --lora_r 8 --lora_alpha 16 \ --num_train_epochs 3 \ --learning_rate 2e-4 ``` #### Convert to GGUF ```bash # Merge LoRA weights python -c " from peft import PeftModel from transformers import AutoModelForCausalLM base = AutoModelForCausalLM.from_pretrained('Qwen/Qwen2.5-0.5B-Instruct') model = PeftModel.from_pretrained(base, './ruvltra-routing-lora') model.merge_and_unload().save_pretrained('./ruvltra-routing-merged') " # Convert and quantize python llama.cpp/convert_hf_to_gguf.py ./ruvltra-routing-merged --outfile ruvltra-routing-f16.gguf ./llama.cpp/llama-quantize ruvltra-routing-f16.gguf ruvltra-routing-q4_k_m.gguf Q4_K_M ``` #### Contrastive Embedding Training **Using RuvLLM CLI (recommended):** ```bash # Full contrastive training pipeline with triplet loss npx @ruvector/ruvllm train contrastive --output ./training-output # Exports: triplets.jsonl, embeddings.json, lora_config.json, train.sh ``` **Using Python (for GPU training):** ```python from sentence_transformers import SentenceTransformer, losses, InputExample from torch.utils.data import DataLoader train_examples = [ InputExample(texts=["implement login", "build auth component"], label=1.0), InputExample(texts=["implement login", "write unit tests"], label=0.0), ] model = SentenceTransformer("Qwen/Qwen2.5-0.5B-Instruct") train_loss = losses.CosineSimilarityLoss(model) model.fit([(DataLoader(train_examples, batch_size=16), train_loss)], epochs=5) ``` **Resources:** [Issue #122](https://github.com/ruvnet/ruvector/issues/122) | [LoRA Paper](https://arxiv.org/abs/2106.09685) | [Sentence Transformers](https://www.sbert.net/docs/training/overview.html) #### Rust Training Module For production-scale dataset generation, use the Rust training module ([full docs](./crates/ruvllm/src/training/README.md)): ```rust use ruvllm::training::{DatasetGenerator, DatasetConfig}; let config = DatasetConfig { examples_per_category: 100, enable_augmentation: true, seed: 42, ..Default::default() }; let dataset = DatasetGenerator::new(config).generate(); let (train, val, test) = dataset.split(0.7, 0.15, 0.15, 42); dataset.export_jsonl("training.jsonl")?; ``` **Features:** - **5 agent categories**: Coder, Researcher, Security, Architecture, Reviewer (20% each) - **Model routing**: Haiku (simple) → Sonnet (moderate) → Opus (complex/security) - **Data augmentation**: Paraphrasing, complexity variations, domain transfer - **8 technical domains**: Web, Systems, DataScience, Mobile, DevOps, Security, Database, API - **Quality scores**: 0.80-0.96 based on template quality and category - **Performance**: ~10,000 examples/second, ~50 MB/s JSONL export ```bash cargo run --example generate_claude_dataset --release # Outputs: train.jsonl, val.jsonl, test.jsonl, stats.json ```

### Distributed Systems | Crate | Description | crates.io | |-------|-------------|-----------| | [ruvector-cluster](./crates/ruvector-cluster) | Cluster management and coordination | [![crates.io](https://img.shields.io/crates/v/ruvector-cluster.svg)](https://crates.io/crates/ruvector-cluster) | | [ruvector-raft](./crates/ruvector-raft) | Raft consensus implementation | [![crates.io](https://img.shields.io/crates/v/ruvector-raft.svg)](https://crates.io/crates/ruvector-raft) | | [ruvector-replication](./crates/ruvector-replication) | Data replication and synchronization | [![crates.io](https://img.shields.io/crates/v/ruvector-replication.svg)](https://crates.io/crates/ruvector-replication) | ### AI Agent Routing (Tiny Dancer) | Crate | Description | crates.io | |-------|-------------|-----------| | [ruvector-tiny-dancer-core](./crates/ruvector-tiny-dancer-core) | FastGRNN neural inference for AI routing | [![crates.io](https://img.shields.io/crates/v/ruvector-tiny-dancer-core.svg)](https://crates.io/crates/ruvector-tiny-dancer-core) | | [ruvector-tiny-dancer-node](./crates/ruvector-tiny-dancer-node) | Node.js bindings for AI routing | [![crates.io](https://img.shields.io/crates/v/ruvector-tiny-dancer-node.svg)](https://crates.io/crates/ruvector-tiny-dancer-node) | | [ruvector-tiny-dancer-wasm](./crates/ruvector-tiny-dancer-wasm) | WASM bindings for browser AI routing | [![crates.io](https://img.shields.io/crates/v/ruvector-tiny-dancer-wasm.svg)](https://crates.io/crates/ruvector-tiny-dancer-wasm) | ### Router (Semantic Routing) | Crate | Description | crates.io | |-------|-------------|-----------| | [ruvector-router-core](./crates/ruvector-router-core) | Core semantic routing engine | [![crates.io](https://img.shields.io/crates/v/ruvector-router-core.svg)](https://crates.io/crates/ruvector-router-core) | | [ruvector-router-cli](./crates/ruvector-router-cli) | CLI for router testing and benchmarking | [![crates.io](https://img.shields.io/crates/v/ruvector-router-cli.svg)](https://crates.io/crates/ruvector-router-cli) | | [ruvector-router-ffi](./crates/ruvector-router-ffi) | FFI bindings for other languages | [![crates.io](https://img.shields.io/crates/v/ruvector-router-ffi.svg)](https://crates.io/crates/ruvector-router-ffi) | | [ruvector-router-wasm](./crates/ruvector-router-wasm) | WASM bindings for browser routing | [![crates.io](https://img.shields.io/crates/v/ruvector-router-wasm.svg)](https://crates.io/crates/ruvector-router-wasm) | **Hybrid Routing** achieves **90% accuracy** for agent routing using keyword-first strategy with embedding fallback. See [Issue #122](https://github.com/ruvnet/ruvector/issues/122) for benchmarks and the [training tutorials](#-ruvllm-training--fine-tuning-tutorials) for fine-tuning guides. ### Dynamic Min-Cut (December 2025 Breakthrough) | Crate | Description | crates.io | |-------|-------------|-----------| | [ruvector-mincut](./crates/ruvector-mincut) | Subpolynomial fully-dynamic min-cut ([arXiv:2512.13105](https://arxiv.org/abs/2512.13105)) | [![crates.io](https://img.shields.io/crates/v/ruvector-mincut.svg)](https://crates.io/crates/ruvector-mincut) | | [ruvector-mincut-node](./crates/ruvector-mincut-node) | Node.js bindings for min-cut | [![crates.io](https://img.shields.io/crates/v/ruvector-mincut-node.svg)](https://crates.io/crates/ruvector-mincut-node) | | [ruvector-mincut-wasm](./crates/ruvector-mincut-wasm) | WASM bindings for browser min-cut | [![crates.io](https://img.shields.io/crates/v/ruvector-mincut-wasm.svg)](https://crates.io/crates/ruvector-mincut-wasm) | **First deterministic exact fully-dynamic min-cut** with verified **n^0.12 subpolynomial** update scaling: - **Brain connectivity** — Detect Alzheimer's markers by tracking neural pathway changes in milliseconds - **Network resilience** — Predict outages before they happen, route around failures instantly - **AI agent coordination** — Find communication bottlenecks in multi-agent systems - **Neural network pruning** — Identify which connections can be removed without losing accuracy - **448+ tests**, 256-core parallel optimization, 8KB per core (compile-time verified) ```rust use ruvector_mincut::{DynamicMinCut, Graph}; let mut graph = Graph::new(); graph.add_edge(0, 1, 10.0); graph.add_edge(1, 2, 5.0); let mincut = DynamicMinCut::new(&graph); let (value, cut_edges) = mincut.compute(); // Updates in subpolynomial time as edges change ``` ### Quantum Coherence (ruQu) | Crate | Description | crates.io | |-------|-------------|-----------| | [ruqu](./crates/ruQu) | Classical nervous system for quantum machines - coherence via min-cut | [![crates.io](https://img.shields.io/crates/v/ruqu.svg)](https://crates.io/crates/ruqu) | | [cognitum-gate-kernel](./crates/cognitum-gate-kernel) | Anytime-valid coherence gate kernel | [![crates.io](https://img.shields.io/crates/v/cognitum-gate-kernel.svg)](https://crates.io/crates/cognitum-gate-kernel) | | [cognitum-gate-tilezero](./crates/cognitum-gate-tilezero) | TileZero arbiter for coherence decisions | [![crates.io](https://img.shields.io/crates/v/cognitum-gate-tilezero.svg)](https://crates.io/crates/cognitum-gate-tilezero) | | [mcp-gate](./crates/mcp-gate) | MCP server for coherence gate integration | [![crates.io](https://img.shields.io/crates/v/mcp-gate.svg)](https://crates.io/crates/mcp-gate) | **ruQu Features:** Real-time quantum coherence assessment, MWPM decoder integration, mincut-gated attention (50% FLOPs reduction). ```rust use ruqu::{CoherenceGate, SyndromeFilter}; let gate = CoherenceGate::new(); let syndrome = gate.assess_coherence(&quantum_state)?; ``` ### Advanced Math & Inference | Crate | Description | crates.io | |-------|-------------|-----------| | [ruvector-math](./crates/ruvector-math) | Core math utilities, SIMD operations | [![crates.io](https://img.shields.io/crates/v/ruvector-math.svg)](https://crates.io/crates/ruvector-math) | | [ruvector-math-wasm](./crates/ruvector-math-wasm) | WASM bindings for math operations | [![crates.io](https://img.shields.io/crates/v/ruvector-math-wasm.svg)](https://crates.io/crates/ruvector-math-wasm) | | [ruvector-sparse-inference](./crates/ruvector-sparse-inference) | Sparse tensor inference engine | [![crates.io](https://img.shields.io/crates/v/ruvector-sparse-inference.svg)](https://crates.io/crates/ruvector-sparse-inference) | | [ruvector-sparse-inference-wasm](./crates/ruvector-sparse-inference-wasm) | WASM bindings for sparse inference | [![crates.io](https://img.shields.io/crates/v/ruvector-sparse-inference-wasm.svg)](https://crates.io/crates/ruvector-sparse-inference-wasm) | | [ruvector-hyperbolic-hnsw](./crates/ruvector-hyperbolic-hnsw) | HNSW in hyperbolic space (Poincaré/Lorentz) | [![crates.io](https://img.shields.io/crates/v/ruvector-hyperbolic-hnsw.svg)](https://crates.io/crates/ruvector-hyperbolic-hnsw) | | [ruvector-hyperbolic-hnsw-wasm](./crates/ruvector-hyperbolic-hnsw-wasm) | WASM bindings for hyperbolic HNSW | [![crates.io](https://img.shields.io/crates/v/ruvector-hyperbolic-hnsw-wasm.svg)](https://crates.io/crates/ruvector-hyperbolic-hnsw-wasm) | ### FPGA & Hardware Acceleration | Crate | Description | crates.io | |-------|-------------|-----------| | [ruvector-fpga-transformer](./crates/ruvector-fpga-transformer) | FPGA-optimized transformer inference | [![crates.io](https://img.shields.io/crates/v/ruvector-fpga-transformer.svg)](https://crates.io/crates/ruvector-fpga-transformer) | | [ruvector-fpga-transformer-wasm](./crates/ruvector-fpga-transformer-wasm) | WASM simulation of FPGA transformer | [![crates.io](https://img.shields.io/crates/v/ruvector-fpga-transformer-wasm.svg)](https://crates.io/crates/ruvector-fpga-transformer-wasm) | | [ruvector-mincut-gated-transformer](./crates/ruvector-mincut-gated-transformer) | MinCut-gated attention for 50% compute reduction | [![crates.io](https://img.shields.io/crates/v/ruvector-mincut-gated-transformer.svg)](https://crates.io/crates/ruvector-mincut-gated-transformer) | | [ruvector-mincut-gated-transformer-wasm](./crates/ruvector-mincut-gated-transformer-wasm) | WASM bindings for mincut-gated transformer | [![crates.io](https://img.shields.io/crates/v/ruvector-mincut-gated-transformer-wasm.svg)](https://crates.io/crates/ruvector-mincut-gated-transformer-wasm) | ### Neuromorphic & Bio-Inspired Learning | Crate | Description | crates.io | |-------|-------------|-----------| | [ruvector-nervous-system](./crates/ruvector-nervous-system) | Spiking neural networks with BTSP learning & EWC plasticity | [![crates.io](https://img.shields.io/crates/v/ruvector-nervous-system.svg)](https://crates.io/crates/ruvector-nervous-system) | | [ruvector-nervous-system-wasm](./crates/ruvector-nervous-system-wasm) | WASM bindings for neuromorphic learning | [![crates.io](https://img.shields.io/crates/v/ruvector-nervous-system-wasm.svg)](https://crates.io/crates/ruvector-nervous-system-wasm) | | [ruvector-learning-wasm](./crates/ruvector-learning-wasm) | MicroLoRA adaptation (<100µs latency) | [![crates.io](https://img.shields.io/crates/v/ruvector-learning-wasm.svg)](https://crates.io/crates/ruvector-learning-wasm) | | [ruvector-economy-wasm](./crates/ruvector-economy-wasm) | CRDT-based autonomous credit economy | [![crates.io](https://img.shields.io/crates/v/ruvector-economy-wasm.svg)](https://crates.io/crates/ruvector-economy-wasm) | | [ruvector-exotic-wasm](./crates/ruvector-exotic-wasm) | Exotic AI primitives (strange loops, time crystals) | [![crates.io](https://img.shields.io/crates/v/ruvector-exotic-wasm.svg)](https://crates.io/crates/ruvector-exotic-wasm) | | [ruvector-attention-unified-wasm](./crates/ruvector-attention-unified-wasm) | Unified 18+ attention mechanisms (Neural, DAG, Mamba SSM) | [![crates.io](https://img.shields.io/crates/v/ruvector-attention-unified-wasm.svg)](https://crates.io/crates/ruvector-attention-unified-wasm) | **Bio-inspired features:** - **Spiking Neural Networks (SNNs)** — 10-50x energy efficiency vs traditional ANNs - **BTSP Learning** — Behavioral Time-Scale Synaptic Plasticity for rapid adaptation - **MicroLoRA** — Sub-microsecond fine-tuning for per-operator learning - **Mamba SSM** — State Space Model attention for linear-time sequences ### Self-Learning Query DAG (ruvector-dag) | Crate | Description | crates.io | |-------|-------------|-----------| | [ruvector-dag](./crates/ruvector-dag) | Neural self-learning DAG for automatic query optimization | [![crates.io](https://img.shields.io/crates/v/ruvector-dag.svg)](https://crates.io/crates/ruvector-dag) | | [ruvector-dag-wasm](./crates/ruvector-dag-wasm) | WASM bindings for browser DAG optimization (58KB gzipped) | [![crates.io](https://img.shields.io/crates/v/ruvector-dag-wasm.svg)](https://crates.io/crates/ruvector-dag-wasm) | **Make your queries faster automatically.** RuVector DAG learns from every query execution and continuously optimizes performance—no manual tuning required. - **7 Attention Mechanisms**: Automatically selects the best strategy (Topological, Causal Cone, Critical Path, MinCut Gated, etc.) - **SONA Learning**: Self-Optimizing Neural Architecture adapts in <100μs per query - **MinCut Control**: Rising "tension" triggers automatic strategy switching and predictive healing - **50-80% Latency Reduction**: Queries improve over time without code changes ```rust use ruvector_dag::{QueryDag, OperatorNode}; use ruvector_dag::attention::{AttentionSelector, SelectionPolicy}; let mut dag = QueryDag::new(); let scan = dag.add_node(OperatorNode::hnsw_scan(0, "vectors_idx", 64)); let filter = dag.add_node(OperatorNode::filter(1, "score > 0.5")); dag.add_edge(scan, filter).unwrap(); // System learns which attention mechanism works best let selector = AttentionSelector::new(); let scores = selector.select_and_apply(SelectionPolicy::Adaptive, &dag)?; ``` See [ruvector-dag README](./crates/ruvector-dag/README.md) for full documentation. ### Standalone Vector Database (rvLite) | Crate | Description | crates.io | |-------|-------------|-----------| | [rvlite](./crates/rvlite) | SQLite-style vector database for browsers & edge | [![crates.io](https://img.shields.io/crates/v/rvlite.svg)](https://crates.io/crates/rvlite) | **Runs anywhere JavaScript runs** — browsers, Node.js, Deno, Bun, Cloudflare Workers, Vercel Edge: - **SQL + SPARQL + Cypher** unified query interface - **Zero dependencies** — thin orchestration over existing WASM crates - **Self-learning** via SONA ReasoningBank integration ```typescript import { RvLite } from '@rvlite/wasm'; const db = await RvLite.create(); await db.sql(`CREATE TABLE docs (id SERIAL, embedding VECTOR(384))`); await db.sparql(`SELECT ?s WHERE { ?s rdf:type ex:Document }`); await db.cypher(`MATCH (d:Doc)-[:SIMILAR]->(r) RETURN r`); ``` ### Self-Optimizing Neural Architecture (SONA) | Crate | Description | crates.io | npm | |-------|-------------|-----------|-----| | [ruvector-sona](./crates/sona) | Runtime-adaptive learning with LoRA, EWC++, and ReasoningBank | [![crates.io](https://img.shields.io/crates/v/ruvector-sona.svg)](https://crates.io/crates/ruvector-sona) | [![npm](https://img.shields.io/npm/v/@ruvector/sona.svg)](https://www.npmjs.com/package/@ruvector/sona) | **SONA** enables AI systems to continuously improve from user feedback without expensive retraining: - **Two-tier LoRA**: MicroLoRA (rank 1-2) for instant adaptation, BaseLoRA (rank 4-16) for long-term learning - **EWC++**: Elastic Weight Consolidation prevents catastrophic forgetting - **ReasoningBank**: K-means++ clustering stores and retrieves successful reasoning patterns - **Lock-free Trajectories**: ~50ns overhead per step with crossbeam ArrayQueue - **Sub-millisecond Learning**: <0.8ms per trajectory processing ```bash # Rust cargo add ruvector-sona # Node.js npm install @ruvector/sona ``` ```rust use ruvector_sona::{SonaEngine, SonaConfig}; let engine = SonaEngine::new(SonaConfig::default()); let traj_id = engine.start_trajectory(query_embedding); engine.record_step(traj_id, node_id, 0.85, 150); engine.end_trajectory(traj_id, 0.90); engine.learn_from_feedback(LearningSignal::positive(50.0, 0.95)); ``` ```javascript // Node.js const { SonaEngine } = require('@ruvector/sona'); const engine = new SonaEngine(256); // 256 hidden dimensions const trajId = engine.beginTrajectory([0.1, 0.2, ...]); engine.addTrajectoryStep(trajId, activations, attention, 0.9); engine.endTrajectory(trajId, 0.95); ``` ### PostgreSQL Extension | Crate | Description | crates.io | npm | |-------|-------------|-----------|-----| | [ruvector-postgres](./crates/ruvector-postgres) | pgvector-compatible PostgreSQL extension with SIMD optimization | [![crates.io](https://img.shields.io/crates/v/ruvector-postgres.svg)](https://crates.io/crates/ruvector-postgres) | [![npm](https://img.shields.io/npm/v/@ruvector/postgres-cli.svg)](https://www.npmjs.com/package/@ruvector/postgres-cli) | **v0.2.0** — Drop-in replacement for pgvector with **77+ SQL functions**, full **AVX-512/AVX2/NEON SIMD** acceleration (~2x faster than AVX2), HNSW and IVFFlat indexes, 39 attention mechanisms, GNN layers, hyperbolic embeddings (Poincaré + Lorentz), sparse vectors/BM25, **W3C SPARQL 1.1** with 50+ RDF functions, **local embeddings** (6 fastembed models), and self-learning capabilities. ```bash # Docker (recommended) docker run -d -e POSTGRES_PASSWORD=secret -p 5432:5432 ruvector/postgres:latest # From source cargo install cargo-pgrx --version "0.12.9" --locked cargo pgrx install --release # CLI tool for management npm install -g @ruvector/postgres-cli ruvector-pg install ruvector-pg vector create table --dim 1536 --index hnsw ``` See [ruvector-postgres README](./crates/ruvector-postgres/README.md) for full SQL API reference and advanced features. ### Tools & Utilities | Crate | Description | crates.io | |-------|-------------|-----------| | [ruvector-bench](./crates/ruvector-bench) | Benchmarking suite for vector operations | [![crates.io](https://img.shields.io/crates/v/ruvector-bench.svg)](https://crates.io/crates/ruvector-bench) | | [ruvector-metrics](./crates/ruvector-metrics) | Observability, metrics, and monitoring | [![crates.io](https://img.shields.io/crates/v/ruvector-metrics.svg)](https://crates.io/crates/ruvector-metrics) | | [ruvector-filter](./crates/ruvector-filter) | Metadata filtering and query predicates | [![crates.io](https://img.shields.io/crates/v/ruvector-filter.svg)](https://crates.io/crates/ruvector-filter) | | [ruvector-collections](./crates/ruvector-collections) | Multi-tenant collection management | [![crates.io](https://img.shields.io/crates/v/ruvector-collections.svg)](https://crates.io/crates/ruvector-collections) | | [ruvector-snapshot](./crates/ruvector-snapshot) | Point-in-time snapshots and backups | [![crates.io](https://img.shields.io/crates/v/ruvector-snapshot.svg)](https://crates.io/crates/ruvector-snapshot) | | [profiling](./crates/profiling) | Performance profiling and analysis tools | [![crates.io](https://img.shields.io/crates/v/ruvector-profiling.svg)](https://crates.io/crates/ruvector-profiling) | | [micro-hnsw-wasm](./crates/micro-hnsw-wasm) | Lightweight HNSW implementation for WASM | [![crates.io](https://img.shields.io/crates/v/micro-hnsw-wasm.svg)](https://crates.io/crates/micro-hnsw-wasm) | ### Embedded & IoT | Crate | Description | Target | |-------|-------------|--------| | [ruvector-esp32](./examples/edge) | ESP32/ESP-IDF vector search | ESP32, ESP32-S3 | | [rvlite](./crates/rvlite) | SQLite-style edge DB (no_std compatible) | ARM, RISC-V, WASM | | [micro-hnsw-wasm](./crates/micro-hnsw-wasm) | <50KB HNSW for constrained devices | WASM, embedded | ```rust // ESP32 example (no_std) #![no_std] use rvlite::RvLite; let db = RvLite::new(128); // 128-dim vectors db.insert(0, &embedding); let results = db.search(&query, 5); ```

🌐 WASM Packages (Browser & Edge)

Specialized WebAssembly modules for browser and edge deployment. These packages bring advanced AI and distributed computing primitives to JavaScript/TypeScript with near-native performance. ### Quick Install (All Browser WASM) ```bash # Core vector search npm install ruvector-wasm @ruvector/rvlite # AI & Neural npm install @ruvector/gnn-wasm @ruvector/attention-wasm @ruvector/sona-wasm # Graph & Algorithms npm install @ruvector/graph-wasm @ruvector/mincut-wasm @ruvector/hyperbolic-hnsw-wasm # Exotic AI npm install @ruvector/economy-wasm @ruvector/exotic-wasm @ruvector/nervous-system-wasm # LLM (browser inference) npm install @ruvector/ruvllm-wasm ``` | Category | Packages | Total Size | |----------|----------|------------| | **Core** | ruvector-wasm, rvlite | ~200KB | | **AI/Neural** | gnn, attention, sona | ~300KB | | **Graph** | graph, mincut, hyperbolic-hnsw | ~250KB | | **Exotic** | economy, exotic, nervous-system | ~350KB | | **LLM** | ruvllm-wasm | ~500KB | ### Installation ```bash # Install individual packages npm install @ruvector/learning-wasm npm install @ruvector/economy-wasm npm install @ruvector/exotic-wasm npm install @ruvector/nervous-system-wasm npm install @ruvector/attention-unified-wasm # Or build from source cd crates/ruvector-learning-wasm wasm-pack build --target web ``` ### ruvector-learning-wasm **MicroLoRA, BTSP, and HDC for self-learning AI systems.** Ultra-fast Low-Rank Adaptation (LoRA) optimized for WASM execution with <100us adaptation latency. Designed for real-time per-operator learning in query optimization and AI agent systems. | Feature | Performance | Description | |---------|-------------|-------------| | **MicroLoRA** | <100us latency | Rank-2 LoRA matrices for instant weight adaptation | | **Per-Operator Scoping** | Zero-allocation hot paths | Separate adapters for different operator types | | **Trajectory Tracking** | Lock-free buffers | Record learning trajectories for replay | **Architecture:** ``` Input Embedding (256-dim) | v +---------+ | A: d x 2 | Down projection +---------+ | v +---------+ | B: 2 x d | Up projection +---------+ | v Delta W = alpha * (A @ B) | v Output = Input + Delta W ``` **JavaScript/TypeScript Example:** ```typescript import init, { WasmMicroLoRA } from '@ruvector/learning-wasm'; await init(); // Create MicroLoRA engine (256-dim, alpha=0.1, lr=0.01) const lora = new WasmMicroLoRA(256, 0.1, 0.01); // Forward pass with adaptation const input = new Float32Array(256).fill(0.5); const output = lora.forward_array(input); // Adapt based on gradient signal const gradient = new Float32Array(256).fill(0.1); lora.adapt_array(gradient); // Adapt with reward signal for RL lora.adapt_with_reward(0.8); // 80% improvement console.log(`Adaptations: ${lora.adapt_count()}`); console.log(`Delta norm: ${lora.delta_norm()}`); ``` ### ruvector-economy-wasm **CRDT-based autonomous credit economy for distributed compute networks.** P2P-safe concurrent transactions using Conflict-free Replicated Data Types (CRDTs). Features a 10x-to-1x early adopter contribution curve and stake/slash mechanisms for participation incentives. | Feature | Description | |---------|-------------| | **CRDT Ledger** | G-Counter (earned) + PN-Counter (spent) for P2P consistency | | **Contribution Curve** | 10x early adopter multiplier decaying to 1x baseline | | **Stake/Slash** | Participation requirements with slashing for bad actors | | **Reputation Scoring** | Multi-factor: accuracy * uptime * stake_weight | | **Merkle Verification** | SHA-256 state root for quick ledger verification | **Architecture:** ``` +------------------------+ | CreditLedger | <-- CRDT-based P2P-safe ledger | +------------------+ | | | G-Counter: Earned| | <-- Monotonically increasing | | PN-Counter: Spent| | <-- Can handle disputes/refunds | | Stake: Locked | | <-- Participation requirement | | State Root | | <-- Merkle root for verification | +------------------+ | +------------------------+ | v +------------------------+ | ContributionCurve | <-- Exponential decay: 10x -> 1x +------------------------+ | v +------------------------+ | ReputationScore | <-- accuracy * uptime * stake_weight +------------------------+ ``` **JavaScript/TypeScript Example:** ```typescript import init, { CreditLedger, ReputationScore, contribution_multiplier } from '@ruvector/economy-wasm'; await init(); // Create a new ledger for a node const ledger = new CreditLedger("node-123"); // Earn credits (with early adopter multiplier) ledger.creditWithMultiplier(100, "task:abc"); console.log(`Balance: ${ledger.balance()}`); console.log(`Multiplier: ${ledger.currentMultiplier()}x`); // Stake for participation ledger.stake(50); console.log(`Staked: ${ledger.stakedAmount()}`); // Check multiplier for network compute hours const mult = contribution_multiplier(50000.0); // 50K hours console.log(`Network multiplier: ${mult}x`); // ~8.5x // Track reputation const rep = new ReputationScore(0.95, 0.98, 1000); console.log(`Composite score: ${rep.composite_score()}`); // P2P merge with another ledger (CRDT operation) const otherEarned = new Uint8Array([/* serialized earned counter */]); const otherSpent = new Uint8Array([/* serialized spent counter */]); const mergedCount = ledger.merge(otherEarned, otherSpent); ``` ### ruvector-exotic-wasm **Exotic AI mechanisms for emergent behavior in distributed systems.** Novel coordination primitives inspired by decentralized governance, developmental biology, and quantum physics. | Mechanism | Inspiration | Use Case | |-----------|-------------|----------| | **Neural Autonomous Organization (NAO)** | DAOs + oscillatory sync | Decentralized AI agent governance | | **Morphogenetic Network** | Developmental biology | Emergent network topology | | **Time Crystal Coordinator** | Quantum time crystals | Robust distributed coordination | **NAO Features:** - Stake-weighted quadratic voting - Oscillatory synchronization for coherence - Quorum-based consensus (configurable threshold) **Morphogenetic Network Features:** - Cellular differentiation through morphogen gradients - Emergent network topology via growth/pruning - Synaptic pruning for optimization **Time Crystal Features:** - Period-doubled oscillations for stable coordination - Floquet engineering for noise resilience - Phase-locked agent synchronization **JavaScript/TypeScript Example:** ```typescript import init, { WasmNAO, WasmMorphogeneticNetwork, WasmTimeCrystal, ExoticEcosystem } from '@ruvector/exotic-wasm'; await init(); // Neural Autonomous Organization const nao = new WasmNAO(0.7); // 70% quorum nao.addMember("agent_1", 100); // 100 stake nao.addMember("agent_2", 50); const propId = nao.propose("Upgrade memory backend"); nao.vote(propId, "agent_1", 0.9); // 90% approval weight nao.vote(propId, "agent_2", 0.6); if (nao.execute(propId)) { console.log("Proposal executed!"); } // Morphogenetic Network const net = new WasmMorphogeneticNetwork(100, 100); // 100x100 grid net.seedSignaling(50, 50); // Seed signaling cell at center for (let i = 0; i < 1000; i++) { net.grow(0.1); // 10% growth rate } net.differentiate(); net.prune(0.1); // 10% pruning threshold // Time Crystal Coordinator const crystal = new WasmTimeCrystal(10, 100); // 10 oscillators, 100ms period crystal.crystallize(); for (let i = 0; i < 200; i++) { const pattern = crystal.tick(); // Use pattern for coordination decisions } console.log(`Synchronization: ${crystal.orderParameter()}`); // Combined Ecosystem (all three working together) const eco = new ExoticEcosystem(5, 50, 8); // 5 agents, 50x50 grid, 8 oscillators eco.crystallize(); for (let i = 0; i < 100; i++) { eco.step(); } console.log(eco.summaryJson()); ``` ### ruvector-nervous-system-wasm **Bio-inspired neural system components for browser execution.** | Component | Performance | Description | |-----------|-------------|-------------| | **BTSP** | Immediate | Behavioral Timescale Synaptic Plasticity for one-shot learning | | **HDC** | <50ns bind, <100ns similarity | Hyperdimensional Computing with 10,000-bit vectors | | **WTA** | <1us | Winner-Take-All for instant decisions | | **K-WTA** | <10us | K-Winner-Take-All for sparse distributed coding | | **Global Workspace** | <10us | 4-7 item attention bottleneck (Miller's Law) | **Hyperdimensional Computing:** - 10,000-bit binary hypervectors - 10^40 representational capacity - XOR binding (associative, commutative, self-inverse) - Hamming distance similarity with SIMD optimization **Biological References:** - BTSP: Bittner et al. 2017 - Hippocampal place fields - HDC: Kanerva 1988, Plate 2003 - Hyperdimensional computing - WTA: Cortical microcircuits - Lateral inhibition - Global Workspace: Baars 1988, Dehaene 2014 - Consciousness **JavaScript/TypeScript Example:** ```typescript import init, { BTSPLayer, Hypervector, HdcMemory, WTALayer, KWTALayer, GlobalWorkspace, WorkspaceItem, } from '@ruvector/nervous-system-wasm'; await init(); // One-shot learning with BTSP const btsp = new BTSPLayer(100, 2000.0); // 100 dim, 2000ms tau const pattern = new Float32Array(100).fill(0.1); btsp.one_shot_associate(pattern, 1.0); // Immediate association const output = btsp.forward(pattern); // Hyperdimensional Computing const apple = Hypervector.random(); const orange = Hypervector.random(); const fruit = apple.bind(orange); // XOR binding const similarity = apple.similarity(orange); // ~0.0 (orthogonal) console.log(`Similarity: ${similarity}`); // Random vectors are orthogonal // HDC Memory const memory = new HdcMemory(); memory.store("apple", apple); memory.store("orange", orange); const results = memory.retrieve(apple, 0.9); // threshold 0.9 const topK = memory.top_k(fruit, 3); // top-3 similar // Instant decisions with WTA const wta = new WTALayer(1000, 0.5, 0.8); // 1000 neurons, threshold, inhibition const activations = new Float32Array(1000); // ... fill activations ... const winner = wta.compete(activations); // Sparse coding with K-WTA const kwta = new KWTALayer(1000, 50); // 1000 neurons, k=50 winners const winners = kwta.select(activations); // Attention bottleneck with Global Workspace const workspace = new GlobalWorkspace(7); // Miller's Law: 7 +/- 2 const item = new WorkspaceItem( new Float32Array([1, 2, 3]), // content 0.9, // salience 1, // source Date.now() // timestamp ); workspace.broadcast(item); ``` ### ruvector-attention-unified-wasm **Unified API for 18+ attention mechanisms across Neural, DAG, Graph, and SSM domains.** A single WASM interface that routes to the appropriate attention implementation based on your data structure and requirements. | Category | Mechanisms | Best For | |----------|------------|----------| | **Neural** | Scaled Dot-Product, Multi-Head, Hyperbolic, Linear, Flash, Local-Global, MoE | Transformers, sequences | | **DAG** | Topological, Causal Cone, Critical Path, MinCut-Gated, Hierarchical Lorentz, Parallel Branch, Temporal BTSP | Query DAGs, workflows | | **Graph** | GAT, GCN, GraphSAGE | GNNs, knowledge graphs | | **SSM** | Mamba | Long sequences, streaming | **Mechanism Selection:** ``` +------------------+ +-------------------+ | Your Data | --> | UnifiedAttention | --> Optimal Mechanism +------------------+ +-------------------+ | +----------------------+----------------------+ | | | +----v----+ +-----v-----+ +-----v----+ | Neural | | DAG | | Graph | +---------+ +-----------+ +----------+ | dot_prod| | topological| | gat | | multi_hd| | causal_cone| | gcn | | flash | | mincut_gtd | | graphsage| +---------+ +-----------+ +----------+ ``` **JavaScript/TypeScript Example:** ```typescript import init, { UnifiedAttention, availableMechanisms, getStats, softmax, temperatureSoftmax, cosineSimilarity, // Neural attention ScaledDotProductAttention, MultiHeadAttention, // DAG attention TopologicalAttention, MinCutGatedAttention, // Graph attention GraphAttention, // SSM MambaSSM, } from '@ruvector/attention-unified-wasm'; await init(); // List all available mechanisms console.log(availableMechanisms()); // { neural: [...], dag: [...], graph: [...], ssm: [...] } console.log(getStats()); // { total_mechanisms: 18, neural_count: 7, dag_count: 7, ... } // Unified selector - routes to appropriate implementation const attention = new UnifiedAttention("multi_head"); console.log(`Category: ${attention.category}`); // "neural" console.log(`Supports sequences: ${attention.supportsSequences()}`); // true console.log(`Supports graphs: ${attention.supportsGraphs()}`); // false // For DAG structures const dagAttention = new UnifiedAttention("topological"); console.log(`Category: ${dagAttention.category}`); // "dag" console.log(`Supports graphs: ${dagAttention.supportsGraphs()}`); // true // Hyperbolic attention for hierarchical data const hypAttention = new UnifiedAttention("hierarchical_lorentz"); console.log(`Supports hyperbolic: ${hypAttention.supportsHyperbolic()}`); // true // Utility functions const logits = [1.0, 2.0, 3.0, 4.0]; const probs = softmax(logits); console.log(`Probabilities sum to: ${probs.reduce((a, b) => a + b)}`); // 1.0 // Temperature-scaled softmax (lower = more peaked) const sharperProbs = temperatureSoftmax(logits, 0.5); // Cosine similarity const vecA = [1.0, 0.0, 0.0]; const vecB = [1.0, 0.0, 0.0]; console.log(`Similarity: ${cosineSimilarity(vecA, vecB)}`); // 1.0 ``` ### WASM Package Summary | Package | Size Target | Key Features | |---------|-------------|--------------| | `@ruvector/learning-wasm` | <50KB | MicroLoRA (<100us), trajectory tracking | | `@ruvector/economy-wasm` | <100KB | CRDT ledger, 10x->1x curve, stake/slash | | `@ruvector/exotic-wasm` | <150KB | NAO, Morphogenetic, Time Crystal | | `@ruvector/nervous-system-wasm` | <100KB | BTSP, HDC (10K-bit), WTA, Global Workspace | | `@ruvector/attention-unified-wasm` | <200KB | 18+ attention mechanisms, unified API | **Common Patterns:** ```typescript // All packages follow the same initialization pattern import init, { /* exports */ } from '@ruvector/-wasm'; await init(); // Version check import { version } from '@ruvector/-wasm'; console.log(`Version: ${version()}`); // Feature discovery import { available_mechanisms } from '@ruvector/-wasm'; console.log(available_mechanisms()); ```

🧠 Self-Learning Intelligence Hooks

**Make your AI assistant smarter over time.** When you use Claude Code (or any AI coding assistant), it starts fresh every session. It doesn't remember which approaches worked, which files you typically edit together, or what errors you've seen before. **RuVector Hooks fixes this.** It's a lightweight intelligence layer that: 1. **Remembers what works** — Tracks which agent types succeed for different tasks 2. **Learns from mistakes** — Records error patterns and suggests fixes you've used before 3. **Predicts your workflow** — Knows that after editing `api.rs`, you usually edit `api_test.rs` 4. **Coordinates teams** — Manages multi-agent swarms for complex tasks Think of it as giving your AI assistant a memory and intuition about your codebase. #### How It Works ``` ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Claude Code │────▶│ RuVector Hooks │────▶│ Intelligence │ │ (PreToolUse) │ │ (pre-edit) │ │ Layer │ └─────────────────┘ └──────────────────┘ └─────────────────┘ │ ┌───────────────────────────────────────────────┘ ▼ ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Q-Learning │ │ Vector Memory │ │ Swarm Graph │ │ α=0.1 γ=0.95 │ │ 64-dim embed │ │ Coordination │ └─────────────────┘ └──────────────────┘ └─────────────────┘ ``` The hooks integrate with Claude Code's event system: - **PreToolUse** → Provides guidance before edits (agent routing, related files) - **PostToolUse** → Records outcomes for learning (success/failure, patterns) - **SessionStart/Stop** → Manages session state and metrics export #### Technical Specifications | Component | Implementation | Details | |-----------|----------------|---------| | **Q-Learning** | Temporal Difference | α=0.1, γ=0.95, ε=0.1 (ε-greedy exploration) | | **Embeddings** | Hash-based vectors | 64 dimensions, normalized, cosine similarity | | **LRU Cache** | `lru` crate | 1000 entries, ~10x faster Q-value lookups | | **Compression** | `flate2` gzip | 70-83% storage reduction, fast compression | | **Storage** | JSON / PostgreSQL | Auto-fallback, 5000 memory entry limit | | **Cross-platform** | Rust + TypeScript | Windows (USERPROFILE), Unix (HOME) | #### Performance | Metric | Value | |--------|-------| | Q-value lookup (cached) | <1µs | | Q-value lookup (uncached) | ~50µs | | Memory search (1000 entries) | <5ms | | Storage compression ratio | 70-83% | | Session start overhead | <10ms | | Crate/Package | Description | Status | |---------------|-------------|--------| | [ruvector-cli hooks](./crates/ruvector-cli) | Rust CLI with 34 hooks commands | [![crates.io](https://img.shields.io/crates/v/ruvector-cli.svg)](https://crates.io/crates/ruvector-cli) | | [@ruvector/cli hooks](./npm/packages/cli) | npm CLI with 29 hooks commands | [![npm](https://img.shields.io/npm/v/@ruvector/cli.svg)](https://www.npmjs.com/package/@ruvector/cli) | #### Quick Start ```bash # Rust CLI cargo install ruvector-cli ruvector hooks init ruvector hooks install # npm CLI npx @ruvector/cli hooks init npx @ruvector/cli hooks install ``` #### Core Capabilities | Feature | Description | Technical Details | |---------|-------------|-------------------| | **Q-Learning Routing** | Routes tasks to best agent with learned confidence scores | TD learning with α=0.1, γ=0.95, ε-greedy exploration | | **Semantic Memory** | Vector-based memory with embeddings for context retrieval | 64-dim hash embeddings, cosine similarity, top-k search | | **Error Learning** | Records error patterns and suggests fixes | Pattern matching for E0308, E0433, TS2322, etc. | | **File Sequences** | Predicts next files to edit based on historical patterns | Markov chain transitions, frequency-weighted suggestions | | **Swarm Coordination** | Registers agents, tracks coordination edges, optimizes | Graph-based topology, weighted edges, task assignment | | **LRU Cache** | 1000-entry cache for faster Q-value lookups | ~10x speedup, automatic eviction, RefCell for interior mutability | | **Gzip Compression** | Storage savings with automatic compression | flate2 fast mode, 70-83% reduction, transparent load/save | | **Batch Saves** | Dirty flag tracking to reduce disk I/O | Only writes when data changes, force_save() override | | **Shell Completions** | Tab completion for all commands | bash, zsh, fish, PowerShell support | #### Supported Error Codes The intelligence layer has built-in knowledge for common error patterns: | Language | Error Codes | Auto-Suggested Fixes | |----------|-------------|---------------------| | **Rust** | E0308, E0433, E0425, E0277, E0382 | Type mismatches, missing imports, borrow checker | | **TypeScript** | TS2322, TS2339, TS2345, TS7006 | Type assignments, property access, argument types | | **Python** | ImportError, AttributeError, TypeError | Module imports, attribute access, type errors | | **Go** | undefined, cannot use, not enough arguments | Variable scope, type conversion, function calls | #### Commands Reference ```bash # Setup ruvector hooks init [--force] [--postgres] # Initialize hooks (--postgres for DB schema) ruvector hooks install # Install into Claude settings # Core ruvector hooks stats # Show intelligence statistics ruvector hooks session-start [--resume] # Start/resume a session ruvector hooks session-end # End session with metrics # Memory ruvector hooks remember -t edit "content" # Store in semantic memory ruvector hooks recall "query" -k 5 # Search memory semantically # Learning ruvector hooks learn --reward 0.8 # Record trajectory ruvector hooks suggest --actions "a,b,c" # Get action suggestion ruvector hooks route "implement caching" --file src/cache.rs # Route to agent # Claude Code Hooks ruvector hooks pre-edit # Pre-edit intelligence hook ruvector hooks post-edit --success # Post-edit learning hook ruvector hooks pre-command # Pre-command hook ruvector hooks post-command --success # Post-command hook ruvector hooks suggest-context # UserPromptSubmit context injection ruvector hooks track-notification # Track notification patterns ruvector hooks pre-compact [--auto] # Pre-compact hook (auto/manual) # Claude Code v2.0.55+ Features ruvector hooks lsp-diagnostic --file --severity error # LSP diagnostics ruvector hooks suggest-ultrathink "complex task" # Recommend extended reasoning ruvector hooks async-agent --action spawn --agent-id # Async sub-agents # Intelligence ruvector hooks record-error # Record error pattern ruvector hooks suggest-fix E0308 # Get fix for error code ruvector hooks suggest-next -n 3 # Predict next files ruvector hooks should-test # Check if tests needed # Swarm ruvector hooks swarm-register # Register agent ruvector hooks swarm-coordinate # Record coordination ruvector hooks swarm-optimize "task1,task2" # Optimize distribution ruvector hooks swarm-recommend "rust" # Recommend agent for task ruvector hooks swarm-heal # Handle agent failure ruvector hooks swarm-stats # Show swarm statistics # Optimization (Rust only) ruvector hooks compress # Compress storage (70-83% savings) ruvector hooks cache-stats # Show LRU cache statistics ruvector hooks completions bash # Generate shell completions ``` #### Tutorial: Claude Code Integration **1. Initialize and install hooks:** ```bash ruvector hooks init ruvector hooks install --settings-dir .claude ``` This creates `.claude/settings.json` with hook configurations: ```json { "hooks": { "PreToolUse": [ { "matcher": "Edit|Write|MultiEdit", "hooks": ["ruvector hooks pre-edit \"$TOOL_INPUT_FILE_PATH\""] }, { "matcher": "Bash", "hooks": ["ruvector hooks pre-command \"$TOOL_INPUT_COMMAND\""] } ], "PostToolUse": [ { "matcher": "Edit|Write|MultiEdit", "hooks": ["ruvector hooks post-edit ... --success"] }, { "matcher": "Bash", "hooks": ["ruvector hooks post-command ... --success"] } ], "SessionStart": ["ruvector hooks session-start"], "Stop": ["ruvector hooks session-end --export-metrics"], "PreCompact": ["ruvector hooks pre-compact"] } } ``` **All 7 Claude Code hooks covered:** | Hook | When It Fires | What RuVector Does | |------|---------------|-------------------| | `PreToolUse` | Before file edit, command, or Task | Suggests agent, shows related files, validates agent assignments | | `PostToolUse` | After file edit or command | Records outcome, updates Q-values, injects context | | `SessionStart` | When session begins/resumes | Loads intelligence, shows stats (startup vs resume) | | `Stop` | When session ends | Saves state, exports metrics | | `PreCompact` | Before context compaction | Preserves critical memories (auto vs manual) | | `UserPromptSubmit` | Before processing user prompt | Injects learned patterns as context | | `Notification` | On system notifications | Tracks notification patterns | **Advanced Features:** - **Stdin JSON Parsing**: Hooks receive full JSON via stdin (session_id, tool_input, tool_response) - **Context Injection**: PostToolUse returns `additionalContext` to inject into Claude's context - **Timeout Optimization**: All hooks have optimized timeouts (1-5 seconds vs 60s default) **2. Use routing for intelligent agent selection:** ```bash # Route a task to the best agent $ ruvector hooks route "implement vector search" --file src/lib.rs { "recommended": "rust-developer", "confidence": 0.85, "reasoning": "learned from 47 similar edits" } ``` **3. Learn from outcomes:** ```bash # Record successful outcome ruvector hooks learn "edit-rs-lib" "rust-developer" --reward 1.0 # Record failed outcome ruvector hooks learn "edit-rs-lib" "typescript-dev" --reward -0.5 ``` **4. Get error fix suggestions:** ```bash $ ruvector hooks suggest-fix E0308 { "code": "E0308", "type": "type_mismatch", "fixes": [ "Check return type matches function signature", "Use .into() or .as_ref() for type conversion", "Verify generic type parameters" ] } ``` #### Tutorial: Swarm Coordination **1. Register agents:** ```bash ruvector hooks swarm-register agent-1 rust-developer --capabilities "rust,async,testing" ruvector hooks swarm-register agent-2 typescript-dev --capabilities "ts,react,node" ruvector hooks swarm-register agent-3 reviewer --capabilities "review,security,performance" ``` **2. Record coordination patterns:** ```bash # Agent-1 hands off to Agent-3 for review ruvector hooks swarm-coordinate agent-1 agent-3 --weight 0.9 ``` **3. Optimize task distribution:** ```bash $ ruvector hooks swarm-optimize "implement-api,write-tests,code-review" { "assignments": { "implement-api": "agent-1", "write-tests": "agent-1", "code-review": "agent-3" } } ``` **4. Handle failures with self-healing:** ```bash # Mark agent as failed and redistribute ruvector hooks swarm-heal agent-2 ``` #### PostgreSQL Storage (Optional) For production deployments, use PostgreSQL instead of JSON files: ```bash # Set connection URL export RUVECTOR_POSTGRES_URL="postgres://user:pass@localhost/ruvector" # Initialize PostgreSQL schema (automatic) ruvector hooks init --postgres # Or apply schema manually psql $RUVECTOR_POSTGRES_URL -f crates/ruvector-cli/sql/hooks_schema.sql # Build CLI with postgres feature cargo build -p ruvector-cli --features postgres ``` The PostgreSQL backend provides: - Vector embeddings with native `ruvector` type - Q-learning functions (`ruvector_hooks_update_q`, `ruvector_hooks_best_action`) - Swarm coordination tables with foreign key relationships - Automatic memory cleanup (keeps last 5000 entries)

🔬 Scientific OCR (SciPix)

| Crate | Description | crates.io | |-------|-------------|-----------| | [ruvector-scipix](./examples/scipix) | OCR engine for scientific documents, math equations → LaTeX/MathML | [![crates.io](https://img.shields.io/crates/v/ruvector-scipix.svg)](https://crates.io/crates/ruvector-scipix) | **SciPix** extracts text and mathematical equations from images, converting them to LaTeX, MathML, or plain text. Features GPU-accelerated ONNX inference, SIMD-optimized preprocessing, REST API server, CLI tool, and MCP integration for AI assistants. ```bash # Install cargo add ruvector-scipix # CLI usage scipix-cli ocr --input equation.png --format latex scipix-cli serve --port 3000 # MCP server for Claude/AI assistants scipix-cli mcp claude mcp add scipix -- scipix-cli mcp ```

🔗 ONNX Embeddings

| Example | Description | Path | |---------|-------------|------| | [ruvector-onnx-embeddings](./examples/onnx-embeddings) | Production-ready ONNX embedding generation in pure Rust | `examples/onnx-embeddings` | **ONNX Embeddings** provides native embedding generation using ONNX Runtime — no Python required. Supports 8+ pretrained models (all-MiniLM, BGE, E5, GTE), multiple pooling strategies, GPU acceleration (CUDA, TensorRT, CoreML, WebGPU), and direct RuVector index integration for RAG pipelines. ```rust use ruvector_onnx_embeddings::{Embedder, PretrainedModel}; #[tokio::main] async fn main() -> anyhow::Result<()> { // Create embedder with default model (all-MiniLM-L6-v2) let mut embedder = Embedder::default_model().await?; // Generate embedding (384 dimensions) let embedding = embedder.embed_one("Hello, world!")?; // Compute semantic similarity let sim = embedder.similarity( "I love programming in Rust", "Rust is my favorite language" )?; println!("Similarity: {:.4}", sim); // ~0.85 Ok(()) } ``` **Supported Models:** | Model | Dimension | Speed | Best For | |-------|-----------|-------|----------| | `AllMiniLmL6V2` | 384 | Fast | General purpose (default) | | `BgeSmallEnV15` | 384 | Fast | Search & retrieval | | `AllMpnetBaseV2` | 768 | Accurate | Production RAG |

🔧 Bindings & Tools

| Crate | Description | crates.io | |-------|-------------|-----------| | [ruvector-node](./crates/ruvector-node) | Main Node.js bindings (napi-rs) | [![crates.io](https://img.shields.io/crates/v/ruvector-node.svg)](https://crates.io/crates/ruvector-node) | | [ruvector-wasm](./crates/ruvector-wasm) | Main WASM bindings for browsers | [![crates.io](https://img.shields.io/crates/v/ruvector-wasm.svg)](https://crates.io/crates/ruvector-wasm) | | [ruvllm-wasm](./crates/ruvllm-wasm) | LLM integration WASM bindings | [![crates.io](https://img.shields.io/crates/v/ruvllm-wasm.svg)](https://crates.io/crates/ruvllm-wasm) | | [ruvector-cli](./crates/ruvector-cli) | Command-line interface | [![crates.io](https://img.shields.io/crates/v/ruvector-cli.svg)](https://crates.io/crates/ruvector-cli) | | [ruvector-server](./crates/ruvector-server) | HTTP/gRPC server | [![crates.io](https://img.shields.io/crates/v/ruvector-server.svg)](https://crates.io/crates/ruvector-server) |

📚 Production Examples

28 production-ready examples demonstrating RuVector integration patterns. | Example | Description | Type | |---------|-------------|------| | [agentic-jujutsu](./examples/agentic-jujutsu) | Quantum-resistant version control for AI agents (23x faster than Git) | Rust | | [mincut](./examples/mincut) | 6 self-organizing network demos: strange loops, time crystals, causal discovery | Rust | | [subpolynomial-time](./examples/subpolynomial-time) | n^0.12 subpolynomial algorithm demos | Rust | | [exo-ai-2025](./examples/exo-ai-2025) | Cognitive substrate with 9 neural-symbolic crates + 11 research experiments | Rust/TS | | [neural-trader](./examples/neural-trader) | AI trading with DRL + sentiment analysis + SONA learning | Rust | | [ultra-low-latency-sim](./examples/ultra-low-latency-sim) | 13+ quadrillion meta-simulations/sec with SIMD | Rust | | [meta-cognition-spiking-neural-network](./examples/meta-cognition-spiking-neural-network) | Spiking neural network with meta-cognitive learning (10-50x speedup) | npm | | [spiking-network](./examples/spiking-network) | Biologically-inspired spiking neural networks | Rust | | [ruvLLM](./examples/ruvLLM) | LLM integration patterns for RAG and AI agents | Rust | | [onnx-embeddings](./examples/onnx-embeddings) | Production ONNX embedding generation without Python | Rust | | [onnx-embeddings-wasm](./examples/onnx-embeddings-wasm) | WASM ONNX embeddings for browsers | WASM | | [refrag-pipeline](./examples/refrag-pipeline) | RAG pipeline with vector search and document processing | Rust | | [scipix](./examples/scipix) | Scientific OCR: equations → LaTeX/MathML with ONNX inference | Rust | | [graph](./examples/graph) | Graph database examples with Cypher queries | Rust | | [edge](./examples/edge) | 364KB WASM edge deployment | Rust | | [edge-full](./examples/edge-full) | Full-featured edge vector DB | Rust | | [edge-net](./examples/edge-net) | Networked edge deployment with zero-cost swarms | Rust | | [vibecast-7sense](./examples/vibecast-7sense) | 7-sense perception AI application | TypeScript | | [apify](./examples/apify) | 13 Apify actors: trading, memory engine, synth data, market research | npm | | [google-cloud](./examples/google-cloud) | GCP templates for Cloud Run, GKE, Vertex AI | Terraform | | [wasm-react](./examples/wasm-react) | React integration with WASM vector operations | WASM | | [wasm-vanilla](./examples/wasm-vanilla) | Vanilla JS WASM example for browser vector search | WASM | | [wasm](./examples/wasm) | Core WASM examples and bindings | WASM | | [nodejs](./examples/nodejs) | Node.js integration examples | Node.js | | [rust](./examples/rust) | Core Rust usage examples | Rust |

🎓 Tutorials

### Tutorial 1: Vector Search in 60 Seconds ```javascript import { VectorDB } from 'ruvector'; // Create DB with 384-dimensional vectors const db = new VectorDB(384); // Add vectors db.insert('doc1', [0.1, 0.2, ...]); // 384 floats db.insert('doc2', [0.3, 0.1, ...]); // Search (returns top 5 nearest neighbors) const results = db.search(queryVector, 5); // -> [{ id: 'doc1', score: 0.95 }, { id: 'doc2', score: 0.87 }] ``` ### Tutorial 2: Graph Queries with Cypher ```javascript import { GraphDB } from 'ruvector'; const graph = new GraphDB(); // Create nodes and relationships graph.query(` CREATE (a:Person {name: 'Alice', embedding: $emb1}) CREATE (b:Person {name: 'Bob', embedding: $emb2}) CREATE (a)-[:KNOWS {since: 2020}]->(b) `, { emb1: aliceVector, emb2: bobVector }); // Hybrid query: graph traversal + vector similarity const results = graph.query(` MATCH (p:Person)-[:KNOWS*1..3]->(friend) WHERE vector.similarity(friend.embedding, $query) > 0.8 RETURN friend.name, vector.similarity(friend.embedding, $query) as score ORDER BY score DESC `, { query: queryVector }); ``` ### Tutorial 3: Self-Learning with SONA ```rust use ruvector_sona::{SonaEngine, SonaConfig}; // Initialize SONA with LoRA adapters let sona = SonaEngine::with_config(SonaConfig { hidden_dim: 256, lora_rank: 8, ewc_lambda: 0.4, // Elastic Weight Consolidation ..Default::default() }); // Record successful action let mut trajectory = sona.begin_trajectory(query_embedding); trajectory.add_step(result_embedding, vec![], 1.0); // reward=1.0 sona.end_trajectory(trajectory, true); // success=true // SONA learns and improves future predictions sona.force_learn(); // Later: get improved predictions let prediction = sona.predict(&new_query_embedding); ``` ### Tutorial 4: Dynamic Min-Cut (n^0.12 Updates) ```rust use ruvector_mincut::{DynamicMinCut, Graph}; // Build graph let mut graph = Graph::new(100); // 100 nodes graph.add_edge(0, 1, 10.0); graph.add_edge(1, 2, 5.0); graph.add_edge(0, 2, 15.0); // Compute initial min-cut let mut mincut = DynamicMinCut::new(&graph); let (value, cut_edges) = mincut.compute(); println!("Min-cut value: {}", value); // -> 15.0 // Dynamic update - subpolynomial time O(n^0.12)! graph.update_edge(1, 2, 20.0); let (new_value, _) = mincut.recompute(); // Much faster than recomputing from scratch ``` ### Tutorial 5: 39 Attention Mechanisms ```rust use ruvector_attention::{ Attention, FlashAttention, LinearAttention, HyperbolicAttention, GraphAttention, MinCutGatedAttention }; // FlashAttention - O(n) memory, fastest for long sequences let flash = FlashAttention::new(512, 8); // dim=512, heads=8 let output = flash.forward(&query, &key, &value); // LinearAttention - O(n) time complexity let linear = LinearAttention::new(512, 8); // HyperbolicAttention - for hierarchical data (Poincaré ball) let hyper = HyperbolicAttention::new(512, 8, Curvature(-1.0)); // GraphAttention - respects graph structure let gat = GraphAttention::new(512, 8, &adjacency_matrix); // MinCutGatedAttention - 50% compute reduction via sparsity let mincut_gated = MinCutGatedAttention::new(512, 8, sparsity: 0.5); let sparse_output = mincut_gated.forward(&query, &key, &value); ``` ### Tutorial 6: Spiking Neural Networks ```javascript import { SpikingNetwork, HDCEncoder } from '@ruvector/spiking-neural'; // High-Dimensional Computing encoder (10K-bit vectors) const encoder = new HDCEncoder(10000); const encoded = encoder.encode("hello world"); // Spiking network with BTSP learning const network = new SpikingNetwork({ layers: [784, 256, 10], learning: 'btsp', // Behavioral Time-Scale Plasticity threshold: 1.0 }); // Train with spike timing network.train(spikes, labels, { epochs: 10 }); // Inference const output = network.forward(inputSpikes); ``` ### Tutorial 7: Claude Code Hooks Integration ```bash # 1. Initialize hooks npx @ruvector/cli hooks init # 2. Install into Claude settings npx @ruvector/cli hooks install # 3. Hooks now capture: # - File edits (pre/post) # - Commands (pre/post) # - Sessions (start/end) # - Errors and fixes # 4. Query learned patterns npx @ruvector/cli hooks recall "authentication error" # -> Returns similar past solutions # 5. Get AI routing suggestions npx @ruvector/cli hooks route "implement caching" # -> Suggests: rust-developer (confidence: 0.89) ``` ### Tutorial 8: Edge Deployment with rvLite ```javascript import { RvLite } from '@ruvector/rvlite'; // Create persistent edge database (IndexedDB in browser) const db = await RvLite.create({ path: 'my-vectors.db', dimensions: 384 }); // Works offline - all computation local await db.insert('doc1', embedding1, { title: 'Hello' }); await db.insert('doc2', embedding2, { title: 'World' }); // Semantic search with metadata filtering const results = await db.search(queryEmbedding, { limit: 10, filter: { title: { $contains: 'Hello' } } }); // Sync when online await db.sync('https://api.example.com/vectors'); ```

📦 npm Packages (40+ Packages)

#### ✅ Published | Package | Description | Version | Downloads | |---------|-------------|---------|-----------| | [ruvector](https://www.npmjs.com/package/ruvector) | All-in-one CLI & package | [![npm](https://img.shields.io/npm/v/ruvector.svg)](https://www.npmjs.com/package/ruvector) | [![downloads](https://img.shields.io/npm/dt/ruvector.svg)](https://www.npmjs.com/package/ruvector) | | [@ruvector/core](https://www.npmjs.com/package/@ruvector/core) | Core vector database | [![npm](https://img.shields.io/npm/v/@ruvector/core.svg)](https://www.npmjs.com/package/@ruvector/core) | [![downloads](https://img.shields.io/npm/dt/@ruvector/core.svg)](https://www.npmjs.com/package/@ruvector/core) | | [@ruvector/gnn](https://www.npmjs.com/package/@ruvector/gnn) | Graph Neural Network layers | [![npm](https://img.shields.io/npm/v/@ruvector/gnn.svg)](https://www.npmjs.com/package/@ruvector/gnn) | [![downloads](https://img.shields.io/npm/dt/@ruvector/gnn.svg)](https://www.npmjs.com/package/@ruvector/gnn) | | [@ruvector/graph-node](https://www.npmjs.com/package/@ruvector/graph-node) | Hypergraph with Cypher | [![npm](https://img.shields.io/npm/v/@ruvector/graph-node.svg)](https://www.npmjs.com/package/@ruvector/graph-node) | [![downloads](https://img.shields.io/npm/dt/@ruvector/graph-node.svg)](https://www.npmjs.com/package/@ruvector/graph-node) | | [@ruvector/tiny-dancer](https://www.npmjs.com/package/@ruvector/tiny-dancer) | FastGRNN AI routing | [![npm](https://img.shields.io/npm/v/@ruvector/tiny-dancer.svg)](https://www.npmjs.com/package/@ruvector/tiny-dancer) | [![downloads](https://img.shields.io/npm/dt/@ruvector/tiny-dancer.svg)](https://www.npmjs.com/package/@ruvector/tiny-dancer) | | [@ruvector/router](https://www.npmjs.com/package/@ruvector/router) | Semantic router + HNSW | [![npm](https://img.shields.io/npm/v/@ruvector/router.svg)](https://www.npmjs.com/package/@ruvector/router) | [![downloads](https://img.shields.io/npm/dt/@ruvector/router.svg)](https://www.npmjs.com/package/@ruvector/router) | | [@ruvector/attention](https://www.npmjs.com/package/@ruvector/attention) | 39 attention mechanisms | [![npm](https://img.shields.io/npm/v/@ruvector/attention.svg)](https://www.npmjs.com/package/@ruvector/attention) | [![downloads](https://img.shields.io/npm/dt/@ruvector/attention.svg)](https://www.npmjs.com/package/@ruvector/attention) | | [@ruvector/sona](https://www.npmjs.com/package/@ruvector/sona) | Self-Optimizing Neural Architecture | [![npm](https://img.shields.io/npm/v/@ruvector/sona.svg)](https://www.npmjs.com/package/@ruvector/sona) | [![downloads](https://img.shields.io/npm/dt/@ruvector/sona.svg)](https://www.npmjs.com/package/@ruvector/sona) | | [@ruvector/ruvllm](https://www.npmjs.com/package/@ruvector/ruvllm) | LLM orchestration + SONA | [![npm](https://img.shields.io/npm/v/@ruvector/ruvllm.svg)](https://www.npmjs.com/package/@ruvector/ruvllm) | [![downloads](https://img.shields.io/npm/dt/@ruvector/ruvllm.svg)](https://www.npmjs.com/package/@ruvector/ruvllm) | | [@ruvector/cli](https://www.npmjs.com/package/@ruvector/cli) | CLI + self-learning hooks | [![npm](https://img.shields.io/npm/v/@ruvector/cli.svg)](https://www.npmjs.com/package/@ruvector/cli) | [![downloads](https://img.shields.io/npm/dt/@ruvector/cli.svg)](https://www.npmjs.com/package/@ruvector/cli) | | [@ruvector/rvlite](https://www.npmjs.com/package/@ruvector/rvlite) | SQLite-style edge DB | [![npm](https://img.shields.io/npm/v/@ruvector/rvlite.svg)](https://www.npmjs.com/package/@ruvector/rvlite) | [![downloads](https://img.shields.io/npm/dt/@ruvector/rvlite.svg)](https://www.npmjs.com/package/@ruvector/rvlite) | | [@ruvector/cluster](https://www.npmjs.com/package/@ruvector/cluster) | Distributed clustering | [![npm](https://img.shields.io/npm/v/@ruvector/cluster.svg)](https://www.npmjs.com/package/@ruvector/cluster) | [![downloads](https://img.shields.io/npm/dt/@ruvector/cluster.svg)](https://www.npmjs.com/package/@ruvector/cluster) | | [@ruvector/server](https://www.npmjs.com/package/@ruvector/server) | HTTP/gRPC server | [![npm](https://img.shields.io/npm/v/@ruvector/server.svg)](https://www.npmjs.com/package/@ruvector/server) | [![downloads](https://img.shields.io/npm/dt/@ruvector/server.svg)](https://www.npmjs.com/package/@ruvector/server) | | [@ruvector/rudag](https://www.npmjs.com/package/@ruvector/rudag) | Self-learning DAG | [![npm](https://img.shields.io/npm/v/@ruvector/rudag.svg)](https://www.npmjs.com/package/@ruvector/rudag) | [![downloads](https://img.shields.io/npm/dt/@ruvector/rudag.svg)](https://www.npmjs.com/package/@ruvector/rudag) | | [@ruvector/burst-scaling](https://www.npmjs.com/package/@ruvector/burst-scaling) | 10-50x burst scaling | [![npm](https://img.shields.io/npm/v/@ruvector/burst-scaling.svg)](https://www.npmjs.com/package/@ruvector/burst-scaling) | [![downloads](https://img.shields.io/npm/dt/@ruvector/burst-scaling.svg)](https://www.npmjs.com/package/@ruvector/burst-scaling) | | [@ruvector/spiking-neural](https://www.npmjs.com/package/@ruvector/spiking-neural) | Spiking neural networks | [![npm](https://img.shields.io/npm/v/@ruvector/spiking-neural.svg)](https://www.npmjs.com/package/@ruvector/spiking-neural) | [![downloads](https://img.shields.io/npm/dt/@ruvector/spiking-neural.svg)](https://www.npmjs.com/package/@ruvector/spiking-neural) |

WASM & Utility Packages

| Package | Description | Version | Downloads | |---------|-------------|---------|-----------| | [@ruvector/wasm](https://www.npmjs.com/package/@ruvector/wasm) | WASM core vector DB | [![npm](https://img.shields.io/npm/v/@ruvector/wasm.svg)](https://www.npmjs.com/package/@ruvector/wasm) | [![downloads](https://img.shields.io/npm/dt/@ruvector/wasm.svg)](https://www.npmjs.com/package/@ruvector/wasm) | | [@ruvector/gnn-wasm](https://www.npmjs.com/package/@ruvector/gnn-wasm) | WASM GNN layers | [![npm](https://img.shields.io/npm/v/@ruvector/gnn-wasm.svg)](https://www.npmjs.com/package/@ruvector/gnn-wasm) | [![downloads](https://img.shields.io/npm/dt/@ruvector/gnn-wasm.svg)](https://www.npmjs.com/package/@ruvector/gnn-wasm) | | [@ruvector/graph-wasm](https://www.npmjs.com/package/@ruvector/graph-wasm) | WASM graph DB | [![npm](https://img.shields.io/npm/v/@ruvector/graph-wasm.svg)](https://www.npmjs.com/package/@ruvector/graph-wasm) | [![downloads](https://img.shields.io/npm/dt/@ruvector/graph-wasm.svg)](https://www.npmjs.com/package/@ruvector/graph-wasm) | | [@ruvector/attention-wasm](https://www.npmjs.com/package/@ruvector/attention-wasm) | WASM attention | [![npm](https://img.shields.io/npm/v/@ruvector/attention-wasm.svg)](https://www.npmjs.com/package/@ruvector/attention-wasm) | [![downloads](https://img.shields.io/npm/dt/@ruvector/attention-wasm.svg)](https://www.npmjs.com/package/@ruvector/attention-wasm) | | [@ruvector/tiny-dancer-wasm](https://www.npmjs.com/package/@ruvector/tiny-dancer-wasm) | WASM AI routing | [![npm](https://img.shields.io/npm/v/@ruvector/tiny-dancer-wasm.svg)](https://www.npmjs.com/package/@ruvector/tiny-dancer-wasm) | [![downloads](https://img.shields.io/npm/dt/@ruvector/tiny-dancer-wasm.svg)](https://www.npmjs.com/package/@ruvector/tiny-dancer-wasm) | | [@ruvector/router-wasm](https://www.npmjs.com/package/@ruvector/router-wasm) | WASM semantic router | [![npm](https://img.shields.io/npm/v/@ruvector/router-wasm.svg)](https://www.npmjs.com/package/@ruvector/router-wasm) | [![downloads](https://img.shields.io/npm/dt/@ruvector/router-wasm.svg)](https://www.npmjs.com/package/@ruvector/router-wasm) | | [@ruvector/postgres-cli](https://www.npmjs.com/package/@ruvector/postgres-cli) | Postgres extension CLI | [![npm](https://img.shields.io/npm/v/@ruvector/postgres-cli.svg)](https://www.npmjs.com/package/@ruvector/postgres-cli) | [![downloads](https://img.shields.io/npm/dt/@ruvector/postgres-cli.svg)](https://www.npmjs.com/package/@ruvector/postgres-cli) | | [@ruvector/agentic-synth](https://www.npmjs.com/package/@ruvector/agentic-synth) | Synthetic data generator | [![npm](https://img.shields.io/npm/v/@ruvector/agentic-synth.svg)](https://www.npmjs.com/package/@ruvector/agentic-synth) | [![downloads](https://img.shields.io/npm/dt/@ruvector/agentic-synth.svg)](https://www.npmjs.com/package/@ruvector/agentic-synth) | | [@ruvector/graph-data-generator](https://www.npmjs.com/package/@ruvector/graph-data-generator) | Graph data generation | [![npm](https://img.shields.io/npm/v/@ruvector/graph-data-generator.svg)](https://www.npmjs.com/package/@ruvector/graph-data-generator) | [![downloads](https://img.shields.io/npm/dt/@ruvector/graph-data-generator.svg)](https://www.npmjs.com/package/@ruvector/graph-data-generator) | | [@ruvector/agentic-integration](https://www.npmjs.com/package/@ruvector/agentic-integration) | Agentic workflows | [![npm](https://img.shields.io/npm/v/@ruvector/agentic-integration.svg)](https://www.npmjs.com/package/@ruvector/agentic-integration) | [![downloads](https://img.shields.io/npm/dt/@ruvector/agentic-integration.svg)](https://www.npmjs.com/package/@ruvector/agentic-integration) |

**Platform-specific native bindings** (auto-detected): - `@ruvector/node-linux-x64-gnu`, `@ruvector/node-linux-arm64-gnu`, `@ruvector/node-darwin-x64`, `@ruvector/node-darwin-arm64`, `@ruvector/node-win32-x64-msvc` - `@ruvector/gnn-linux-x64-gnu`, `@ruvector/gnn-linux-arm64-gnu`, `@ruvector/gnn-darwin-x64`, `@ruvector/gnn-darwin-arm64`, `@ruvector/gnn-win32-x64-msvc` - `@ruvector/tiny-dancer-linux-x64-gnu`, `@ruvector/tiny-dancer-linux-arm64-gnu`, `@ruvector/tiny-dancer-darwin-x64`, `@ruvector/tiny-dancer-darwin-arm64`, `@ruvector/tiny-dancer-win32-x64-msvc` - `@ruvector/router-linux-x64-gnu`, `@ruvector/router-linux-arm64-gnu`, `@ruvector/router-darwin-x64`, `@ruvector/router-darwin-arm64`, `@ruvector/router-win32-x64-msvc` - `@ruvector/attention-linux-x64-gnu`, `@ruvector/attention-linux-arm64-gnu`, `@ruvector/attention-darwin-x64`, `@ruvector/attention-darwin-arm64`, `@ruvector/attention-win32-x64-msvc` - `@ruvector/ruvllm-linux-x64-gnu`, `@ruvector/ruvllm-linux-arm64-gnu`, `@ruvector/ruvllm-darwin-x64`, `@ruvector/ruvllm-darwin-arm64`, `@ruvector/ruvllm-win32-x64-msvc` #### 🚧 Planned | Package | Description | Status | |---------|-------------|--------| | @ruvector/raft | Raft consensus for distributed ops | Crate ready | | @ruvector/replication | Multi-master replication | Crate ready | | @ruvector/scipix | Scientific OCR (LaTeX/MathML) | Crate ready | See [GitHub Issue #20](https://github.com/ruvnet/ruvector/issues/20) for multi-platform npm package roadmap. ```bash # Install all-in-one package npm install ruvector # Or install individual packages npm install @ruvector/core @ruvector/gnn @ruvector/graph-node # List all available packages npx ruvector install ``` ```javascript const ruvector = require('ruvector'); // Vector search const db = new ruvector.VectorDB(128); db.insert('doc1', embedding1); const results = db.search(queryEmbedding, 10); // Graph queries (Cypher) db.execute("CREATE (a:Person {name: 'Alice'})-[:KNOWS]->(b:Person {name: 'Bob'})"); db.execute("MATCH (p:Person)-[:KNOWS]->(friend) RETURN friend.name"); // GNN-enhanced search const layer = new ruvector.GNNLayer(128, 256, 4); const enhanced = layer.forward(query, neighbors, weights); // Compression (2-32x memory savings) const compressed = ruvector.compress(embedding, 0.3); // Tiny Dancer: AI agent routing const router = new ruvector.Router(); const decision = router.route(candidates, { optimize: 'cost' }); ```

🦀 Rust Usage Examples

```bash cargo add ruvector-graph ruvector-gnn ``` ```rust use ruvector_graph::{GraphDB, NodeBuilder}; use ruvector_gnn::{RuvectorLayer, differentiable_search}; let db = GraphDB::new(); let doc = NodeBuilder::new("doc1") .label("Document") .property("embedding", vec![0.1, 0.2, 0.3]) .build(); db.create_node(doc)?; // GNN layer let layer = RuvectorLayer::new(128, 256, 4, 0.1); let enhanced = layer.forward(&query, &neighbors, &weights); ``` ```rust use ruvector_raft::{RaftNode, RaftNodeConfig}; use ruvector_cluster::{ClusterManager, ConsistentHashRing}; use ruvector_replication::{SyncManager, SyncMode}; // Configure a 5-node Raft cluster let config = RaftNodeConfig { node_id: "node-1".into(), cluster_members: vec!["node-1", "node-2", "node-3", "node-4", "node-5"] .into_iter().map(Into::into).collect(), election_timeout_min: 150, // ms election_timeout_max: 300, // ms heartbeat_interval: 50, // ms }; let raft = RaftNode::new(config); // Auto-sharding with consistent hashing (150 virtual nodes per real node) let ring = ConsistentHashRing::new(64, 3); // 64 shards, replication factor 3 let shard = ring.get_shard("my-vector-key"); // Multi-master replication with conflict resolution let sync = SyncManager::new(SyncMode::SemiSync { min_replicas: 2 }); ```

📁 Project Structure

``` crates/ ├── ruvector-core/ # Vector DB engine (HNSW, storage) ├── ruvector-graph/ # Graph DB + Cypher parser + Hyperedges ├── ruvector-gnn/ # GNN layers, compression, training ├── ruvector-tiny-dancer-core/ # AI agent routing (FastGRNN) ├── ruvector-*-wasm/ # WebAssembly bindings └── ruvector-*-node/ # Node.js bindings (napi-rs) ```

## Contributing We welcome contributions! See [CONTRIBUTING.md](./docs/development/CONTRIBUTING.md). ```bash # Run tests cargo test --workspace # Run benchmarks cargo bench --workspace # Build WASM cargo build -p ruvector-gnn-wasm --target wasm32-unknown-unknown ``` ## License MIT License — free for commercial and personal use. ---

**Built by [rUv](https://ruv.io)** • [GitHub](https://github.com/ruvnet/ruvector) • [npm](https://npmjs.com/package/ruvector) • [Docs](./docs/) *Vector search that gets smarter over time.*