plugins/ruflo-ruvector/README.md
Self-learning vector database powered by [email protected] — HNSW, Adaptive LoRA embeddings, hooks-based intelligence, SONA self-optimizing patterns, brain (collective knowledge), and 103 MCP tools.
Pinned version: this plugin targets
[email protected]. Earlier 0.1.x versions are missing several commands (brain,route,sona); some legacy docs referenced 2.x features that do not exist on npm. Always invoke with the pin.
Wraps the ruvector npm package as a Ruflo plugin, providing vector embedding, semantic search, code-graph clustering, hyperbolic projection, self-learning hooks, and SONA / Brain diagnostics. ruvector's Rust backend delivers sub-millisecond queries and 52,000+ inserts/sec.
# Required
npm install [email protected]
# Optional add-ons (install as needed)
npm install ruvector-onnx-embeddings-wasm # required for `embed text` to work
npm install @ruvector/pi-brain # required for `brain` subcommands
npm install @ruvector/ruvllm # required for `sona` subcommands (JS fallback)
Run a health check:
npx -y [email protected] doctor
claude --plugin-dir plugins/ruflo-ruvector
Register with the pinned version:
claude mcp add ruvector -- npx -y [email protected] mcp start
Key tool categories: hooks routing, AST analysis, diff classification, coverage routing, graph clustering, security scanning, RAG context, brain knowledge, SONA learning.
| Agent | Model | Role |
|---|---|---|
vector-engineer | sonnet | Embedding, HNSW indexing, code-graph clustering, hyperbolic projection, hooks routing, brain/SONA |
| Skill | Usage | Description |
|---|---|---|
vector-setup | /vector-setup [--full] | First-run installer: pins [email protected], adds ONNX/Brain/SONA/router add-ons, registers MCP, runs doctor |
vector-embed | /vector-embed <text> | ONNX embeddings (384-dim) via embed text |
vector-cluster | /vector-cluster <files...> | Spectral/Louvain code-graph clustering via hooks graph-cluster |
vector-hyperbolic | /vector-hyperbolic <text> | Standard ONNX embed + Poincare projection in user code |
/vector slash command)The full surface is documented in commands/vector.md (80+ subcommands). Quick reference:
# Embedding
/vector embed <text> # ruvector embed text "<text>"
/vector embed-adaptive <text> # ruvector embed text "<text>" --adaptive --domain code
/vector embed-file <path> # read file, pass content as text
/vector embed-benchmark # ruvector embed benchmark
# Database lifecycle
/vector db create <path> # ruvector create <path> -d 384 -m cosine
/vector db stats <path> # ruvector stats <path>
/vector insert <db> <json> # ruvector insert <db> <json>
/vector search <db> <vector-json> # ruvector search <db> -v <json> -k N
/vector export <db> # ruvector export <db> -o backup.json
/vector import <file> # ruvector import <file> -d <database>
# RVF cognitive containers (45 example stores)
/vector rvf create|ingest|query|status|segments|derive|compact|export|examples|download
# GNN + attention (real native bindings)
/vector gnn info|layer|search|compress
/vector attention list|compute|benchmark|hyperbolic|info
# Code intelligence (hooks)
/vector ast <file> # ruvector hooks ast-analyze <file>
/vector hooks ast-complexity <files...>
/vector hooks coverage-route <file> | coverage-suggest <files...>
/vector hooks rag-context <query>
/vector hooks route|route-enhanced|suggest-context
/vector cluster <files...> # ruvector hooks graph-cluster <files>
/vector hooks security-scan <files...>
/vector hooks diff-analyze|diff-classify|diff-similar [commit]
/vector hooks remember|recall <query>
/vector hooks coedit-record|coedit-suggest|error-record|error-suggest
/vector hooks trajectory-begin|trajectory-step|trajectory-end
# Native + workers
/vector native list|run <type>|benchmark|compare
/vector workers triggers|presets|phases|dispatch|status|...
# Collective intelligence
/vector brain status|search|share|list|drift|partition|transfer|sync|page (needs @ruvector/pi-brain)
/vector sona status|info|stats|patterns|train|export (needs @ruvector/ruvllm)
/vector llm models|embed|benchmark|info (needs @ruvector/ruvllm)
# Identity + edge compute (pi network)
/vector identity generate|show|export|import
/vector edge status|balance|tasks|join|dashboard
# Server / decompile / demo / system
/vector server [-p 8080] [-g 50051]
/vector decompile <npm-pkg-or-file-or-url>
/vector demo --basic | --gnn | --graph
/vector doctor | info | benchmark | install | setup
# 0. One-time setup
/vector-setup
# 1. Create a database
npx -y [email protected] create project.db -d 384 -m cosine
# 2. Embed every TypeScript source file (loop — no built-in --batch)
mkdir -p .vec
for f in $(find src -name '*.ts'); do
npx -y [email protected] embed text "$(cat "$f")" -o ".vec/${f//\//_}.json"
done
# 3. Insert all embeddings (assumes a JSON array of {id, vector, metadata})
jq -s '[.[] | {id: input_filename, vector: .vector}]' .vec/*.json > corpus.json
npx -y [email protected] insert project.db corpus.json
# 4. Search by query embedding
QV=$(npx -y [email protected] embed text "JWT refresh-token rotation" --output -)
npx -y [email protected] search project.db -v "$QV" -k 5
# 5. Inspect index health
npx -y [email protected] stats project.db
For an alternative store format with lineage tracking, replace steps 1–3 with:
npx -y [email protected] rvf create project.rvf
npx -y [email protected] rvf ingest project.rvf < corpus.json
npx -y [email protected] rvf query project.rvf
| Feature | CLI | Notes |
|---|---|---|
| HNSW search | search <db> -v ... -k N | ~0.045ms latency |
| Adaptive LoRA embeddings | embed text "..." --adaptive --domain code | LoRA-tuned |
| Distance metrics | create <path> -m cosine|euclidean|dot | set at create time |
| RVF cognitive containers | `rvf create | ingest |
| Attention mechanisms | attention list | DotProduct, MultiHead, Flash, Hyperbolic, Linear, MoE, GraphRoPe, EdgeFeatured, DualSpace, LocalGlobal |
| GNN ops | `gnn layer | search |
| Code-graph clustering | hooks graph-cluster <files> | spectral / Louvain |
| Diff embeddings | `hooks diff-analyze | diff-classify |
| Coverage-aware routing | `hooks coverage-route | coverage-suggest` |
| RAG context | hooks rag-context "query" | works in CLI and MCP |
| AST analysis | `hooks ast-analyze | ast-complexity` |
| Self-learning loop | `hooks remember | recall |
| Native workers | `native list | run <security |
| Background workers | `workers dispatch | status |
| Decompile npm/JS | decompile <target> | inspect upstream packages |
| Server | server -p 8080 | HTTP/gRPC mode |
| Demo | `demo --basic | --gnn |
| Identity (pi key) | `identity generate | show |
| Edge compute | `edge status | balance |
| Issue | Detail | Workaround |
|---|---|---|
| ONNX runtime missing | embed text → ONNX WASM files not bundled | npm i ruvector-onnx-embeddings-wasm (see /vector-setup) |
optimize | Self-reports "not yet shipped in this release" | none — track upstream issue 401 |
hooks force-learn | TypeError intel.tick is not a function | run a real trajectory via trajectory-begin/step/end |
hooks graph-mincut | Cannot read properties of undefined (reading 'length') | use hooks graph-cluster |
hooks git-churn | Fails outside a git repo | run from inside the repo |
benchmark | Some installs fail with Missing field 'dimensions' | use attention benchmark or gnn search benchmarking |
cluster (top-level) | Status: Coming Soon | use hooks graph-cluster |
compare, top-level index, midstream, embed --file/--batch/--glob/--model poincare | Don't exist | see commands/vector.md for replacements |
# Full pretrain pipeline + agent generation
npx -y [email protected] hooks init --pretrain --build-agents quality
# Smart agent routing (positional task!)
npx -y [email protected] hooks route "implement OAuth flow"
npx -y [email protected] hooks route-enhanced "fix CVE-2025-1234"
# Code analysis (positional file!)
npx -y [email protected] hooks ast-analyze src/module.ts
npx -y [email protected] hooks diff-analyze HEAD
npx -y [email protected] hooks coverage-route src/module.ts
npx -y [email protected] hooks security-scan src/
npm install @ruvector/pi-brain # required dependency
npx -y [email protected] brain status
npx -y [email protected] brain search "authentication patterns"
npx -y [email protected] brain list
npx -y [email protected] brain drift code # knowledge drift for a domain
npx -y [email protected] sona status
npx -y [email protected] sona patterns "auth refactor"
npx -y [email protected] sona stats
| Operation | Latency | Notes |
|---|---|---|
| HNSW search | ~0.045ms | 8,800x vs ONNX inference |
| Memory cache | ~0.01ms | 40,000x vs ONNX inference |
| Insert | 52,000+/sec | Rust backend (@ruvector/core) |
| Memory per vector | ~50 bytes | Efficient storage |
embed text will report ONNX WASM files not bundled until you install ruvector-onnx-embeddings-wasm.--file, --batch, --glob, --namespace, --k, --task, --model poincare flags — these were in older docs but never shipped in 0.2.25. See agents/vector-engineer.md for the replacement table.brain requires @ruvector/pi-brain — install separately.sona requires @ruvector/ruvllm — install separately (the native binding is not always present in the npm tarball).cluster is "Coming Soon" — for actual clustering use hooks graph-cluster <files>.compare, midstream, top-level index subcommands do not exist.bash plugins/ruflo-ruvector/scripts/smoke.sh
# Expected: "11 passed, 0 failed"
ruflo-agentdb — HNSW storage backend in AgentDBruflo-intelligence — SONA pattern learning integrationruflo-knowledge-graph — Graph RAG for multi-hop retrievalruflo-rag-memory — Simple semantic search via ruvectorMIT