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

release: v3.5.3 β€” publish fixes, branding, cleanup

rUv4c651cd098fa
diff --git a/.claude/helpers/statusline.cjs b/.claude/helpers/statusline.cjs
index 1d74ed53a2..4030ae471b 100644
--- a/.claude/helpers/statusline.cjs
+++ b/.claude/helpers/statusline.cjs
@@ -1,6 +1,6 @@
#!/usr/bin/env node
/**
- * Claude Flow V3 Statusline Generator (Optimized)
+ * RuFlo V3 Statusline Generator (Optimized)
* Displays real-time V3 implementation progress and system status
*
* Usage: node statusline.cjs [--json] [--compact]
@@ -549,7 +549,7 @@ function generateStatusline() {
const parts = [];
// Branding
- parts.push(`${c.bold}${c.brightPurple}\u258A Claude Flow V3${c.reset}`);
+ parts.push(`${c.bold}${c.brightPurple}\u258A RuFlo V3${c.reset}`);
// User + swarm indicator
const dot = swarm.coordinationActive ? `${c.brightGreen}\u25CF${c.reset}` : `${c.brightCyan}\u25CF${c.reset}`;
@@ -616,7 +616,7 @@ function generateDashboard() {
const lines = [];
// Header
- let header = `${c.bold}${c.brightPurple}\u258A Claude Flow V3 ${c.reset}`;
+ let header = `${c.bold}${c.brightPurple}\u258A RuFlo V3 ${c.reset}`;
header += `${swarm.coordinationActive ? c.brightCyan : c.dim}\u25CF ${c.brightCyan}${git.name}${c.reset}`;
if (git.gitBranch) {
header += ` ${c.dim}\u2502${c.reset} ${c.brightBlue}\u23C7 ${git.gitBranch}${c.reset}`;
diff --git a/.claude/settings.json b/.claude/settings.json
index e131e51d69..14f6878f99 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -183,7 +183,7 @@
"pr": "\ud83e\udd16 Generated with [claude-flow](https://github.com/ruvnet/claude-flow)"
},
"claudeFlow": {
- "version": "3.0.0",
+ "version": "3.5.2",
"enabled": true,
"modelPreferences": {
"default": "claude-opus-4-6",
diff --git a/README.md b/README.md
index a6baa52cb3..c5444d7481 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,8 @@
-# 🌊 Ruflo v3: Enterprise AI Orchestration Platform
+# 🌊 RuFlo v3.5: Enterprise AI Orchestration Platform
<div align="center">
-![Ruflo Banner](ruflo/assets/ruFlo.png)
+![Ruflo Banner](ruflo/assets/ruflo-small.jpeg)
diff --git a/docs/ruvector-postgres/README.md b/docs/ruvector-postgres/README.md
deleted file mode 100644
index e772b44bbd..0000000000
--- a/docs/ruvector-postgres/README.md
+++ /dev/null
@@ -1,480 +0,0 @@
-# RuVector PostgreSQL Testing Environment
-
-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.
-
-## RuVector Features
-
-| Feature | Description |
-|---------|-------------|
-| **77+ SQL Functions** | Comprehensive vector operations in SQL |
-| **HNSW/IVFFlat Indexing** | ~61Β΅s search latency, 16,400 QPS |
-| **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
-
-### Option 1: Use CLI Setup Command (Recommended)
-
-```bash
-# Generate Docker files and SQL in any directory
-npx claude-flow ruvector setup --output ./my-ruvector
-
-# Start the container
-cd my-ruvector
-docker-compose up -d
-```
-
-### Option 2: Use Existing Files
-
-```bash
-# From this directory
-docker-compose up -d
-
-# Or from the project root
-docker-compose -f docs/ruvector-postgres/docker-compose.yml up -d
-```
-
-### 2. Verify the container is running
-
-```bash
-docker-compose ps
-```
-
-You should see:
-```
-NAME STATUS PORTS
-ruvector-postgres running (healthy) 0.0.0.0:5432->5432/tcp
-```
-
-### 3. Test the connection
-
-```bash
-# Check RuVector version
-docker exec ruvector-postgres psql -U claude -d claude_flow -c "SELECT ruvector_version();"
-
-# Expected output:
-# 2.0.0
-```
-
-## Connection Details
-
-| Setting | Value |
-|---------|-------|
-| Host | `localhost` |
-| Port | `5432` |
-| Database | `claude_flow` |
-| Username | `claude` |
-| Password | `claude-flow-test` |
-| Schema | `claude_flow` |
-
-## RuVector SQL Syntax
-
-### Important: Extension Installation
-
-The RuVector extension requires an explicit version when installing:
-
-```sql
--- CORRECT: Use explicit version
-CREATE EXTENSION IF NOT EXISTS ruvector VERSION '0.1.0';
-
--- INCORRECT: Will fail without version
--- CREATE EXTENSION IF NOT EXISTS ruvector;
-```
-
-### Vector Type
-
-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)
-```
-
-### Distance Operators
-
-| Operator | Description | Index Support |
-|----------|-------------|---------------|
-| `<=>` | Cosine distance | HNSW |
-| `<->` | L2 (Euclidean) distance | HNSW |
-| `<#>` | Negative inner product | HNSW |
-
-```sql
--- Cosine similarity search
-SELECT * FROM embeddings
-ORDER BY embedding <=> '[0.1, 0.2, ...]'::ruvector(384)
-LIMIT 10;
-
--- Convert distance to similarity
-SELECT (1 - (a.embedding <=> b.embedding)) AS similarity
-FROM embeddings a, embeddings b;
-```
-
-### HNSW Index
-
-```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)
-```
-
-### 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
-);
-```
-
-### 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 |
-|-------|-------------|
-| `memory_entries` | Main memory storage (key-value with embeddings) |
-| `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();
-```
-
-## Common Operations
-
-### Insert embedding
-
-```bash
-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
-);
-"
-```
-
-### Similarity search
-
-```bash
-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;
-"
-```
-
-### Check HNSW indices
-
-```bash
-docker exec ruvector-postgres psql -U claude -d claude_flow -c "
-SELECT indexname FROM pg_indexes
-WHERE schemaname = 'claude_flow' AND indexdef LIKE '%hnsw%';
-"
-```
-
-### Check RuVector SIMD status
-
-```bash
-docker exec ruvector-postgres psql -U claude -d claude_flow -c "
-SELECT ruvector_version(), ruvector_simd_info();
-"
-```
-
-## Migration from sql.js/JSON
-
-To migrate from Claude-Flow's sql.js/JSON storage to RuVector PostgreSQL:
-
-### Option 1: Use CLI Import Tool (Recommended)
-
-```bash
-# Export current memory to JSON
-npx claude-flow memory list --format json > memory-export.json
-
-# Import directly to PostgreSQL
-npx claude-flow ruvector import --input memory-export.json
-
-# Or generate SQL file first (dry-run)
-npx claude-flow ruvector import --input memory-export.json --output import.sql
-docker exec -i ruvector-postgres psql -U claude -d claude_flow < import.sql
-```
-
-The import tool:
-- Supports JSON arrays or objects
-- Handles namespaces and metadata
-- Uses upsert (ON CONFLICT) for safe re-imports
-- Shows import statistics
-
-### Option 2: Manual Migration
-
-```bash
-# Export memory entries to JSON
-npx claude-flow memory list --format json > memory-export.json
-
-# Create SQL from JSON using jq
-cat memory-export.json | jq -r '.[] | "INSERT INTO claude_flow.memory_entries (key, value, namespace, metadata) VALUES (\047\(.key)\047, \047\(.value | tostring)\047, \047\(.namespace // "default")\047, \047\(.metadata // {} | tojson)\047::jsonb);"' > import.sql
-
-# Import to PostgreSQL
-docker exec -i ruvector-postgres psql -U claude -d claude_flow < import.sql
-```
-
-### Generate Embeddings
-
-Embeddings can be generated via Claude-Flow MCP and updated:
-
-```sql
--- After generating embedding via MCP
-UPDATE claude_flow.memory_entries
-SET embedding = '[...]'::ruvector(384)
-WHERE key = 'my-key' AND namespace = 'my-namespace';
-```
-
-## pgAdmin (Optional)
-
-For visual database management:
-
-```bash
-# Start with pgAdmin
-docker-compose --profile gui up -d
-```
-
-Access at: http://localhost:5050
-- Email: `[email protected]`
-- Password: `admin`
-
-## Troubleshooting
-
-### Extension creation fails
-
-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
-
-```bash
-# Check logs
-docker-compose logs postgres
-
-# Check if port 5432 is in use
-lsof -i :5432
-
-# Reset completely
-docker-compose down -v
-docker-compose up -d
-```
-
-### HNSW warnings
-
-Warnings like `HNSW: Could not extract query vector` during COUNT queries are benign and can be ignored.
-
-### Type mismatch errors
-
-Ensure you're using:
-- `ruvector(384)` for vector columns
-- `real[]` for hyperbolic function arguments
-- `::ruvector(384)` for casting string vectors
-
-## 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
-```
-
-## Performance Benchmarks
-
-| 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 PostgreSQL Docker Hub](https://hub.docker.com/r/ruvnet/ruvector-postgres)
-- [Claude-Flow Documentation](https://github.com/ruvnet/claude-flow)
diff --git a/docs/ruvector-postgres/agents/architect.yaml b/docs/ruvector-postgres/agents/architect.yaml
deleted file mode 100644
index 5d787d0b38..0000000000
--- a/docs/ruvector-postgres/agents/architect.yaml
+++ /dev/null
@@ -1,11 +0,0 @@
-# architect agent configuration
-type: architect
-version: "3.0.0"
-capabilities:
- - system-design
- - api-design
- - documentation
-optimizations:
- - context-caching
- - memory-persistence
-createdAt: "2026-01-17T20:49:42.572Z"
diff --git a/docs/ruvector-postgres/agents/coder.yaml b/docs/ruvector-postgres/agents/coder.yaml
deleted file mode 100644
index 9cfa53cde6..0000000000
--- a/docs/ruvector-postgres/agents/coder.yaml
+++ /dev/null
@@ -1,11 +0,0 @@
-# coder agent configuration
-type: coder
-version: "3.0.0"
-capabilities:
- - code-generation
- - refactoring
- - debugging
-optimizations:
- - flash-attention
- - token-reduction
-createdAt: "2026-01-17T20:49:42.572Z"
diff --git a/docs/ruvector-postgres/agents/reviewer.yaml b/docs/ruvector-postgres/agents/reviewer.yaml
deleted file mode 100644
index ef02b45e49..0000000000
--- a/docs/ruvector-postgres/agents/reviewer.yaml
+++ /dev/null
@@ -1,10 +0,0 @@
-# reviewer agent configuration
-type: reviewer
-version: "3.0.0"
-capabilities:
- - code-review
- - quality-analysis
- - best-practices
-optimizations:
- - incremental-analysis
-createdAt: "2026-01-17T20:49:42.572Z"
diff --git a/docs/ruvector-postgres/agents/security-architect.yaml b/docs/ruvector-postgres/agents/security-architect.yaml
deleted file mode 100644
index 483b232fcf..0000000000
--- a/docs/ruvector-postgres/agents/security-architect.yaml
+++ /dev/null
@@ -1,10 +0,0 @@
-# security-architect agent configuration
-type: security-architect
-version: "3.0.0"
-capabilities:
- - threat-modeling
- - vulnerability-analysis
- - security-review
-optimizations:
- - pattern-matching
-createdAt: "2026-01-17T20:49:42.572Z"
diff --git a/docs/ruvector-postgres/agents/tester.yaml b/docs/ruvector-postgres/agents/tester.yaml
deleted file mode 100644
index 8b4e988047..0000000000
--- a/docs/ruvector-postgres/agents/tester.yaml
+++ /dev/null
@@ -1,10 +0,0 @@
-# tester agent configuration
-type: tester
-version: "3.0.0"
-capabilities:
- - unit-testing
- - integration-testing
- - coverage
-optimizations:
- - parallel-execution
-createdAt: "2026-01-17T20:49:42.572Z"
diff --git a/docs/ruvector-postgres/docker-compose.yml b/docs/ruvector-postgres/docker-compose.yml
deleted file mode 100644
index 38a0ca3656..0000000000
--- a/docs/ruvector-postgres/docker-compose.yml
+++ /dev/null
@@ -1,54 +0,0 @@
-# RuVector PostgreSQL Testing Environment
-# Official RuVector extension from ruvnet/ruvector-postgres
-#
-# Features:
-# - 230+ SQL functions for vector operations
-# - HNSW/IVFFlat indexing with SIMD acceleration
-# - Flash Attention, GNN operations
-# - Hybrid search (dense + sparse)
-# - Multi-tenancy support
-# - Self-healing capabilities
-#
-# Performance: ~61Β΅s latency, 16,400 QPS with HNSW
-
-services:
- postgres:
- image: ruvnet/ruvector-postgres:latest
- container_name: ruvector-postgres
- environment:
- POSTGRES_USER: claude
- POSTGRES_PASSWORD: claude-flow-test
- POSTGRES_DB: claude_flow
- ports:
- - "5432:5432"
- volumes:
- - postgres_data:/var/lib/postgresql/data
- - ./scripts/init-db.sql:/docker-entrypoint-initdb.d/01-init.sql
- healthcheck:
- test: ["CMD-SHELL", "pg_isready -U claude -d claude_flow"]
- interval: 5s
- timeout: 5s
- retries: 10
- command: >
- postgres
- -c work_mem=256MB
- -c maintenance_work_mem=512MB
-
- # Optional: pgAdmin for visual database management
- pgadmin:
- image: dpage/pgadmin4:latest
- container_name: ruvector-pgadmin
- environment:
- PGADMIN_DEFAULT_EMAIL: [email protected]
- PGADMIN_DEFAULT_PASSWORD: admin
- PGADMIN_CONFIG_SERVER_MODE: 'False'
- ports:
- - "5050:80"
- depends_on:
- postgres:
- condition: service_healthy
- profiles:
- - gui
-
-volumes:
- postgres_data:
diff --git a/docs/ruvector-postgres/examples/attention-ops.sql b/docs/ruvector-postgres/examples/attention-ops.sql
deleted file mode 100644
index 28219d1291..0000000000
--- a/docs/ruvector-postgres/examples/attention-ops.sql
+++ /dev/null
@@ -1,499 +0,0 @@
--- RuVector PostgreSQL Attention Operations
--- Optimized for Claude-Flow V3 Neural Features
---
--- Implements attention mechanisms in SQL for:
--- - Self-attention (query = key = value)
--- - Multi-head attention
--- - Cross-attention
--- - Flash attention patterns
-
--- ============================================
--- 1. ATTENTION SCORE COMPUTATION
--- ============================================
-
--- Basic attention score: softmax(Q * K^T / sqrt(d_k)) * V
--- Using cosine similarity as a proxy for dot product attention
-
-CREATE OR REPLACE FUNCTION claude_flow.attention_scores(
- query_embedding vector(384),
- limit_count INT DEFAULT 10,
- temperature FLOAT DEFAULT 1.0
-)
-RETURNS TABLE (
- id UUID,
- content TEXT,
- raw_score FLOAT,
- attention_weight FLOAT,
- metadata JSONB
-) AS $$
-DECLARE
- softmax_sum FLOAT;
-BEGIN
- -- Calculate softmax denominator
- SELECT SUM(EXP((1 - (embedding <=> query_embedding)) / temperature))
- INTO softmax_sum
- FROM claude_flow.embeddings
- WHERE embedding IS NOT NULL;
-
- RETURN QUERY
- SELECT
- e.id,
- e.content,
- (1 - (e.embedding <=> query_embedding))::FLOAT AS r_score,
- (EXP((1 - (e.embedding <=> query_embedding)) / temperature) / NULLIF(softmax_sum, 0))::FLOAT AS a_weight,
- e.metadata
- FROM claude_flow.embeddings e
- WHERE e.embedding IS NOT NULL
- ORDER BY a_weight DESC
- LIMIT limit_count;
-END;
-$$ LANGUAGE plpgsql STABLE;
-
-
--- ============================================
--- 2. SELF-ATTENTION LAYER
--- ============================================
-
--- Self-attention: each embedding attends to all others
-CREATE OR REPLACE FUNCTION claude_flow.self_attention(
- source_ids UUID[],
- head_count INT DEFAULT 4,
- temperature FLOAT DEFAULT 1.0
-)
-RETURNS TABLE (
- source_id UUID,
- attended_id UUID,
- head_idx INT,
- attention_score FLOAT,
- source_content TEXT,
- attended_content TEXT
-) AS $$
-BEGIN
- RETURN QUERY
- WITH source_embeddings AS (
- SELECT id, content, embedding
- FROM claude_flow.embeddings
- WHERE id = ANY(source_ids)
- AND embedding IS NOT NULL
- ),
- all_pairs AS (
- SELECT
- s.id AS s_id,
- s.content AS s_content,
- s.embedding AS s_emb,
- t.id AS t_id,
- t.content AS t_content,
- t.embedding AS t_emb,
- h.head_idx AS h_idx
- FROM source_embeddings s
- CROSS JOIN claude_flow.embeddings t
- CROSS JOIN generate_series(1, head_count) AS h(head_idx)
- WHERE t.embedding IS NOT NULL
- ),
- raw_scores AS (
- SELECT
- ap.s_id,
- ap.s_content,
- ap.t_id,
- ap.t_content,
- ap.h_idx,
- (1 - (ap.s_emb <=> ap.t_emb))::FLOAT AS score
- FROM all_pairs ap
- ),
- softmax_scores AS (
- SELECT
- rs.s_id,
- rs.s_content,
- rs.t_id,
- rs.t_content,
- rs.h_idx,
- rs.score,
- EXP(rs.score / temperature) /
- SUM(EXP(rs.score / temperature)) OVER (PARTITION BY rs.s_id, rs.h_idx) AS attn_score
- FROM raw_scores rs
- )
- SELECT
- ss.s_id,
- ss.t_id,
- ss.h_idx,
- ss.attn_score::FLOAT,
- ss.s_content,
- ss.t_content
- FROM softmax_scores ss
- WHERE ss.attn_score > 0.01 -- Filter low attention
- ORDER BY ss.s_id, ss.h_idx, ss.attn_score DESC;
-END;
-$$ LANGUAGE plpgsql STABLE;
-
-
--- ============================================
--- 3. CROSS-ATTENTION
--- ============================================
-
--- Cross-attention between two sets of embeddings
-CREATE OR REPLACE FUNCTION claude_flow.cross_attention(
- query_ids UUID[],
- key_value_filter JSONB DEFAULT NULL,
- temperature FLOAT DEFAULT 1.0
-)
-RETURNS TABLE (
- query_id UUID,
- key_id UUID,
- attention_weight FLOAT,
- query_content TEXT,
- key_content TEXT,
- key_metadata JSONB
-) AS $$
-BEGIN
- RETURN QUERY
- WITH queries AS (
- SELECT id, content, embedding
- FROM claude_flow.embeddings
- WHERE id = ANY(query_ids)
- AND embedding IS NOT NULL
- ),
- keys AS (
- SELECT id, content, embedding, metadata
- FROM claude_flow.embeddings
- WHERE embedding IS NOT NULL
- AND (key_value_filter IS NULL OR metadata @> key_value_filter)
- AND id != ALL(query_ids)
- ),
- raw_attention AS (
- SELECT
- q.id AS q_id,
- q.content AS q_content,
- k.id AS k_id,
- k.content AS k_content,
- k.metadata AS k_meta,
- (1 - (q.embedding <=> k.embedding))::FLOAT AS score
- FROM queries q
- CROSS JOIN keys k
- ),
- softmax_attention AS (
- SELECT
- ra.*,
- EXP(ra.score / temperature) /
- SUM(EXP(ra.score / temperature)) OVER (PARTITION BY ra.q_id) AS attn_weight
- FROM raw_attention ra
- )
- SELECT
- sa.q_id,
- sa.k_id,
- sa.attn_weight::FLOAT,
- sa.q_content,
- sa.k_content,
- sa.k_meta
- FROM softmax_attention sa
- WHERE sa.attn_weight > 0.01
- ORDER BY sa.q_id, sa.attn_weight DESC;
-END;
-$$ LANGUAGE plpgsql STABLE;
-
-
--- ============================================
--- 4. MULTI-HEAD ATTENTION AGGREGATION
--- ============================================
-
--- Aggregate multi-head attention outputs
-CREATE OR REPLACE FUNCTION claude_flow.multihead_attention_aggregate(
- query_embedding vector(384),
- num_heads INT DEFAULT 8,
- head_dim INT DEFAULT 48, -- 384 / 8
- limit_count INT DEFAULT 10
-)
-RETURNS TABLE (
- id UUID,
- content TEXT,
- aggregated_attention FLOAT,
- head_attentions FLOAT[],
- metadata JSONB
-) AS $$
-BEGIN
- RETURN QUERY
- WITH per_head_attention AS (
- SELECT
- e.id,
- e.content,
- e.metadata,
- h.head_idx,
- -- Simulate head projection by using different parts of the embedding
- (1 - (
- subvector(e.embedding, (h.head_idx - 1) * head_dim + 1, head_dim) <=>
- subvector(query_embedding, (h.head_idx - 1) * head_dim + 1, head_dim)
- ))::FLOAT AS head_score
- FROM claude_flow.embeddings e
- CROSS JOIN generate_series(1, num_heads) AS h(head_idx)
- WHERE e.embedding IS NOT NULL
- ),
- aggregated AS (
- SELECT
- pha.id,
- pha.content,
- pha.metadata,
- AVG(pha.head_score)::FLOAT AS avg_attention,
- array_agg(pha.head_score ORDER BY pha.head_idx) AS head_scores
- FROM per_head_attention pha
- GROUP BY pha.id, pha.content, pha.metadata
- )
- SELECT
- a.id,
- a.content,
- a.avg_attention,
- a.head_scores,
- a.metadata
- FROM aggregated a
- ORDER BY a.avg_attention DESC
- LIMIT limit_count;
-END;
-$$ LANGUAGE plpgsql STABLE;
-
-
--- ============================================
--- 5. FLASH ATTENTION PATTERN (Block-wise)
--- ============================================
-
--- Simulates Flash Attention by processing in blocks
--- Reduces memory usage for large-scale attention
-
-CREATE OR REPLACE FUNCTION claude_flow.flash_attention_search(
- query_embedding vector(384),
- block_size INT DEFAULT 64,
- limit_count INT DEFAULT 10
-)
-RETURNS TABLE (
- id UUID,
- content TEXT,
- attention_score FLOAT,
- block_id INT,
- metadata JSONB
-) AS $$
-BEGIN
- RETURN QUERY
- WITH numbered_embeddings AS (
- SELECT
- e.id,
- e.content,
- e.embedding,
- e.metadata,
- ROW_NUMBER() OVER (ORDER BY e.created_at) AS row_num
- FROM claude_flow.embeddings e
- WHERE e.embedding IS NOT NULL
- ),
- blocked AS (
- SELECT
- ne.*,
- ((ne.row_num - 1) / block_size + 1)::INT AS blk_id
- FROM numbered_embeddings ne
- ),
- block_max AS (
- -- Find max score per block (for numerical stability)
- SELECT
- b.blk_id,
- MAX(1 - (b.embedding <=> query_embedding))::FLOAT AS max_score
- FROM blocked b
- GROUP BY b.blk_id
- ),
- block_attention AS (
- SELECT
- b.id,
- b.content,
- b.embedding,
- b.metadata,
- b.blk_id,
- (1 - (b.embedding <=> query_embedding))::FLOAT AS raw_score,
- bm.max_score,
- EXP((1 - (b.embedding <=> query_embedding)) - bm.max_score) AS stable_exp
- FROM blocked b
- JOIN block_max bm ON b.blk_id = bm.blk_id
- ),
- block_sums AS (
- SELECT
- blk_id,
- SUM(stable_exp) AS sum_exp
- FROM block_attention
- GROUP BY blk_id
- ),
- final_attention AS (
- SELECT
- ba.id,
- ba.content,
- ba.metadata,
- ba.blk_id,
- (ba.stable_exp / NULLIF(bs.sum_exp, 0))::FLOAT AS attn_score
- FROM block_attention ba
- JOIN block_sums bs ON ba.blk_id = bs.blk_id
- )
- SELECT
- fa.id,
- fa.content,
- fa.attn_score,
- fa.blk_id,
- fa.metadata
- FROM final_attention fa
- ORDER BY fa.attn_score DESC
- LIMIT limit_count;
-END;
-$$ LANGUAGE plpgsql STABLE;
-
-
--- ============================================
--- 6. ATTENTION-WEIGHTED RETRIEVAL
--- ============================================
-
--- Use attention to weight context retrieval for RAG
-CREATE OR REPLACE FUNCTION claude_flow.attention_weighted_retrieve(
- query_embedding vector(384),
- context_window INT DEFAULT 5,
- attention_threshold FLOAT DEFAULT 0.1
-)
-RETURNS TABLE (
- context_text TEXT,
- total_attention FLOAT,
- contributing_ids UUID[]
-) AS $$
-BEGIN
- RETURN QUERY
- WITH attention_scores AS (
- SELECT
- e.id,
- e.content,
- (1 - (e.embedding <=> query_embedding))::FLOAT AS score
- FROM claude_flow.embeddings e
- WHERE e.embedding IS NOT NULL
- ),
- softmax_attention AS (
- SELECT
- a.id,
- a.content,
- a.score,
- (a.score / NULLIF(SUM(a.score) OVER (), 0))::FLOAT AS attention_weight
- FROM attention_scores a
- ),
- filtered AS (
- SELECT *
- FROM softmax_attention sa
- WHERE sa.attention_weight >= attention_threshold
- ORDER BY sa.attention_weight DESC
- LIMIT context_window
- )
- SELECT
- string_agg(f.content, E'\n\n' ORDER BY f.attention_weight DESC) AS ctx_text,
- SUM(f.attention_weight)::FLOAT AS total_attn,
- array_agg(f.id ORDER BY f.attention_weight DESC) AS contrib_ids
- FROM filtered f;
-END;
-$$ LANGUAGE plpgsql STABLE;
-
-
--- ============================================
--- 7. CAUSAL ATTENTION MASK
--- ============================================
-
--- Attention with causal masking (only attend to earlier items)
-CREATE OR REPLACE FUNCTION claude_flow.causal_attention(
- source_ids UUID[],
- temperature FLOAT DEFAULT 1.0
-)
-RETURNS TABLE (
- source_id UUID,
- attended_id UUID,
- attention_score FLOAT,
- source_created TIMESTAMPTZ,
- attended_created TIMESTAMPTZ
-) AS $$
-BEGIN
- RETURN QUERY
- WITH sources AS (
- SELECT id, content, embedding, created_at
- FROM claude_flow.embeddings
- WHERE id = ANY(source_ids)
- AND embedding IS NOT NULL
- ),
- causal_pairs AS (
- SELECT
- s.id AS s_id,
- s.embedding AS s_emb,
- s.created_at AS s_created,
- t.id AS t_id,
- t.embedding AS t_emb,
- t.created_at AS t_created,
- (1 - (s.embedding <=> t.embedding))::FLOAT AS score
- FROM sources s
- JOIN claude_flow.embeddings t ON t.created_at <= s.created_at -- Causal mask
- WHERE t.embedding IS NOT NULL
- ),
- softmax_scores AS (
- SELECT
- cp.*,
- EXP(cp.score / temperature) /
- SUM(EXP(cp.score / temperature)) OVER (PARTITION BY cp.s_id) AS attn
- FROM causal_pairs cp
- )
- SELECT
- ss.s_id,
- ss.t_id,
- ss.attn::FLOAT,
- ss.s_created,
- ss.t_created
- FROM softmax_scores ss
- WHERE ss.attn > 0.01
- ORDER BY ss.s_id, ss.attn DESC;
-END;
-$$ LANGUAGE plpgsql STABLE;
-
-
--- ============================================
--- 8. ATTENTION VISUALIZATION HELPER
--- ============================================
-
--- Generate attention matrix for visualization
-CREATE OR REPLACE FUNCTION claude_flow.attention_matrix(
- embedding_ids UUID[],
- temperature FLOAT DEFAULT 1.0
-)
-RETURNS TABLE (
- row_id UUID,
- col_id UUID,
- row_idx INT,
- col_idx INT,
- attention_value FLOAT
-) AS $$
-BEGIN
- RETURN QUERY
- WITH indexed AS (
- SELECT
- e.id,
- e.embedding,
- ROW_NUMBER() OVER (ORDER BY array_position(embedding_ids, e.id)) AS idx
- FROM claude_flow.embeddings e
- WHERE e.id = ANY(embedding_ids)
- AND e.embedding IS NOT NULL
- ),
- pairs AS (
- SELECT
- i1.id AS r_id,
- i1.idx AS r_idx,
- i2.id AS c_id,
- i2.idx AS c_idx,
- (1 - (i1.embedding <=> i2.embedding))::FLOAT AS score
- FROM indexed i1
- CROSS JOIN indexed i2
- ),
- softmax AS (
- SELECT
- p.*,
- EXP(p.score / temperature) /
- SUM(EXP(p.score / temperature)) OVER (PARTITION BY p.r_id) AS attn
- FROM pairs p
- )
- SELECT
- s.r_id,
- s.c_id,
- s.r_idx::INT,
- s.c_idx::INT,
- s.attn::FLOAT
- FROM softmax s
- ORDER BY s.r_idx, s.c_idx;
-END;
-$$ LANGUAGE plpgsql STABLE;
diff --git a/docs/ruvector-postgres/examples/basic-queries.sql b/docs/ruvector-postgres/examples/basic-queries.sql
deleted file mode 100644
index 03fcbb7168..0000000000
--- a/docs/ruvector-postgres/examples/basic-queries.sql
+++ /dev/null
@@ -1,295 +0,0 @@
--- ============================================
--- RUVECTOR POSTGRESQL BASIC QUERIES
--- ============================================
---
--- Basic vector operations using RuVector PostgreSQL extension
--- from ruvnet/ruvector (77+ SQL functions)
---
--- Features demonstrated:
--- - Vector storage and retrieval
--- - HNSW indexed similarity search
--- - Local embedding generation (fastembed)
--- - Metadata filtering
--- - SIMD-accelerated distance calculations
-
--- Set search path
-SET search_path TO claude_flow, ruvector, public;
-
--- ============================================
--- 1. INSERT EMBEDDINGS
--- ============================================
-
--- Insert with local embedding generation (no API calls)
-INSERT INTO claude_flow.embeddings (content, embedding, metadata)
-VALUES (
- 'Introduction to machine learning algorithms',
- ruvector.fastembed('Introduction to machine learning algorithms', 'all-MiniLM-L6-v2'),
- '{"category": "tutorial", "language": "english", "level": "beginner"}'::jsonb
-);
-
--- Insert multiple embeddings
-INSERT INTO claude_flow.embeddings (content, embedding, metadata)
-SELECT
- title,
- ruvector.fastembed(title, 'all-MiniLM-L6-v2'),
- jsonb_build_object('category', category, 'agent', agent)
-FROM (VALUES
- ('Building REST APIs with Node.js', 'backend', 'coder'),
- ('Deep learning fundamentals', 'ai', 'researcher'),
- ('PostgreSQL performance optimization', 'database', 'perf-engineer'),
- ('Secure authentication patterns', 'security', 'security-architect'),
- ('Test-driven development practices', 'testing', 'tester')
-) AS data(title, category, agent);
-
-
--- ============================================
--- 2. SIMILARITY SEARCH (HNSW Indexed)
--- ============================================
-
--- Basic similarity search (~61Β΅s latency with HNSW)
-SELECT
- id,
- content,
- ruvector.cosine_similarity(
- embedding,
- ruvector.fastembed('machine learning', 'all-MiniLM-L6-v2')
- ) AS similarity
-FROM claude_flow.embeddings
-WHERE embedding IS NOT NULL
-ORDER BY embedding <-> ruvector.fastembed('machine learning', 'all-MiniLM-L6-v2')
-LIMIT 5;
-
--- Search with minimum similarity threshold
-SELECT
- id,
- content,
- ruvector.cosine_similarity(embedding, query_emb) AS similarity,
- metadata
-FROM claude_flow.embeddings,
- LATERAL (SELECT ruvector.fastembed('API development', 'all-MiniLM-L6-v2') AS query_emb) q
-WHERE embedding IS NOT NULL
- AND ruvector.cosine_similarity(embedding, query_emb) > 0.5
-ORDER BY embedding <-> query_emb
-LIMIT 10;
-
-
--- ============================================
--- 3. DISTANCE CALCULATIONS
--- ============================================
-
--- Cosine similarity (most common for text)
-SELECT
- a.content AS content_a,
- b.content AS content_b,
- ruvector.cosine_similarity(a.embedding, b.embedding) AS cosine_sim
-FROM claude_flow.embeddings a
-CROSS JOIN claude_flow.embeddings b
-WHERE a.id < b.id
- AND a.embedding IS NOT NULL
- AND b.embedding IS NOT NULL
-LIMIT 10;
-
--- Euclidean distance
-SELECT
- content,
- ruvector.euclidean_distance(
- embedding,
- ruvector.fastembed('database optimization', 'all-MiniLM-L6-v2')
- ) AS l2_distance
-FROM claude_flow.embeddings
-WHERE embedding IS NOT NULL
-ORDER BY l2_distance
-LIMIT 5;
-
--- Dot product (for normalized vectors)
-SELECT
- content,
- ruvector.dot_product(embedding, query_emb) AS dot_product
-FROM claude_flow.embeddings,
- LATERAL (SELECT ruvector.fastembed('security', 'all-MiniLM-L6-v2') AS query_emb) q
-WHERE embedding IS NOT NULL
-ORDER BY dot_product DESC
-LIMIT 5;
-
-
--- ============================================
--- 4. METADATA FILTERING + VECTOR SEARCH
--- ============================================
-
--- Filter by category, then search
-SELECT
- content,
- metadata->>'category' AS category,
- ruvector.cosine_similarity(embedding, query_emb) AS similarity
-FROM claude_flow.embeddings,
- LATERAL (SELECT ruvector.fastembed('best practices', 'all-MiniLM-L6-v2') AS query_emb) q
-WHERE embedding IS NOT NULL
- AND metadata->>'category' = 'testing'
-ORDER BY embedding <-> query_emb
-LIMIT 5;
-
--- Filter by multiple metadata fields
-SELECT
- content,
- metadata,
- ruvector.cosine_similarity(embedding, query_emb) AS similarity
-FROM claude_flow.embeddings,
- LATERAL (SELECT ruvector.fastembed('development', 'all-MiniLM-L6-v2') AS query_emb) q
-WHERE embedding IS NOT NULL
- AND metadata @> '{"agent": "coder"}'::jsonb
-ORDER BY embedding <-> query_emb
-LIMIT 5;
-
-
--- ============================================
--- 5. PATTERN OPERATIONS
--- ============================================
-
--- Store a learned pattern
-INSERT INTO claude_flow.patterns (name, description, embedding, pattern_type, confidence)
-VALUES (
- 'api-error-handling',
- 'Standard error handling pattern for REST APIs',
- ruvector.fastembed('REST API error handling with proper status codes and error messages', 'all-MiniLM-L6-v2'),
- 'code-pattern',
- 0.85
-);
-
--- Search patterns by type and similarity
-SELECT
- name,
- description,
- confidence,
- ruvector.cosine_similarity(embedding, query_emb) AS match_score
-FROM claude_flow.patterns,
- LATERAL (SELECT ruvector.fastembed('handling errors in APIs', 'all-MiniLM-L6-v2') AS query_emb) q
-WHERE embedding IS NOT NULL
- AND pattern_type = 'code-pattern'
- AND confidence >= 0.7
-ORDER BY embedding <-> query_emb
-LIMIT 5;
-
--- Update pattern confidence based on success/failure
-UPDATE claude_flow.patterns
-SET
- confidence = LEAST(1.0, confidence + 0.05),
- success_count = success_count + 1
-WHERE name = 'api-error-handling';
-
-
--- ============================================
--- 6. AGENT MEMORY OPERATIONS
--- ============================================
-
--- Register/update agent with memory embedding
-INSERT INTO claude_flow.agents (agent_id, agent_type, state, memory_embedding)
-VALUES (
- 'coder-v3-001',
- 'coder',
- '{"specializations": ["typescript", "node"], "tasks_completed": 0}'::jsonb,
- ruvector.fastembed('TypeScript Node.js backend development', 'all-MiniLM-L6-v2')
-)
-ON CONFLICT (agent_id) DO UPDATE SET
- state = EXCLUDED.state,
- memory_embedding = EXCLUDED.memory_embedding,
- last_active = NOW();
-
--- Find agents with similar expertise
-SELECT
- agent_id,
- agent_type,
- state->>'specializations' AS specializations,
- ruvector.cosine_similarity(memory_embedding, query_emb) AS expertise_match
-FROM claude_flow.agents,
- LATERAL (SELECT ruvector.fastembed('React frontend development', 'all-MiniLM-L6-v2') AS query_emb) q
-WHERE memory_embedding IS NOT NULL
-ORDER BY memory_embedding <-> query_emb
-LIMIT 3;
-
-
--- ============================================
--- 7. BATCH EMBEDDING GENERATION
--- ============================================
-
--- Generate embeddings for multiple texts at once
-SELECT
- text_content,
- ruvector.fastembed(text_content, 'all-MiniLM-L6-v2') AS embedding
-FROM unnest(ARRAY[
- 'First document about databases',
- 'Second document about APIs',
- 'Third document about testing'
-]) AS text_content;
-
--- Update existing records with embeddings
-UPDATE claude_flow.embeddings
-SET embedding = ruvector.fastembed(content, 'all-MiniLM-L6-v2')
-WHERE embedding IS NULL;
-
-
--- ============================================
--- 8. INDEX MANAGEMENT
--- ============================================
-
--- Check HNSW index status
-SELECT
- indexname,
- indexdef
-FROM pg_indexes
-WHERE schemaname = 'claude_flow'
- AND indexdef LIKE '%ruvector_hnsw%';
-
--- Check index usage statistics
-SELECT
- schemaname,
- relname,
- indexrelname,
- idx_scan,
- idx_tup_read
-FROM pg_stat_user_indexes
-WHERE schemaname = 'claude_flow';
-
--- Trigger self-learning optimization
-SELECT ruvector.learn_optimize('claude_flow.embeddings', 'embedding');
-
-
--- ============================================
--- 9. AGGREGATIONS
--- ============================================
-
--- Count by category with average similarity to a topic
-SELECT
- metadata->>'category' AS category,
- COUNT(*) AS count,
- AVG(ruvector.cosine_similarity(embedding, query_emb)) AS avg_relevance
-FROM claude_flow.embeddings,
- LATERAL (SELECT ruvector.fastembed('software development', 'all-MiniLM-L6-v2') AS query_emb) q
-WHERE embedding IS NOT NULL
- AND metadata->>'category' IS NOT NULL
-GROUP BY metadata->>'category'
-ORDER BY avg_relevance DESC;
-
--- Find centroid of embeddings by category
-SELECT
- metadata->>'category' AS category,
- COUNT(*) AS count
-FROM claude_flow.embeddings
-WHERE metadata->>'category' IS NOT NULL
-GROUP BY metadata->>'category';
-
-
--- ============================================
--- 10. MAINTENANCE
--- ============================================
-
--- Delete old embeddings
-DELETE FROM claude_flow.embeddings
-WHERE created_at < NOW() - INTERVAL '30 days';
-
--- Vacuum and analyze for optimal performance
-VACUUM ANALYZE claude_flow.embeddings;
-VACUUM ANALYZE claude_flow.patterns;
-VACUUM ANALYZE claude_flow.agents;
-
--- Reindex HNSW (if needed after many updates)
-REINDEX INDEX CONCURRENTLY claude_flow.idx_embeddings_hnsw;
diff --git a/docs/ruvector-postgres/examples/similarity-search.sql b/docs/ruvector-postgres/examples/similarity-search.sql
deleted file mode 100644
index 8c2c827a99..0000000000
--- a/docs/ruvector-postgres/examples/similarity-search.sql
+++ /dev/null
@@ -1,371 +0,0 @@
--- RuVector PostgreSQL Similarity Search
--- Optimized for Claude-Flow V3 HNSW Integration
---
--- Advanced semantic search with 150x-12,500x performance improvement
--- using HNSW (Hierarchical Navigable Small World) indexing
-
--- ============================================
--- 1. HNSW INDEX CONFIGURATION
--- ============================================
-
--- Check current HNSW index status
-SELECT
- indexname,
- indexdef
-FROM pg_indexes
-WHERE schemaname = 'claude_flow'
- AND indexdef LIKE '%hnsw%';
-
--- Optimal HNSW parameters for V3
--- m = 16: Balance between recall and index size
--- ef_construction = 64: Higher = better recall, slower build
-DROP INDEX IF EXISTS claude_flow.idx_embeddings_hnsw_optimized;
-
-CREATE INDEX idx_embeddings_hnsw_optimized
-ON claude_flow.embeddings
-USING hnsw (embedding vector_cosine_ops)
-WITH (m = 16, ef_construction = 100); -- Higher ef_construction for better recall
-
--- Set search parameters (higher ef = better recall, slower search)
-SET hnsw.ef_search = 100; -- Default is 40, increase for better recall
-
-
--- ============================================
--- 2. SEMANTIC SEARCH FUNCTIONS
--- ============================================
-
--- Enhanced search function with configurable parameters
-CREATE OR REPLACE FUNCTION claude_flow.semantic_search(
- query_embedding vector(384),
- limit_count INT DEFAULT 10,
- min_similarity FLOAT DEFAULT 0.5,
- category_filter TEXT DEFAULT NULL,
- agent_filter TEXT DEFAULT NULL
-)
-RETURNS TABLE (
- id UUID,
- content TEXT,
- similarity FLOAT,
- metadata JSONB,
- created_at TIMESTAMPTZ
-) AS $$
-BEGIN
- RETURN QUERY
- SELECT
- e.id,
- e.content,
- (1 - (e.embedding <=> query_embedding))::FLOAT AS similarity,
- e.metadata,
- e.created_at
- FROM claude_flow.embeddings e
- WHERE e.embedding IS NOT NULL
- AND (1 - (e.embedding <=> query_embedding)) >= min_similarity
- AND (category_filter IS NULL OR e.metadata->>'category' = category_filter)
- AND (agent_filter IS NULL OR e.metadata->>'agent' = agent_filter)
- ORDER BY e.embedding <=> query_embedding
- LIMIT limit_count;
-END;
-$$ LANGUAGE plpgsql STABLE;
-
-
--- ============================================
--- 3. MULTI-STAGE RETRIEVAL (RAG Pattern)
--- ============================================
-
--- Stage 1: Coarse retrieval with HNSW (fast, approximate)
--- Stage 2: Re-rank with exact similarity (precise, slower)
-
-CREATE OR REPLACE FUNCTION claude_flow.rag_retrieve(
- query_embedding vector(384),
- coarse_limit INT DEFAULT 100,
- final_limit INT DEFAULT 10,
- min_similarity FLOAT DEFAULT 0.6
-)
-RETURNS TABLE (
- id UUID,
- content TEXT,
- coarse_similarity FLOAT,
- exact_similarity FLOAT,
- metadata JSONB
-) AS $$
-BEGIN
- RETURN QUERY
- WITH coarse_results AS (
- -- Stage 1: Fast HNSW search
- SELECT
- e.id,
- e.content,
- e.embedding,
- e.metadata,
- (1 - (e.embedding <=> query_embedding))::FLOAT AS coarse_sim
- FROM claude_flow.embeddings e
- WHERE e.embedding IS NOT NULL
- ORDER BY e.embedding <=> query_embedding
- LIMIT coarse_limit
- )
- -- Stage 2: Re-rank with exact computation
- SELECT
- cr.id,
- cr.content,
- cr.coarse_sim,
- (1 - (cr.embedding <=> query_embedding))::FLOAT AS exact_sim,
- cr.metadata
- FROM coarse_results cr
- WHERE cr.coarse_sim >= min_similarity
- ORDER BY exact_sim DESC
- LIMIT final_limit;
-END;
-$$ LANGUAGE plpgsql STABLE;
-
-
--- ============================================
--- 4. HYBRID SEARCH (Vector + Keyword)
--- ============================================
-
--- Enable full-text search
-CREATE INDEX IF NOT EXISTS idx_embeddings_content_fts
-ON claude_flow.embeddings
-USING gin(to_tsvector('english', content));
-
--- Hybrid search combining vector similarity and keyword matching
-CREATE OR REPLACE FUNCTION claude_flow.hybrid_search(
- query_embedding vector(384),
- keyword_query TEXT,
- limit_count INT DEFAULT 10,
- vector_weight FLOAT DEFAULT 0.7,
- keyword_weight FLOAT DEFAULT 0.3
-)
-RETURNS TABLE (
- id UUID,
- content TEXT,
- vector_score FLOAT,
- keyword_score FLOAT,
- combined_score FLOAT,
- metadata JSONB
-) AS $$
-BEGIN
- RETURN QUERY
- SELECT
- e.id,
- e.content,
- (1 - (e.embedding <=> query_embedding))::FLOAT AS v_score,
- COALESCE(ts_rank_cd(to_tsvector('english', e.content), plainto_tsquery('english', keyword_query)), 0)::FLOAT AS k_score,
- (
- vector_weight * (1 - (e.embedding <=> query_embedding)) +
- keyword_weight * COALESCE(ts_rank_cd(to_tsvector('english', e.content), plainto_tsquery('english', keyword_query)), 0)
- )::FLOAT AS c_score,
- e.metadata
- FROM claude_flow.embeddings e
- WHERE e.embedding IS NOT NULL
- AND (
- (1 - (e.embedding <=> query_embedding)) > 0.3
- OR to_tsvector('english', e.content) @@ plainto_tsquery('english', keyword_query)
- )
- ORDER BY c_score DESC
- LIMIT limit_count;
-END;
-$$ LANGUAGE plpgsql STABLE;
-
-
--- ============================================
--- 5. CLUSTER-BASED SEARCH
--- ============================================
-
--- Find embeddings similar to a cluster of query embeddings
-CREATE OR REPLACE FUNCTION claude_flow.cluster_search(
- query_embeddings vector(384)[],
- limit_count INT DEFAULT 10,
- aggregation_method TEXT DEFAULT 'max' -- 'max', 'avg', 'min'
-)
-RETURNS TABLE (
- id UUID,
- content TEXT,
- best_similarity FLOAT,
- avg_similarity FLOAT,
- matching_queries INT,
- metadata JSONB
-) AS $$
-BEGIN
- RETURN QUERY
- WITH query_similarities AS (
- SELECT
- e.id,
- e.content,
- e.metadata,
- q.query_idx,
- (1 - (e.embedding <=> q.query_emb))::FLOAT AS similarity
- FROM claude_flow.embeddings e
- CROSS JOIN LATERAL unnest(query_embeddings) WITH ORDINALITY AS q(query_emb, query_idx)
- WHERE e.embedding IS NOT NULL
- ),
- aggregated AS (
- SELECT
- qs.id,
- qs.content,
- qs.metadata,
- MAX(qs.similarity) AS max_sim,
- AVG(qs.similarity)::FLOAT AS avg_sim,
- MIN(qs.similarity) AS min_sim,
- COUNT(DISTINCT qs.query_idx)::INT AS match_count
- FROM query_similarities qs
- WHERE qs.similarity > 0.5
- GROUP BY qs.id, qs.content, qs.metadata
- )
- SELECT
- a.id,
- a.content,
- CASE aggregation_method
- WHEN 'max' THEN a.max_sim
- WHEN 'avg' THEN a.avg_sim
- WHEN 'min' THEN a.min_sim
- ELSE a.max_sim
- END AS best_similarity,
- a.avg_sim,
- a.match_count,
- a.metadata
- FROM aggregated a
- ORDER BY
- CASE aggregation_method
- WHEN 'max' THEN a.max_sim
- WHEN 'avg' THEN a.avg_sim
- WHEN 'min' THEN a.min_sim
- ELSE a.max_sim
- END DESC
- LIMIT limit_count;
-END;
-$$ LANGUAGE plpgsql STABLE;
-
-
--- ============================================
--- 6. TEMPORAL SIMILARITY SEARCH
--- ============================================
-
--- Search with time decay (recent items weighted higher)
-CREATE OR REPLACE FUNCTION claude_flow.temporal_search(
- query_embedding vector(384),
- limit_count INT DEFAULT 10,
- decay_days INT DEFAULT 7,
- time_weight FLOAT DEFAULT 0.2
-)
-RETURNS TABLE (
- id UUID,
- content TEXT,
- vector_similarity FLOAT,
- recency_score FLOAT,
- combined_score FLOAT,
- created_at TIMESTAMPTZ,
- metadata JSONB
-) AS $$
-BEGIN
- RETURN QUERY
- SELECT
- e.id,
- e.content,
- (1 - (e.embedding <=> query_embedding))::FLOAT AS v_sim,
- (EXP(-EXTRACT(EPOCH FROM (NOW() - e.created_at)) / (decay_days * 86400)))::FLOAT AS r_score,
- (
- (1 - time_weight) * (1 - (e.embedding <=> query_embedding)) +
- time_weight * EXP(-EXTRACT(EPOCH FROM (NOW() - e.created_at)) / (decay_days * 86400))
- )::FLOAT AS c_score,
- e.created_at,
- e.metadata
- FROM claude_flow.embeddings e
- WHERE e.embedding IS NOT NULL
- ORDER BY c_score DESC
- LIMIT limit_count;
-END;
-$$ LANGUAGE plpgsql STABLE;
-
-
--- ============================================
--- 7. DIVERSITY-AWARE SEARCH (MMR)
--- ============================================
-
--- Maximal Marginal Relevance for diverse results
-CREATE OR REPLACE FUNCTION claude_flow.mmr_search(
- query_embedding vector(384),
- limit_count INT DEFAULT 10,
- lambda FLOAT DEFAULT 0.5 -- 1.0 = pure relevance, 0.0 = pure diversity
-)
-RETURNS TABLE (
- id UUID,
- content TEXT,
- relevance FLOAT,
- diversity_penalty FLOAT,
- mmr_score FLOAT,
- metadata JSONB
-) AS $$
-DECLARE
- rec RECORD;
- selected_ids UUID[] := ARRAY[]::UUID[];
- selected_embeddings vector(384)[] := ARRAY[]::vector(384)[];
- max_sim_to_selected FLOAT;
-BEGIN
- -- Iteratively select documents using MMR
- FOR i IN 1..limit_count LOOP
- SELECT INTO rec
- e.id,
- e.content,
- e.embedding,
- e.metadata,
- (1 - (e.embedding <=> query_embedding))::FLOAT AS rel
- FROM claude_flow.embeddings e
- WHERE e.embedding IS NOT NULL
- AND e.id != ALL(selected_ids)
- ORDER BY
- lambda * (1 - (e.embedding <=> query_embedding)) -
- (1 - lambda) * COALESCE(
- (SELECT MAX(1 - (e.embedding <=> se))::FLOAT
- FROM unnest(selected_embeddings) AS se),
- 0
- ) DESC
- LIMIT 1;
-
- EXIT WHEN rec IS NULL;
-
- selected_ids := array_append(selected_ids, rec.id);
- selected_embeddings := array_append(selected_embeddings, rec.embedding);
-
- -- Calculate diversity penalty
- SELECT COALESCE(MAX(1 - (rec.embedding <=> se))::FLOAT, 0)
- INTO max_sim_to_selected
- FROM unnest(selected_embeddings[1:array_length(selected_embeddings,1)-1]) AS se;
-
- id := rec.id;
- content := rec.content;
- relevance := rec.rel;
- diversity_penalty := max_sim_to_selected;
- mmr_score := lambda * rec.rel - (1 - lambda) * max_sim_to_selected;
- metadata := rec.metadata;
-
- RETURN NEXT;
- END LOOP;
-END;
-$$ LANGUAGE plpgsql STABLE;
-
-
--- ============================================
--- 8. BENCHMARK QUERIES
--- ============================================
-
--- Performance test: measure search latency
-EXPLAIN ANALYZE
-SELECT
- id,
- content,
- 1 - (embedding <=> (SELECT embedding FROM claude_flow.embeddings LIMIT 1)) AS similarity
-FROM claude_flow.embeddings
-WHERE embedding IS NOT NULL
-ORDER BY embedding <=> (SELECT embedding FROM claude_flow.embeddings LIMIT 1)
-LIMIT 10;
-
--- Index usage verification
-SELECT
- schemaname,
- relname,
- indexrelname,
- idx_scan,
- idx_tup_read,
- idx_tup_fetch
-FROM pg_stat_user_indexes
-WHERE schemaname = 'claude_flow';
diff --git a/docs/ruvector-postgres/examples/v3-demo.sql b/docs/ruvector-postgres/examples/v3-demo.sql
deleted file mode 100644
index a5e08cc693..0000000000
--- a/docs/ruvector-postgres/examples/v3-demo.sql
+++ /dev/null
@@ -1,636 +0,0 @@
--- ============================================
--- RUVECTOR POSTGRESQL V3 COMPREHENSIVE DEMO
--- ============================================
---
--- Complete demonstration of RuVector PostgreSQL Bridge
--- optimized for Claude-Flow V3 features:
---
--- - HNSW Indexing (150x-12,500x faster search)
--- - SONA Integration (pattern learning)
--- - Multi-agent memory coordination
--- - Neural attention mechanisms
--- - Hyperbolic embeddings (PoincarΓ© ball)
--- - Int8 quantization (3.92x memory reduction)
---
--- Run this script to set up a fully-featured demo environment
-
--- ============================================
--- PART 1: SCHEMA SETUP
--- ============================================
-
-\echo '======================================'
-\echo 'Part 1: Schema Setup'
-\echo '======================================'
-
--- Ensure we're using the correct schema
-SET search_path TO claude_flow, public;
-
--- Enable required extensions
-CREATE EXTENSION IF NOT EXISTS vector;
-CREATE EXTENSION IF NOT EXISTS pgcrypto;
-
--- Create enhanced tables for V3 features
-
--- SONA Trajectories for reinforcement learning
-CREATE TABLE IF NOT EXISTS claude_flow.trajectories (
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
- trajectory_id VARCHAR(255) NOT NULL UNIQUE,
- agent_type VARCHAR(50),
- task_description TEXT,
- status VARCHAR(20) DEFAULT 'in_progress',
- steps JSONB DEFAULT '[]',
- outcome VARCHAR(20), -- 'success', 'failure', 'partial'
- quality_score FLOAT,
- started_at TIMESTAMPTZ DEFAULT NOW(),
- ended_at TIMESTAMPTZ,
- metadata JSONB DEFAULT '{}'
-);
-
--- ReasoningBank patterns with confidence tracking
-CREATE TABLE IF NOT EXISTS claude_flow.reasoning_patterns (
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
- pattern_id VARCHAR(255) NOT NULL UNIQUE,
- pattern_type VARCHAR(50),
- description TEXT,
- embedding vector(384),
- confidence FLOAT DEFAULT 0.5,
- success_count INT DEFAULT 0,
- failure_count INT DEFAULT 0,
- last_used TIMESTAMPTZ,
- ewc_importance FLOAT DEFAULT 1.0, -- EWC++ importance weight
- created_at TIMESTAMPTZ DEFAULT NOW(),
- metadata JSONB DEFAULT '{}'
-);
-
--- Hyperbolic embeddings table (PoincarΓ© ball model)
-CREATE TABLE IF NOT EXISTS claude_flow.hyperbolic_embeddings (
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
- content TEXT NOT NULL,
- euclidean_embedding vector(384),
- poincare_embedding vector(384), -- In PoincarΓ© ball (||x|| < 1)
- curvature FLOAT DEFAULT -1.0,
- hierarchy_level INT DEFAULT 0,
- parent_id UUID REFERENCES claude_flow.hyperbolic_embeddings(id),
- created_at TIMESTAMPTZ DEFAULT NOW(),
- metadata JSONB DEFAULT '{}'
-);
-
--- Create HNSW indices for optimal V3 performance
-CREATE INDEX IF NOT EXISTS idx_reasoning_patterns_hnsw
-ON claude_flow.reasoning_patterns
-USING hnsw (embedding vector_cosine_ops)
-WITH (m = 16, ef_construction = 100);
-
-CREATE INDEX IF NOT EXISTS idx_hyperbolic_hnsw
-ON claude_flow.hyperbolic_embeddings
-USING hnsw (euclidean_embedding vector_cosine_ops)
-WITH (m = 16, ef_construction = 100);
-
-\echo 'Schema setup complete'
-
--- ============================================
--- PART 2: SONA TRAJECTORY FUNCTIONS
--- ============================================
-
-\echo ''
-\echo '======================================'
-\echo 'Part 2: SONA Trajectory Functions'
-\echo '======================================'
-
--- Start a new learning trajectory
-CREATE OR REPLACE FUNCTION claude_flow.trajectory_start(
- p_task TEXT,
- p_agent_type TEXT DEFAULT 'general'
-)
-RETURNS TEXT AS $$
-DECLARE
- v_trajectory_id TEXT;
-BEGIN
- v_trajectory_id := 'traj-' || encode(gen_random_bytes(8), 'hex');
-
- INSERT INTO claude_flow.trajectories (trajectory_id, agent_type, task_description)
- VALUES (v_trajectory_id, p_agent_type, p_task);
-
- RETURN v_trajectory_id;
-END;
-$$ LANGUAGE plpgsql;
-
--- Record a step in the trajectory
-CREATE OR REPLACE FUNCTION claude_flow.trajectory_step(
- p_trajectory_id TEXT,
- p_action TEXT,
- p_result TEXT DEFAULT NULL,
- p_quality FLOAT DEFAULT 0.5
-)
-RETURNS VOID AS $$
-BEGIN
- UPDATE claude_flow.trajectories
- SET steps = steps || jsonb_build_object(
- 'action', p_action,
- 'result', p_result,
- 'quality', p_quality,
- 'timestamp', NOW()
- )::jsonb
- WHERE trajectory_id = p_trajectory_id;
-END;
-$$ LANGUAGE plpgsql;
-
--- End trajectory and trigger learning
-CREATE OR REPLACE FUNCTION claude_flow.trajectory_end(
- p_trajectory_id TEXT,
- p_success BOOLEAN,
- p_feedback TEXT DEFAULT NULL
-)
-RETURNS TABLE (
- trajectory_id TEXT,
- total_steps INT,
- avg_quality FLOAT,
- outcome TEXT
-) AS $$
-DECLARE
- v_steps JSONB;
- v_avg_quality FLOAT;
- v_outcome TEXT;
-BEGIN
- -- Update trajectory status
- v_outcome := CASE WHEN p_success THEN 'success' ELSE 'failure' END;
-
- UPDATE claude_flow.trajectories t
- SET
- status = 'completed',
- outcome = v_outcome,
- ended_at = NOW(),
- metadata = metadata || jsonb_build_object('feedback', p_feedback)
- WHERE t.trajectory_id = p_trajectory_id
- RETURNING t.steps INTO v_steps;
-
- -- Calculate average quality
- SELECT AVG((s->>'quality')::FLOAT)
- INTO v_avg_quality
- FROM jsonb_array_elements(v_steps) AS s;
-
- -- Update quality score
- UPDATE claude_flow.trajectories
- SET quality_score = v_avg_quality
- WHERE trajectories.trajectory_id = p_trajectory_id;
-
- RETURN QUERY
- SELECT
- p_trajectory_id,
- jsonb_array_length(v_steps)::INT,
- COALESCE(v_avg_quality, 0.0)::FLOAT,
- v_outcome;
-END;
-$$ LANGUAGE plpgsql;
-
-\echo 'SONA trajectory functions created'
-
--- ============================================
--- PART 3: REASONINGBANK PATTERN LEARNING
--- ============================================
-
-\echo ''
-\echo '======================================'
-\echo 'Part 3: ReasoningBank Pattern Learning'
-\echo '======================================'
-
--- Store a pattern with embedding
-CREATE OR REPLACE FUNCTION claude_flow.pattern_store(
- p_pattern_id TEXT,
- p_description TEXT,
- p_embedding vector(384),
- p_type TEXT DEFAULT 'general',
- p_initial_confidence FLOAT DEFAULT 0.5
-)
-RETURNS UUID AS $$
-DECLARE
- v_id UUID;
-BEGIN
- INSERT INTO claude_flow.reasoning_patterns (
- pattern_id, pattern_type, description, embedding, confidence
- )
- VALUES (p_pattern_id, p_type, p_description, p_embedding, p_initial_confidence)
- ON CONFLICT (pattern_id) DO UPDATE SET
- description = EXCLUDED.description,
- embedding = EXCLUDED.embedding,
- last_used = NOW()
- RETURNING id INTO v_id;
-
- RETURN v_id;
-END;
-$$ LANGUAGE plpgsql;
-
--- Search patterns with HNSW (150x faster)
-CREATE OR REPLACE FUNCTION claude_flow.pattern_search(
- p_query_embedding vector(384),
- p_limit INT DEFAULT 5,
- p_min_confidence FLOAT DEFAULT 0.3,
- p_type_filter TEXT DEFAULT NULL
-)
-RETURNS TABLE (
- pattern_id TEXT,
- description TEXT,
- similarity FLOAT,
- confidence FLOAT,
- success_rate FLOAT,
- pattern_type TEXT
-) AS $$
-BEGIN
- -- Set HNSW search parameters for optimal recall
- SET LOCAL hnsw.ef_search = 100;
-
- RETURN QUERY
- SELECT
- rp.pattern_id,
- rp.description,
- (1 - (rp.embedding <=> p_query_embedding))::FLOAT AS sim,
- rp.confidence,
- CASE
- WHEN (rp.success_count + rp.failure_count) > 0
- THEN rp.success_count::FLOAT / (rp.success_count + rp.failure_count)
- ELSE 0.5
- END AS success_rate,
- rp.pattern_type
- FROM claude_flow.reasoning_patterns rp
- WHERE rp.embedding IS NOT NULL
- AND rp.confidence >= p_min_confidence
- AND (p_type_filter IS NULL OR rp.pattern_type = p_type_filter)
- ORDER BY rp.embedding <=> p_query_embedding
- LIMIT p_limit;
-END;
-$$ LANGUAGE plpgsql;
-
--- Update pattern confidence with EWC++ inspired importance weighting
-CREATE OR REPLACE FUNCTION claude_flow.pattern_feedback(
- p_pattern_id TEXT,
- p_success BOOLEAN,
- p_quality FLOAT DEFAULT 0.5
-)
-RETURNS VOID AS $$
-DECLARE
- v_current_confidence FLOAT;
- v_learning_rate FLOAT := 0.1;
- v_ewc_lambda FLOAT := 0.5; -- EWC++ regularization strength
-BEGIN
- SELECT confidence INTO v_current_confidence
- FROM claude_flow.reasoning_patterns
- WHERE pattern_id = p_pattern_id;
-
- -- Update with EWC++-inspired update rule
- UPDATE claude_flow.reasoning_patterns
- SET
- confidence = GREATEST(0.0, LEAST(1.0,
- v_current_confidence +
- v_learning_rate * ewc_importance * (p_quality - v_current_confidence)
- )),
- success_count = success_count + CASE WHEN p_success THEN 1 ELSE 0 END,
- failure_count = failure_count + CASE WHEN NOT p_success THEN 1 ELSE 0 END,
- last_used = NOW(),
- -- Increase importance for frequently used patterns
- ewc_importance = LEAST(2.0, ewc_importance + 0.1)
- WHERE pattern_id = p_pattern_id;
-END;
-$$ LANGUAGE plpgsql;
-
-\echo 'ReasoningBank functions created'
-
--- ============================================
--- PART 4: HYPERBOLIC EMBEDDINGS
--- ============================================
-
-\echo ''
-\echo '======================================'
-\echo 'Part 4: Hyperbolic Embeddings'
-\echo '======================================'
-
--- Convert Euclidean to PoincarΓ© ball embedding
-CREATE OR REPLACE FUNCTION claude_flow.euclidean_to_poincare(
- p_euclidean vector(384),
- p_curvature FLOAT DEFAULT -1.0
-)
-RETURNS vector(384) AS $$
-DECLARE
- v_norm FLOAT;
- v_scale FLOAT;
- v_result FLOAT[];
- v_dim INT := 384;
-BEGIN
- -- Get L2 norm
- SELECT sqrt(SUM(val * val))
- INTO v_norm
- FROM unnest(p_euclidean::float[]) AS val;
-
- -- Map to PoincarΓ© ball: x / (1 + sqrt(1 + |c| * ||x||^2))
- v_scale := 1.0 / (1.0 + sqrt(1.0 + abs(p_curvature) * v_norm * v_norm));
-
- SELECT array_agg(val * v_scale)
- INTO v_result
- FROM unnest(p_euclidean::float[]) AS val;
-
- RETURN v_result::vector(384);
-END;
-$$ LANGUAGE plpgsql IMMUTABLE;
-
--- PoincarΓ© distance (geodesic in hyperbolic space)
-CREATE OR REPLACE FUNCTION claude_flow.poincare_distance(
- p_x vector(384),
- p_y vector(384),
- p_curvature FLOAT DEFAULT -1.0
-)
-RETURNS FLOAT AS $$
-DECLARE
- v_x_norm_sq FLOAT;
- v_y_norm_sq FLOAT;
- v_diff_norm_sq FLOAT;
- v_numerator FLOAT;
- v_denominator FLOAT;
-BEGIN
- -- ||x||^2
- SELECT SUM(val * val) INTO v_x_norm_sq
- FROM unnest(p_x::float[]) AS val;
-
- -- ||y||^2
- SELECT SUM(val * val) INTO v_y_norm_sq
- FROM unnest(p_y::float[]) AS val;
-
- -- ||x - y||^2
- SELECT SUM((a - b) * (a - b)) INTO v_diff_norm_sq
- FROM unnest(p_x::float[], p_y::float[]) AS t(a, b);
-
- -- PoincarΓ© distance formula
- v_numerator := 2.0 * v_diff_norm_sq;
- v_denominator := (1.0 - v_x_norm_sq) * (1.0 - v_y_norm_sq);
-
- IF v_denominator <= 0 THEN
- RETURN 999999.0; -- Points outside ball
- END IF;
-
- RETURN (1.0 / sqrt(abs(p_curvature))) *
- acosh(1.0 + v_numerator / v_denominator);
-END;
-$$ LANGUAGE plpgsql IMMUTABLE;
-
--- Search in hyperbolic space (for hierarchical data)
-CREATE OR REPLACE FUNCTION claude_flow.hyperbolic_search(
- p_query_embedding vector(384),
- p_limit INT DEFAULT 10,
- p_curvature FLOAT DEFAULT -1.0
-)
-RETURNS TABLE (
- id UUID,
- content TEXT,
- euclidean_distance FLOAT,
- poincare_distance FLOAT,
- hierarchy_level INT,
- metadata JSONB
-) AS $$
-DECLARE
- v_query_poincare vector(384);
-BEGIN
- -- Convert query to PoincarΓ© space
- v_query_poincare := claude_flow.euclidean_to_poincare(p_query_embedding, p_curvature);
-
- RETURN QUERY
- SELECT
- he.id,
- he.content,
- (he.euclidean_embedding <=> p_query_embedding)::FLOAT AS euc_dist,
- claude_flow.poincare_distance(he.poincare_embedding, v_query_poincare, p_curvature) AS poinc_dist,
- he.hierarchy_level,
- he.metadata
- FROM claude_flow.hyperbolic_embeddings he
- WHERE he.euclidean_embedding IS NOT NULL
- ORDER BY he.euclidean_embedding <=> p_query_embedding -- Use HNSW for initial filtering
- LIMIT p_limit * 2 -- Fetch more for re-ranking
-)
--- Re-rank by PoincarΓ© distance
-ORDER BY poinc_dist
-LIMIT p_limit;
-END;
-$$ LANGUAGE plpgsql;
-
-\echo 'Hyperbolic embedding functions created'
-
--- ============================================
--- PART 5: AGENT MEMORY COORDINATION
--- ============================================
-
-\echo ''
-\echo '======================================'
-\echo 'Part 5: Agent Memory Coordination'
-\echo '======================================'
-
--- Multi-agent memory sharing
-CREATE OR REPLACE FUNCTION claude_flow.share_agent_memory(
- p_source_agent TEXT,
- p_target_agents TEXT[],
- p_knowledge_filter JSONB DEFAULT NULL
-)
-RETURNS TABLE (
- target_agent TEXT,
- patterns_shared INT,
- similarity_threshold FLOAT
-) AS $$
-DECLARE
- v_source_embedding vector(384);
- v_target TEXT;
- v_shared_count INT;
-BEGIN
- -- Get source agent's memory embedding
- SELECT memory_embedding INTO v_source_embedding
- FROM claude_flow.agents
- WHERE agent_id = p_source_agent;
-
- IF v_source_embedding IS NULL THEN
- RAISE EXCEPTION 'Source agent % not found or has no memory', p_source_agent;
- END IF;
-
- -- Share with each target agent
- FOREACH v_target IN ARRAY p_target_agents LOOP
- -- Find relevant patterns from source
- WITH relevant_patterns AS (
- SELECT embedding, confidence
- FROM claude_flow.reasoning_patterns
- WHERE (1 - (embedding <=> v_source_embedding)) > 0.5
- AND (p_knowledge_filter IS NULL OR metadata @> p_knowledge_filter)
- ORDER BY embedding <=> v_source_embedding
- LIMIT 10
- )
- -- Update target agent's memory (weighted average)
- UPDATE claude_flow.agents
- SET
- memory_embedding = (
- SELECT AVG(embedding)::vector(384)
- FROM (
- SELECT memory_embedding AS embedding FROM claude_flow.agents WHERE agent_id = v_target
- UNION ALL
- SELECT embedding FROM relevant_patterns
- ) combined
- ),
- last_active = NOW()
- WHERE agent_id = v_target;
-
- GET DIAGNOSTICS v_shared_count = ROW_COUNT;
-
- target_agent := v_target;
- patterns_shared := v_shared_count;
- similarity_threshold := 0.5;
- RETURN NEXT;
- END LOOP;
-END;
-$$ LANGUAGE plpgsql;
-
--- Find agents with complementary knowledge
-CREATE OR REPLACE FUNCTION claude_flow.find_complementary_agents(
- p_task_embedding vector(384),
- p_exclude_agents TEXT[] DEFAULT ARRAY[]::TEXT[],
- p_limit INT DEFAULT 3
-)
-RETURNS TABLE (
- agent_id TEXT,
- agent_type TEXT,
- relevance_score FLOAT,
- complementary_score FLOAT,
- combined_score FLOAT
-) AS $$
-BEGIN
- RETURN QUERY
- WITH agent_relevance AS (
- SELECT
- a.agent_id,
- a.agent_type,
- a.memory_embedding,
- (1 - (a.memory_embedding <=> p_task_embedding))::FLOAT AS relevance
- FROM claude_flow.agents a
- WHERE a.memory_embedding IS NOT NULL
- AND a.agent_id != ALL(p_exclude_agents)
- ),
- agent_pairs AS (
- SELECT
- ar1.agent_id,
- ar1.agent_type,
- ar1.relevance,
- -- Complementary = different from already selected
- COALESCE(
- 1 - MAX(1 - (ar1.memory_embedding <=> ar2.memory_embedding)),
- 1.0
- )::FLOAT AS complementary
- FROM agent_relevance ar1
- LEFT JOIN agent_relevance ar2 ON ar2.agent_id = ANY(p_exclude_agents)
- GROUP BY ar1.agent_id, ar1.agent_type, ar1.relevance, ar1.memory_embedding
- )
- SELECT
- ap.agent_id,
- ap.agent_type,
- ap.relevance,
- ap.complementary,
- (0.6 * ap.relevance + 0.4 * ap.complementary)::FLOAT AS combined
- FROM agent_pairs ap
- ORDER BY combined DESC
- LIMIT p_limit;
-END;
-$$ LANGUAGE plpgsql;
-
-\echo 'Agent coordination functions created'
-
--- ============================================
--- PART 6: DEMO DATA
--- ============================================
-
-\echo ''
-\echo '======================================'
-\echo 'Part 6: Loading Demo Data'
-\echo '======================================'
-
--- Insert sample embeddings with realistic metadata
-INSERT INTO claude_flow.embeddings (content, metadata) VALUES
- ('Implementing JWT authentication with refresh token rotation',
- '{"category": "security", "language": "typescript", "complexity": "medium", "agent": "security-architect"}'),
- ('Building a RESTful API with Express and TypeScript',
- '{"category": "backend", "language": "typescript", "complexity": "low", "agent": "coder"}'),
- ('Setting up PostgreSQL with pgvector for semantic search',
- '{"category": "database", "language": "sql", "complexity": "medium", "agent": "architect"}'),
- ('Implementing HNSW indexing for fast vector similarity search',
- '{"category": "performance", "language": "sql", "complexity": "high", "agent": "perf-engineer"}'),
- ('Creating a React component with TDD London School approach',
- '{"category": "frontend", "language": "typescript", "complexity": "medium", "agent": "tester"}'),
- ('Setting up CI/CD pipeline with GitHub Actions',
- '{"category": "devops", "language": "yaml", "complexity": "medium", "agent": "cicd-engineer"}'),
- ('Implementing rate limiting with sliding window algorithm',
- '{"category": "security", "language": "typescript", "complexity": "high", "agent": "security-architect"}'),
- ('Building a multi-agent swarm with hierarchical coordination',
- '{"category": "ai", "language": "typescript", "complexity": "high", "agent": "architect"}'),
- ('Optimizing database queries with EXPLAIN ANALYZE',
- '{"category": "database", "language": "sql", "complexity": "medium", "agent": "perf-engineer"}'),
- ('Implementing EWC++ for continual learning without forgetting',
- '{"category": "ai", "language": "python", "complexity": "high", "agent": "ml-developer"}')
-ON CONFLICT DO NOTHING;
-
--- Insert sample agents
-INSERT INTO claude_flow.agents (agent_id, agent_type, state) VALUES
- ('coder-001', 'coder', '{"specializations": ["typescript", "react"], "tasks_completed": 42}'),
- ('architect-001', 'architect', '{"specializations": ["system-design", "ddd"], "tasks_completed": 28}'),
- ('tester-001', 'tester', '{"specializations": ["tdd", "integration"], "tasks_completed": 35}'),
- ('security-001', 'security-architect', '{"specializations": ["auth", "crypto"], "tasks_completed": 15}'),
- ('perf-001', 'perf-engineer', '{"specializations": ["database", "caching"], "tasks_completed": 22}')
-ON CONFLICT (agent_id) DO UPDATE SET
- state = EXCLUDED.state,
- last_active = NOW();
-
--- Insert sample reasoning patterns
-INSERT INTO claude_flow.reasoning_patterns (pattern_id, pattern_type, description, confidence) VALUES
- ('auth-jwt-refresh', 'security', 'JWT with refresh token rotation pattern', 0.92),
- ('api-rest-design', 'architecture', 'RESTful API design with proper status codes', 0.88),
- ('db-index-btree', 'performance', 'B-tree index for range queries', 0.85),
- ('db-index-hnsw', 'performance', 'HNSW index for vector similarity', 0.95),
- ('tdd-london-mock', 'testing', 'London School TDD with mocks first', 0.82),
- ('swarm-hierarchical', 'coordination', 'Hierarchical swarm with queen coordinator', 0.90)
-ON CONFLICT (pattern_id) DO NOTHING;
-
-\echo 'Demo data loaded'
-
--- ============================================
--- PART 7: VERIFICATION QUERIES
--- ============================================
-
-\echo ''
-\echo '======================================'
-\echo 'Part 7: Verification'
-\echo '======================================'
-
--- Count records
-SELECT 'embeddings' AS table_name, COUNT(*) AS count FROM claude_flow.embeddings
-UNION ALL
-SELECT 'patterns', COUNT(*) FROM claude_flow.patterns
-UNION ALL
-SELECT 'agents', COUNT(*) FROM claude_flow.agents
-UNION ALL
-SELECT 'reasoning_patterns', COUNT(*) FROM claude_flow.reasoning_patterns
-UNION ALL
-SELECT 'trajectories', COUNT(*) FROM claude_flow.trajectories;
-
--- Show indices
-SELECT indexname, indexdef
-FROM pg_indexes
-WHERE schemaname = 'claude_flow'
- AND indexdef LIKE '%hnsw%';
-
-\echo ''
-\echo '======================================'
-\echo 'RuVector V3 Demo Setup Complete!'
-\echo '======================================'
-\echo ''
-\echo 'Available functions:'
-\echo ' - claude_flow.semantic_search(embedding, limit, threshold)'
-\echo ' - claude_flow.rag_retrieve(embedding, coarse_limit, final_limit)'
-\echo ' - claude_flow.hybrid_search(embedding, keyword, limit)'
-\echo ' - claude_flow.trajectory_start(task, agent_type)'
-\echo ' - claude_flow.trajectory_step(id, action, result, quality)'
-\echo ' - claude_flow.trajectory_end(id, success, feedback)'
-\echo ' - claude_flow.pattern_store(id, desc, embedding, type)'
-\echo ' - claude_flow.pattern_search(embedding, limit, confidence)'
-\echo ' - claude_flow.pattern_feedback(id, success, quality)'
-\echo ' - claude_flow.hyperbolic_search(embedding, limit, curvature)'
-\echo ' - claude_flow.share_agent_memory(source, targets, filter)'
-\echo ' - claude_flow.find_complementary_agents(task_embedding)'
-\echo ''
diff --git a/docs/ruvector-postgres/scripts/cleanup.sh b/docs/ruvector-postgres/scripts/cleanup.sh
deleted file mode 100755
index 84a5dd2d2c..0000000000
--- a/docs/ruvector-postgres/scripts/cleanup.sh
+++ /dev/null
@@ -1,41 +0,0 @@
-#!/bin/bash
-# Clean up RuVector PostgreSQL data
-
-set -e
-
-HOST="${PGHOST:-localhost}"
-PORT="${PGPORT:-5432}"
-DATABASE="${PGDATABASE:-claude_flow}"
-USER="${PGUSER:-claude}"
-PASSWORD="${PGPASSWORD:-claude-flow-test}"
-
-echo "🧹 Cleaning up RuVector PostgreSQL"
-echo "=========================================="
-echo ""
-echo "⚠️ WARNING: This will delete ALL data in the claude_flow schema!"
-echo ""
-read -p "Are you sure? (y/N) " -n 1 -r
-echo ""
-
-if [[ ! $REPLY =~ ^[Yy]$ ]]; then
- echo "Cancelled."
- exit 0
-fi
-
-echo ""
-echo "Dropping schema..."
-PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -c \
- "DROP SCHEMA IF EXISTS claude_flow CASCADE;"
-
-echo "Recreating schema..."
-PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -c \
- "CREATE SCHEMA claude_flow; GRANT ALL ON SCHEMA claude_flow TO $USER;"
-
-echo ""
-echo "βœ… Cleanup complete!"
-echo ""
-echo "To reinitialize, run:"
-echo " docker-compose down -v && docker-compose up -d"
-echo ""
-echo "Or run the init script manually:"
-echo " ./scripts/run-migrations.sh"
diff --git a/docs/ruvector-postgres/scripts/init-db.sql b/docs/ruvector-postgres/scripts/init-db.sql
deleted file mode 100644
index f2715cd7ac..0000000000
--- a/docs/ruvector-postgres/scripts/init-db.sql
+++ /dev/null
@@ -1,452 +0,0 @@
--- ============================================
--- RUVECTOR POSTGRESQL INITIALIZATION SCRIPT
--- ============================================
---
--- This script initializes RuVector PostgreSQL extension
--- from ruvnet/ruvector-postgres with Claude-Flow V3 integration.
---
--- RuVector 2.0.0 provides 77+ SQL functions including:
--- - Vector similarity search (HNSW with SIMD)
--- - Hyperbolic embeddings (PoincarΓ©/Lorentz)
--- - Graph operations (Cypher queries)
--- - RDF/SPARQL support
--- - Agent routing and learning
---
--- Performance: ~61Β΅s latency, 16,400 QPS
-
--- ============================================
--- PART 1: EXTENSION AND SCHEMA SETUP
--- ============================================
-
--- Enable RuVector extension (use VERSION to work around control file issue)
-CREATE EXTENSION IF NOT EXISTS ruvector VERSION '0.1.0';
-
--- Enable additional required extensions
-CREATE EXTENSION IF NOT EXISTS pgcrypto;
-
--- Create the claude_flow schema
-CREATE SCHEMA IF NOT EXISTS claude_flow;
-
--- Grant permissions
-GRANT ALL ON SCHEMA claude_flow TO claude;
-
--- Set search path
-SET search_path TO claude_flow, public;
-
--- ============================================
--- PART 2: CORE TABLES
--- ============================================
-
--- Embeddings table with RuVector vector type (384-dim for all-MiniLM-L6-v2)
-CREATE TABLE IF NOT EXISTS claude_flow.embeddings (
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
- content TEXT NOT NULL,
- embedding ruvector(384),
- metadata JSONB DEFAULT '{}',
- created_at TIMESTAMPTZ DEFAULT NOW(),
- updated_at TIMESTAMPTZ DEFAULT NOW()
-);
-
--- Patterns table for learned patterns (ReasoningBank)
-CREATE TABLE IF NOT EXISTS claude_flow.patterns (
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
- name VARCHAR(255) NOT NULL,
- description TEXT,
- embedding ruvector(384),
- pattern_type VARCHAR(50),
- confidence FLOAT DEFAULT 0.5,
- success_count INT DEFAULT 0,
- failure_count INT DEFAULT 0,
- ewc_importance FLOAT DEFAULT 1.0,
- metadata JSONB DEFAULT '{}',
- created_at TIMESTAMPTZ DEFAULT NOW()
-);
-
--- Agents table for multi-agent memory coordination
-CREATE TABLE IF NOT EXISTS claude_flow.agents (
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
- agent_id VARCHAR(255) NOT NULL UNIQUE,
- agent_type VARCHAR(50),
- state JSONB DEFAULT '{}',
- memory_embedding ruvector(384),
- last_active TIMESTAMPTZ DEFAULT NOW(),
- created_at TIMESTAMPTZ DEFAULT NOW()
-);
-
--- Trajectories table for SONA reinforcement learning
-CREATE TABLE IF NOT EXISTS claude_flow.trajectories (
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
- trajectory_id VARCHAR(255) NOT NULL UNIQUE,
- agent_type VARCHAR(50),
- task_description TEXT,
- status VARCHAR(20) DEFAULT 'in_progress',
- steps JSONB DEFAULT '[]',
- outcome VARCHAR(20),
- quality_score FLOAT,
- started_at TIMESTAMPTZ DEFAULT NOW(),
- ended_at TIMESTAMPTZ
-);
-
--- Hyperbolic embeddings for hierarchical data
-CREATE TABLE IF NOT EXISTS claude_flow.hyperbolic_embeddings (
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
- content TEXT NOT NULL,
- euclidean_embedding ruvector(384),
- poincare_embedding real[], -- Array for hyperbolic operations
- curvature FLOAT DEFAULT -1.0,
- hierarchy_level INT DEFAULT 0,
- parent_id UUID REFERENCES claude_flow.hyperbolic_embeddings(id),
- metadata JSONB DEFAULT '{}',
- created_at TIMESTAMPTZ DEFAULT NOW()
-);
-
--- Graph nodes for GNN operations
-CREATE TABLE IF NOT EXISTS claude_flow.graph_nodes (
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
- node_id VARCHAR(255) NOT NULL UNIQUE,
- node_type VARCHAR(50),
- embedding ruvector(384),
- features JSONB DEFAULT '{}',
- created_at TIMESTAMPTZ DEFAULT NOW()
-);
-
--- Graph edges for message passing
-CREATE TABLE IF NOT EXISTS claude_flow.graph_edges (
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
- source_id UUID REFERENCES claude_flow.graph_nodes(id),
- target_id UUID REFERENCES claude_flow.graph_nodes(id),
- edge_type VARCHAR(50),
- weight FLOAT DEFAULT 1.0,
- metadata JSONB DEFAULT '{}',
- created_at TIMESTAMPTZ DEFAULT NOW()
-);
-
--- ============================================
--- PART 3: HNSW INDICES
--- ============================================
-
--- HNSW index for embeddings (cosine distance)
-CREATE INDEX IF NOT EXISTS idx_embeddings_hnsw
-ON claude_flow.embeddings
-USING hnsw (embedding ruvector_cosine_ops)
-WITH (m = 16, ef_construction = 100);
-
--- HNSW index for patterns
-CREATE INDEX IF NOT EXISTS idx_patterns_hnsw
-ON claude_flow.patterns
-USING hnsw (embedding ruvector_cosine_ops)
-WITH (m = 16, ef_construction = 100);
-
--- HNSW index for agent memory
-CREATE INDEX IF NOT EXISTS idx_agents_hnsw
-ON claude_flow.agents
-USING hnsw (memory_embedding ruvector_cosine_ops)
-WITH (m = 16, ef_construction = 64);
-
--- HNSW index for hyperbolic embeddings
-CREATE INDEX IF NOT EXISTS idx_hyperbolic_hnsw
-ON claude_flow.hyperbolic_embeddings
-USING hnsw (euclidean_embedding ruvector_cosine_ops)
-WITH (m = 16, ef_construction = 100);
-
--- HNSW index for graph nodes
-CREATE INDEX IF NOT EXISTS idx_graph_nodes_hnsw
-ON claude_flow.graph_nodes
-USING hnsw (embedding ruvector_cosine_ops)
-WITH (m = 16, ef_construction = 64);
-
--- ============================================
--- PART 4: CORE SEARCH FUNCTIONS
--- ============================================
-
--- Semantic similarity search using RuVector HNSW
-CREATE OR REPLACE FUNCTION claude_flow.search_similar(
- query_embedding ruvector(384),
- limit_count INT DEFAULT 10,
- min_similarity FLOAT DEFAULT 0.5
-)
-RETURNS TABLE (
- id UUID,
- content TEXT,
- similarity FLOAT,
- metadata JSONB
-) AS $$
-BEGIN
- RETURN QUERY
- SELECT
- e.id,
- e.content,
- (1 - (e.embedding <=> query_embedding))::FLOAT AS similarity,
- e.metadata
- FROM claude_flow.embeddings e
- WHERE e.embedding IS NOT NULL
- AND (1 - (e.embedding <=> query_embedding)) >= min_similarity
- ORDER BY e.embedding <=> query_embedding
- LIMIT limit_count;
-END;
-$$ LANGUAGE plpgsql STABLE;
-
--- Pattern search with type filtering
-CREATE OR REPLACE FUNCTION claude_flow.search_patterns(
- query_embedding ruvector(384),
- pattern_type_filter VARCHAR(50) DEFAULT NULL,
- limit_count INT DEFAULT 10,
- min_confidence FLOAT DEFAULT 0.5
-)
-RETURNS TABLE (
- id UUID,
- name VARCHAR(255),
- description TEXT,
- similarity FLOAT,
- confidence FLOAT,
- metadata JSONB
-) AS $$
-BEGIN
- RETURN QUERY
- SELECT
- p.id,
- p.name,
- p.description,
- (1 - (p.embedding <=> query_embedding))::FLOAT AS similarity,
- p.confidence,
- p.metadata
- FROM claude_flow.patterns p
- WHERE p.embedding IS NOT NULL
- AND p.confidence >= min_confidence
- AND (pattern_type_filter IS NULL OR p.pattern_type = pattern_type_filter)
- ORDER BY p.embedding <=> query_embedding
- LIMIT limit_count;
-END;
-$$ LANGUAGE plpgsql STABLE;
-
--- Agent routing by expertise similarity
-CREATE OR REPLACE FUNCTION claude_flow.find_agents(
- query_embedding ruvector(384),
- agent_type_filter VARCHAR(50) DEFAULT NULL,
- limit_count INT DEFAULT 5
-)
-RETURNS TABLE (
- agent_id VARCHAR(255),
- agent_type VARCHAR(50),
- similarity FLOAT,
- state JSONB
-) AS $$
-BEGIN
- RETURN QUERY
- SELECT
- a.agent_id,
- a.agent_type,
- (1 - (a.memory_embedding <=> query_embedding))::FLOAT AS similarity,
- a.state
- FROM claude_flow.agents a
- WHERE a.memory_embedding IS NOT NULL
- AND (agent_type_filter IS NULL OR a.agent_type = agent_type_filter)
- ORDER BY a.memory_embedding <=> query_embedding
- LIMIT limit_count;
-END;
-$$ LANGUAGE plpgsql STABLE;
-
--- ============================================
--- PART 5: HYPERBOLIC OPERATIONS
--- ============================================
-
--- Convert Euclidean to PoincarΓ© embedding
-CREATE OR REPLACE FUNCTION claude_flow.to_poincare(
- euclidean real[],
- curvature FLOAT DEFAULT -1.0
-)
-RETURNS real[] AS $$
-BEGIN
- RETURN ruvector_exp_map(ARRAY_FILL(0.0::real, ARRAY[array_length(euclidean, 1)]), euclidean, curvature);
-END;
-$$ LANGUAGE plpgsql IMMUTABLE;
-
--- PoincarΓ© distance (geodesic)
-CREATE OR REPLACE FUNCTION claude_flow.poincare_distance(
- x real[],
- y real[],
- curvature FLOAT DEFAULT -1.0
-)
-RETURNS FLOAT AS $$
-BEGIN
- RETURN ruvector_poincare_distance(x, y, curvature);
-END;
-$$ LANGUAGE plpgsql IMMUTABLE;
-
--- Hyperbolic search in PoincarΓ© ball
-CREATE OR REPLACE FUNCTION claude_flow.hyperbolic_search(
- query ruvector(384),
- limit_count INT DEFAULT 10,
- curvature FLOAT DEFAULT -1.0
-)
-RETURNS TABLE (
- id UUID,
- content TEXT,
- euclidean_dist FLOAT,
- hyperbolic_dist FLOAT,
- hierarchy_level INT,
- metadata JSONB
-) AS $$
-DECLARE
- query_arr real[];
- query_poincare real[];
-BEGIN
- -- Convert query to array and then to PoincarΓ©
- SELECT array_agg(x ORDER BY ordinality) INTO query_arr
- FROM unnest(string_to_array(trim(both '[]' from query::text), ',')) WITH ORDINALITY AS t(x, ordinality);
-
- query_poincare := claude_flow.to_poincare(query_arr, curvature);
-
- RETURN QUERY
- SELECT
- he.id,
- he.content,
- (he.euclidean_embedding <-> query)::FLOAT AS euc_dist,
- COALESCE(ruvector_poincare_distance(he.poincare_embedding, query_poincare, curvature), 999.0)::FLOAT AS hyp_dist,
- he.hierarchy_level,
- he.metadata
- FROM claude_flow.hyperbolic_embeddings he
- WHERE he.euclidean_embedding IS NOT NULL
- ORDER BY he.euclidean_embedding <-> query
- LIMIT limit_count;
-END;
-$$ LANGUAGE plpgsql STABLE;
-
--- ============================================
--- PART 6: UTILITY FUNCTIONS
--- ============================================
-
--- Get RuVector version info
-CREATE OR REPLACE FUNCTION claude_flow.ruvector_info()
-RETURNS TABLE (
- version TEXT,
- simd_info TEXT
-) AS $$
-BEGIN
- RETURN QUERY
- SELECT ruvector_version(), ruvector_simd_info();
-END;
-$$ LANGUAGE plpgsql STABLE;
-
--- Cosine similarity helper (converts cosine distance to similarity)
-CREATE OR REPLACE FUNCTION claude_flow.cosine_similarity(
- a ruvector,
- b ruvector
-)
-RETURNS FLOAT AS $$
-BEGIN
- RETURN (1 - (a <=> b))::FLOAT;
-END;
-$$ LANGUAGE plpgsql IMMUTABLE;
-
--- L2 distance helper
-CREATE OR REPLACE FUNCTION claude_flow.l2_distance(
- a ruvector,
- b ruvector
-)
-RETURNS FLOAT AS $$
-BEGIN
- RETURN (a <-> b)::FLOAT;
-END;
-$$ LANGUAGE plpgsql IMMUTABLE;
-
--- Update embedding with auto-timestamp
-CREATE OR REPLACE FUNCTION claude_flow.update_embedding(
- embedding_id UUID,
- new_content TEXT DEFAULT NULL,
- new_embedding ruvector(384) DEFAULT NULL,
- new_metadata JSONB DEFAULT NULL
-)
-RETURNS void AS $$
-BEGIN
- UPDATE claude_flow.embeddings
- SET
- content = COALESCE(new_content, content),
- embedding = COALESCE(new_embedding, embedding),
- metadata = COALESCE(new_metadata, metadata),
- updated_at = NOW()
- WHERE id = embedding_id;
-END;
-$$ LANGUAGE plpgsql;
-
--- ============================================
--- PART 7: SAMPLE DATA
--- ============================================
-
--- Insert sample embeddings (without actual vectors - those need to come from model)
-INSERT INTO claude_flow.embeddings (content, metadata) VALUES
- ('Implementing JWT authentication with refresh token rotation',
- '{"category": "security", "language": "typescript", "agent": "security-architect"}'),
- ('Building a RESTful API with Express and TypeScript',
- '{"category": "backend", "language": "typescript", "agent": "coder"}'),
- ('Setting up RuVector PostgreSQL for semantic search',
- '{"category": "database", "language": "sql", "agent": "architect"}'),
- ('HNSW indexing for sub-millisecond vector search',
- '{"category": "performance", "language": "sql", "agent": "perf-engineer"}'),
- ('TDD London School approach with mocks',
- '{"category": "testing", "language": "typescript", "agent": "tester"}'),
- ('Multi-head attention mechanism in transformer architectures',
- '{"category": "ai", "language": "python", "agent": "ml-developer"}'),
- ('Graph neural networks for knowledge representation',
- '{"category": "ai", "language": "python", "agent": "ml-developer"}'),
- ('Hyperbolic embeddings for hierarchical data',
- '{"category": "ai", "language": "python", "agent": "researcher"}'),
- ('BM25 ranking for hybrid search optimization',
- '{"category": "search", "language": "sql", "agent": "perf-engineer"}'),
- ('Multi-agent swarm coordination patterns',
- '{"category": "ai", "language": "typescript", "agent": "architect"}')
-ON CONFLICT DO NOTHING;
-
--- Insert sample agents
-INSERT INTO claude_flow.agents (agent_id, agent_type, state) VALUES
- ('coder-001', 'coder', '{"specializations": ["typescript", "react"], "tasks_completed": 42}'),
- ('architect-001', 'architect', '{"specializations": ["system-design", "ddd"], "tasks_completed": 28}'),
- ('tester-001', 'tester', '{"specializations": ["tdd", "integration"], "tasks_completed": 35}'),
- ('security-001', 'security-architect', '{"specializations": ["auth", "crypto"], "tasks_completed": 15}'),
- ('perf-001', 'perf-engineer', '{"specializations": ["database", "caching"], "tasks_completed": 22}')
-ON CONFLICT (agent_id) DO UPDATE SET last_active = NOW();
-
--- Insert sample patterns
-INSERT INTO claude_flow.patterns (name, pattern_type, description, confidence) VALUES
- ('jwt-refresh-rotation', 'security', 'JWT with secure refresh token rotation', 0.92),
- ('hnsw-search-pattern', 'performance', 'HNSW index for vector similarity search', 0.95),
- ('tdd-london-mocks', 'testing', 'London School TDD with mocks first', 0.85),
- ('hierarchical-swarm', 'coordination', 'Anti-drift hierarchical swarm topology', 0.90),
- ('gnn-message-passing', 'ai', 'GNN message aggregation pattern', 0.88)
-ON CONFLICT DO NOTHING;
-
--- ============================================
--- COMPLETION
--- ============================================
-
-DO $$
-DECLARE
- v_version TEXT;
- v_simd TEXT;
-BEGIN
- SELECT ruvector_version() INTO v_version;
- SELECT ruvector_simd_info() INTO v_simd;
-
- RAISE NOTICE '';
- RAISE NOTICE '============================================';
- RAISE NOTICE 'RuVector PostgreSQL Initialization Complete!';
- RAISE NOTICE '============================================';
- RAISE NOTICE '';
- RAISE NOTICE 'RuVector Version: %', v_version;
- RAISE NOTICE 'SIMD: %', v_simd;
- RAISE NOTICE '';
- RAISE NOTICE 'Schema: claude_flow';
- RAISE NOTICE 'Tables: embeddings, patterns, agents, trajectories,';
- RAISE NOTICE ' hyperbolic_embeddings, graph_nodes, graph_edges';
- RAISE NOTICE 'Indices: 5 HNSW indices created';
- RAISE NOTICE '';
- RAISE NOTICE 'Key Functions:';
- RAISE NOTICE ' - claude_flow.search_similar(embedding, limit, min_sim)';
- RAISE NOTICE ' - claude_flow.search_patterns(embedding, type, limit)';
- RAISE NOTICE ' - claude_flow.find_agents(embedding, type, limit)';
- RAISE NOTICE ' - claude_flow.hyperbolic_search(embedding, limit, curvature)';
- RAISE NOTICE ' - claude_flow.cosine_similarity(a, b)';
- RAISE NOTICE '';
- RAISE NOTICE 'Operators: <=> (cosine), <-> (L2), <#> (neg inner product)';
- RAISE NOTICE '';
-END $$;
diff --git a/docs/ruvector-postgres/scripts/run-migrations.sh b/docs/ruvector-postgres/scripts/run-migrations.sh
deleted file mode 100755
index f3036a99f6..0000000000
--- a/docs/ruvector-postgres/scripts/run-migrations.sh
+++ /dev/null
@@ -1,59 +0,0 @@
-#!/bin/bash
-# Run RuVector PostgreSQL migrations
-
-set -e
-
-HOST="${PGHOST:-localhost}"
-PORT="${PGPORT:-5432}"
-DATABASE="${PGDATABASE:-claude_flow}"
-USER="${PGUSER:-claude}"
-PASSWORD="${PGPASSWORD:-claude-flow-test}"
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
-MIGRATIONS_DIR="$PROJECT_ROOT/v3/@claude-flow/plugins/src/integrations/ruvector/migrations"
-
-echo "πŸš€ Running RuVector PostgreSQL Migrations"
-echo "=========================================="
-echo ""
-echo "Host: $HOST:$PORT"
-echo "Database: $DATABASE"
-echo "User: $USER"
-echo "Migrations: $MIGRATIONS_DIR"
-echo ""
-
-# Check if migrations directory exists
-if [ ! -d "$MIGRATIONS_DIR" ]; then
- echo "❌ Migrations directory not found: $MIGRATIONS_DIR"
- echo ""
- echo "Trying to use CLI instead..."
- npx claude-flow@alpha ruvector migrate \
- --host $HOST \
- --port $PORT \
- --database $DATABASE \
- --user $USER \
- --up
- exit $?
-fi
-
-# Run each migration in order
-for migration in $(ls -1 "$MIGRATIONS_DIR"/*.sql 2>/dev/null | sort); do
- filename=$(basename "$migration")
- echo "πŸ“„ Running: $filename"
-
- PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -f "$migration" 2>&1 | \
- grep -v "^$" | while read line; do
- echo " $line"
- done
-
- if [ ${PIPESTATUS[0]} -eq 0 ]; then
- echo " βœ… Complete"
- else
- echo " ❌ Failed"
- exit 1
- fi
- echo ""
-done
-
-echo "=========================================="
-echo "βœ… All migrations complete!"
diff --git a/docs/ruvector-postgres/scripts/test-connection.sh b/docs/ruvector-postgres/scripts/test-connection.sh
deleted file mode 100755
index f0e9633a54..0000000000
--- a/docs/ruvector-postgres/scripts/test-connection.sh
+++ /dev/null
@@ -1,175 +0,0 @@
-#!/bin/bash
-# Test connection to RuVector PostgreSQL
-#
-# Tests:
-# - Basic connection
-# - RuVector extension
-# - Schema and tables
-# - HNSW indices
-# - Local embedding generation
-# - Sample data
-
-set -e
-
-HOST="${PGHOST:-localhost}"
-PORT="${PGPORT:-5432}"
-DATABASE="${PGDATABASE:-claude_flow}"
-USER="${PGUSER:-claude}"
-PASSWORD="${PGPASSWORD:-claude-flow-test}"
-
-echo "============================================"
-echo "RuVector PostgreSQL Connection Test"
-echo "============================================"
-echo ""
-echo "Host: $HOST:$PORT"
-echo "Database: $DATABASE"
-echo "User: $USER"
-echo ""
-
-# 1. Test basic connection
-echo "1. Testing connection..."
-PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -c "SELECT 1;" > /dev/null 2>&1
-if [ $? -eq 0 ]; then
- echo " βœ… Connection successful"
-else
- echo " ❌ Connection failed"
- exit 1
-fi
-
-# 2. Check PostgreSQL version
-echo ""
-echo "2. PostgreSQL version:"
-PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -t -c "SELECT version();" | head -1 | xargs
-
-# 3. Check RuVector extension
-echo ""
-echo "3. Checking RuVector extension..."
-RESULT=$(PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -t -c \
- "SELECT extversion FROM pg_extension WHERE extname = 'ruvector';" 2>/dev/null | tr -d ' ')
-if [ -n "$RESULT" ]; then
- echo " βœ… RuVector version: $RESULT"
-else
- # Fallback to check for vector extension (pgvector compatibility)
- RESULT=$(PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -t -c \
- "SELECT extversion FROM pg_extension WHERE extname = 'vector';" 2>/dev/null | tr -d ' ')
- if [ -n "$RESULT" ]; then
- echo " ⚠️ pgvector found (version: $RESULT) - RuVector not installed"
- echo " Consider using ruvector/postgres:latest for full features"
- else
- echo " ❌ No vector extension found"
- fi
-fi
-
-# 4. Check schema
-echo ""
-echo "4. Checking claude_flow schema..."
-RESULT=$(PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -t -c \
- "SELECT COUNT(*) FROM information_schema.schemata WHERE schema_name = 'claude_flow';" | tr -d ' ')
-if [ "$RESULT" = "1" ]; then
- echo " βœ… Schema exists"
-else
- echo " ❌ Schema not found"
-fi
-
-# 5. Check tables
-echo ""
-echo "5. Checking tables..."
-TABLES=$(PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -t -c \
- "SELECT table_name FROM information_schema.tables WHERE table_schema = 'claude_flow' ORDER BY table_name;" | tr -d ' ' | grep -v "^$")
-for table in $TABLES; do
- echo " βœ… Table: $table"
-done
-
-# 6. Check HNSW indices
-echo ""
-echo "6. Checking HNSW indices..."
-INDICES=$(PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -t -c \
- "SELECT indexname FROM pg_indexes WHERE schemaname = 'claude_flow' AND (indexdef LIKE '%hnsw%' OR indexdef LIKE '%ruvector_hnsw%');" | tr -d ' ' | grep -v "^$")
-if [ -n "$INDICES" ]; then
- for idx in $INDICES; do
- echo " βœ… Index: $idx"
- done
-else
- echo " ⚠️ No HNSW indices found"
-fi
-
-# 7. Test local embedding generation
-echo ""
-echo "7. Testing local embedding generation..."
-RESULT=$(PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -t -c \
- "SELECT CASE WHEN ruvector.fastembed('test', 'all-MiniLM-L6-v2') IS NOT NULL THEN 'success' ELSE 'failed' END;" 2>/dev/null | tr -d ' ')
-if [ "$RESULT" = "success" ]; then
- echo " βœ… Local embedding generation works"
-else
- # Try with basic vector function as fallback
- echo " ⚠️ ruvector.fastembed not available"
- echo " (May need full RuVector extension)"
-fi
-
-# 8. Count sample data
-echo ""
-echo "8. Sample data counts:"
-
-COUNT=$(PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -t -c \
- "SELECT COUNT(*) FROM claude_flow.embeddings;" 2>/dev/null | tr -d ' ')
-echo " πŸ“Š Embeddings: ${COUNT:-0} rows"
-
-COUNT=$(PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -t -c \
- "SELECT COUNT(*) FROM claude_flow.patterns;" 2>/dev/null | tr -d ' ')
-echo " πŸ“Š Patterns: ${COUNT:-0} rows"
-
-COUNT=$(PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -t -c \
- "SELECT COUNT(*) FROM claude_flow.agents;" 2>/dev/null | tr -d ' ')
-echo " πŸ“Š Agents: ${COUNT:-0} rows"
-
-# 9. Check RuVector-specific features
-echo ""
-echo "9. RuVector feature availability:"
-
-# Check for attention functions
-PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -t -c \
- "SELECT ruvector.softmax_attention(NULL::ruvector.vector(384), NULL::ruvector.vector(384), 1.0);" > /dev/null 2>&1
-if [ $? -eq 0 ]; then
- echo " βœ… Attention mechanisms"
-else
- echo " ⚠️ Attention mechanisms not available"
-fi
-
-# Check for hyperbolic functions
-PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -t -c \
- "SELECT ruvector.exp_map_poincare(NULL::ruvector.vector(384), -1.0);" > /dev/null 2>&1
-if [ $? -eq 0 ]; then
- echo " βœ… Hyperbolic embeddings"
-else
- echo " ⚠️ Hyperbolic embeddings not available"
-fi
-
-# Check for GNN functions
-PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -t -c \
- "SELECT ruvector.gnn_aggregate(NULL::ruvector.vector(384)[], 'mean');" > /dev/null 2>&1
-if [ $? -eq 0 ]; then
- echo " βœ… GNN operations"
-else
- echo " ⚠️ GNN operations not available"
-fi
-
-# Check for self-learning
-PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -t -c \
- "SELECT ruvector.learn_optimize('claude_flow.embeddings', 'embedding');" > /dev/null 2>&1
-if [ $? -eq 0 ]; then
- echo " βœ… Self-learning optimization"
-else
- echo " ⚠️ Self-learning not available"
-fi
-
-echo ""
-echo "============================================"
-echo "βœ… Connection test complete!"
-echo "============================================"
-echo ""
-echo "Connection string:"
-echo " postgresql://$USER:****@$HOST:$PORT/$DATABASE"
-echo ""
-echo "To run example queries:"
-echo " psql postgresql://$USER@$HOST:$PORT/$DATABASE -f examples/basic-queries.sql"
-echo ""
diff --git a/docs/ruvector-postgres/tests/benchmark.sh b/docs/ruvector-postgres/tests/benchmark.sh
deleted file mode 100755
index 8e1be87d2d..0000000000
--- a/docs/ruvector-postgres/tests/benchmark.sh
+++ /dev/null
@@ -1,180 +0,0 @@
-#!/bin/bash
-# RuVector PostgreSQL Performance Benchmarks
-#
-# Measures:
-# - Search latency (HNSW)
-# - Insert throughput
-# - Local embedding generation
-# - Attention computation
-
-set -e
-
-HOST="${PGHOST:-localhost}"
-PORT="${PGPORT:-5432}"
-DATABASE="${PGDATABASE:-claude_flow}"
-USER="${PGUSER:-claude}"
-PASSWORD="${PGPASSWORD:-claude-flow-test}"
-
-ITERATIONS="${1:-100}"
-
-echo "============================================"
-echo "RuVector PostgreSQL Benchmarks"
-echo "============================================"
-echo ""
-echo "Host: $HOST:$PORT"
-echo "Database: $DATABASE"
-echo "Iterations: $ITERATIONS"
-echo ""
-
-# Helper to run SQL with timing
-run_timed() {
- local name="$1"
- local sql="$2"
- local iterations="${3:-$ITERATIONS}"
-
- echo "Benchmarking: $name"
-
- local start=$(date +%s%N)
-
- for ((i=1; i<=iterations; i++)); do
- PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -t -c "$sql" > /dev/null 2>&1
- done
-
- local end=$(date +%s%N)
- local total_ms=$(( (end - start) / 1000000 ))
- local avg_ms=$(echo "scale=3; $total_ms / $iterations" | bc)
-
- echo " Total: ${total_ms}ms for $iterations iterations"
- echo " Average: ${avg_ms}ms per operation"
- echo ""
-}
-
-# ============================================
-# 1. SEARCH LATENCY
-# ============================================
-
-echo "============================================"
-echo "1. HNSW Search Latency"
-echo "============================================"
-
-run_timed "Simple similarity search" \
- "SELECT id FROM claude_flow.embeddings WHERE embedding IS NOT NULL ORDER BY embedding <-> ruvector.fastembed('test query', 'all-MiniLM-L6-v2') LIMIT 10"
-
-run_timed "Search with threshold" \
- "SELECT id, content FROM claude_flow.embeddings WHERE embedding IS NOT NULL AND ruvector.cosine_similarity(embedding, ruvector.fastembed('test', 'all-MiniLM-L6-v2')) > 0.5 ORDER BY embedding <-> ruvector.fastembed('test', 'all-MiniLM-L6-v2') LIMIT 10"
-
-# ============================================
-# 2. EMBEDDING GENERATION
-# ============================================
-
-echo "============================================"
-echo "2. Local Embedding Generation"
-echo "============================================"
-
-run_timed "Single embedding (384-dim)" \
- "SELECT ruvector.fastembed('This is a test sentence for embedding generation', 'all-MiniLM-L6-v2')" \
- 50
-
-# ============================================
-# 3. INSERT THROUGHPUT
-# ============================================
-
-echo "============================================"
-echo "3. Insert Throughput"
-echo "============================================"
-
-# Clean up test data first
-PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -c \
- "DELETE FROM claude_flow.embeddings WHERE metadata->>'benchmark' = 'true'" > /dev/null 2>&1
-
-echo "Inserting $ITERATIONS embeddings..."
-local start=$(date +%s%N)
-
-for ((i=1; i<=ITERATIONS; i++)); do
- PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -t -c \
- "INSERT INTO claude_flow.embeddings (content, embedding, metadata) VALUES ('Benchmark content $i', ruvector.fastembed('Benchmark content $i', 'all-MiniLM-L6-v2'), '{\"benchmark\": true}'::jsonb)" > /dev/null 2>&1
-done
-
-local end=$(date +%s%N)
-local total_ms=$(( (end - start) / 1000000 ))
-local rate=$(echo "scale=1; $ITERATIONS * 1000 / $total_ms" | bc)
-
-echo " Total: ${total_ms}ms for $ITERATIONS inserts"
-echo " Rate: ${rate} inserts/second"
-echo ""
-
-# Clean up
-PGPASSWORD=$PASSWORD psql -h $HOST -p $PORT -U $USER -d $DATABASE -c \
- "DELETE FROM claude_flow.embeddings WHERE metadata->>'benchmark' = 'true'" > /dev/null 2>&1
-
-# ============================================
-# 4. DISTANCE CALCULATIONS
-# ============================================
-
-echo "============================================"
-echo "4. Distance Calculations"
-echo "============================================"
-
-run_timed "Cosine similarity" \
- "SELECT ruvector.cosine_similarity(ruvector.fastembed('hello', 'all-MiniLM-L6-v2'), ruvector.fastembed('world', 'all-MiniLM-L6-v2'))" \
- 50
-
-run_timed "Euclidean distance" \
- "SELECT ruvector.euclidean_distance(ruvector.fastembed('hello', 'all-MiniLM-L6-v2'), ruvector.fastembed('world', 'all-MiniLM-L6-v2'))" \
- 50
-
-run_timed "Dot product" \
- "SELECT ruvector.dot_product(ruvector.fastembed('hello', 'all-MiniLM-L6-v2'), ruvector.fastembed('world', 'all-MiniLM-L6-v2'))" \
- 50
-
-# ============================================
-# 5. ATTENTION MECHANISMS
-# ============================================
-
-echo "============================================"
-echo "5. Attention Mechanisms"
-echo "============================================"
-
-run_timed "Softmax attention" \
- "SELECT ruvector.softmax_attention(ruvector.fastembed('query', 'all-MiniLM-L6-v2'), ruvector.fastembed('key', 'all-MiniLM-L6-v2'), 1.0)" \
- 50
-
-run_timed "Multi-head attention (8 heads)" \
- "SELECT ruvector.multihead_attention_aggregate(ruvector.fastembed('query', 'all-MiniLM-L6-v2'), ruvector.fastembed('key', 'all-MiniLM-L6-v2'), 8)" \
- 50
-
-# ============================================
-# 6. HYPERBOLIC OPERATIONS
-# ============================================
-
-echo "============================================"
-echo "6. Hyperbolic Operations"
-echo "============================================"
-
-run_timed "PoincarΓ© mapping" \
- "SELECT ruvector.exp_map_poincare(ruvector.fastembed('test', 'all-MiniLM-L6-v2'), -1.0)" \
- 50
-
-run_timed "Hyperbolic distance" \
- "SELECT ruvector.hyperbolic_distance(ruvector.exp_map_poincare(ruvector.fastembed('a', 'all-MiniLM-L6-v2'), -1.0), ruvector.exp_map_poincare(ruvector.fastembed('b', 'all-MiniLM-L6-v2'), -1.0), 'poincare', -1.0)" \
- 50
-
-# ============================================
-# SUMMARY
-# ============================================
-
-echo "============================================"
-echo "Benchmark Complete"
-echo "============================================"
-echo ""
-echo "Expected performance:"
-echo " - HNSW Search: ~61Β΅s (k=10, 384-dim)"
-echo " - Throughput: 16,400 QPS"
-echo " - Insert Rate: 10,000+/sec with batching"
-echo ""
-echo "Note: Actual performance depends on:"
-echo " - Data volume"
-echo " - Index build status"
-echo " - Hardware (SIMD support)"
-echo " - Connection overhead"
-echo ""
diff --git a/docs/ruvector-postgres/tests/test-vectors.ts b/docs/ruvector-postgres/tests/test-vectors.ts
deleted file mode 100644
index 4e6e40aa5a..0000000000
--- a/docs/ruvector-postgres/tests/test-vectors.ts
+++ /dev/null
@@ -1,416 +0,0 @@
-/**
- * RuVector PostgreSQL Test Suite
- *
- * Tests for RuVector PostgreSQL extension integration
- * with Claude-Flow V3.
- *
- * Run: npx ts-node tests/test-vectors.ts
- */
-
-import { Pool, PoolClient } from 'pg';
-
-// Configuration
-const config = {
- host: process.env.PGHOST || 'localhost',
- port: parseInt(process.env.PGPORT || '5432'),
- database: process.env.PGDATABASE || 'claude_flow',
- user: process.env.PGUSER || 'claude',
- password: process.env.PGPASSWORD || 'claude-flow-test',
-};
-
-// Test results tracking
-interface TestResult {
- name: string;
- passed: boolean;
- duration: number;
- error?: string;
-}
-
-const results: TestResult[] = [];
-
-// Helper to run a test
-async function runTest(
- name: string,
- testFn: (client: PoolClient) => Promise<void>
-): Promise<void> {
- const pool = new Pool(config);
- const client = await pool.connect();
- const start = Date.now();
-
- try {
- await testFn(client);
- results.push({
- name,
- passed: true,
- duration: Date.now() - start,
- });
- console.log(`βœ… ${name} (${Date.now() - start}ms)`);
- } catch (error) {
- results.push({
- name,
- passed: false,
- duration: Date.now() - start,
- error: error instanceof Error ? error.message : String(error),
- });
- console.log(`❌ ${name}: ${error}`);
- } finally {
- client.release();
- await pool.end();
- }
-}
-
-// ============================================
-// TESTS
-// ============================================
-
-async function testConnection(client: PoolClient): Promise<void> {
- const result = await client.query('SELECT 1 AS connected');
- if (result.rows[0].connected !== 1) {
- throw new Error('Connection test failed');
- }
-}
-
-async function testRuVectorExtension(client: PoolClient): Promise<void> {
- const result = await client.query(`
- SELECT extname, extversion
- FROM pg_extension
- WHERE extname = 'ruvector'
- `);
- if (result.rows.length === 0) {
- throw new Error('RuVector extension not installed');
- }
-}
-
-async function testSchemaExists(client: PoolClient): Promise<void> {
- const result = await client.query(`
- SELECT schema_name
- FROM information_schema.schemata
- WHERE schema_name = 'claude_flow'
- `);
- if (result.rows.length === 0) {
- throw new Error('claude_flow schema not found');
- }
-}
-
-async function testTablesExist(client: PoolClient): Promise<void> {
- const tables = [
- 'embeddings',
- 'patterns',
- 'agents',
- 'trajectories',
- 'hyperbolic_embeddings',
- 'graph_nodes',
- 'graph_edges',
- ];
-
- for (const table of tables) {
- const result = await client.query(`
- SELECT table_name
- FROM information_schema.tables
- WHERE table_schema = 'claude_flow' AND table_name = $1
- `, [table]);
- if (result.rows.length === 0) {
- throw new Error(`Table ${table} not found`);
- }
- }
-}
-
-async function testHNSWIndices(client: PoolClient): Promise<void> {
- const result = await client.query(`
- SELECT indexname
- FROM pg_indexes
- WHERE schemaname = 'claude_flow'
- AND indexdef LIKE '%ruvector_hnsw%'
- `);
- if (result.rows.length === 0) {
- throw new Error('No HNSW indices found');
- }
-}
-
-async function testLocalEmbedding(client: PoolClient): Promise<void> {
- const result = await client.query(`
- SELECT ruvector.fastembed('test text', 'all-MiniLM-L6-v2') AS embedding
- `);
- if (!result.rows[0].embedding) {
- throw new Error('Local embedding generation failed');
- }
- // Check dimension
- const dimResult = await client.query(`
- SELECT array_length(ruvector.fastembed('test', 'all-MiniLM-L6-v2')::float[], 1) AS dim
- `);
- if (dimResult.rows[0].dim !== 384) {
- throw new Error(`Expected 384 dimensions, got ${dimResult.rows[0].dim}`);
- }
-}
-
-async function testCosineSimilarity(client: PoolClient): Promise<void> {
- const result = await client.query(`
- SELECT ruvector.cosine_similarity(
- ruvector.fastembed('hello world', 'all-MiniLM-L6-v2'),
- ruvector.fastembed('hello world', 'all-MiniLM-L6-v2')
- ) AS similarity
- `);
- const similarity = parseFloat(result.rows[0].similarity);
- if (similarity < 0.99) {
- throw new Error(`Expected similarity ~1.0, got ${similarity}`);
- }
-}
-
-async function testSimilaritySearch(client: PoolClient): Promise<void> {
- // Insert test data
- await client.query(`
- INSERT INTO claude_flow.embeddings (content, embedding, metadata)
- VALUES (
- 'test search content',
- ruvector.fastembed('test search content', 'all-MiniLM-L6-v2'),
- '{"test": true}'::jsonb
- )
- ON CONFLICT DO NOTHING
- `);
-
- // Search
- const result = await client.query(`
- SELECT content, ruvector.cosine_similarity(
- embedding,
- ruvector.fastembed('search content', 'all-MiniLM-L6-v2')
- ) AS similarity
- FROM claude_flow.embeddings
- WHERE embedding IS NOT NULL
- ORDER BY embedding <-> ruvector.fastembed('search content', 'all-MiniLM-L6-v2')
- LIMIT 1
- `);
-
- if (result.rows.length === 0) {
- throw new Error('Search returned no results');
- }
-}
-
-async function testAttentionFunctions(client: PoolClient): Promise<void> {
- const result = await client.query(`
- SELECT ruvector.softmax_attention(
- ruvector.fastembed('query', 'all-MiniLM-L6-v2'),
- ruvector.fastembed('key', 'all-MiniLM-L6-v2'),
- 1.0
- ) AS attention
- `);
- if (result.rows[0].attention === null) {
- throw new Error('Attention function failed');
- }
-}
-
-async function testMultiHeadAttention(client: PoolClient): Promise<void> {
- const result = await client.query(`
- SELECT ruvector.multihead_attention_aggregate(
- ruvector.fastembed('query text', 'all-MiniLM-L6-v2'),
- ruvector.fastembed('key text', 'all-MiniLM-L6-v2'),
- 8
- ) AS attention
- `);
- if (result.rows[0].attention === null) {
- throw new Error('Multi-head attention function failed');
- }
-}
-
-async function testHyperbolicOperations(client: PoolClient): Promise<void> {
- const result = await client.query(`
- SELECT ruvector.exp_map_poincare(
- ruvector.fastembed('test', 'all-MiniLM-L6-v2'),
- -1.0
- ) AS poincare
- `);
- if (!result.rows[0].poincare) {
- throw new Error('PoincarΓ© mapping failed');
- }
-}
-
-async function testSparseVector(client: PoolClient): Promise<void> {
- // This tests BM25 scoring if sparse vectors are supported
- try {
- const result = await client.query(`
- SELECT ruvector.bm25_score(
- null::ruvector.sparse_vector,
- 'test query'
- ) AS score
- `);
- // Score should be 0 for null sparse vector
- } catch (error) {
- // Sparse vectors might not be populated in test data
- console.log(' (sparse vector test skipped - no sparse data)');
- }
-}
-
-async function testAgentMemory(client: PoolClient): Promise<void> {
- // Insert test agent
- await client.query(`
- INSERT INTO claude_flow.agents (agent_id, agent_type, state, memory_embedding)
- VALUES (
- 'test-agent-001',
- 'tester',
- '{"test": true}'::jsonb,
- ruvector.fastembed('testing agent memory', 'all-MiniLM-L6-v2')
- )
- ON CONFLICT (agent_id) DO UPDATE SET
- memory_embedding = EXCLUDED.memory_embedding,
- last_active = NOW()
- `);
-
- // Search by memory similarity
- const result = await client.query(`
- SELECT agent_id, ruvector.cosine_similarity(
- memory_embedding,
- ruvector.fastembed('testing', 'all-MiniLM-L6-v2')
- ) AS similarity
- FROM claude_flow.agents
- WHERE agent_id = 'test-agent-001'
- `);
-
- if (result.rows.length === 0 || parseFloat(result.rows[0].similarity) < 0.5) {
- throw new Error('Agent memory search failed');
- }
-}
-
-async function testPatternStorage(client: PoolClient): Promise<void> {
- // Insert test pattern
- await client.query(`
- INSERT INTO claude_flow.patterns (name, description, embedding, pattern_type, confidence)
- VALUES (
- 'test-pattern-001',
- 'Test pattern for unit tests',
- ruvector.fastembed('test pattern unit testing', 'all-MiniLM-L6-v2'),
- 'test',
- 0.9
- )
- ON CONFLICT DO NOTHING
- `);
-
- // Search patterns
- const result = await client.query(`
- SELECT name, confidence
- FROM claude_flow.patterns
- WHERE embedding IS NOT NULL
- AND pattern_type = 'test'
- ORDER BY embedding <-> ruvector.fastembed('testing', 'all-MiniLM-L6-v2')
- LIMIT 1
- `);
-
- if (result.rows.length === 0) {
- throw new Error('Pattern search failed');
- }
-}
-
-async function testSearchFunction(client: PoolClient): Promise<void> {
- const result = await client.query(`
- SELECT * FROM claude_flow.search_similar(
- ruvector.fastembed('development', 'all-MiniLM-L6-v2'),
- 5,
- 0.3
- )
- `);
- // Function should execute without error
- if (result.rows === undefined) {
- throw new Error('search_similar function failed');
- }
-}
-
-async function testSelfLearning(client: PoolClient): Promise<void> {
- try {
- await client.query(`
- SELECT ruvector.learn_optimize('claude_flow.embeddings', 'embedding')
- `);
- } catch (error) {
- // Self-learning might not be available in all versions
- console.log(' (self-learning test skipped - feature may not be available)');
- }
-}
-
-async function testSearchLatency(client: PoolClient): Promise<void> {
- // Warm up
- await client.query(`
- SELECT id FROM claude_flow.embeddings
- WHERE embedding IS NOT NULL
- ORDER BY embedding <-> ruvector.fastembed('test', 'all-MiniLM-L6-v2')
- LIMIT 10
- `);
-
- // Measure latency
- const iterations = 10;
- const start = Date.now();
-
- for (let i = 0; i < iterations; i++) {
- await client.query(`
- SELECT id FROM claude_flow.embeddings
- WHERE embedding IS NOT NULL
- ORDER BY embedding <-> ruvector.fastembed('test query ${i}', 'all-MiniLM-L6-v2')
- LIMIT 10
- `);
- }
-
- const avgLatency = (Date.now() - start) / iterations;
- console.log(` Average search latency: ${avgLatency.toFixed(2)}ms`);
-
- // Should be under 100ms (relaxed for test environment)
- if (avgLatency > 100) {
- console.log(' (Warning: latency higher than expected, may improve with more data/tuning)');
- }
-}
-
-// ============================================
-// MAIN
-// ============================================
-
-async function main(): Promise<void> {
- console.log('');
- console.log('============================================');
- console.log('RuVector PostgreSQL Test Suite');
- console.log('============================================');
- console.log('');
-
- // Run all tests
- await runTest('Connection', testConnection);
- await runTest('RuVector Extension', testRuVectorExtension);
- await runTest('Schema Exists', testSchemaExists);
- await runTest('Tables Exist', testTablesExist);
- await runTest('HNSW Indices', testHNSWIndices);
- await runTest('Local Embedding Generation', testLocalEmbedding);
- await runTest('Cosine Similarity', testCosineSimilarity);
- await runTest('Similarity Search', testSimilaritySearch);
- await runTest('Attention Functions', testAttentionFunctions);
- await runTest('Multi-Head Attention', testMultiHeadAttention);
- await runTest('Hyperbolic Operations', testHyperbolicOperations);
- await runTest('Sparse Vector / BM25', testSparseVector);
- await runTest('Agent Memory', testAgentMemory);
- await runTest('Pattern Storage', testPatternStorage);
- await runTest('search_similar Function', testSearchFunction);
- await runTest('Self-Learning Optimization', testSelfLearning);
- await runTest('Search Latency', testSearchLatency);
-
- // Summary
- console.log('');
- console.log('============================================');
- console.log('Test Summary');
- console.log('============================================');
-
- const passed = results.filter((r) => r.passed).length;
- const failed = results.filter((r) => !r.passed).length;
- const totalDuration = results.reduce((sum, r) => sum + r.duration, 0);
-
- console.log(`Passed: ${passed}`);
- console.log(`Failed: ${failed}`);
- console.log(`Total Duration: ${totalDuration}ms`);
- console.log('');
-
- if (failed > 0) {
- console.log('Failed Tests:');
- results
- .filter((r) => !r.passed)
- .forEach((r) => console.log(` - ${r.name}: ${r.error}`));
- process.exit(1);
- }
-
- console.log('All tests passed! βœ…');
-}
-
-main().catch((error) => {
- console.error('Test suite failed:', error);
- process.exit(1);
-});
diff --git a/docs/ruvector-postgres/tmp.json b/docs/ruvector-postgres/tmp.json
deleted file mode 100644
index e69de29bb2..0000000000
diff --git a/package.json b/package.json
index 0f8740cbcc..83bedf83c0 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "claude-flow",
- "version": "3.5.2",
+ "version": "3.5.3",
"description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
"main": "dist/index.js",
"type": "module",
diff --git a/packages/coflow/bin/coflow.js b/packages/coflow/bin/coflow.js
deleted file mode 100755
index 0b1dd6ac4b..0000000000
--- a/packages/coflow/bin/coflow.js
+++ /dev/null
@@ -1,20 +0,0 @@
-#!/usr/bin/env node
-/**
- * coflow - Shorthand CLI for Claude Flow
- *
- * Delegates all commands to @claude-flow/cli.
- * Usage: npx coflow <command> [options]
- *
- * Auto-detects MCP mode when stdin is piped and no args provided.
- */
-
-import { createRequire } from 'module';
-import { fileURLToPath } from 'url';
-import { dirname, resolve } from 'path';
-
-// Find @claude-flow/cli's entry point
-const require = createRequire(import.meta.url);
-const cliPath = require.resolve('@claude-flow/cli/bin/cli.js');
-
-// Import and run the CLI
-await import(cliPath);
diff --git a/packages/coflow/package.json b/packages/coflow/package.json
deleted file mode 100644
index 4f9bb5d926..0000000000
--- a/packages/coflow/package.json
+++ /dev/null
@@ -1,49 +0,0 @@
-{
- "name": "coflow",
- "version": "3.1.0-alpha.4",
- "description": "CoFlow - Shorthand CLI for Claude Flow. Enterprise AI agent orchestration for Claude Code.",
- "type": "module",
- "bin": {
- "coflow": "./bin/coflow.js"
- },
- "files": [
- "bin/**",
- "README.md",
- "LICENSE"
- ],
- "keywords": [
- "coflow",
- "claude-flow",
- "claude",
- "claude-code",
- "ai-agents",
- "multi-agent",
- "swarm",
- "mcp",
- "orchestration",
- "cli"
- ],
- "author": {
- "name": "RuvNet",
- "email": "[email protected]",
- "url": "https://ruv.io"
- },
- "license": "MIT",
- "homepage": "https://github.com/ruvnet/claude-flow#readme",
- "repository": {
- "type": "git",
- "url": "https://github.com/ruvnet/claude-flow.git"
- },
- "bugs": {
- "url": "https://github.com/ruvnet/claude-flow/issues"
- },
- "dependencies": {
- "@claude-flow/cli": "^3.1.0-alpha.4"
- },
- "engines": {
- "node": ">=20.0.0"
- },
- "publishConfig": {
- "access": "public"
- }
-}
diff --git a/packages/coflow/tmp.json b/packages/coflow/tmp.json
deleted file mode 100644
index e69de29bb2..0000000000
diff --git a/ruflo/package.json b/ruflo/package.json
index 3f6b63c30c..e6f8cce3ef 100644
--- a/ruflo/package.json
+++ b/ruflo/package.json
@@ -1,6 +1,6 @@
{
"name": "ruflo",
- "version": "3.5.2",
+ "version": "3.5.3",
"description": "Ruflo - Enterprise AI agent orchestration platform. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
"main": "bin/ruflo.js",
"type": "module",
diff --git a/v3/@claude-flow/cli/README.md b/v3/@claude-flow/cli/README.md
index bf2b00a1a7..c5444d7481 100644
--- a/v3/@claude-flow/cli/README.md
+++ b/v3/@claude-flow/cli/README.md
@@ -1,8 +1,8 @@
-# 🌊 Ruflo v3: Enterprise AI Orchestration Platform
+# 🌊 RuFlo v3.5: Enterprise AI Orchestration Platform
<div align="center">
-![Ruflo Banner](ruflo/assets/ruFlo.png)
+![Ruflo Banner](ruflo/assets/ruflo-small.jpeg)
@@ -143,7 +143,7 @@ flowchart TB
```bash
# Use RuVector via Ruflo
-npx ruflo@alpha hooks intelligence --status
+npx ruflo@latest hooks intelligence --status
```
</details>
@@ -158,7 +158,7 @@ curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/claude-flow@main/scripts/install.s
curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/claude-flow@main/scripts/install.sh | bash -s -- --full
# Or via npx
-npx ruflo@alpha init --wizard
+npx ruflo@latest init --wizard
```
---
@@ -481,14 +481,14 @@ curl ... | bash -s -- --full
```bash
# Quick start (no install needed)
-npx ruflo@alpha init
+npx ruflo@latest init
# Or install globally
-npm install -g ruflo@alpha
+npm install -g ruflo@latest
ruflo init
# With Bun (faster)
-bunx ruflo@alpha init
+bunx ruflo@latest init
```
#### Install Profiles
@@ -500,7 +500,7 @@ bunx ruflo@alpha init
```bash
# Minimal install (skip ML/embeddings)
-npm install -g ruflo@alpha --omit=optional
+npm install -g ruflo@latest --omit=optional
```
<details>
@@ -512,13 +512,13 @@ Ruflo supports both **Claude Code** and **OpenAI Codex CLI** via the [@claude-fl
```bash
# Initialize for Codex CLI (creates AGENTS.md instead of CLAUDE.md)
-npx ruflo@alpha init --codex
+npx ruflo@latest init --codex
# Full Codex setup with all 137+ skills
-npx ruflo@alpha init --codex --full
+npx ruflo@latest init --codex --full
# Initialize for both platforms (dual mode)
-npx ruflo@alpha init --dual
+npx ruflo@latest init --dual
```
### Platform Comparison
@@ -661,16 +661,16 @@ The **Intelligence Loop** (ADR-050) automates this cycle through hooks. Each ses
```bash
# Initialize project
-npx ruflo@alpha init
+npx ruflo@latest init
# Start MCP server for Claude Code integration
-npx ruflo@alpha mcp start
+npx ruflo@latest mcp start
# Run a task with agents
-npx ruflo@alpha --agent coder --task "Implement user authentication"
+npx ruflo@latest --agent coder --task "Implement user authentication"
# List available agents
-npx ruflo@alpha --list
+npx ruflo@latest --list
```
### Upgrading
@@ -2510,7 +2510,7 @@ Claude Code pipes JSON session data via **stdin** to the statusline script after
**Setup (Automatic):**
-Run `npx ruflo@alpha init` β€” this generates `.claude/settings.json` with the correct statusline config and creates the helper script at `.claude/helpers/statusline.cjs`.
+Run `npx ruflo@latest init` β€” this generates `.claude/settings.json` with the correct statusline config and creates the helper script at `.claude/helpers/statusline.cjs`.
The generated config uses a **fast local script** (no `npx` cold-start):
```json
@@ -2528,7 +2528,7 @@ The generated config uses a **fast local script** (no `npx` cold-start):
If your statusline is not updating, run the upgrade command to regenerate helpers and fix the config:
```bash
-npx ruflo@alpha init --update --settings
+npx ruflo@latest init --update --settings
```
This removes invalid config fields and regenerates the statusline helper with stdin support.
@@ -3030,6 +3030,136 @@ sqlite3 .claude-flow/data/transcript-archive.db \
---
+## πŸ’Ύ Storage: RVF (RuVector Format)
+
+Ruflo uses RVF β€” a compact binary storage format that replaces the 18MB sql.js WASM dependency with pure TypeScript. No native compilation, no WASM downloads, works everywhere Node.js runs.
+
+<details>
+<summary>πŸ’Ύ <strong>RVF Storage</strong> β€” Binary format, vector search, migration, and auto-selection</summary>
+
+### Why RVF?
+
+Previous versions shipped sql.js (18MB WASM blob) for persistent storage. This caused slow cold starts, large installs, and compatibility issues on ARM/Alpine. RVF eliminates all of that:
+
+| | Before (sql.js) | After (RVF) |
+|---|---|---|
+| **Install size** | +18MB WASM | 0 extra deps |
+| **Cold start** | ~2s (WASM compile) | <50ms |
+| **Platform support** | x86/ARM issues | Runs everywhere |
+| **Native deps** | Optional hnswlib-node | Pure TypeScript fallback |
+
+### How it works
+
+RVF files use a simple binary layout: a 4-byte magic header (`RVF\0`), a JSON metadata section, then packed entries. Each module has its own format variant:
+
+| Format | Magic Bytes | Used By | Purpose |
+|--------|-------------|---------|---------|
+| `RVF\0` | `0x52564600` | Memory backend | Entries + HNSW index |
+| `RVEC` | `0x52564543` | Embedding cache | Cached vectors with LRU eviction |
+| `RVFL` | `0x5256464C` | Event log | Append-only domain events |
+| `RVLS` | β€” | Learning store | SONA patterns + trajectories |
+
+### Storage auto-selection
+
+You don't need to pick a backend. The `DatabaseProvider` tries each option in order and uses the first one available:
+
+```
+RVF (pure TypeScript) β†’ better-sqlite3 (native) β†’ sql.js (WASM) β†’ JSON (fallback)
+```
+
+RVF is always available since it has zero dependencies, so it wins by default. If you have `better-sqlite3` installed (e.g., for advanced queries), it gets priority.
+
+### Vector search with HnswLite
+
+RVF includes `HnswLite` β€” a pure TypeScript implementation of the HNSW (Hierarchical Navigable Small World) algorithm for fast nearest-neighbor search. It's used automatically when storing entries with embeddings.
+
+```typescript
+import { RvfBackend } from '@claude-flow/memory';
+
+const backend = new RvfBackend({ databasePath: './memory.rvf' });
+await backend.initialize();
+
+// Store entries β€” embeddings are indexed automatically
+await backend.store({ id: '1', key: 'auth-pattern', content: '...', embedding: vector });
+
+// Search by similarity
+const results = await backend.search({ embedding: queryVector, limit: 10 });
+```
+
+Supports cosine, dot product, and Euclidean distance metrics. For large datasets (100K+ entries), install `hnswlib-node` for the native implementation β€” the backend switches automatically.
+
+### Migrating from older formats
+
+The `RvfMigrator` converts between JSON files, SQLite databases, and RVF:
+
+```typescript
+import { RvfMigrator } from '@claude-flow/memory';
+
+// Auto-detect format and migrate
+await RvfMigrator.autoMigrate('./old-memory.db', './memory.rvf');
+
+// Or be explicit
+await RvfMigrator.fromJsonFile('./backup.json', './memory.rvf');
+await RvfMigrator.fromSqlite('./legacy.db', './memory.rvf');
+
+// Export back to JSON for inspection
+await RvfMigrator.toJsonFile('./memory.rvf', './export.json');
+```
+
+Format detection works by reading the first few bytes of the file β€” no file extension guessing.
+
+### Crash safety
+
+All write operations use atomic writes: data goes to a temporary file first, then a single `rename()` call swaps it into place. If the process crashes mid-write, the old file stays intact.
+
+- **Memory backend**: `file.rvf.tmp` β†’ `file.rvf`
+- **Embedding cache**: `file.rvec.tmp.{random}` β†’ `file.rvec`
+- **Event log**: Append-only (no overwrite needed)
+
+### SONA learning persistence
+
+The `PersistentSonaCoordinator` stores learning patterns and trajectories in RVF format, so agents retain knowledge across sessions:
+
+```typescript
+import { PersistentSonaCoordinator } from '@claude-flow/memory';
+
+const sona = new PersistentSonaCoordinator({
+ storePath: './data/sona-learning.rvls',
+});
+await sona.initialize();
+
+// Patterns survive restarts
+const similar = sona.findSimilarPatterns(embedding, 5);
+sona.storePattern('routing', embedding);
+await sona.shutdown(); // persists to disk
+```
+
+### Security
+
+RVF validates inputs at every boundary:
+
+- **Path validation** β€” null bytes and traversal attempts are rejected
+- **Header validation** β€” corrupted files are detected before parsing
+- **Payload limits** β€” event log entries cap at 100MB to prevent memory exhaustion
+- **Dimension validation** β€” embedding dimensions must be between 1 and 10,000
+- **Concurrent write protection** β€” a lock flag prevents overlapping disk flushes
+
+### Configuration
+
+```bash
+# Environment variables
+CLAUDE_FLOW_MEMORY_BACKEND=hybrid # auto-selects RVF
+CLAUDE_FLOW_MEMORY_PATH=./data/memory
+
+# Or via CLI
+ruflo memory init --force
+ruflo config set memory.backend hybrid
+```
+
+</details>
+
+---
+
## 🧠 Intelligence & Learning
Self-learning hooks, pattern recognition, and intelligent task routing.
@@ -4279,21 +4409,21 @@ console.log(results);
**CLI Commands:**
```bash
# Initialize memory database
-npx ruflo@alpha memory init --force
+npx ruflo@latest memory init --force
# Store patterns
-npx ruflo@alpha memory store --key "pattern-auth" --value "JWT authentication with refresh tokens"
-npx ruflo@alpha memory store --key "pattern-cache" --value "Redis caching for API responses"
+npx ruflo@latest memory store --key "pattern-auth" --value "JWT authentication with refresh tokens"
+npx ruflo@latest memory store --key "pattern-cache" --value "Redis caching for API responses"
# Build HNSW index for 150x-12,500x faster search
-npx ruflo@alpha memory search --query "authentication" --build-hnsw
+npx ruflo@latest memory search --query "authentication" --build-hnsw
# Semantic search (uses HNSW if built)
-npx ruflo@alpha memory search --query "how to cache data" --limit 5
+npx ruflo@latest memory search --query "how to cache data" --limit 5
# List and manage entries
-npx ruflo@alpha memory list --namespace patterns
-npx ruflo@alpha memory stats
+npx ruflo@latest memory list --namespace patterns
+npx ruflo@latest memory stats
```
</details>
@@ -5973,7 +6103,7 @@ Domain-Driven Design with bounded contexts, clean architecture, and measured per
| Module | Purpose | Key Features |
|--------|---------|--------------|
| `@claude-flow/hooks` | Event-driven lifecycle | ReasoningBank, 27 hooks, pattern learning |
-| `@claude-flow/memory` | Unified vector storage | AgentDB, HNSW indexing, 150x faster search, LearningBridge, MemoryGraph, AgentMemoryScope |
+| `@claude-flow/memory` | Unified vector storage | AgentDB, RVF binary format, HnswLite, RvfMigrator, SONA persistence, LearningBridge, MemoryGraph |
| `@claude-flow/security` | CVE remediation | Input validation, path security, AIDefence |
| `@claude-flow/swarm` | Multi-agent coordination | 6 topologies, Byzantine consensus, auto-scaling |
| `@claude-flow/plugins` | WASM extensions | RuVector plugins, semantic search, intent routing |
@@ -5981,7 +6111,7 @@ Domain-Driven Design with bounded contexts, clean architecture, and measured per
| `@claude-flow/neural` | Self-learning | SONA, 9 RL algorithms, EWC++ memory preservation |
| `@claude-flow/testing` | Quality assurance | London School TDD, Vitest, fixtures, mocks |
| `@claude-flow/deployment` | Release automation | Versioning, changelogs, NPM publishing |
-| `@claude-flow/shared` | Common utilities | Types, validation schemas, constants |
+| `@claude-flow/shared` | Common utilities | Types, validation schemas, RvfEventLog, constants |
| `@claude-flow/browser` | Browser automation | 59 MCP tools, element refs, trajectory learning |
### Architecture Principles
diff --git a/v3/@claude-flow/cli/package.json b/v3/@claude-flow/cli/package.json
index 734e80c1af..e5776d6469 100644
--- a/v3/@claude-flow/cli/package.json
+++ b/v3/@claude-flow/cli/package.json
@@ -1,6 +1,6 @@
{
"name": "@claude-flow/cli",
- "version": "3.5.2",
+ "version": "3.5.3",
"type": "module",
"description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
"main": "dist/src/index.js",
diff --git a/v3/implementation/adrs/ADR-059-bug-triage-2026-03.md b/v3/implementation/adrs/ADR-059-bug-triage-2026-03.md
index 8367c0f983..8f05f4245a 100644
--- a/v3/implementation/adrs/ADR-059-bug-triage-2026-03.md
+++ b/v3/implementation/adrs/ADR-059-bug-triage-2026-03.md
@@ -1,7 +1,7 @@
# ADR-059: Bug Triage & Priority Matrix β€” March 2026
-**Status:** Accepted
-**Date:** 2026-03-05
+**Status:** Accepted β€” Fixes Verified
+**Date:** 2026-03-05 (updated 2026-03-05)
**Author:** claude-flow
## Context
@@ -27,10 +27,11 @@ Note: `@claude-flow/memory` (AgentDB) is now published at `@latest`, which affec
- **Impact:** Supply-chain trust β€” the `preinstall` script in `package.json` silently deletes npm cache entries for `claude-flow` and `ruflo`. This resembles malicious behavior and will trigger security scanners (Socket, Snyk, npm audit).
- **Risk:** Package ban from npm registry; user trust erosion.
- **Fix:** Remove the obfuscated preinstall script entirely. If cache-busting is needed, document it as an explicit post-install step.
+- **Status:** βœ… **FIXED** in PR #1298. Preinstall script removed from root `package.json`. Issue #1261 closed.
### 2. RVF ObjectId cross-package matching failure (Chat UI β€” fixed in #1297)
- **Impact:** All conversation lookups returned wrong data. `findOne({_id})` matched ALL documents because MongoDB's `ObjectId` was treated as an empty operator object by the RVF store.
-- **Status:** Fixed in `feat/ruflo-chat-ui-branding` (merged). Verify no regression.
+- **Status:** βœ… **FIXED** in PR #1297. Added `toHexString` detection and `isObjectIdLike` helper to `rvf.ts`. Verified: two conversations return distinct data via API. No regression.
### 3. Windows: daemon and memory init silently fail (#1282)
- **Impact:** `init --start-all` reports success but creates nothing on Windows. Zero functionality for Windows users.
@@ -48,10 +49,12 @@ Note: `@claude-flow/memory` (AgentDB) is now published at `@latest`, which affec
### 5. Claude Code hooks: misconfigured commands cause silent failures (#1284)
- **Impact:** Generated `settings.json` contains broken hook commands. Users get no feedback β€” hooks silently fail, degrading learning, session management, and intelligence features.
- **Fix:** Validate all hook commands at generation time; add `--dry-run` flag to hooks.
+- **Status:** βœ… **FIXED** in PR #1298. All hook commands in `settings-generator.ts` and `executor.ts` now use `git rev-parse --show-toplevel` for absolute path resolution. Issue #1284 closed.
### 6. Hook commands use relative paths, break when CWD != project root (#1259)
- **Impact:** All hooks break when invoked from subdirectories or IDE integrations that set CWD differently.
- **Fix:** Resolve all hook command paths to absolute paths at generation time using `findRepoRoot()`.
+- **Status:** βœ… **FIXED** in PR #1298. Added `hookCmd()`, `hookCmdEsm()`, `hookHandlerCmd()`, `autoMemoryCmd()` helpers that resolve paths via `git rev-parse --show-toplevel`. Issue #1259 closed.
### 7. auto-memory-hook.mjs fails to resolve @claude-flow/memory (#1287)
- **Impact:** Auto-memory import fails when installed as nested dependency (common in monorepos and npx). Memory persistence across sessions broken.
@@ -62,10 +65,12 @@ Note: `@claude-flow/memory` (AgentDB) is now published at `@latest`, which affec
- **Impact:** AgentDB v3 controllers (ReasoningBank, SkillLibrary, ExplainableRecall) are implemented but never instantiated at runtime. The entire intelligence layer is dead code.
- **Note:** `@claude-flow/memory` (AgentDB) is now published at `@latest`. The export is available but CLI init doesn't wire it.
- **Fix:** Update CLI to `import { ControllerRegistry } from '@claude-flow/memory'` (now on @latest); wire into init sequence.
+- **Status:** βœ… **FIXED** in PR #1298. Added `activateControllerRegistry()` in `memory-initializer.ts` (lines 1089-1139). CLI `memory init` now wires ControllerRegistry singleton, activating ReasoningBank, SkillLibrary, and ExplainableRecall. Issue #1264 closed.
### 9. MCP schema invalid for strict clients β€” array missing `items` (#1294)
- **Impact:** MCP tool schemas fail validation on strict OpenAI-compatible clients. Tools with array parameters are rejected, blocking tool execution for some models.
- **Fix:** Audit all MCP tool schemas; add `items` to every array-type parameter.
+- **Status:** βœ… **FIXED** in PR #1298. Added `items` field to 13 array schemas across 7 MCP tool files (system-tools, github-tools, hooks-tools, coordination-tools, daa-tools, performance-tools). Issue #1294 closed.
### 10. Settings-generator.js missing 13 hooks, 9 env vars, and memory config (#1291)
- **Impact:** Fresh installs get incomplete configuration. 13 hooks never fire, 9 env vars undocumented.
@@ -86,14 +91,17 @@ Note: `@claude-flow/memory` (AgentDB) is now published at `@latest`, which affec
### 13. MCP server and statusline report 'claude-flow' v3.0.0 branding (#1280)
- **Impact:** Confusing branding β€” MCP server still identifies as `claude-flow` v3.0.0 instead of `ruflo` v3.5.x.
- **Fix:** Update MCP server metadata, version string, and statusline template.
+- **Status:** βœ… **FIXED** in PR #1298. MCP `system-tools.ts` now reads version from `package.json` at runtime via `getPackageVersion()`. Branding updated to "RuFlo" across 20+ CLI files. Statusline.cjs updated. Issue #1280 closed.
### 14. Statusline shows 'Claude Flow V3' instead of 'Ruflo V3' (#1254)
- **Impact:** Branding inconsistency in IDE status bar.
- **Fix:** Update statusline configuration defaults.
+- **Status:** βœ… **FIXED** in PR #1298. Updated `statusline.cjs` (lines 3, 552, 619) from "Claude Flow V3" to "RuFlo V3". Updated `settings.json` version to 3.5.2. Issue #1254 closed.
### 15. MCP server version mismatch β€” reports v3.0.0-alpha, package is v3.5.2 (#1253)
- **Impact:** Version confusion for users and integrations checking compatibility.
- **Fix:** Read version from `package.json` at runtime instead of hardcoding.
+- **Status:** βœ… **FIXED** in PR #1298. Replaced hardcoded `'3.0.0-alpha'` with `PKG_VERSION` read from `package.json` via `getPackageVersion()` in `system-tools.ts`. Issue #1253 closed.
### 16. doctor: disk space check reports wrong capacity percentage (#1288)
- **Impact:** Misleading health check output. Low severity but erodes trust in diagnostics.
@@ -114,10 +122,12 @@ Note: `@claude-flow/memory` (AgentDB) is now published at `@latest`, which affec
### 20. Chat UI: web_search sends empty queries β†’ 400 errors
- **Impact:** MCP `web_search` tool invoked with empty `{}` input, returning 400. Observed in runtime logs.
- **Fix:** Validate search query is non-empty before dispatching; return graceful "no query" message.
+- **Status:** βœ… **FIXED** in PR #1298. Added empty-query validation in `mcp-bridge/index.js` `executeTool()` β€” returns graceful MCP-formatted error instead of 400.
### 21. Chat UI: settings duplication in RVF store
- **Impact:** 23+ duplicate settings entries for single session. `findOneAndUpdate` creates new docs instead of updating existing ones due to ObjectId matching issue (same root cause as #2, partially fixed).
- **Fix:** Add deduplication pass on startup; verify `findOneAndUpdate` uses string comparison for `_id`.
+- **Status:** βœ… **FIXED** in PR #1298. Added deduplication pass in `rvf.ts` β€” sorts by `updatedAt`, keeps newest, deletes duplicates. `findOneAndUpdate` now uses string comparison for `_id`.
---
@@ -156,22 +166,63 @@ Note: `@claude-flow/memory` (AgentDB) is now published at `@latest`, which affec
## Summary Matrix
-| Priority | Count | Key Themes |
-|----------|-------|------------|
-| **P0** | 3 | Supply-chain security, data corruption, platform failure |
-| **P1** | 7 | Daemon stability, hooks reliability, MCP compliance, AgentDB wiring |
-| **P2** | 11 | Branding, version strings, CLI UX, Chat UI runtime, neural wiring |
-| **P3** | 9 | Feature requests, enhancements, housekeeping |
+| Priority | Count | Fixed | Remaining | Key Themes |
+|----------|-------|-------|-----------|------------|
+| **P0** | 3 | 2 | 1 | Supply-chain security, data corruption, platform failure |
+| **P1** | 7 | 4 | 3 | Daemon stability, hooks reliability, MCP compliance, AgentDB wiring |
+| **P2** | 11 | 5 | 6 | Branding, version strings, CLI UX, Chat UI runtime, neural wiring |
+| **P3** | 9 | 0 | 9 | Feature requests, enhancements, housekeeping |
+| **Total** | **30** | **11** | **19** | |
+
+## Resolution Log
+
+Fixes delivered in PR #1297 and PR #1298, merged to `main` on 2026-03-05.
+
+### Issues Closed (11)
+
+| # | Issue | PR | Fix Summary |
+|---|-------|----|-------------|
+| 1 | #1261 β€” Obfuscated preinstall | #1298 | Removed preinstall script from root `package.json` |
+| 2 | (Chat UI) β€” RVF ObjectId | #1297 | `toHexString` detection + `isObjectIdLike` helper in `rvf.ts` |
+| 5 | #1284 β€” Hooks silent failures | #1298 | All hook commands use `git rev-parse --show-toplevel` |
+| 6 | #1259 β€” Hooks relative paths | #1298 | `hookCmd()`, `hookCmdEsm()`, `hookHandlerCmd()`, `autoMemoryCmd()` helpers |
+| 8 | #1264 β€” AgentDB ControllerRegistry | #1298 | `activateControllerRegistry()` in `memory-initializer.ts` |
+| 9 | #1294 β€” MCP array missing `items` | #1298 | 13 schemas fixed across 7 MCP tool files |
+| 13 | #1280 β€” MCP branding v3.0.0 | #1298 | `getPackageVersion()` reads from `package.json` at runtime |
+| 14 | #1254 β€” Statusline branding | #1298 | `statusline.cjs` updated to "RuFlo V3" |
+| 15 | #1253 β€” MCP version mismatch | #1298 | Hardcoded `'3.0.0-alpha'` replaced with `PKG_VERSION` |
+| 20 | (Chat UI) β€” Empty web_search | #1298 | Empty-query validation in `mcp-bridge/index.js` |
+| 21 | (Chat UI) β€” Settings duplication | #1298 | Dedup pass on startup + string `_id` comparison |
+
+### Validation Results (2026-03-05)
+
+All fixes validated via Docker-based regression testing:
+
+- βœ… Preinstall script removed (no `preinstall` in `package.json`)
+- βœ… TypeScript compilation clean (`tsc --noEmit`)
+- βœ… Docker build succeeds (all containers healthy)
+- βœ… Conversation isolation verified (two distinct conversations return different data)
+- βœ… MCP bridge healthy (`/health` returns 200)
+- βœ… Empty web_search handled gracefully (no 400 error)
+- βœ… All static assets return 200 (logo, favicons, manifest)
+
+### Remaining Open Issues (19)
+
+**P0 (1):** #1282 Windows daemon/memory init
+**P1 (3):** #1283 macOS daemon, #1287 auto-memory-hook resolution, #1291 settings-generator completeness
+**P2 (6):** #1281 missing MCP tools, #1256 CacheManager unref, #1288 doctor disk space, #1289 stdio status, #1279 zero swarms, #1243 SONA wiring
+**P3 (9):** Feature requests and housekeeping (#1276, #1290, #1238, #1262, #1267, #1268, #1273, #1272, #1236, #1245, #1242, #1251)
## Decision
-1. **Immediately** address P0 items β€” the preinstall script (#1261) is a trust/security emergency.
-2. **This week** fix P1 daemon and hooks issues β€” they block the core value proposition (learning, agents, memory).
-3. **Next sprint** batch P2 branding/version fixes and Chat UI stabilization.
+1. ~~**Immediately** address P0 items~~ β€” βœ… Done (2 of 3). #1282 Windows remains.
+2. ~~**This week** fix P1 hooks/MCP issues~~ β€” βœ… Partially done (4 of 7). Daemon (#1283), auto-memory (#1287), settings-generator (#1291) remain.
+3. ~~**Next sprint** batch P2 branding/version fixes~~ β€” βœ… Partially done (5 of 11). Six P2 items remain.
4. **Backlog** P3 feature requests for roadmap planning.
## Consequences
-- P0 fixes may require an emergency patch release (v3.5.3).
-- P1 fixes should ship as v3.6.0 with improved platform test matrix (Windows CI, macOS CI).
-- The AgentDB wiring gap (#1264) is the single highest-leverage fix β€” now that `@claude-flow/memory` is on @latest, the export is available and just needs CLI wiring. This unblocks the entire intelligence layer.
+- P0/P1/P2 fixes shipped as PR #1297 and PR #1298 (merged to `main`).
+- Remaining P0 item (#1282 Windows) requires platform-specific CI matrix β€” target v3.5.3.
+- Remaining P1 items (#1283, #1287, #1291) should ship as v3.6.0 with macOS CI.
+- The AgentDB wiring gap (#1264) is now **resolved** β€” ControllerRegistry is wired and the intelligence layer is active.
diff --git a/v3/package-lock.json b/v3/package-lock.json
index b8204bbfcf..5c5bc87910 100644
--- a/v3/package-lock.json
+++ b/v3/package-lock.json
@@ -1789,7 +1789,7 @@
}
},
"@claude-flow/cli": {
- "version": "3.5.2",
+ "version": "3.5.3",
"hasInstallScript": true,
"license": "MIT",
"dependencies": {