ruvnet/ruvector repository overview

# 1. Run RuVector
docker run -d --name ruvector -p 5432:5432 ruvnet/ruvector:latest

# 2. Connect to the database
psql -h localhost -U ruvector -d ruvector_db
# Password: ruvector

# 3. Enable RuVector
CREATE EXTENSION ruvector;
SELECT ruvector_version();

User Query → HNSW Index → Top K Results
                ↓
         (never improves)

User Query → HNSW Index → GNN Layer → Enhanced Results
                 ↑                           │
                 │     learns from           │
                 └───── user feedback ───────┘

-- Enable learning mode
SELECT ruvector_enable_learning(true);

-- Record that users found result helpful (0.95 = very helpful)
SELECT ruvector_record_feedback('query_123', 0.95, '{"clicked": true}');

-- Let the system auto-optimize
SELECT ruvector_auto_tune();

                                    ┌─────────────────┐
                                    │  Code Expert    │
                                    │  (Claude 4)     │
                                    └────────▲────────┘
                                             │
User: "Fix this bug" ──→ FastGRNN ──────────┼──→ Best Match!
                         Router              │
                                             │
                                    ┌────────┴────────┐
                                    │  Math Expert    │
                                    │  (Gemini 2.0)   │
                                    └─────────────────┘
                                             │
                                    ┌────────┴────────┐
                                    │  Creative Writer│
                                    │  (Llama 4)      │
                                    └─────────────────┘

-- Register specialized AI agents
SELECT ruvector_register_agent('code_expert', ARRAY['coding', 'debugging']);
SELECT ruvector_register_agent('writer', ARRAY['creative', 'editing']);

-- Route a query to the best agent
SELECT ruvector_route($user_query_embedding);
-- Returns: 'code_expert' for "How do I fix this bug?"

┌─────────────────────────────────────────────────────────────┐
│                      Load Balancer                          │
└─────────────────────────┬───────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
    ┌──────────┐    ┌──────────┐    ┌──────────┐
    │ Node 1   │◄──►│ Node 2   │◄──►│ Node 3   │
    │ (Leader) │    │(Follower)│    │(Follower)│
    └──────────┘    └──────────┘    └──────────┘
          │               │               │
          ▼               ▼               ▼
    ┌──────────┐    ┌──────────┐    ┌──────────┐
    │ Shard A  │    │ Shard B  │    │ Shard C  │
    │ 0-33%    │    │ 33-66%   │    │ 66-100%  │
    └──────────┘    └──────────┘    └──────────┘

    ◄──────── Raft Consensus Protocol ────────►

# Single node (development)
docker run -d -p 5432:5432 ruvnet/ruvector:latest

# Cluster mode (production) - coming in v0.3.0
docker-compose up -d ruvector-cluster
# Automatically shards data across nodes
# Raft consensus ensures consistency

# Full build with all features (default)
docker build -t my-ruvector:full -f docker/Dockerfile .

# Minimal PostgreSQL-only build (no Node.js)
docker build --build-arg INCLUDE_NPM=false \
             -t my-ruvector:minimal -f docker/Dockerfile .

# Custom feature selection
docker build --build-arg PG_VERSION=16 \
             --build-arg INCLUDE_SONA=true \
             --build-arg INCLUDE_RUVLLM=false \
             -t my-ruvector:custom -f docker/Dockerfile .

docker run ruvnet/ruvector:latest printenv | grep RUVECTOR
# RUVECTOR_INCLUDE_NPM=true
# RUVECTOR_INCLUDE_SONA=true
# RUVECTOR_INCLUDE_RUVLLM=true
# RUVECTOR_INCLUDE_CLI=true

SELECT ruvector_l2_distance(a, b);
SELECT ruvector_cosine_distance(a, b);
SELECT ruvector_inner_product(a, b);
SELECT ruvector_l1_distance(a, b);
SELECT ruvector_normalize(embedding);
SELECT ruvector_add(a, b);
SELECT ruvector_sub(a, b);
SELECT ruvector_mul_scalar(vec, 2.0);

SELECT ruvector_poincare_distance(ARRAY[0.1,0.2], ARRAY[0.3,0.4]);
SELECT ruvector_lorentz_distance(a, b);
SELECT ruvector_mobius_add(a, b);
SELECT ruvector_exp_map(base, tangent);
SELECT ruvector_log_map(base, target);
SELECT ruvector_poincare_to_lorentz(vec);
SELECT ruvector_lorentz_to_poincare(vec);
SELECT ruvector_minkowski_dot(a, b);

SELECT ruvector_sparse_dot(a, b);
SELECT ruvector_sparse_cosine(a, b);
SELECT ruvector_sparse_euclidean(a, b);
SELECT ruvector_sparse_manhattan(a, b);
SELECT ruvector_sparse_bm25(query, doc, k1, b);
SELECT ruvector_sparse_norm(vec);
SELECT ruvector_sparse_top_k(vec, k);
SELECT ruvector_to_sparse(indices, values, dim);
SELECT ruvector_sparse_to_dense(sparse, dim);
SELECT ruvector_dense_to_sparse(dense, threshold);

SELECT ruvector_gcn_forward(features, adjacency, weights);
SELECT ruvector_graphsage_forward(features, neighbors, weights);

SELECT ruvector_create_graph('my_graph');
SELECT ruvector_add_node('my_graph', 'Person', '{"name": "Alice"}');
SELECT ruvector_add_edge('my_graph', 1, 2, 'KNOWS', '{}');
SELECT ruvector_cypher('my_graph', 'MATCH (n) RETURN n');
SELECT ruvector_shortest_path('my_graph', 1, 10);
SELECT ruvector_list_graphs();
SELECT ruvector_graph_stats('my_graph');
SELECT ruvector_delete_graph('my_graph');

SELECT ruvector_register_agent('agent_name', ARRAY['cap1', 'cap2']);
SELECT ruvector_register_agent_full(name, capabilities, embedding, metadata);
SELECT ruvector_route(query_embedding);
SELECT ruvector_list_agents();
SELECT ruvector_get_agent('agent_name');
SELECT ruvector_find_agents_by_capability('coding');
SELECT ruvector_set_agent_active('agent_name', true);
SELECT ruvector_update_agent_metrics('agent_name', metrics);
SELECT ruvector_remove_agent('agent_name');
SELECT ruvector_clear_agents();
SELECT ruvector_routing_stats();

SELECT ruvector_enable_learning(true);
SELECT ruvector_record_feedback(query_id, relevance_score, context);
SELECT ruvector_learning_stats();
SELECT ruvector_extract_patterns();
SELECT ruvector_clear_learning();
SELECT ruvector_auto_tune();
SELECT ruvector_get_search_params();

SELECT ruvector_version();
SELECT ruvector_simd_info();
SELECT ruvector_memory_stats();
SELECT ruvector_dims(embedding);
SELECT ruvector_norm(embedding);

CREATE EXTENSION ruvector;

-- Store documents with their embeddings
CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    title TEXT,
    embedding ruvector(1536)  -- 1536 dimensions for OpenAI embeddings
);

INSERT INTO documents (title, embedding) VALUES
    ('AI Guide', '[0.1, 0.2, ...]'::ruvector);

-- Create HNSW index for blazing fast searches
CREATE INDEX ON documents USING hnsw (embedding ruvector_l2_ops);

-- Find the 10 most similar documents to your query
SELECT title, embedding <-> $query AS distance
FROM documents ORDER BY distance LIMIT 10;

-- Score = 70% semantic similarity + 30% keyword match (BM25)
SELECT title,
    0.7 * (1.0 / (1.0 + embedding <-> $query_vec)) +
    0.3 * ruvector_sparse_bm25(terms, doc_terms, 1.2, 0.75) AS score
FROM documents ORDER BY score DESC LIMIT 10;

-- Store taxonomy nodes with Poincaré embeddings
CREATE TABLE taxonomy (
    id SERIAL PRIMARY KEY,
    name TEXT,
    parent_id INTEGER,
    embedding ruvector(128)  -- Trained in hyperbolic space
);

-- Find nodes closest in the hierarchy using hyperbolic distance
SELECT name, ruvector_poincare_distance(
    (SELECT embedding FROM taxonomy WHERE id = 1),
    embedding
) AS distance
FROM taxonomy ORDER BY distance LIMIT 10;

-- Register your specialized AI agents with their capabilities
SELECT ruvector_register_agent('code_expert', ARRAY['coding', 'debugging', 'refactoring']);
SELECT ruvector_register_agent('math_expert', ARRAY['math', 'statistics', 'calculus']);
SELECT ruvector_register_agent('writer', ARRAY['writing', 'editing', 'storytelling']);

-- When a user asks a question, find the best agent to handle it
SELECT ruvector_route($user_query_embedding);
-- Returns: 'code_expert' for "How do I fix this bug?"
-- Returns: 'math_expert' for "Solve this equation"

-- Enable the learning system
SELECT ruvector_enable_learning(true);

-- Record user feedback: they clicked result #3 with 95% satisfaction
SELECT ruvector_record_feedback('query_123', 0.95, '{"clicked_rank": 3}');

-- Let the system auto-optimize based on learned patterns
SELECT ruvector_auto_tune();

-- Check what the system has learned
SELECT * FROM ruvector_learning_stats();

-- Create a social network graph
SELECT ruvector_create_graph('social');

-- Add people as nodes
SELECT ruvector_add_node('social', 'Person', '{"name": "Alice", "age": 30}');
SELECT ruvector_add_node('social', 'Person', '{"name": "Bob", "age": 25}');

-- Connect them with a relationship
SELECT ruvector_add_edge('social', 1, 2, 'KNOWS', '{"since": 2020}');

-- Query: "Who does Alice know?"
SELECT ruvector_cypher('social',
    'MATCH (a:Person)-[:KNOWS]->(b:Person)
     WHERE a.name = "Alice"
     RETURN b.name');
-- Returns: Bob

-- Apply Graph Convolutional Network layer to enhance embeddings
-- based on their connections to other nodes
SELECT ruvector_gcn_forward(
    ARRAY[[0.1, 0.2], [0.3, 0.4]],  -- Current node features
    ARRAY[[0, 1], [1, 0]],           -- Adjacency matrix (who's connected)
    ARRAY[[0.5, 0.5], [0.5, 0.5]]    -- Learned weights
);
-- Returns: Enhanced embeddings that incorporate neighbor information

-- Create a sparse vector: only 3 out of 100 dimensions are non-zero
SELECT ruvector_to_sparse(
    ARRAY[0, 5, 10],              -- Which dimensions have values
    ARRAY[0.5, 0.3, 0.2]::real[], -- The values at those positions
    100                            -- Total dimensions
);
-- Returns: '{0:0.5,5:0.3,10:0.2}/100'

-- Calculate BM25 score for text ranking
SELECT ruvector_sparse_bm25(
    '{0:1.0,5:0.5}/100',  -- Query terms
    '{0:0.8,5:0.3}/100',  -- Document terms
    1.2,                   -- k1: term saturation parameter
    0.75                   -- b: length normalization
);

CREATE INDEX ON items USING hnsw (embedding ruvector_l2_ops)
WITH (m = 16, ef_construction = 64);
SET ruvector.ef_search = 100;

CREATE INDEX ON items USING ivfflat (embedding ruvector_l2_ops)
WITH (lists = 100);
SET ruvector.ivfflat_probes = 10;

docker run -d \
  -v ruvector-data:/var/lib/postgresql/data \
  -p 5432:5432 \
  ruvnet/ruvector:latest