mirror of
https://github.com/ruvnet/RuVector.git
synced 2026-05-27 00:25:10 +00:00
d294274a6a
* feat(postgres): Add RuVector Postgres v2 implementation plan Complete specification for RuVector Postgres v2 with: Architecture: - PostgreSQL extension (pgrx) with hybrid architecture - SQL handles ACID/joins, RuVector engine handles vectors/graphs/learning - Backward compatible with pgvector SQL surface - Shared memory IPC with bounded contracts (64KB inline, 16MB shared) 4-Phase Implementation: - Phase 1: pgvector-compatible search (1a: function-based, 1b: Index AM) - Phase 2: Tiered storage with compression and exactness GUC - Phase 3: Graph engine with Cypher and SQL join keys - Phase 4: Dynamic mincut integrity gating (key differentiator) Key Technical Details: - lambda_cut: Minimum cut value via Stoer-Wagner (PRIMARY integrity metric) - lambda2: Algebraic connectivity (OPTIONAL drift signal) - DIFFERENT from mincut! - Contracted operational graph (~1000 nodes) - never compute on full similarity graph - Hysteresis model with consecutive samples and cooldown - Operation risk classification (Low/Medium/High) - MVCC visibility with incremental paging API - WAL replay with idempotency and LSN ordering - Partition map versioning and epoch fencing for cluster mode Files: - 00-overview.md: Architecture, consistency contract, benchmark spec - 01-sql-schema.md: SQL schema and types - 02-background-workers.md: IPC contract, mincut worker - 03-index-access-methods.md: Index AM specification - 04-integrity-events.md: Events, hysteresis, operation classes - 05-phase1-pgvector-compat.md: Phase 1a/1b incremental path - 06-phase2-tiered-storage.md: Tiered storage with GUC exactness - 07-phase3-graph-cypher.md: Graph engine with SQL joins - 08-phase4-integrity-control.md: Mincut gating with Stoer-Wagner - 09-migration-guide.md: Migration from pgvector - 10-consistency-replication.md: Consistency and replication model 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs(postgres): Rewrite v2 overview with compelling framing Replace technical executive summary with clear explanation of why RuVector matters: - From symptom monitoring to causal monitoring - Mincut as leading indicator, not metric - Algorithm becomes control signal (control plane, not analytics) - Failure mode class change: cascading → graceful degradation - Explainable operations via witness edges Key message: "We're not making vector search faster. We're making vector infrastructure survivable." 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * feat(postgres): Add hybrid search, multi-tenancy, and self-healing specs Three high-impact additions to RuVector Postgres v2: ## 11-hybrid-search.md - BM25 + Vector Fusion - Single query combines semantic and keyword search - Proper BM25 implementation (not just ts_rank) - Fusion algorithms: RRF (default), linear, learned - Integrity-aware degradation (stress → single branch) - Parallel branch execution - GUC configuration ## 12-multi-tenancy.md - First-Class Tenant Isolation - SET ruvector.tenant_id for transparent scoping - Isolation levels: shared, partition, dedicated - Automatic promotion based on vector count - Per-tenant integrity (stress in one doesn't affect others) - Per-tenant contracted graphs - Resource quotas and rate limiting - Fair scheduling (no noisy neighbors) - RLS integration for defense in depth ## 13-self-healing.md - Automated Remediation - Completes the control loop: sensor → actuator - Problem classification from witness edges: - Hotspot congestion - Centroid skew - Replication lag - Maintenance contention - Index fragmentation - Memory pressure - Built-in strategies: - Rebalance partitions - Pause maintenance jobs - Throttle ingestion - Scale read replicas (K8s) - Compact fragmented indexes - Safety: reversible actions, blast radius limits - Learning: outcome tracking, strategy weight updates - The key insight: "We built the sensor. Now we build the actuator." 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * feat(intelligence): Add self-learning intelligence layer with v3 features Comprehensive intelligence system for Claude Code hooks: Core Features (v2): - VectorMemory with @ruvector/core native HNSW (150x faster) - Hyperbolic distance (Poincaré ball) for hierarchical embeddings - ReasoningBank with Q-learning and pattern decay (7-day half-life) - Confidence Calibration tracking (predicted vs actual accuracy) - A/B Testing with 10% holdout for measuring intelligence lift - Feedback Loop for tracking suggestion follow-through - Active Learning for identifying uncertain states v3 Improvements: - Error Pattern Learning (Rust E0xxx, TypeScript TSxxxx, npm errors) - File Sequence Learning (tracks which files are edited together) - Test Suggestion Triggers (suggests cargo test after source edits) - Hive-Mind swarm coordination (11 agents, 38 edges) Pretrained from memory.db: - 7,697 commands processed - 4,023 vector memories - 117 Q-table states with decay metadata - 8,520 calibration samples Anti-overfitting measures: - Q-values capped at 0.8, floored at -0.5 - Decaying learning rate: 0.3/sqrt(count) - Pattern decay with timestamps 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(intelligence): Fix Q-table lookups - learning now has real effect Three critical bugs were preventing the intelligence layer from using learned patterns: 1. State format mismatch: CLI used spaces ("editing rs in project") but Q-table used underscores ("edit_rs_in_project") - Fixed in cli.js: all states now use underscore format 2. stateKey() hyphen normalization: Function converted hyphens to underscores, but Q-table keys had hyphens (e.g. "ruvector-core") - Fixed regex: /[^a-z0-9-]+/g preserves hyphens 3. A/B testing control group: 10% random sessions ignored learning - Reduced holdout to 5% with persistent session assignment - Added INTELLIGENCE_MODE=treatment env override for development Result: Agent recommendations now show 80% confidence for Rust files using learned Q-values, instead of 0% with random selection. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(hooks): Display intelligence guidance to Claude in foreground Critical fix: PreToolUse hooks were running in background (&) which meant Claude never saw the intelligence output. Now: - PreToolUse: Foreground execution (Claude sees guidance) - pre-edit: Shows recommended agent + confidence + similar edits - pre-command: Shows command patterns + suggestions - Added 3s timeout to prevent blocking - PostToolUse: Background execution (async learning) - post-edit: Records success/failure, learns patterns - post-command: Captures errors, updates Q-values - SessionStart: New hook shows learned patterns at session start - Displays pattern count, memory stats - Shows top 3 learned state-action pairs with Q-values Claude now receives self-learning guidance like: "🧠 Intelligence Analysis: 📁 ruvector-core/lib.rs 🤖 Recommended: rust-developer (80% confidence) 📚 3 similar past edits found" 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> |
||
|---|---|---|
| .. | ||
| api | ||
| architecture | ||
| benchmarks | ||
| cloud-architecture | ||
| development | ||
| examples | ||
| gnn | ||
| guides | ||
| hnsw | ||
| implementation | ||
| integration | ||
| optimization | ||
| plans/subpolynomial-time-mincut | ||
| postgres | ||
| project-phases | ||
| publishing | ||
| research | ||
| sql | ||
| testing | ||
| .gitkeep | ||
| INDEX.md | ||
| README.md | ||
| REPO_STRUCTURE.md | ||
RuVector Documentation
Complete documentation for RuVector, the high-performance Rust vector database with global scale capabilities.
📚 Documentation Structure
Getting Started
Quick start guides and tutorials for new users:
- AGENTICDB_QUICKSTART.md - Quick start for AgenticDB compatibility
- OPTIMIZATION_QUICK_START.md - Performance optimization quick guide
- AGENTICDB_API.md - AgenticDB API reference
- wasm-api.md - WebAssembly API documentation
- wasm-build-guide.md - Building WASM bindings
- advanced-features.md - Advanced features guide
- quick-fix-guide.md - Common issues and fixes
Architecture & Design
System architecture and design documentation:
- TECHNICAL_PLAN.md - Complete technical plan and architecture
- INDEX.md - Documentation index
- architecture/ - System architecture details
- cloud-architecture/ - Global cloud deployment architecture
- architecture-overview.md - 15-region topology
- scaling-strategy.md - Auto-scaling & burst handling
- infrastructure-design.md - GCP infrastructure specs
- DEPLOYMENT_GUIDE.md - Step-by-step deployment
- PERFORMANCE_OPTIMIZATION_GUIDE.md - Advanced tuning
API Reference
API documentation for different platforms:
- api/ - Core API documentation
- RUST_API.md - Rust API reference
- NODEJS_API.md - Node.js API reference
User Guides
Comprehensive user guides:
- guide/ - User guides
- GETTING_STARTED.md - Getting started guide
- BASIC_TUTORIAL.md - Basic tutorial
- ADVANCED_FEATURES.md - Advanced features
- INSTALLATION.md - Installation instructions
Performance & Optimization
Performance tuning and benchmarking:
- optimization/ - Performance optimization guides
- BUILD_OPTIMIZATION.md - Build optimizations
- IMPLEMENTATION_SUMMARY.md - Implementation details
- OPTIMIZATION_RESULTS.md - Optimization results
- PERFORMANCE_TUNING_GUIDE.md - Performance tuning
- benchmarks/ - Benchmarking documentation
- BENCHMARKING_GUIDE.md - How to run benchmarks
Development
Contributing and development guides:
- development/ - Development documentation
- CONTRIBUTING.md - Contribution guidelines
- MIGRATION.md - Migration guide
- FIXING_COMPILATION_ERRORS.md - Troubleshooting compilation
Testing
Testing documentation and reports:
- testing/ - Testing documentation
- TDD_TEST_SUITE_SUMMARY.md - TDD test suite summary
- integration-testing-report.md - Integration test report
Project History
Historical project phase documentation:
- project-phases/ - Project phase documentation
- phase2_hnsw_implementation.md - Phase 2: HNSW
- PHASE3_SUMMARY.md - Phase 3 summary
- phase4-implementation-summary.md - Phase 4 summary
- PHASE5_COMPLETE.md - Phase 5 complete
- phase5-implementation-summary.md - Phase 5 summary
- PHASE6_ADVANCED.md - Phase 6 advanced features
- PHASE6_COMPLETION_REPORT.md - Phase 6 report
- PHASE6_SUMMARY.md - Phase 6 summary
Implementation Summary
- IMPLEMENTATION_SUMMARY.md - Complete implementation overview for global streaming
🚀 Quick Links
For New Users
- Start with Getting Started Guide
- Try the Basic Tutorial
- Review API Documentation
For Cloud Deployment
- Read Architecture Overview
- Follow Deployment Guide
- Apply Performance Optimizations
For Contributors
- Read Contributing Guidelines
- Review Technical Plan
- Check Migration Guide
For Performance Tuning
- Review Optimization Guide
- Run Benchmarks
- Apply Query Optimizations
📊 Documentation Status
| Category | Files | Status |
|---|---|---|
| Getting Started | 7 | ✅ Complete |
| Architecture | 11 | ✅ Complete |
| API Reference | 2 | ✅ Complete |
| User Guides | 4 | ✅ Complete |
| Optimization | 4 | ✅ Complete |
| Development | 3 | ✅ Complete |
| Testing | 2 | ✅ Complete |
| Project Phases | 8 | 📚 Historical |
Total Documentation: 40+ comprehensive documents
🔗 External Resources
- GitHub Repository: https://github.com/ruvnet/ruvector
- Main README: ../README.md
- Changelog: ../CHANGELOG.md
- License: ../LICENSE
Last Updated: 2025-11-20 | Version: 0.1.0 | Status: Production Ready