Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

Checkpoint: File edits

rUvdb2421c8b063
diff --git a/docs/ruvector-postgres/README.md b/docs/ruvector-postgres/README.md
index 39b35006f6..8f5e68343d 100644
--- a/docs/ruvector-postgres/README.md
+++ b/docs/ruvector-postgres/README.md
@@ -1,10 +1,27 @@
# RuVector PostgreSQL Testing Environment
-A Docker-based testing environment for the RuVector PostgreSQL Bridge feature.
+A Docker-based testing environment for the **RuVector PostgreSQL extension** from [ruvnet/ruvector](https://github.com/ruvnet/ruvector).
+
+> **Note**: This uses the official RuVector PostgreSQL extension, not pgvector. RuVector provides 77+ SQL functions with advanced AI capabilities.
+
+## RuVector Features
+
+| Feature | Description |
+|---------|-------------|
+| **77+ SQL Functions** | Comprehensive vector operations in SQL |
+| **HNSW/IVFFlat Indexing** | ~61Β΅s search latency, 16,400 QPS |
+| **39 Attention Mechanisms** | Self, multi-head, cross-attention in SQL |
+| **GNN Operations** | Graph neural network layers (GAT, message passing) |
+| **Hyperbolic Embeddings** | PoincarΓ© and Lorentz space implementations |
+| **Sparse Vectors** | BM25/TF-IDF for hybrid search |
+| **SPARQL Support** | 50+ RDF functions (W3C SPARQL 1.1) |
+| **Local Embeddings** | 6 fastembed models for offline generation |
+| **Self-Learning Indices** | Continuous optimization through GNN layers |
+| **SIMD Acceleration** | AVX-512/AVX2/NEON (~2x faster) |
## Quick Start
-### 1. Start the PostgreSQL container
+### 1. Start the RuVector PostgreSQL container
```bash
# From this directory
@@ -30,7 +47,7 @@ ruvector-postgres running (healthy) 0.0.0.0:5432->5432/tcp
```bash
# Using psql
-docker exec -it ruvector-postgres psql -U claude -d claude_flow -c "SELECT version();"
+docker exec -it ruvector-postgres psql -U claude -d claude_flow -c "SELECT ruvector.version();"
# Or run our test script
./scripts/test-connection.sh
@@ -62,8 +79,9 @@ docs/ruvector-postgres/
β”‚ └── cleanup.sh # Remove all data and reset
β”œβ”€β”€ examples/
β”‚ β”œβ”€β”€ basic-queries.sql # Basic vector operations
-β”‚ β”œβ”€β”€ similarity-search.sql # Semantic search examples
-β”‚ └── attention-ops.sql # Attention mechanism examples
+β”‚ β”œβ”€β”€ similarity-search.sql # HNSW semantic search examples
+β”‚ β”œβ”€β”€ attention-ops.sql # Attention mechanism examples
+β”‚ └── v3-demo.sql # Complete V3 demo with all features
└── tests/
β”œβ”€β”€ test-vectors.ts # TypeScript test suite
└── benchmark.sh # Performance benchmarks
@@ -82,18 +100,19 @@ docs/ruvector-postgres/
## Available Services
-### PostgreSQL with pgvector
+### RuVector PostgreSQL
- **Container**: `ruvector-postgres`
-- **Image**: `pgvector/pgvector:pg16`
+- **Image**: `ruvector/postgres:latest`
- **Port**: 5432
Pre-configured with:
-- pgvector extension enabled
+- RuVector extension enabled (77+ functions)
- `claude_flow` schema created
-- Sample tables (embeddings, patterns, agents)
-- HNSW indices for fast similarity search
+- Core tables (embeddings, patterns, agents, trajectories, hyperbolic_embeddings, graph_nodes, graph_edges)
+- HNSW indices for fast similarity search (~61Β΅s)
- Sample test data
+- Self-learning optimization enabled
### pgAdmin (Optional)
@@ -110,24 +129,46 @@ Access at: http://localhost:5050
## Common Tasks
-### View sample data
+### Generate embeddings locally
```bash
docker exec -it ruvector-postgres psql -U claude -d claude_flow -c \
- "SELECT id, content, metadata FROM claude_flow.embeddings;"
+ "SELECT claude_flow.embed_text('Hello, world!', 'all-MiniLM-L6-v2');"
```
-### Run similarity search (after adding embeddings)
+### Run similarity search
```bash
docker exec -it ruvector-postgres psql -U claude -d claude_flow -c \
"SELECT * FROM claude_flow.search_similar(
- (SELECT embedding FROM claude_flow.embeddings LIMIT 1),
+ claude_flow.embed_text('authentication security'),
5,
0.3
);"
```
+### Run multi-head attention
+
+```bash
+docker exec -it ruvector-postgres psql -U claude -d claude_flow -c \
+ "SELECT * FROM claude_flow.multihead_attention(
+ claude_flow.embed_text('query text'),
+ 8, -- number of heads
+ 5 -- limit
+ );"
+```
+
+### Hyperbolic search (for hierarchical data)
+
+```bash
+docker exec -it ruvector-postgres psql -U claude -d claude_flow -c \
+ "SELECT * FROM claude_flow.hyperbolic_search(
+ claude_flow.embed_text('parent concept'),
+ 10,
+ -1.0 -- curvature
+ );"
+```
+
### Check HNSW indices
```bash
@@ -135,10 +176,11 @@ docker exec -it ruvector-postgres psql -U claude -d claude_flow -c \
"SELECT indexname, indexdef FROM pg_indexes WHERE schemaname = 'claude_flow';"
```
-### Run all migrations
+### Run self-learning optimization
```bash
-./scripts/run-migrations.sh
+docker exec -it ruvector-postgres psql -U claude -d claude_flow -c \
+ "SELECT claude_flow.optimize_indices();"
```
### Reset everything
@@ -193,7 +235,7 @@ npx claude-flow@alpha ruvector optimize \
## Environment Variables
-You can also use environment variables instead of CLI flags:
+You can use environment variables instead of CLI flags:
```bash
export PGHOST=localhost
@@ -202,10 +244,72 @@ export PGDATABASE=claude_flow
export PGUSER=claude
export PGPASSWORD=claude-flow-test
+# RuVector specific
+export RUVECTOR_SIMD=auto
+export RUVECTOR_CACHE_SIZE=256MB
+export RUVECTOR_LEARN_ENABLED=true
+
# Then run without connection flags
npx claude-flow@alpha ruvector status --verbose
```
+## RuVector SQL Functions Reference
+
+### Vector Operations
+| Function | Description |
+|----------|-------------|
+| `ruvector.cosine_similarity(a, b)` | Cosine similarity between vectors |
+| `ruvector.euclidean_distance(a, b)` | L2 distance |
+| `ruvector.dot_product(a, b)` | Inner product |
+| `a <-> b` | Distance operator (uses index) |
+| `a <=> b` | Cosine distance operator |
+
+### Attention Mechanisms
+| Function | Description |
+|----------|-------------|
+| `ruvector.softmax_attention(q, k, temp)` | Softmax attention score |
+| `ruvector.multihead_attention_scores(q, k, heads)` | Per-head attention scores |
+| `ruvector.multihead_attention_aggregate(q, k, heads)` | Aggregated attention |
+| `ruvector.cross_attention_score(q, kv, temp)` | Cross-attention weight |
+
+### GNN Operations
+| Function | Description |
+|----------|-------------|
+| `ruvector.gnn_aggregate(embeddings[], method)` | Aggregate embeddings (mean/sum/max) |
+| `ruvector.gat_score(source, target)` | Graph attention score |
+
+### Hyperbolic Operations
+| Function | Description |
+|----------|-------------|
+| `ruvector.exp_map_poincare(euclidean, curvature)` | Map to PoincarΓ© ball |
+| `ruvector.hyperbolic_distance(a, b, model, curvature)` | Geodesic distance |
+| `ruvector.mobius_add(a, b, curvature)` | MΓΆbius addition |
+
+### Sparse/Hybrid Search
+| Function | Description |
+|----------|-------------|
+| `ruvector.bm25_score(sparse, query_text)` | BM25 ranking score |
+| `ruvector.tfidf_score(sparse, query_text)` | TF-IDF score |
+
+### Local Embeddings
+| Function | Description |
+|----------|-------------|
+| `ruvector.fastembed(text, model)` | Generate embedding locally |
+
+### Self-Learning
+| Function | Description |
+|----------|-------------|
+| `ruvector.learn_optimize(table, column)` | Optimize index through learning |
+
+## Performance Benchmarks
+
+| Metric | Value |
+|--------|-------|
+| HNSW Search Latency | ~61Β΅s (k=10, 384-dim) |
+| Throughput | 16,400 QPS |
+| Memory (1M vectors) | 200MB (PQ8 compression) |
+| Index Build | ~10 min for 1M vectors |
+
## Troubleshooting
### Container won't start
@@ -218,20 +322,21 @@ docker-compose logs postgres
lsof -i :5432
```
-### Permission denied errors
+### RuVector extension missing
```bash
-# Reset permissions
+# Manually enable
docker exec -it ruvector-postgres psql -U claude -d claude_flow -c \
- "GRANT ALL ON SCHEMA claude_flow TO claude;"
+ "CREATE EXTENSION IF NOT EXISTS ruvector;"
```
-### pgvector extension missing
+### Permission denied errors
```bash
-# Manually enable
+# Reset permissions
docker exec -it ruvector-postgres psql -U claude -d claude_flow -c \
- "CREATE EXTENSION IF NOT EXISTS vector;"
+ "GRANT ALL ON SCHEMA claude_flow TO claude;
+ GRANT USAGE ON SCHEMA ruvector TO claude;"
```
### Reset to clean state
@@ -243,6 +348,6 @@ docker-compose up -d
## Learn More
+- [RuVector Repository](https://github.com/ruvnet/ruvector)
- [RuVector PostgreSQL Bridge Documentation](https://github.com/ruvnet/claude-flow/issues/963)
- [ADR-027: RuVector PostgreSQL Integration](../../v3/implementation/adrs/ADR-027-ruvector-postgresql-integration.md)
-- [pgvector Documentation](https://github.com/pgvector/pgvector)