ruvector CLI subcommands hardcode pgvector instead of detecting ruvector extension

[ronmikailov]

Bug

The ruflo ruvector status, ruflo ruvector benchmark, and ruflo ruvector optimize subcommands assume the PostgreSQL instance uses the pgvector extension (vector type), but the official ruvnet/ruvector-postgres Docker image ships its own ruvector extension (v0.3.0) with a custom ruvector UDT — not pgvector's vector type.

Reproduction

# Start the official ruvector-postgres image
docker run -d --name ruvector-postgres -p 5432:5432 ruvnet/ruvector-postgres:latest

# Run status — reports pgvector NOT installed (false negative)
PGPASSWORD=claude-flow-test ruflo ruvector status --verbose --database claude_flow --user claude

# Run benchmark — fails with "type vector does not exist"
PGPASSWORD=claude-flow-test ruflo ruvector benchmark --database claude_flow --user claude

Expected

• status should detect the ruvector extension (not just pgvector)
• benchmark should create columns with the ruvector type (not vector)
• optimize should analyze indexes and types compatible with the ruvector extension

Actual

• status reports: pgvector extension not installed — even though ruvector 0.3.0 is installed and working
• benchmark fails: ERROR: type "vector" does not exist
• optimize was not tested independently but likely has the same hardcoded assumption

Evidence

-- The actual extension installed:
SELECT extname, extversion FROM pg_extension;
--  ruvector | 0.3.0

-- The actual embedding column type:
SELECT udt_name FROM information_schema.columns 
WHERE table_schema='claude_flow' AND table_name='memory_entries' AND column_name='embedding';
--  ruvector

-- Data is healthy: 129 entries, 8 tables, 21 indexes (HNSW), all valid

Suggested Fix

The CLI should check for both extensions and use whichever is present:

SELECT extname FROM pg_extension WHERE extname IN ('vector', 'ruvector');

Then use the detected extension's type for benchmark table creation, status reporting, and optimization analysis.

Environment

• ruvnet/ruvector-postgres:latest
• ruflo CLI (npm, latest)
• PostgreSQL with ruvector extension 0.3.0
• Node v20.19.6

---

Reported from Site360 project integration testing.

[ronmikailov]

Additional Findings

After installing @ruvector/core@0.1.31 (the native Rust HNSW engine), the following issues persist — confirming these are CLI-layer bugs, not missing dependencies:

Bug 2: ruflo ruvector import crashes on all entries

PGPASSWORD=... ruflo ruvector import --input /tmp/ruvector-export.json ...

Exports from sqlite3 -json produce entries with embedding as a JSON array string (e.g., "[-0.002, 0.015, ...]"). The import command tries to call .replace() on something undefined for every entry:

[WARN] Skipped entry "pr-50-merged": Cannot read properties of undefined (reading 'replace')

Result: 147/147 entries skipped, 0 imported.

Bug 3: ruflo embeddings index doesn't detect installed @ruvector/core

Despite @ruvector/core@0.1.31 being in node_modules/@ruvector/core/, the command still says:

[WARN] @ruvector/core not available
[INFO] Install: npm install @ruvector/core

Likely a require() path resolution issue — the CLI may be looking relative to its own node_modules rather than the project's.

Summary of all CLI bugs found

Command	Bug	Severity
ruvector status	Checks for pgvector extension, not ruvector	Medium
ruvector benchmark	Uses vector type instead of ruvector	High
ruvector optimize	Same vector type assumption	High
ruvector import	Crashes on .replace() for every entry	High
ruvector migrate	Requires migrations table that init doesn't create	Low
embeddings index	Can't find @ruvector/core even when installed	Medium

All tested against ruvnet/ruvector-postgres:latest with ruvector extension v0.3.0.

[ronmikailov]

Root Cause Analysis — Full Investigation

Finding 1: @ruvector/core not shipped with ruflo (module resolution)

ruflo globally installed at ~/.nvm/.../lib/node_modules/ruflo/ ships 20 @ruvector/* packages (attention, gnn, graph, sona, ruvllm, etc.) but NOT @ruvector/core.

The CLI code at memory-initializer.js:347 does:

const ruvectorModule = await import('@ruvector/core').catch(() => null);

This resolves from ruflo's own node_modules, not the project's. Fix: either ship @ruvector/core as a dependency of @claude-flow/cli, or resolve from process.cwd() using createRequire(process.cwd()).

Workaround applied: Symlinked @ruvector/core + ruvector-core-linux-x64-gnu into ruflo's node_modules/@ruvector/. This works — VectorDb loads, version() returns 0.1.29.

Finding 2: @ruvector/core needs platform-specific native binary

@ruvector/core@0.1.31 is just a loader (index.js does require('ruvector-core-linux-x64-gnu')). The native binary is a separate optionalDependency that pnpm doesn't install transitively. Users need:

pnpm add @ruvector/core ruvector-core-linux-x64-gnu  # both required

Finding 3: embeddings index -a status never initializes the index

embeddings.js:478 calls getHNSWStatus() synchronously, but getHNSWIndex() (which is async and does the actual import('@ruvector/core')) is never called first for the status action. So hnswIndex is always null and available is always false.

Proof: Running ruflo embeddings index -a build -c default works perfectly (builds 162-vector index), but ruflo embeddings index -a status immediately after still says "not available".

Fix: call await getHNSWIndex() before getHNSWStatus() in the status action path.

Finding 4: ruvector benchmark/optimize/status hardcode pgvector (original report)

These CLI commands use SQL CREATE TABLE ... (embedding vector(...)) with pgvector's vector type. The ruvnet/ruvector-postgres Docker image uses a custom ruvector extension (v0.3.0) with ruvector type — not pgvector.

Finding 5: ruvector import crashes on JSON embedding arrays

The import command gets entries with embedding: "[-0.002, 0.015, ...]" (JSON string arrays from sqlite3 export) and calls .replace() on an undefined value, skipping every entry.

Updated Bug Table

Command	Bug	Root Cause	Fix
embeddings index status	Always says "not available"	Never calls getHNSWIndex() first	Add await getHNSWIndex() before status check
embeddings index build	Works after symlink	@ruvector/core not in ruflo deps	Ship @ruvector/core with ruflo
ruvector status	"pgvector not installed"	Checks only for pgvector extension	Check for both vector and ruvector extensions
ruvector benchmark	"type vector does not exist"	Hardcoded vector type in SQL	Detect extension type, use ruvector when present
ruvector optimize	Same as benchmark	Same SQL hardcoding	Same fix
ruvector import	.replace() crash on all entries	Undefined property access on embedding field	Handle JSON array string format
ruvector migrate	"migrations table not found"	init doesn't create migrations table	Create table in init or skip gracefully

[ronmikailov]

Workaround: Full symlink solution for all missing loaders

Ruflo ships native binaries (@ruvector/*-linux-x64-gnu) but not the JS loader packages. The import('@ruvector/...') calls in @claude-flow/cli resolve from ruflo's own node_modules and fail silently.

Steps to fix locally

# 1. Install all packages into your project
pnpm add ruvector @ruvector/core @ruvector/attention @ruvector/gnn ruvector-core-linux-x64-gnu -w

# 2. Symlink loaders into ruflo's node_modules
RUFLO_MODS=$(dirname $(readlink -f $(which ruflo)))/../../lib/node_modules/ruflo/node_modules
PROJECT_MODS=$(pwd)/node_modules

ln -sf $PROJECT_MODS/@ruvector/core $RUFLO_MODS/@ruvector/core
ln -sf $PROJECT_MODS/@ruvector/attention $RUFLO_MODS/@ruvector/attention
ln -sf $PROJECT_MODS/@ruvector/gnn $RUFLO_MODS/@ruvector/gnn
ln -sf $PROJECT_MODS/ruvector $RUFLO_MODS/ruvector
ln -sf $PROJECT_MODS/ruvector-core-linux-x64-gnu $RUFLO_MODS/ruvector-core-linux-x64-gnu

# 3. Verify
cd $RUFLO_MODS/.. && node --input-type=module -e "
for (const p of ['@ruvector/core', '@ruvector/attention', '@ruvector/gnn', 'ruvector']) {
  try { const m = await import(p); console.log('OK', p); }
  catch(e) { console.log('FAIL', p, e.message.split('\n')[0]); }
}
"

Results after symlinks

• ruvector.isNative(): true — Rust engine active
• ruflo embeddings index -a build: builds 162-vector HNSW index
• 150+ exports available: VectorDB, GNNLayer, FlashAttention, HyperbolicAttention, SONA, TensorCompress, SemanticRouter, etc.
• ruflo embeddings neural still shows "Disabled" — this is a config-flag display issue, not a runtime issue. The packages are loaded and functional.

Suggested upstream fix

Add these to @claude-flow/cli's dependencies (not optionalDependencies):

{
  "dependencies": {
    "ruvector": "^0.2.21",
    "@ruvector/core": "^0.1.31",
    "@ruvector/attention": "^0.1.31",
    "@ruvector/gnn": "^0.1.25"
  }
}

Or alternatively, resolve these from process.cwd() using createRequire() instead of the CLI's own module resolution.

[ruvnet]

Fixed in v3.5.52 (PR #1534, merged)