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

40.6 KB
Raw Blame

RuVector PostgreSQL Bridge Plugin Architecture

Document Information

Property Value
Version 1.0.0
Status Draft
Author Claude Flow Architecture Team
Last Updated 2026-01-16
ADR References ADR-006 (Unified Memory), ADR-009 (Hybrid Memory Backend)

1. Executive Summary

The RuVector PostgreSQL Bridge plugin provides a high-performance integration layer between Claude-Flow v3 and PostgreSQL databases enhanced with RuVector extensions. This plugin exposes 53+ SQL functions for vector operations, 39 attention mechanisms, Graph Neural Network (GNN) layers, hyperbolic embeddings, and self-learning capabilities through MCP tools.

Key Capabilities

  • Vector Operations: Similarity search, clustering, quantization (150x-12,500x faster)
  • Attention Mechanisms: Multi-head, self-attention, cross-attention, sparse variants
  • Graph Processing: GNN layers, message passing, node/edge embeddings
  • Hyperbolic Geometry: Poincare ball, Lorentz model for hierarchical data
  • Self-Learning: Query optimization, index tuning, pattern recognition

2. System Context (C4 Level 1)

+------------------------------------------------------------------+
|                        Claude Code / MCP Client                   |
+------------------------------------------------------------------+
                                |
                                | MCP Protocol (stdio/HTTP/WebSocket)
                                v
+------------------------------------------------------------------+
|                    Claude-Flow v3 MCP Server                      |
|  +------------------------------------------------------------+  |
|  |                 RuVector PostgreSQL Bridge                  |  |
|  |  +----------------+  +----------------+  +---------------+  |  |
|  |  | Connection     |  | Tool           |  | Query         |  |  |
|  |  | Pool Manager   |  | Registry       |  | Executor      |  |  |
|  |  +----------------+  +----------------+  +---------------+  |  |
|  +------------------------------------------------------------+  |
+------------------------------------------------------------------+
                                |
                                | pg Protocol (libpq/node-postgres)
                                v
+------------------------------------------------------------------+
|                    PostgreSQL + RuVector Extensions               |
|  +------------------+  +------------------+  +----------------+   |
|  | pg_ruvector      |  | pg_ruvector_gnn  |  | pg_ruvector    |   |
|  | (vectors)        |  | (graph ops)      |  | _attention     |   |
|  +------------------+  +------------------+  +----------------+   |
+------------------------------------------------------------------+

3. Container Architecture (C4 Level 2)

3.1 Plugin Container Structure

@claude-flow/plugins/src/integrations/ruvector/
|
+-- index.ts                    # Plugin entry point & exports
+-- plugin.ts                   # Main plugin class (extends BasePlugin)
+-- ARCHITECTURE.md             # This document
|
+-- core/
|   +-- connection-manager.ts   # PostgreSQL connection pooling
|   +-- query-executor.ts       # Query execution with metrics
|   +-- schema-manager.ts       # Extension & schema management
|   +-- types.ts                # Core type definitions
|
+-- sql/
|   +-- index.ts                # SQL function registry
|   +-- vector-functions.ts     # 15+ vector similarity functions
|   +-- graph-functions.ts      # 12+ graph-aware query functions
|   +-- pattern-functions.ts    # 10+ pattern matching functions
|   +-- index-functions.ts      # 8+ index management functions
|   +-- aggregate-functions.ts  # 8+ vector aggregation functions
|
+-- attention/
|   +-- index.ts                # Attention mechanism registry
|   +-- multi-head.ts           # Multi-head attention (8 variants)
|   +-- self-attention.ts       # Self-attention (6 variants)
|   +-- cross-attention.ts      # Cross-attention (5 variants)
|   +-- sparse-attention.ts     # Sparse attention (10 variants)
|   +-- linear-attention.ts     # Linear attention (5 variants)
|   +-- flash-attention.ts      # Flash Attention v2 integration
|   +-- types.ts                # Attention type definitions
|
+-- gnn/
|   +-- index.ts                # GNN layer registry
|   +-- graph-conv.ts           # Graph convolution layers
|   +-- message-passing.ts      # Message passing networks
|   +-- node-embeddings.ts      # Node embedding generation
|   +-- edge-embeddings.ts      # Edge embedding generation
|   +-- pooling.ts              # Graph pooling operations
|   +-- types.ts                # GNN type definitions
|
+-- hyperbolic/
|   +-- index.ts                # Hyperbolic embedding registry
|   +-- poincare.ts             # Poincare ball model
|   +-- lorentz.ts              # Lorentz (hyperboloid) model
|   +-- distance.ts             # Distance calculations
|   +-- operations.ts           # Mobius operations
|   +-- types.ts                # Hyperbolic type definitions
|
+-- learning/
|   +-- index.ts                # Self-learning registry
|   +-- query-optimizer.ts      # Query plan optimization
|   +-- index-tuner.ts          # Index parameter tuning
|   +-- pattern-recognizer.ts   # Pattern recognition engine
|   +-- statistics-collector.ts # Usage statistics collection
|   +-- types.ts                # Learning type definitions
|
+-- mcp/
|   +-- index.ts                # MCP tool registration
|   +-- vector-tools.ts         # Vector operation tools
|   +-- attention-tools.ts      # Attention mechanism tools
|   +-- gnn-tools.ts            # GNN operation tools
|   +-- hyperbolic-tools.ts     # Hyperbolic embedding tools
|   +-- admin-tools.ts          # Administration tools

4. Component Architecture (C4 Level 3)

4.1 Core Components

4.1.1 Connection Manager

/**
 * PostgreSQL Connection Pool Manager
 *
 * Manages connection lifecycle, health checks, and load balancing
 * for PostgreSQL instances with RuVector extensions.
 */
interface IConnectionManager {
  // Connection lifecycle
  initialize(config: ConnectionConfig): Promise<void>;
  shutdown(): Promise<void>;

  // Connection acquisition
  acquire(): Promise<PooledConnection>;
  release(connection: PooledConnection): void;

  // Health monitoring
  healthCheck(): Promise<HealthCheckResult>;
  getStats(): ConnectionPoolStats;

  // Extension management
  ensureExtensions(): Promise<ExtensionStatus[]>;
}

interface ConnectionConfig {
  host: string;
  port: number;
  database: string;
  user: string;
  password: string;
  ssl?: SSLConfig;
  pool: {
    min: number;           // Default: 2
    max: number;           // Default: 10
    idleTimeout: number;   // Default: 30000ms
    acquireTimeout: number; // Default: 5000ms
  };
  extensions: {
    ruvector: boolean;
    ruvector_gnn?: boolean;
    ruvector_attention?: boolean;
  };
}

Design Decisions:

  • Uses pg (node-postgres) for PostgreSQL connectivity
  • Connection pooling with configurable min/max connections
  • Automatic reconnection with exponential backoff
  • Health checks verify extension availability

4.1.2 Query Executor

/**
 * Query Executor with Metrics Collection
 *
 * Executes SQL queries with timing, caching, and error handling.
 */
interface IQueryExecutor {
  // Query execution
  execute<T>(query: string, params?: unknown[]): Promise<QueryResult<T>>;
  executeMany<T>(queries: BatchQuery[]): Promise<QueryResult<T>[]>;

  // Prepared statements
  prepare(name: string, query: string): Promise<PreparedStatement>;
  executePrepared<T>(name: string, params?: unknown[]): Promise<QueryResult<T>>;

  // Transaction support
  beginTransaction(): Promise<Transaction>;

  // Metrics
  getQueryStats(): QueryStatistics;
  resetStats(): void;
}

interface QueryResult<T> {
  rows: T[];
  rowCount: number;
  fields: FieldInfo[];
  duration: number;
  fromCache: boolean;
}

Design Decisions:

  • Query result caching with configurable TTL
  • Automatic query plan analysis for optimization hints
  • Prepared statement reuse for repeated queries
  • Comprehensive metrics collection

4.2 SQL Functions Module

4.2.1 Vector Functions (15+)

Function Description SQL Signature
rv_similarity Cosine similarity rv_similarity(vector, vector) -> float
rv_distance Euclidean distance rv_distance(vector, vector) -> float
rv_inner_product Inner product rv_inner_product(vector, vector) -> float
rv_l1_distance Manhattan distance rv_l1_distance(vector, vector) -> float
rv_l2_distance L2 distance rv_l2_distance(vector, vector) -> float
rv_cosine_distance Cosine distance rv_cosine_distance(vector, vector) -> float
rv_normalize L2 normalization rv_normalize(vector) -> vector
rv_add Vector addition rv_add(vector, vector) -> vector
rv_subtract Vector subtraction rv_subtract(vector, vector) -> vector
rv_multiply Scalar multiplication rv_multiply(vector, float) -> vector
rv_dimensions Get dimensions rv_dimensions(vector) -> int
rv_slice Vector slicing rv_slice(vector, int, int) -> vector
rv_concat Vector concatenation rv_concat(vector, vector) -> vector
rv_quantize Quantization rv_quantize(vector, int) -> bytea
rv_dequantize Dequantization rv_dequantize(bytea, int) -> vector
interface VectorFunctions {
  // Similarity/Distance
  similarity(a: Float32Array, b: Float32Array): Promise<number>;
  distance(a: Float32Array, b: Float32Array, metric: DistanceMetric): Promise<number>;

  // Operations
  normalize(v: Float32Array): Promise<Float32Array>;
  add(a: Float32Array, b: Float32Array): Promise<Float32Array>;
  subtract(a: Float32Array, b: Float32Array): Promise<Float32Array>;
  multiply(v: Float32Array, scalar: number): Promise<Float32Array>;

  // Transformations
  quantize(v: Float32Array, bits: 4 | 8 | 16): Promise<Uint8Array>;
  dequantize(data: Uint8Array, bits: 4 | 8 | 16): Promise<Float32Array>;
}

type DistanceMetric = 'euclidean' | 'cosine' | 'manhattan' | 'inner_product';

4.2.2 Graph-Aware Functions (12+)

Function Description SQL Signature
rv_graph_neighbors K-nearest neighbors rv_graph_neighbors(id, k) -> setof record
rv_graph_similarity Graph-based similarity rv_graph_similarity(id1, id2) -> float
rv_graph_cluster Graph clustering rv_graph_cluster(table, k) -> setof record
rv_graph_pagerank PageRank scores rv_graph_pagerank(table) -> setof record
rv_graph_connected Connected components rv_graph_connected(table) -> setof record
rv_graph_shortest_path Shortest path rv_graph_shortest_path(table, id1, id2) -> path
rv_graph_community Community detection rv_graph_community(table) -> setof record
rv_graph_centrality Node centrality rv_graph_centrality(table, metric) -> setof record
rv_graph_embedding Graph embedding rv_graph_embedding(table) -> setof vector
rv_graph_walk Random walk rv_graph_walk(table, start, steps) -> path
rv_graph_subgraph Subgraph extraction rv_graph_subgraph(table, nodes) -> table
rv_graph_metrics Graph statistics rv_graph_metrics(table) -> record

4.2.3 Pattern Matching Functions (10+)

Function Description SQL Signature
rv_pattern_search Pattern similarity search rv_pattern_search(vector, table, k) -> setof record
rv_pattern_match Exact pattern match rv_pattern_match(pattern, table) -> setof record
rv_pattern_cluster Pattern clustering rv_pattern_cluster(table, k) -> setof record
rv_pattern_detect Anomaly detection rv_pattern_detect(table, threshold) -> setof record
rv_pattern_frequent Frequent patterns rv_pattern_frequent(table, min_support) -> setof record
rv_pattern_sequence Sequence pattern mining rv_pattern_sequence(table, max_gap) -> setof record
rv_pattern_associate Association rules rv_pattern_associate(table, confidence) -> setof record
rv_pattern_timeseries Time series patterns rv_pattern_timeseries(table, window) -> setof record
rv_pattern_similarity_join Similarity join rv_pattern_similarity_join(t1, t2, threshold) -> setof record
rv_pattern_deduplicate Near-duplicate detection rv_pattern_deduplicate(table, threshold) -> setof record

4.2.4 Index Management Functions (8+)

Function Description SQL Signature
rv_index_create Create HNSW index rv_index_create(table, column, config) -> void
rv_index_drop Drop index rv_index_drop(index_name) -> void
rv_index_rebuild Rebuild index rv_index_rebuild(index_name) -> void
rv_index_stats Index statistics rv_index_stats(index_name) -> record
rv_index_tune Auto-tune parameters rv_index_tune(index_name) -> record
rv_index_validate Validate index integrity rv_index_validate(index_name) -> boolean
rv_index_compact Compact index rv_index_compact(index_name) -> void
rv_index_analyze Analyze query performance rv_index_analyze(query) -> record

4.3 Attention Mechanisms Module (39 Total)

4.3.1 Multi-Head Attention (8 variants)

interface MultiHeadAttention {
  // Standard implementations
  standard(query: Tensor, key: Tensor, value: Tensor, config: MHAConfig): Promise<Tensor>;
  scaled(query: Tensor, key: Tensor, value: Tensor, config: MHAConfig): Promise<Tensor>;

  // Optimized variants
  flashAttention(query: Tensor, key: Tensor, value: Tensor, config: FlashConfig): Promise<Tensor>;
  memoryEfficient(query: Tensor, key: Tensor, value: Tensor, config: MEConfig): Promise<Tensor>;

  // Specialized variants
  rotary(query: Tensor, key: Tensor, value: Tensor, config: RoPEConfig): Promise<Tensor>;
  alibi(query: Tensor, key: Tensor, value: Tensor, config: ALiBiConfig): Promise<Tensor>;
  grouped(query: Tensor, key: Tensor, value: Tensor, config: GQAConfig): Promise<Tensor>;
  multiQuery(query: Tensor, key: Tensor, value: Tensor, config: MQAConfig): Promise<Tensor>;
}

interface MHAConfig {
  numHeads: number;
  headDim: number;
  dropout?: number;
  causal?: boolean;
  maxSeqLen?: number;
}
Variant Description Use Case
mha_standard Standard multi-head attention General purpose
mha_scaled Scaled dot-product attention Transformer default
mha_flash Flash Attention v2 Long sequences (2.49x-7.47x speedup)
mha_memory_efficient Memory-efficient attention Large batch sizes
mha_rotary Rotary position embeddings (RoPE) Position-aware attention
mha_alibi Attention with Linear Biases Extrapolation to longer sequences
mha_grouped Grouped-Query Attention (GQA) Reduced KV cache
mha_multi_query Multi-Query Attention (MQA) Single KV head

4.3.2 Self-Attention (6 variants)

Variant Description Complexity
self_standard Standard self-attention O(n^2)
self_causal Causal (autoregressive) O(n^2)
self_bidirectional Bidirectional O(n^2)
self_local Local window attention O(n * w)
self_sliding Sliding window O(n * w)
self_dilated Dilated attention O(n * w)

4.3.3 Cross-Attention (5 variants)

Variant Description Use Case
cross_standard Standard cross-attention Encoder-decoder
cross_memory Memory-augmented External memory
cross_perceiver Perceiver-style Variable-length inputs
cross_latent Latent cross-attention Latent space mapping
cross_adaptive Adaptive cross-attention Dynamic routing

4.3.4 Sparse Attention (10 variants)

Variant Description Pattern
sparse_strided Strided attention Fixed stride
sparse_fixed Fixed pattern Predefined mask
sparse_random Random attention Sampled positions
sparse_local_global Local + global tokens Longformer-style
sparse_bigbird BigBird pattern Random + local + global
sparse_longformer Longformer pattern Sliding + global
sparse_axial Axial attention Row/column decomposition
sparse_star Star transformer Global token hub
sparse_cluster Cluster attention Learned clusters
sparse_routing Routing attention Top-k selection

4.3.5 Linear Attention (5 variants)

Variant Description Complexity
linear_standard Linear attention O(n)
linear_performer Performer (FAVOR+) O(n)
linear_rfa Random Feature Attention O(n)
linear_cosformer Cosine-reweighted O(n)
linear_nystrom Nystrom approximation O(n * m)

4.4 GNN Layers Module

4.4.1 Graph Convolution Layers

interface GraphConvolutionLayers {
  // Standard layers
  gcn(features: Tensor, adjacency: SparseTensor, weights: Tensor): Promise<Tensor>;
  graphSAGE(features: Tensor, adjacency: SparseTensor, config: SAGEConfig): Promise<Tensor>;
  gat(features: Tensor, adjacency: SparseTensor, config: GATConfig): Promise<Tensor>;
  gin(features: Tensor, adjacency: SparseTensor, config: GINConfig): Promise<Tensor>;

  // Advanced layers
  edgeConv(features: Tensor, edges: Tensor, config: EdgeConvConfig): Promise<Tensor>;
  gatv2(features: Tensor, adjacency: SparseTensor, config: GATv2Config): Promise<Tensor>;
  pna(features: Tensor, adjacency: SparseTensor, config: PNAConfig): Promise<Tensor>;
}
Layer Description Reference
GCN Graph Convolutional Network Kipf & Welling (2016)
GraphSAGE Sample and Aggregate Hamilton et al. (2017)
GAT Graph Attention Network Velickovic et al. (2018)
GATv2 Improved GAT Brody et al. (2021)
GIN Graph Isomorphism Network Xu et al. (2019)
EdgeConv Edge Convolution Wang et al. (2019)
PNA Principal Neighbourhood Aggregation Corso et al. (2020)

4.4.2 Message Passing Networks

interface MessagePassingNetwork {
  // Core operations
  propagate(
    nodeFeatures: Tensor,
    edgeIndex: Tensor,
    edgeFeatures?: Tensor
  ): Promise<Tensor>;

  // Message functions
  message(source: Tensor, target: Tensor, edge?: Tensor): Promise<Tensor>;
  aggregate(messages: Tensor, index: Tensor, method: AggregateMethod): Promise<Tensor>;
  update(nodeFeatures: Tensor, aggregated: Tensor): Promise<Tensor>;
}

type AggregateMethod = 'sum' | 'mean' | 'max' | 'min' | 'attention' | 'lstm';

4.4.3 Node/Edge Embeddings

interface EmbeddingGenerator {
  // Node embeddings
  node2vec(adjacency: SparseTensor, config: Node2VecConfig): Promise<Tensor>;
  deepwalk(adjacency: SparseTensor, config: DeepWalkConfig): Promise<Tensor>;
  struc2vec(adjacency: SparseTensor, config: Struc2VecConfig): Promise<Tensor>;

  // Edge embeddings
  edgeEmbedding(nodeEmbeddings: Tensor, edgeIndex: Tensor, method: EdgeMethod): Promise<Tensor>;

  // Subgraph embeddings
  subgraphEmbedding(nodeEmbeddings: Tensor, subgraphNodes: number[]): Promise<Float32Array>;
}

type EdgeMethod = 'hadamard' | 'average' | 'l1' | 'l2' | 'concat';

4.5 Hyperbolic Embeddings Module

4.5.1 Poincare Ball Model

interface PoincareBallOperations {
  // Core operations (curvature c = -1 default)
  expMap(v: Float32Array, base?: Float32Array): Promise<Float32Array>;
  logMap(point: Float32Array, base?: Float32Array): Promise<Float32Array>;

  // Distance
  distance(a: Float32Array, b: Float32Array): Promise<number>;

  // Mobius operations
  mobiusAdd(a: Float32Array, b: Float32Array): Promise<Float32Array>;
  mobiusScalarMul(r: number, v: Float32Array): Promise<Float32Array>;
  mobiusMatVecMul(M: Float32Array[], v: Float32Array): Promise<Float32Array>;

  // Transformations
  euclideanToPoincare(v: Float32Array): Promise<Float32Array>;
  poincareToEuclidean(v: Float32Array): Promise<Float32Array>;

  // Aggregation
  centroid(points: Float32Array[], weights?: number[]): Promise<Float32Array>;
  midpoint(a: Float32Array, b: Float32Array): Promise<Float32Array>;

  // Utilities
  norm(v: Float32Array): Promise<number>;
  project(v: Float32Array): Promise<Float32Array>;
  isInBall(v: Float32Array): Promise<boolean>;
}

4.5.2 Lorentz (Hyperboloid) Model

interface LorentzModelOperations {
  // Core operations
  expMap(v: Float32Array, base?: Float32Array): Promise<Float32Array>;
  logMap(point: Float32Array, base?: Float32Array): Promise<Float32Array>;

  // Distance (Minkowski inner product based)
  distance(a: Float32Array, b: Float32Array): Promise<number>;
  minkowskiInnerProduct(a: Float32Array, b: Float32Array): Promise<number>;

  // Transformations
  lorentzToPoincare(v: Float32Array): Promise<Float32Array>;
  poincareToLorentz(v: Float32Array): Promise<Float32Array>;

  // Lorentz operations
  lorentzBoost(v: Float32Array, velocity: Float32Array): Promise<Float32Array>;
  parallelTransport(v: Float32Array, from: Float32Array, to: Float32Array): Promise<Float32Array>;

  // Utilities
  lorentzNorm(v: Float32Array): Promise<number>;
  projectToHyperboloid(v: Float32Array): Promise<Float32Array>;
}

4.5.3 Distance Calculations

Function Model Formula
poincare_distance Poincare d(x,y) = arcosh(1 + 2
lorentz_distance Lorentz d(x,y) = arcosh(-<x,y>_L)
klein_distance Klein d(x,y) = arcosh(1 - 2<x,y> / ((1-
halfplane_distance Upper half-plane d(x,y) = 2 * arcsinh(

4.6 Self-Learning Module

4.6.1 Query Optimizer

interface QueryOptimizer {
  // Query analysis
  analyzeQuery(sql: string): Promise<QueryAnalysis>;
  suggestOptimizations(sql: string): Promise<Optimization[]>;

  // Learning
  recordExecution(query: string, plan: QueryPlan, duration: number): Promise<void>;
  learnFromHistory(): Promise<LearningReport>;

  // Optimization application
  rewrite(sql: string): Promise<string>;
  selectIndex(query: string, available: Index[]): Promise<Index | null>;
}

interface QueryAnalysis {
  complexity: 'low' | 'medium' | 'high';
  estimatedCost: number;
  bottlenecks: Bottleneck[];
  recommendations: string[];
  vectorOperations: VectorOperation[];
}

interface Optimization {
  type: 'index' | 'rewrite' | 'parallel' | 'cache';
  description: string;
  expectedSpeedup: number;
  sql?: string;
}

4.6.2 Index Tuner

interface IndexTuner {
  // Analysis
  analyzeWorkload(queries: QueryLog[]): Promise<WorkloadAnalysis>;
  recommendIndexes(analysis: WorkloadAnalysis): Promise<IndexRecommendation[]>;

  // HNSW tuning
  tuneHNSW(indexName: string): Promise<HNSWParams>;
  estimateHNSWParams(dataSize: number, dimensions: number, queryPattern: QueryPattern): HNSWParams;

  // IVF tuning
  tuneIVF(indexName: string): Promise<IVFParams>;
  estimateIVFParams(dataSize: number, dimensions: number): IVFParams;

  // Monitoring
  monitorPerformance(indexName: string): Promise<PerformanceMetrics>;
}

interface HNSWParams {
  m: number;              // Max connections per layer (default: 16)
  efConstruction: number; // Construction search depth (default: 200)
  efSearch: number;       // Query search depth (default: 100)
  ml: number;            // Level multiplier (default: 1/ln(M))
}

4.6.3 Pattern Recognizer

interface PatternRecognizer {
  // Query pattern detection
  detectQueryPatterns(queries: Query[]): Promise<QueryPattern[]>;
  classifyQuery(sql: string): Promise<QueryClassification>;

  // Data pattern detection
  detectDataPatterns(vectors: Float32Array[]): Promise<DataPattern[]>;
  detectAnomalies(vectors: Float32Array[], threshold: number): Promise<Anomaly[]>;

  // Learning
  trainOnPatterns(patterns: Pattern[]): Promise<void>;
  predictPattern(query: string): Promise<PatternPrediction>;
}

interface QueryPattern {
  id: string;
  template: string;
  frequency: number;
  avgDuration: number;
  vectorOperations: string[];
}

5. Data Flow Diagrams

5.1 Vector Similarity Search Flow

+-------------+     +-----------------+     +------------------+
|   Client    |     |  RuVector       |     |   PostgreSQL     |
|   Request   | --> |  Bridge Plugin  | --> |   + RuVector     |
+-------------+     +-----------------+     +------------------+
      |                    |                        |
      | 1. MCP Tool Call   |                        |
      | (vector_search)    |                        |
      |                    |                        |
      |              2. Validate input              |
      |              3. Get connection              |
      |                    |                        |
      |                    | 4. Execute query       |
      |                    | SELECT * FROM items   |
      |                    | ORDER BY embedding    |
      |                    | <=> $1 LIMIT $2       |
      |                    |----------------------->|
      |                    |                        |
      |                    | 5. HNSW index scan    |
      |                    |<-----------------------|
      |                    |                        |
      |              6. Transform results          |
      |              7. Update metrics             |
      |<-------------------|                        |
      | 8. MCP Response    |                        |

5.2 Attention Mechanism Flow

+-------------+     +-----------------+     +------------------+
|   Input     |     |   Attention     |     |   PostgreSQL     |
|   Tensors   | --> |   Module        | --> |   UDF Execution  |
+-------------+     +-----------------+     +------------------+
      |                    |                        |
      | Q, K, V tensors    |                        |
      |                    |                        |
      |              1. Select variant              |
      |              2. Prepare parameters          |
      |                    |                        |
      |                    | 3. Execute UDF         |
      |                    | rv_attention_mha(      |
      |                    |   $Q, $K, $V, $config  |
      |                    | )                      |
      |                    |----------------------->|
      |                    |                        |
      |                    | 4. SIMD computation   |
      |                    | (in-database)         |
      |                    |<-----------------------|
      |                    |                        |
      |              5. Return attention output    |
      |<-------------------|                        |

5.3 Self-Learning Flow

+-------------+     +-----------------+     +------------------+
|   Query     |     |   Learning      |     |   Statistics     |
|   Execution | --> |   Module        | --> |   Storage        |
+-------------+     +-----------------+     +------------------+
      |                    |                        |
      | Query + Results    |                        |
      |                    |                        |
      |              1. Record execution           |
      |              2. Extract features           |
      |                    |                        |
      |                    | 3. Store statistics   |
      |                    |----------------------->|
      |                    |                        |
      |              4. Analyze patterns           |
      |              5. Update models              |
      |                    |                        |
      |              6. Generate recommendations   |
      |<-------------------|                        |

6. Interface Definitions

6.1 Plugin Interface

import { BasePlugin } from '@claude-flow/plugins';

export class RuVectorPostgreSQLBridgePlugin extends BasePlugin {
  // Metadata
  static readonly PLUGIN_NAME = 'ruvector-postgresql-bridge';
  static readonly VERSION = '1.0.0';

  // Components
  private connectionManager: ConnectionManager;
  private queryExecutor: QueryExecutor;
  private sqlFunctions: SQLFunctionRegistry;
  private attentionMechanisms: AttentionRegistry;
  private gnnLayers: GNNRegistry;
  private hyperbolicOps: HyperbolicRegistry;
  private learningEngine: LearningEngine;

  // Plugin lifecycle
  protected async onInitialize(): Promise<void>;
  protected async onShutdown(): Promise<void>;
  protected async onHealthCheck(): Promise<Record<string, HealthStatus>>;

  // Extension registration
  registerMCPTools(): MCPToolDefinition[];
  registerHooks(): HookDefinition[];
  registerAgentTypes(): AgentTypeDefinition[];
}

6.2 MCP Tool Definitions

// Vector Operations Tools
interface VectorTools {
  'ruvector:search': {
    input: {
      query: number[];      // Query vector
      table: string;        // Table name
      column: string;       // Vector column
      k: number;           // Number of results
      metric?: string;      // Distance metric
      filter?: string;      // SQL WHERE clause
    };
    output: {
      results: Array<{
        id: string;
        score: number;
        metadata: Record<string, unknown>;
      }>;
      duration: number;
    };
  };

  'ruvector:index:create': {
    input: {
      table: string;
      column: string;
      type: 'hnsw' | 'ivf' | 'flat';
      params?: {
        m?: number;
        efConstruction?: number;
        lists?: number;
      };
    };
    output: {
      indexName: string;
      created: boolean;
    };
  };

  // ... 50+ more tools
}

// Attention Tools
interface AttentionTools {
  'ruvector:attention:mha': {
    input: {
      query: number[][];
      key: number[][];
      value: number[][];
      config: {
        numHeads: number;
        dropout?: number;
        causal?: boolean;
      };
    };
    output: {
      attention: number[][];
      weights?: number[][][];
    };
  };

  // ... more attention tools
}

// GNN Tools
interface GNNTools {
  'ruvector:gnn:propagate': {
    input: {
      features: number[][];
      edgeIndex: number[][];
      layer: 'gcn' | 'gat' | 'sage' | 'gin';
      config: Record<string, unknown>;
    };
    output: {
      features: number[][];
    };
  };

  // ... more GNN tools
}

6.3 Configuration Schema

interface RuVectorBridgeConfig {
  // Connection settings
  connection: {
    host: string;
    port: number;
    database: string;
    user: string;
    password: string;
    ssl?: {
      enabled: boolean;
      ca?: string;
      key?: string;
      cert?: string;
    };
  };

  // Pool settings
  pool: {
    min: number;
    max: number;
    idleTimeout: number;
    acquireTimeout: number;
    maxWaitingClients: number;
  };

  // Feature flags
  features: {
    vectorOperations: boolean;
    attentionMechanisms: boolean;
    gnnLayers: boolean;
    hyperbolicEmbeddings: boolean;
    selfLearning: boolean;
  };

  // Learning settings
  learning: {
    enabled: boolean;
    queryHistorySize: number;
    patternUpdateInterval: number;
    indexTuningEnabled: boolean;
  };

  // Performance settings
  performance: {
    queryTimeout: number;
    cacheEnabled: boolean;
    cacheTTL: number;
    maxBatchSize: number;
  };
}

7. Extension Points

7.1 Custom SQL Functions

interface SQLFunctionExtension {
  // Register custom function
  registerFunction(definition: CustomFunctionDefinition): void;

  // Function definition
  interface CustomFunctionDefinition {
    name: string;
    args: ArgDefinition[];
    returns: ReturnType;
    implementation: string;  // SQL or PL/pgSQL
    volatile?: boolean;
    parallel?: 'safe' | 'restricted' | 'unsafe';
  }
}

7.2 Custom Attention Mechanisms

interface AttentionExtension {
  // Register custom attention
  registerAttention(definition: CustomAttentionDefinition): void;

  interface CustomAttentionDefinition {
    name: string;
    compute: (query: Tensor, key: Tensor, value: Tensor, config: unknown) => Promise<Tensor>;
    validateConfig: (config: unknown) => boolean;
    estimateComplexity: (seqLen: number, dim: number) => ComplexityEstimate;
  }
}

7.3 Custom GNN Layers

interface GNNExtension {
  // Register custom layer
  registerLayer(definition: CustomLayerDefinition): void;

  interface CustomLayerDefinition {
    name: string;
    message: (source: Tensor, target: Tensor, edge?: Tensor) => Tensor;
    aggregate: (messages: Tensor, index: Tensor) => Tensor;
    update: (node: Tensor, aggregated: Tensor) => Tensor;
  }
}

7.4 Custom Learning Strategies

interface LearningExtension {
  // Register custom optimizer
  registerOptimizer(definition: CustomOptimizerDefinition): void;

  // Register custom tuner
  registerTuner(definition: CustomTunerDefinition): void;

  // Register custom pattern detector
  registerPatternDetector(definition: CustomPatternDetectorDefinition): void;
}

8. Performance Considerations

8.1 Connection Pooling

Configuration Small Workload Medium Workload High Workload
min connections 2 5 10
max connections 10 25 50
idle timeout 60s 30s 15s
acquire timeout 10s 5s 3s

8.2 Index Selection Guide

Data Size Dimensions Query Pattern Recommended Index
< 10K Any Any Flat (exact)
10K - 1M < 256 High recall HNSW (m=16, ef=100)
10K - 1M >= 256 Balanced HNSW (m=32, ef=200)
> 1M < 256 High throughput IVF (lists=sqrt(n))
> 1M >= 256 Balanced IVF-HNSW hybrid

8.3 Attention Mechanism Selection

Sequence Length Memory Constraint Recommended
< 512 None Standard MHA
512 - 2K Moderate Flash Attention
2K - 8K Strict Sparse (Longformer)
> 8K Strict Linear (Performer)

8.4 Memory Optimization

// Quantization levels and memory savings
const QUANTIZATION_SAVINGS = {
  'float32': { bits: 32, ratio: 1.0 },
  'float16': { bits: 16, ratio: 0.5 },
  'int8':    { bits: 8,  ratio: 0.25 },
  'int4':    { bits: 4,  ratio: 0.125 },
};

// Recommended quantization by use case
const QUANTIZATION_RECOMMENDATIONS = {
  'similarity_search': 'int8',    // 4x memory reduction, <2% recall loss
  'clustering': 'float16',        // 2x memory reduction, minimal loss
  'exact_match': 'float32',       // No quantization
  'approximate_nn': 'int4',       // 8x memory reduction, ~5% recall loss
};

9. Security Considerations

9.1 Connection Security

  • TLS/SSL required for production connections
  • Certificate validation enabled by default
  • Connection string credentials never logged
  • Secrets retrieved from environment or secret manager

9.2 Query Security

  • Parameterized queries only (no string interpolation)
  • Input validation via Zod schemas
  • SQL injection prevention via prepared statements
  • Query timeout enforcement

9.3 Data Security

  • Vector data encrypted at rest (PostgreSQL TDE)
  • Network encryption via TLS 1.3
  • Access control via PostgreSQL roles
  • Audit logging for sensitive operations

10. Deployment Architecture

10.1 Single Node Deployment

+------------------------------------------+
|           Application Server             |
|  +------------------------------------+  |
|  |      Claude-Flow MCP Server        |  |
|  |  +------------------------------+  |  |
|  |  |   RuVector Bridge Plugin     |  |  |
|  |  +------------------------------+  |  |
|  +------------------------------------+  |
+------------------------------------------+
                    |
                    | pg protocol
                    v
+------------------------------------------+
|        PostgreSQL + RuVector             |
|        (Single Instance)                 |
+------------------------------------------+

10.2 High Availability Deployment

+------------------------------------------+
|           Load Balancer                  |
+------------------------------------------+
         |              |              |
         v              v              v
+------------+  +------------+  +------------+
|  MCP       |  |  MCP       |  |  MCP       |
|  Server 1  |  |  Server 2  |  |  Server 3  |
+------------+  +------------+  +------------+
         |              |              |
         +-------+------+-------+------+
                 |              |
                 v              v
         +------------+  +------------+
         |  Primary   |  |  Replica   |
         |  PostgreSQL|  |  PostgreSQL|
         |  + RuVector|  |  + RuVector|
         +------------+  +------------+

10.3 Distributed Deployment

+------------------------------------------+
|           Global Load Balancer           |
+------------------------------------------+
         |                      |
         v                      v
+------------------+   +------------------+
|    Region A      |   |    Region B      |
| +-------------+  |   | +-------------+  |
| |  MCP Pool   |  |   | |  MCP Pool   |  |
| +-------------+  |   | +-------------+  |
|       |          |   |       |          |
|       v          |   |       v          |
| +-------------+  |   | +-------------+  |
| |  PG Cluster |  |   | |  PG Cluster |  |
| |  (Citus)    |  |   | |  (Citus)    |  |
| +-------------+  |   | +-------------+  |
+------------------+   +------------------+

11. Testing Strategy

11.1 Unit Tests

  • SQL function validation
  • Attention mechanism correctness
  • GNN layer outputs
  • Hyperbolic operations accuracy
  • Configuration validation

11.2 Integration Tests

  • Connection pooling behavior
  • Query execution correctness
  • MCP tool functionality
  • Learning engine feedback loop
  • Extension installation/upgrade

11.3 Performance Tests

  • Vector search latency (p50, p95, p99)
  • Attention throughput (tokens/second)
  • GNN propagation time
  • Index build/query tradeoffs
  • Connection pool saturation

11.4 Chaos Tests

  • Connection failure recovery
  • PostgreSQL restart handling
  • Extension upgrade during operation
  • Memory pressure scenarios
  • Network partition behavior

12. Monitoring and Observability

12.1 Metrics

Metric Type Description
ruvector_query_duration_seconds Histogram Query execution time
ruvector_pool_connections_active Gauge Active connections
ruvector_pool_connections_idle Gauge Idle connections
ruvector_index_size_bytes Gauge Index storage size
ruvector_attention_tokens_processed Counter Tokens processed
ruvector_learning_patterns_detected Counter Patterns detected

12.2 Logging

// Structured log format
interface LogEntry {
  timestamp: string;
  level: 'debug' | 'info' | 'warn' | 'error';
  module: string;
  message: string;
  context: {
    queryId?: string;
    duration?: number;
    rowCount?: number;
    error?: string;
  };
}

12.3 Tracing

  • OpenTelemetry integration
  • Distributed trace context propagation
  • Span attributes for vector operations
  • Query plan visualization

13. Migration Guide

13.1 From pgvector

-- Convert pgvector to ruvector
ALTER TABLE items
  ALTER COLUMN embedding TYPE ruvector
  USING embedding::ruvector;

-- Rebuild indexes
DROP INDEX IF EXISTS items_embedding_idx;
CREATE INDEX items_embedding_idx ON items
  USING ruvector_hnsw (embedding ruvector_cosine_ops)
  WITH (m = 16, ef_construction = 200);

13.2 From In-Memory VectorDB

// Migrate from AgentDB to PostgreSQL
async function migrate(agentDB: AgentDBBridge, pgBridge: RuVectorBridge) {
  const entries = await agentDB.listAll();

  for (const entry of entries) {
    await pgBridge.insert({
      id: entry.id,
      vector: entry.vector,
      metadata: entry.metadata,
    });
  }
}

14. Appendix

A. Complete SQL Function Reference

See /docs/sql-functions-reference.md for the complete 53+ function reference.

B. Attention Mechanism Benchmarks

See /docs/attention-benchmarks.md for performance comparisons.

C. GNN Layer Specifications

See /docs/gnn-specifications.md for detailed layer documentation.

D. Hyperbolic Geometry Mathematics

See /docs/hyperbolic-math.md for mathematical foundations.

E. Self-Learning Algorithm Details

See /docs/learning-algorithms.md for algorithm descriptions.


15. Revision History

Version Date Author Changes
1.0.0 2026-01-16 Architecture Team Initial architecture document