Self-learning vector database powered by ruvector@0.3.3 — HNSW, Adaptive LoRA embeddings, hooks-based intelligence, SONA self-optimizing patterns, brain (collective knowledge), and 97 MCP tools (verified via ruvector mcp tools).
Pinned version: this plugin targets
ruvector@0.3.3. 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 ruvector@0.3.3
# Optional add-ons (install as needed)
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 ruvector@0.3.3 doctorclaude --plugin-dir plugins/ruflo-ruvectorRegister with the pinned version:
claude mcp add ruvector -- npx -y ruvector@0.3.3 mcp startKey tool categories: hooks routing, AST analysis, diff classification, coverage routing, graph clustering, security scanning, RAG context, brain knowledge, SONA learning.
| Skill | Usage | Description |
|---|---|---|
vector-setup |
/vector-setup [--full] |
First-run installer: pins ruvector@0.3.3, 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 |
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 ruvector@0.3.3 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 ruvector@0.3.3 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 ruvector@0.3.3 insert project.db corpus.json
# 4. Search by query embedding
QV=$(npx -y ruvector@0.3.3 embed text "JWT refresh-token rotation" --output -)
npx -y ruvector@0.3.3 search project.db -v "$QV" -k 5
# 5. Inspect index health
npx -y ruvector@0.3.3 stats project.dbFor an alternative store format with lineage tracking, replace steps 1–3 with:
npx -y ruvector@0.3.3 rvf create project.rvf
npx -y ruvector@0.3.3 rvf ingest project.rvf < corpus.json
npx -y ruvector@0.3.3 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 |
|---|---|---|
hooks force-learn |
Runs, but reports skipped: no trajectories to process until a trajectory exists |
record one via trajectory-begin/step/end first |
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, embed --batch/--glob/--model poincare |
Don't exist (embed text takes --input-file and --stdin) |
see commands/vector.md for replacements |
# Full pretrain pipeline + agent generation
npx -y ruvector@0.3.3 hooks init --pretrain --build-agents quality
# Smart agent routing (positional task!)
npx -y ruvector@0.3.3 hooks route "implement OAuth flow"
npx -y ruvector@0.3.3 hooks route-enhanced "fix CVE-2025-1234"
# Code analysis (positional file!)
npx -y ruvector@0.3.3 hooks ast-analyze src/module.ts
npx -y ruvector@0.3.3 hooks diff-analyze HEAD
npx -y ruvector@0.3.3 hooks coverage-route src/module.ts
npx -y ruvector@0.3.3 hooks security-scan src/npm install @ruvector/pi-brain # required dependency
npx -y ruvector@0.3.3 brain status
npx -y ruvector@0.3.3 brain search "authentication patterns"
npx -y ruvector@0.3.3 brain list
npx -y ruvector@0.3.3 brain drift code # knowledge drift for a domainnpx -y ruvector@0.3.3 sona status
npx -y ruvector@0.3.3 sona patterns "auth refactor"
npx -y ruvector@0.3.3 sona stats- ONNX runtime is bundled from 0.3.3 —
embed textworks with no add-on. Older ruvector (0.2.x) reportsONNX WASM files not bundled; this plugin pins 0.3.3 for that reason. - No
--batch,--glob,--namespace,--k,--task,--model poincareflags (embed textdoes take--input-fileand--stdin) — these were in older docs but are not in 0.3.3. Seeagents/vector-engineer.mdfor the replacement table. brainrequires@ruvector/pi-brain— install separately.sonarequires@ruvector/ruvllm— install separately (the native binding is not always present in the npm tarball).- Top-level
clusteris "Coming Soon" — for actual clustering usehooks graph-cluster <files>. compareand top-levelindexsubcommands 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 ruvector
MIT
Function-hook mod (ADR-445, pattern of ruflo-agentdb). It loads from hooks/hooks.json → hooks/register.ts.
A write guard for the vector store and shared brain: hooks_remember, hooks_compress_store, hooks_learn, rvf_ingest, brain_share, brain_transfer and memory_store refuse secrets (a shared brain is the worst place for one). Calls to any tool of the ruvector MCP server are counted.
- Command:
/ruvector-modanswers locally with no model call. Verbs:status,scan <text>,tools(which ruvector tools are connected). - Status file:
.claude-flow/ruvector-mod/status.json({version, updatedMs, ...counters}), written at session start and as counters change. - Safety: no network, no process spawning; it only uses tools already connected.
- Option
guard(onby default,offto disable): a tighten-onlytool.callguard. A call to one of the tools above whose input holds a key, token, private key or password is denied. The reason never repeats the secret. - Test:
claude plugin validate plugins/ruflo-ruvector,claude plugin test plugins/ruflo-ruvector,bash plugins/ruflo-ruvector/scripts/smoke.sh.