🐘 RuVector PostgreSQL Bridge - Enterprise Vector Database Integration

# 🐘 RuVector PostgreSQL Bridge

## Enterprise-Grade Vector Database for AI Agent Systems

**Transform your Claude-Flow agents with production-ready vector storage, sub-millisecond search, and advanced AI capabilities—all powered by 77+ SQL functions.**

[](https://hub.docker.com/r/ruvnet/ruvector-postgres)
[](https://github.com/ruvnet/ruvector)
[](https://github.com/ruvnet/ruvector)

---

## 🚀 Key Highlights

| Capability | Specification |
|------------|---------------|
| **Search Latency** | ~61µs (150x faster than brute force) |
| **Throughput** | 16,400 queries per second |
| **SQL Functions** | 77+ comprehensive vector operations |
| **Attention Mechanisms** | 39 types (self, multi-head, cross) |
| **SIMD Optimization** | AVX-512/AVX2/NEON (~2x faster) |
| **Hyperbolic Embeddings** | Poincaré ball model for hierarchical data |
| **Graph Operations** | GAT, GNN message passing, Cypher queries |
| **Self-Learning** | Indices optimize automatically over time |

---

## ⚡ Quick Start (30 seconds)

```bash
# Option 1: Use CLI Setup (Recommended)
npx claude-flow ruvector setup --output ./my-ruvector
cd my-ruvector && docker-compose up -d

# Option 2: From repository
cd docs/ruvector-postgres && docker-compose up -d

# Verify
docker exec ruvector-postgres psql -U claude -d claude_flow -c "SELECT ruvector_version();"
# Output: 2.0.0
```

---

## 🔄 Migration from sql.js/JSON

Easily migrate your existing Claude-Flow memory to PostgreSQL:

```bash
# Export current memory
npx claude-flow memory list --format json > memory-export.json

# Import to RuVector PostgreSQL
npx claude-flow ruvector import --input memory-export.json

# Or generate SQL first (dry-run)
npx claude-flow ruvector import --input memory-export.json --output import.sql
```

---

## 🆚 Why RuVector over pgvector?

| Feature | pgvector | RuVector |
|---------|----------|----------|
| **SQL Functions** | ~10 basic | **77+ comprehensive** |
| **Search Latency** | ~1ms | **~61µs** |
| **Throughput** | ~5K QPS | **16,400 QPS** |
| **Attention Mechanisms** | ❌ None | **✅ 39 mechanisms** |
| **GNN Operations** | ❌ None | **✅ GAT, message passing** |
| **Hyperbolic Embeddings** | ❌ None | **✅ Poincaré/Lorentz** |
| **Hybrid Search** | ❌ Manual | **✅ BM25/TF-IDF built-in** |
| **Local Embeddings** | ❌ None | **✅ 6 fastembed models** |
| **Self-Learning** | ❌ None | **✅ GNN-based optimization** |
| **SIMD Optimization** | Basic | **AVX-512/AVX2/NEON** |

---

📖 Introduction

### What is RuVector PostgreSQL Bridge?

RuVector PostgreSQL Bridge connects Claude-Flow's AI agent system directly to PostgreSQL databases with the **RuVector extension** (ruvnet/ruvector). This provides:

- **77+ SQL functions** for vector operations directly in the database
- **39 Attention mechanisms** (self, multi-head, cross-attention)
- **GNN layers** for graph neural network operations
- **Hyperbolic embeddings** (Poincaré and Lorentz space)
- **Sparse vectors** for hybrid BM25/TF-IDF search
- **Local embeddings** with 6 fastembed models
- **Self-learning indices** that optimize over time
- **SIMD acceleration** (AVX-512/AVX2/NEON)

### When Should You Use It?

✅ **Use RuVector PostgreSQL Bridge when:**
- You need advanced AI operations (attention, GNN, hyperbolic)
- You want hybrid search (vector + BM25/TF-IDF)
- You need local embedding generation without external APIs
- You want self-learning indices that improve over time
- You need sub-millisecond search latency (~61µs)
- Multiple agents need concurrent access to vectors

❌ **Stick with in-memory when:**
- You're prototyping or experimenting
- Your dataset is small (<10,000 vectors)
- You don't need persistent storage
- You don't have PostgreSQL infrastructure

---

⚡ Capabilities

### Core Features

| Feature | Description | Benefit |
|---------|-------------|---------|
| **77+ SQL Functions** | Comprehensive vector operations | Full AI toolkit in SQL |
| **HNSW/IVFFlat Indexing** | ~61µs search latency | 150x faster than brute force |
| **SIMD Acceleration** | AVX-512/AVX2/NEON | 2x faster distance calculations |
| **39 Attention Mechanisms** | Self, multi-head, cross-attention | Transformer ops in SQL |
| **GNN Operations** | GAT, message passing | Graph learning in database |
| **Hyperbolic Embeddings** | Poincaré/Lorentz space | Better hierarchical representations |
| **Sparse Vectors** | BM25/TF-IDF | Hybrid search capabilities |
| **Local Embeddings** | 6 fastembed models | Offline embedding generation |
| **Self-Learning** | GNN-based optimization | Indices improve over time |

### Performance Specifications

| Metric | Value | Notes |
|--------|-------|-------|
| HNSW Search | ~61µs | k=10, 384-dimensional vectors |
| Throughput | 16,400 QPS | Sustained under load |
| Memory (1M vectors) | 200MB | With PQ8 compression |
| Insert Rate | 10,000+/sec | With batching enabled |
| Index Build | ~10 min | One-time for 1M vectors |
| Concurrent Queries | 100+ | PostgreSQL connection pooling |

### RuVector SQL Functions

#### Vector Operations
```sql
-- Distance/similarity functions
cosine_similarity_arr(a, b) -- Cosine similarity
l2_distance_arr(a, b) -- L2 distance
a <-> b -- L2 distance operator (indexed)
a <=> b -- Cosine distance operator
a <#> b -- Negative inner product
```

#### Hyperbolic Embeddings
```sql
-- Poincaré distance
ruvector_poincare_distance(a, b, curvature)

-- Exponential map (Euclidean to Poincaré)
ruvector_exp_map(origin, tangent, curvature)

-- Möbius addition
ruvector_mobius_add(a, b, curvature)
```

---

🔧 CLI Commands

Claude-Flow provides CLI commands for RuVector PostgreSQL management:

### `ruvector setup`

Generate Docker files and SQL for easy setup:

```bash
# Output to default directory (./ruvector-postgres)
npx claude-flow ruvector setup

# Output to custom directory
npx claude-flow ruvector setup --output /path/to/dir

# Print files to stdout (for inspection)
npx claude-flow ruvector setup --print

# Force overwrite existing files
npx claude-flow ruvector setup --force
```

**Generated files:**
```
ruvector-postgres/
├── docker-compose.yml # Docker services configuration
├── README.md # Quick start guide
└── scripts/
└── init-db.sql # Database initialization
```

### `ruvector import`

Import data from sql.js/JSON memory to PostgreSQL:

```bash
# Import from JSON file (direct execution)
npx claude-flow ruvector import --input memory-export.json

# Generate SQL file (dry-run)
npx claude-flow ruvector import --input memory-export.json --output import.sql

# Use custom Docker container
npx claude-flow ruvector import --input data.json --container my-postgres

# Verbose output
npx claude-flow ruvector import --input data.json --verbose
```

**Supported JSON formats:**
- Array of entries: `[{"key": "...", "value": "...", "namespace": "..."}]`
- Object with entries: `{"entries": [...]}`
- Key-value object: `{"key1": "value1", "key2": "value2"}`

### Other Commands

```bash
# Check connection and schema status
npx claude-flow ruvector status --verbose

# Run database migrations
npx claude-flow ruvector migrate --up

# Run performance benchmarks
npx claude-flow ruvector benchmark --vectors 10000

# Analyze and optimize
npx claude-flow ruvector optimize --analyze

# Backup data
npx claude-flow ruvector backup --output backup.sql
```

---

📦 Docker Testing Environment

### Quick Start

```bash
# Navigate to test environment
cd docs/ruvector-postgres/

# Start RuVector PostgreSQL
docker-compose up -d

# Verify it's running
docker-compose ps

# Test connection
docker exec ruvector-postgres psql -U claude -d claude_flow -c "SELECT ruvector_version();"
```

### Connection Details

| Setting | Value |
|---------|-------|
| Host | `localhost` |
| Port | `5432` |
| Database | `claude_flow` |
| Username | `claude` |
| Password | `claude-flow-test` |

### RuVector SQL Syntax

**Important**: The extension requires explicit version:

```sql
-- CORRECT: Use explicit version
CREATE EXTENSION IF NOT EXISTS ruvector VERSION '0.1.0';

-- Vector type (not pgvector syntax!)
CREATE TABLE embeddings (
id UUID PRIMARY KEY,
embedding ruvector(384) -- RuVector type
);
```

---

📚 Tutorials

### Tutorial 1: Basic Vector Search

Store and search embeddings with HNSW indexing.

```sql
-- Create table with RuVector vector type
CREATE TABLE documents (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
content TEXT NOT NULL,
embedding ruvector(384),
metadata JSONB DEFAULT '{}'
);

-- Create HNSW index (~61µs search)
CREATE INDEX idx_documents_hnsw
ON documents
USING hnsw (embedding ruvector_cosine_ops)
WITH (m = 16, ef_construction = 100);

-- Similarity search
SELECT content, (1 - (embedding <=> query_emb)) AS similarity
FROM documents
ORDER BY embedding <=> query_emb
LIMIT 10;
```

### Tutorial 2: Hyperbolic Embeddings

Better representation for hierarchical data.

```sql
-- Poincaré distance (for hierarchical relationships)
SELECT ruvector_poincare_distance(
ARRAY[0.1, 0.2, 0.0]::real[], -- point A
ARRAY[0.3, 0.1, 0.0]::real[], -- point B
-1.0 -- curvature
) AS distance;

-- Möbius addition in hyperbolic space
SELECT ruvector_mobius_add(
ARRAY[0.1, 0.0]::real[],
ARRAY[0.0, 0.1]::real[],
-1.0
);
```

---

📚 Additional Resources

### Documentation

- [RuVector Docker Hub](https://hub.docker.com/r/ruvnet/ruvector-postgres)
- [Docker Testing Environment](../../docs/ruvector-postgres/README.md)
- [Claude-Flow Documentation](https://github.com/ruvnet/claude-flow)

### Example SQL Files

- [Basic Queries](../../docs/ruvector-postgres/examples/basic-queries.sql)
- [Similarity Search Examples](../../docs/ruvector-postgres/examples/)

---

## 📋 Implementation Status

- [x] Docker testing environment (`docs/ruvector-postgres/`)
- [x] Database initialization script with all tables
- [x] HNSW indexing configuration
- [x] CLI `ruvector setup` command
- [x] CLI `ruvector import` command
- [x] README documentation
- [ ] Full MCP integration
- [ ] Automatic embedding generation
- [ ] Connection pooling support

---

## Quick Links

| Resource | Link |
|----------|------|
| Docker Hub | https://hub.docker.com/r/ruvnet/ruvector-postgres |
| Docker Setup | [docs/ruvector-postgres/](../../docs/ruvector-postgres/) |
| Claude-Flow | https://github.com/ruvnet/claude-flow |

Start by reviewing docs/ruvector-postgres/README.md and the existing `ruvector setup` and `ruvector import` CLI entry points. The issue lists full MCP integration, automatic embedding generation, and connection pooling as unfinished, but does not define which work is in scope. Done requires explicit acceptance criteria for the selected integration area and validation against the Docker PostgreSQL environment.

Written by the indexing model from the issue text.