π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
Checkpoint: File edits
rUvdb2421c8b063
diff --git a/docs/ruvector-postgres/README.md b/docs/ruvector-postgres/README.mdindex 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**: 5432Pre-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```bashdocker 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```bashdocker 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:```bashexport PGHOST=localhost@@ -202,10 +244,72 @@ export PGDATABASE=claude_flowexport PGUSER=claudeexport PGPASSWORD=claude-flow-test+# RuVector specific+export RUVECTOR_SIMD=auto+export RUVECTOR_CACHE_SIZE=256MB+export RUVECTOR_LEARN_ENABLED=true+# Then run without connection flagsnpx 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 postgreslsof -i :5432```-### Permission denied errors+### RuVector extension missing```bash-# Reset permissions+# Manually enabledocker 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 permissionsdocker 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)