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

rUv5dac60f00b80
diff --git a/docs/ruvector-postgres/README.md b/docs/ruvector-postgres/README.md
index 8f5e68343d..32ba1ded3f 100644
--- a/docs/ruvector-postgres/README.md
+++ b/docs/ruvector-postgres/README.md
@@ -1,6 +1,6 @@
# RuVector PostgreSQL Testing Environment
-A Docker-based testing environment for the **RuVector PostgreSQL extension** from [ruvnet/ruvector](https://github.com/ruvnet/ruvector).
+A Docker-based testing environment for the **RuVector PostgreSQL extension** from [ruvnet/ruvector-postgres](https://hub.docker.com/r/ruvnet/ruvector-postgres).
> **Note**: This uses the official RuVector PostgreSQL extension, not pgvector. RuVector provides 77+ SQL functions with advanced AI capabilities.
@@ -10,13 +10,11 @@ A Docker-based testing environment for the **RuVector PostgreSQL extension** fro
|---------|-------------|
| **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 |
+| **Hyperbolic Embeddings** | PoincarΓ© ball model for hierarchical data |
+| **Graph Operations** | GNN message passing, Cypher queries |
+| **SPARQL Support** | RDF triple store functions |
+| **Agent Routing** | Pattern-based task routing |
+| **Self-Learning** | Continuous optimization |
| **SIMD Acceleration** | AVX-512/AVX2/NEON (~2x faster) |
## Quick Start
@@ -46,45 +44,11 @@ ruvector-postgres running (healthy) 0.0.0.0:5432->5432/tcp
### 3. Test the connection
```bash
-# Using psql
-docker exec -it ruvector-postgres psql -U claude -d claude_flow -c "SELECT ruvector.version();"
+# Check RuVector version
+docker exec ruvector-postgres psql -U claude -d claude_flow -c "SELECT ruvector_version();"
-# Or run our test script
-./scripts/test-connection.sh
-```
-
-### 4. Initialize RuVector CLI
-
-```bash
-# Run from project root
-npx claude-flow@alpha ruvector status \
- --host localhost \
- --port 5432 \
- --database claude_flow \
- --user claude
-```
-
-When prompted for password, enter: `claude-flow-test`
-
-## Directory Structure
-
-```
-docs/ruvector-postgres/
-β”œβ”€β”€ README.md # This file
-β”œβ”€β”€ docker-compose.yml # Docker services configuration
-β”œβ”€β”€ scripts/
-β”‚ β”œβ”€β”€ init-db.sql # Database initialization (runs on container start)
-β”‚ β”œβ”€β”€ test-connection.sh # Connection test script
-β”‚ β”œβ”€β”€ run-migrations.sh # Run RuVector migrations
-β”‚ └── cleanup.sh # Remove all data and reset
-β”œβ”€β”€ examples/
-β”‚ β”œβ”€β”€ basic-queries.sql # Basic vector operations
-β”‚ β”œβ”€β”€ 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
+# Expected output:
+# 2.0.0
```
## Connection Details
@@ -98,219 +62,274 @@ docs/ruvector-postgres/
| Password | `claude-flow-test` |
| Schema | `claude_flow` |
-## Available Services
+## RuVector SQL Syntax
-### RuVector PostgreSQL
+### Important: Extension Installation
-- **Container**: `ruvector-postgres`
-- **Image**: `ruvector/postgres:latest`
-- **Port**: 5432
+The RuVector extension requires an explicit version when installing:
-Pre-configured with:
-- RuVector extension enabled (77+ functions)
-- `claude_flow` schema created
-- 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
+```sql
+-- CORRECT: Use explicit version
+CREATE EXTENSION IF NOT EXISTS ruvector VERSION '0.1.0';
-### pgAdmin (Optional)
+-- INCORRECT: Will fail without version
+-- CREATE EXTENSION IF NOT EXISTS ruvector;
+```
-For visual database management:
+### Vector Type
-```bash
-# Start with pgAdmin
-docker-compose --profile gui up -d
+RuVector uses its own `ruvector` type, not `vector`:
+
+```sql
+-- CORRECT: RuVector type
+CREATE TABLE embeddings (
+ id UUID PRIMARY KEY,
+ embedding ruvector(384) -- 384 dimensions
+);
+
+-- INCORRECT: pgvector syntax
+-- embedding vector(384)
+-- embedding ruvector.vector(384)
```
-Access at: http://localhost:5050
-- Email: `[email protected]`
-- Password: `admin`
+### Distance Operators
-## Common Tasks
+| Operator | Description | Index Support |
+|----------|-------------|---------------|
+| `<=>` | Cosine distance | HNSW |
+| `<->` | L2 (Euclidean) distance | HNSW |
+| `<#>` | Negative inner product | HNSW |
-### Generate embeddings locally
+```sql
+-- Cosine similarity search
+SELECT * FROM embeddings
+ORDER BY embedding <=> '[0.1, 0.2, ...]'::ruvector(384)
+LIMIT 10;
-```bash
-docker exec -it ruvector-postgres psql -U claude -d claude_flow -c \
- "SELECT claude_flow.embed_text('Hello, world!', 'all-MiniLM-L6-v2');"
+-- Convert distance to similarity
+SELECT (1 - (a.embedding <=> b.embedding)) AS similarity
+FROM embeddings a, embeddings b;
```
-### Run similarity search
+### HNSW Index
-```bash
-docker exec -it ruvector-postgres psql -U claude -d claude_flow -c \
- "SELECT * FROM claude_flow.search_similar(
- claude_flow.embed_text('authentication security'),
- 5,
- 0.3
- );"
+```sql
+-- Create HNSW index for cosine distance
+CREATE INDEX idx_embeddings_hnsw
+ON embeddings
+USING hnsw (embedding ruvector_cosine_ops)
+WITH (m = 16, ef_construction = 100);
+
+-- For L2 distance
+-- USING hnsw (embedding ruvector_l2_ops)
```
-### Run multi-head attention
+### Hyperbolic Embeddings
+
+Hyperbolic functions use `real[]` arrays, not ruvector type:
+
+```sql
+-- PoincarΓ© distance
+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;
+
+-- Exponential map (Euclidean to PoincarΓ©)
+SELECT ruvector_exp_map(
+ ARRAY[0.0, 0.0, 0.0]::real[], -- origin
+ ARRAY[0.1, 0.2, 0.3]::real[], -- tangent vector
+ -1.0 -- curvature
+);
+
+-- MΓΆbius addition
+SELECT ruvector_mobius_add(
+ ARRAY[0.1, 0.0]::real[],
+ ARRAY[0.0, 0.1]::real[],
+ -1.0
+);
+```
-```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
- );"
+### Array-Based Distance Functions
+
+```sql
+-- Cosine similarity for arrays
+SELECT cosine_similarity_arr(
+ ARRAY[1.0, 0.0, 0.0]::real[],
+ ARRAY[0.7, 0.7, 0.0]::real[]
+);
+
+-- L2 distance for arrays
+SELECT l2_distance_arr(
+ ARRAY[1.0, 0.0, 0.0]::real[],
+ ARRAY[0.0, 1.0, 0.0]::real[]
+);
+```
+
+## Available Tables (Claude-Flow Schema)
+
+The init script creates these tables:
+
+| Table | Description |
+|-------|-------------|
+| `embeddings` | Content with vector embeddings |
+| `patterns` | Learned patterns (ReasoningBank) |
+| `agents` | Multi-agent memory coordination |
+| `trajectories` | SONA reinforcement learning |
+| `hyperbolic_embeddings` | Hierarchical data embeddings |
+| `graph_nodes` | GNN node data |
+| `graph_edges` | GNN edge relationships |
+
+## Custom Functions
+
+The init script creates these helper functions:
+
+```sql
+-- Semantic similarity search
+SELECT * FROM claude_flow.search_similar(
+ '[...]'::ruvector(384), -- query embedding
+ 10, -- limit
+ 0.5 -- min similarity
+);
+
+-- Pattern search with type filtering
+SELECT * FROM claude_flow.search_patterns(
+ '[...]'::ruvector(384),
+ 'security', -- pattern type
+ 10, -- limit
+ 0.5 -- min confidence
+);
+
+-- Find agents by expertise
+SELECT * FROM claude_flow.find_agents(
+ '[...]'::ruvector(384),
+ 'coder', -- agent type
+ 5 -- limit
+);
+
+-- Hyperbolic search
+SELECT * FROM claude_flow.hyperbolic_search(
+ '[...]'::ruvector(384),
+ 10, -- limit
+ -1.0 -- curvature
+);
+
+-- Cosine similarity helper
+SELECT claude_flow.cosine_similarity(a, b);
+
+-- L2 distance helper
+SELECT claude_flow.l2_distance(a, b);
+
+-- Get RuVector info
+SELECT * FROM claude_flow.ruvector_info();
```
-### Hyperbolic search (for hierarchical data)
+## Common Operations
+
+### Insert embedding
```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
- );"
+docker exec ruvector-postgres psql -U claude -d claude_flow -c "
+INSERT INTO claude_flow.embeddings (content, embedding, metadata)
+VALUES (
+ 'Example content',
+ '[0.1,0.2,...]'::ruvector(384),
+ '{\"category\": \"test\"}'::jsonb
+);
+"
```
-### Check HNSW indices
+### Similarity search
```bash
-docker exec -it ruvector-postgres psql -U claude -d claude_flow -c \
- "SELECT indexname, indexdef FROM pg_indexes WHERE schemaname = 'claude_flow';"
+docker exec ruvector-postgres psql -U claude -d claude_flow -c "
+SELECT id, content, (1 - (embedding <=> '[0.1,0.2,...]'::ruvector(384))) AS similarity
+FROM claude_flow.embeddings
+WHERE embedding IS NOT NULL
+ORDER BY embedding <=> '[0.1,0.2,...]'::ruvector(384)
+LIMIT 5;
+"
```
-### Run self-learning optimization
+### Check HNSW indices
```bash
-docker exec -it ruvector-postgres psql -U claude -d claude_flow -c \
- "SELECT claude_flow.optimize_indices();"
+docker exec ruvector-postgres psql -U claude -d claude_flow -c "
+SELECT indexname FROM pg_indexes
+WHERE schemaname = 'claude_flow' AND indexdef LIKE '%hnsw%';
+"
```
-### Reset everything
+### Check RuVector SIMD status
```bash
-./scripts/cleanup.sh
-docker-compose down -v
-docker-compose up -d
+docker exec ruvector-postgres psql -U claude -d claude_flow -c "
+SELECT ruvector_version(), ruvector_simd_info();
+"
```
-## Testing with Claude-Flow CLI
+## Migration from sql.js/JSON
-### Check status
+To migrate from Claude-Flow's sql.js/JSON storage to RuVector PostgreSQL:
+
+### 1. Export current memory
```bash
-npx claude-flow@alpha ruvector status \
- --host localhost \
- --database claude_flow \
- --user claude \
- --verbose
+# Export memory entries to JSON
+npx claude-flow@alpha memory list --format json > memory-export.json
```
-### Run migrations
+### 2. Generate SQL import
```bash
-npx claude-flow@alpha ruvector migrate \
- --host localhost \
- --database claude_flow \
- --user claude \
- --up
+# Create SQL from JSON (manual process currently)
+# For each entry, create an INSERT statement
+cat memory-export.json | jq -r '.[] | "INSERT INTO claude_flow.embeddings (content, metadata) VALUES (\047\(.value | tostring)\047, \047\(.metadata | tojson)\047::jsonb);"'
```
-### Run benchmarks
+### 3. Import to PostgreSQL
```bash
-npx claude-flow@alpha ruvector benchmark \
- --host localhost \
- --database claude_flow \
- --user claude \
- --iterations 100
+docker exec -i ruvector-postgres psql -U claude -d claude_flow < import.sql
```
-### Optimize indices
+### 4. Generate embeddings
-```bash
-npx claude-flow@alpha ruvector optimize \
- --host localhost \
- --database claude_flow \
- --user claude \
- --analyze
+Embeddings need to be generated externally (via Claude-Flow MCP) and updated:
+
+```sql
+-- After generating embedding via MCP
+UPDATE claude_flow.embeddings
+SET embedding = '[...]'::ruvector(384)
+WHERE id = 'uuid-here';
```
-## Environment Variables
+> **Note**: A dedicated migration tool (`npx claude-flow@alpha ruvector import`) is planned for future releases.
+
+## pgAdmin (Optional)
-You can use environment variables instead of CLI flags:
+For visual database management:
```bash
-export PGHOST=localhost
-export PGPORT=5432
-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
+# Start with pgAdmin
+docker-compose --profile gui up -d
```
-## 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 |
+Access at: http://localhost:5050
+- Email: `[email protected]`
+- Password: `admin`
-## Performance Benchmarks
+## Troubleshooting
-| 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 |
+### Extension creation fails
-## Troubleshooting
+If you see: `extension 'ruvector' has no installation script nor update path for version "2.0.0"`
+
+**Solution**: Use explicit version:
+```sql
+CREATE EXTENSION IF NOT EXISTS ruvector VERSION '0.1.0';
+```
### Container won't start
@@ -320,34 +339,47 @@ docker-compose logs postgres
# Check if port 5432 is in use
lsof -i :5432
+
+# Reset completely
+docker-compose down -v
+docker-compose up -d
```
-### RuVector extension missing
+### HNSW warnings
-```bash
-# Manually enable
-docker exec -it ruvector-postgres psql -U claude -d claude_flow -c \
- "CREATE EXTENSION IF NOT EXISTS ruvector;"
-```
+Warnings like `HNSW: Could not extract query vector` during COUNT queries are benign and can be ignored.
-### Permission denied errors
+### Type mismatch errors
-```bash
-# Reset permissions
-docker exec -it ruvector-postgres psql -U claude -d claude_flow -c \
- "GRANT ALL ON SCHEMA claude_flow TO claude;
- GRANT USAGE ON SCHEMA ruvector TO claude;"
-```
+Ensure you're using:
+- `ruvector(384)` for vector columns
+- `real[]` for hyperbolic function arguments
+- `::ruvector(384)` for casting string vectors
-### Reset to clean state
+## Performance Benchmarks
-```bash
-docker-compose down -v
-docker-compose up -d
+| Metric | Value |
+|--------|-------|
+| HNSW Search Latency | ~61Β΅s (k=10, 384-dim) |
+| Throughput | 16,400 QPS |
+| SIMD | AVX2 (8 floats/op) |
+
+## Directory Structure
+
+```
+docs/ruvector-postgres/
+β”œβ”€β”€ README.md # This file
+β”œβ”€β”€ docker-compose.yml # Docker services
+β”œβ”€β”€ scripts/
+β”‚ β”œβ”€β”€ init-db.sql # Database initialization
+β”‚ └── test-connection.sh # Connection test script
+β”œβ”€β”€ examples/
+β”‚ └── basic-queries.sql # Example queries
+└── tests/
+ └── benchmark.sh # Performance benchmarks
```
## 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)
+- [RuVector PostgreSQL Docker Hub](https://hub.docker.com/r/ruvnet/ruvector-postgres)
+- [Claude-Flow Documentation](https://github.com/ruvnet/claude-flow)