π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
fix(plugins): pin ruflo-ruvector to [email protected] + expand verified CLI surface
Reuven6e1bdc211eb4
diff --git a/plugins/ruflo-ruvector/.claude-plugin/plugin.json b/plugins/ruflo-ruvector/.claude-plugin/plugin.jsonindex 73c886f0b7..cbaeac1c0f 100644--- a/plugins/ruflo-ruvector/.claude-plugin/plugin.json+++ b/plugins/ruflo-ruvector/.claude-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "ruflo-ruvector",- "description": "Self-learning vector database via npx ruvector β HNSW, FlashAttention-3, Graph RAG, hybrid search, DiskANN, 103 MCP tools, Brain AGI",- "version": "0.2.0",+ "description": "Self-learning vector database via npx [email protected] β HNSW, adaptive LoRA embeddings, code-graph clustering, hooks routing, brain/SONA, 103 MCP tools",+ "version": "0.2.1","author": {"name": "ruvnet","url": "https://github.com/ruvnet"@@ -13,11 +13,11 @@"ruvector","vector-database","hnsw",- "flash-attention",- "graph-rag",- "hybrid-search",- "diskann",- "mcp",- "brain-agi"+ "adaptive-lora",+ "graph-cluster",+ "hooks",+ "sona",+ "brain",+ "mcp"]}diff --git a/plugins/ruflo-ruvector/README.md b/plugins/ruflo-ruvector/README.mdindex 11c78499cb..ccc2d91a74 100644--- a/plugins/ruflo-ruvector/README.md+++ b/plugins/ruflo-ruvector/README.md@@ -1,15 +1,28 @@# ruflo-ruvector-Self-learning vector database powered by [`ruvector`](https://www.npmjs.com/package/ruvector) β HNSW, FlashAttention-3, Graph RAG, hybrid search, DiskANN, 103 MCP tools, Brain AGI, and 50+ attention mechanisms.+Self-learning vector database powered by [`[email protected]`](https://www.npmjs.com/package/ruvector) β 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.## Overview-Wraps the `ruvector` npm package as a Ruflo plugin, providing vector embedding, semantic search, clustering, hyperbolic space reasoning, self-learning hooks, and Brain AGI diagnostics. ruvector's Rust backend delivers sub-millisecond queries and 52,000+ inserts/sec.+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.## Prerequisites```bash-npm install ruvector+# 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:+```bash+npx -y [email protected] doctor```## Installation@@ -20,107 +33,223 @@ claude --plugin-dir plugins/ruflo-ruvector## MCP Integration (103 Tools)+Register with the pinned version:```bash-claude mcp add ruvector -- npx ruvector mcp start+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, AGI diagnostics, midstream analytics.+Key tool categories: hooks routing, AST analysis, diff classification, coverage routing, graph clustering, security scanning, RAG context, brain knowledge, SONA learning.## Agents| Agent | Model | Role ||-------|-------|------|-| `vector-engineer` | sonnet | Embedding, HNSW indexing, FlashAttention-3, Graph RAG, hybrid search, clustering, hyperbolic space, Brain AGI |+| `vector-engineer` | sonnet | Embedding, HNSW indexing, code-graph clustering, hyperbolic projection, hooks routing, brain/SONA |## Skills| Skill | Usage | Description ||-------|-------|-------------|-| `vector-embed` | `/vector-embed <text-or-file>` | ONNX embeddings (384-dim), normalize, store in HNSW |-| `vector-cluster` | `/vector-cluster <namespace> [--k N]` | k-means or density clustering with labeled summaries |-| `vector-hyperbolic` | `/vector-hyperbolic <text>` | Poincare ball hierarchical embeddings |+| `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 |++## Commands (`/vector` slash command)-## Commands+The full surface is documented in `commands/vector.md` (80+ subcommands). Quick reference:```bash# Embedding-vector embed <text>-vector batch <glob-pattern>-vector compare <text1> <text2>+/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+```++## End-to-End Example: store + search project files-# Search-vector search <query> [--limit N] [--hybrid] [--graph-rag]+```bash+# 0. One-time setup+/vector-setup-# Clustering-vector cluster <namespace> [--k N | --density]+# 1. Create a database+npx -y [email protected] create project.db -d 384 -m cosine-# Index management-vector index create <name>-vector index stats <name>+# 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-# Hyperbolic-vector hyperbolic embed <text>+# 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-# Self-learning hooks-vector hooks init-vector hooks route <task>-vector ast <file>+# 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-# Brain AGI-vector brain status-vector midstream status+# 5. Inspect index health+npx -y [email protected] stats project.db```-## Search Capabilities (ruvector v2.1+)+For an alternative store format with lineage tracking, replace steps 1β3 with:+```bash+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 | Description | Improvement |-|---------|-------------|-------------|-| FlashAttention-3 | IO-aware tiled attention | O(N) memory vs O(N^2) |-| Graph RAG | Knowledge graph + community detection | 30-60% better multi-hop |-| Hybrid Search | Sparse + dense with RRF fusion | 20-49% better retrieval |-| DiskANN / Vamana | SSD-friendly ANN with PQ compression | Large-scale search |-| ColBERT | Per-token late interaction | Fine-grained matching |-| Matryoshka | Adaptive-dimension with cascade | Flexible precision |-| MLA | Multi-Head Latent Attention | ~93% KV-cache compression |-| TurboQuant | 2-4 bit quantization | 6-8x memory reduction |+## Capabilities ([email protected], verified)++| 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|query|derive|compact` | 45 example stores via `rvf examples` |+| Attention mechanisms | `attention list` | DotProduct, MultiHead, Flash, Hyperbolic, Linear, MoE, GraphRoPe, EdgeFeatured, DualSpace, LocalGlobal |+| GNN ops | `gnn layer|search|compress` | multi-head attention layers, differentiable search, tensor compression |+| Code-graph clustering | `hooks graph-cluster <files>` | spectral / Louvain |+| Diff embeddings | `hooks diff-analyze|diff-classify|diff-similar` | git-aware |+| Coverage-aware routing | `hooks coverage-route|coverage-suggest` | test-gap-aware |+| RAG context | `hooks rag-context "query"` | works in CLI and MCP |+| AST analysis | `hooks ast-analyze|ast-complexity` | symbols, complexity, parse time |+| Self-learning loop | `hooks remember|recall|coedit-*|error-*|trajectory-*` | persistent intelligence |+| Native workers | `native list|run <security|analysis|learning>` | no external deps |+| Background workers | `workers dispatch|status|presets|phases` | first run installs `agentic-flow` |+| Decompile npm/JS | `decompile <target>` | inspect upstream packages |+| Server | `server -p 8080` | HTTP/gRPC mode |+| Demo | `demo --basic|--gnn|--graph` | interactive tutorial |+| Identity (pi key) | `identity generate|show|export|import` | for brain + edge |+| Edge compute | `edge status|balance|tasks|join` | distributed, rUv currency |++### Known limitations / bugs in 0.2.25++| 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 |## Self-Learning Hooks```bash-# Full 9-phase pretrain pipeline-npx ruvector hooks init --pretrain --build-agents quality+# 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/+```-# Smart agent routing-npx ruvector hooks route --task "description"+## Brain (Collective Knowledge)-# Code analysis-npx ruvector hooks ast-analyze --file src/module.ts-npx ruvector hooks diff-analyze --file src/module.ts-npx ruvector hooks coverage-route --task "description"-npx ruvector hooks security-scan --path src/-```+```bash+npm install @ruvector/pi-brain # required dependency-## Brain AGI+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+```-Access 8 AGI subsystems:+## SONA (Self-Optimizing Neural Architecture)```bash-npx ruvector brain agi status # Combined diagnostics-npx ruvector brain agi sona # SONA patterns and trajectories-npx ruvector brain agi temporal # Knowledge evolution velocity-npx ruvector brain agi explore # Meta-learning curiosity & regret-npx ruvector brain search "query" # Shared brain knowledge search+npx -y [email protected] sona status+npx -y [email protected] sona patterns "auth refactor"+npx -y [email protected] sona stats```## Performance| Operation | Latency | Notes ||-----------|---------|-------|-| HNSW search | ~0.045ms | 8,800x vs inference |-| Memory cache | ~0.01ms | 40,000x vs inference |-| Insert | 52,000+/sec | Rust backend |+| 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 |+## Known Caveats++- **ONNX runtime not bundled by default** β `embed text` will report `ONNX WASM files not bundled` until you install `ruvector-onnx-embeddings-wasm`.+- **No `--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).+- **Top-level `cluster` is "Coming Soon"** β for actual clustering use `hooks graph-cluster <files>`.+- **`compare`, `midstream`, top-level `index` subcommands do not exist.**++## Architecture Decisions++- [`ADR-0001` β Pin ruflo-ruvector to [email protected] with optional add-ons](./docs/adrs/0001-pin-ruvector-0.2.25.md)++## Smoke test++```bash+bash plugins/ruflo-ruvector/scripts/smoke.sh+# Expected: "11 passed, 0 failed"+```+## Related Plugins- `ruflo-agentdb` β HNSW storage backend in AgentDBdiff --git a/plugins/ruflo-ruvector/agents/vector-engineer.md b/plugins/ruflo-ruvector/agents/vector-engineer.mdindex 16006cfba6..9a5bfa7c4a 100644--- a/plugins/ruflo-ruvector/agents/vector-engineer.md+++ b/plugins/ruflo-ruvector/agents/vector-engineer.md@@ -1,47 +1,57 @@---name: vector-engineer-description: Vector operations specialist using npx ruvector β HNSW indexing, FlashAttention-3, Graph RAG, hybrid search, DiskANN, Brain AGI, 103 MCP tools+description: Vector operations specialist using npx [email protected] β HNSW indexing, adaptive LoRA embeddings, code-graph clustering, hooks routing, brain/SONA, 103 MCP toolsmodel: sonnet---You are a vector engineer that orchestrates the `ruvector` npm package for embedding, indexing, search, clustering, and self-learning intelligence.-### Core Tool: npx ruvector+### Core Tool: npx [email protected] (PINNED)-All vector operations go through the `ruvector` CLI. Install once, then invoke via npx:+All vector operations go through the `ruvector` CLI, pinned to **0.2.25**. Install once, then always invoke with the version pin:```bash-# Ensure installed-npm ls ruvector 2>/dev/null || npm install ruvector--# MCP server (103 tools)-npx ruvector mcp start--# Hooks system (self-learning)-npx ruvector hooks init --pretrain --build-agents quality-npx ruvector hooks route --task "description"-npx ruvector hooks ast-analyze --file src/module.ts-npx ruvector hooks diff-analyze --file src/module.ts-npx ruvector hooks coverage-route --task "description"--# Brain AGI-npx ruvector brain agi status-npx ruvector brain agi sona-npx ruvector brain agi temporal-npx ruvector brain agi explore--# Midstream-npx ruvector midstream status-npx ruvector midstream benchmark+# Ensure pinned version installed+npm ls ruvector 2>/dev/null | grep '0.2.25' || npm install [email protected]++# MCP server (register once with pinned version)+claude mcp add ruvector -- npx -y [email protected] mcp start++# Hooks system (self-learning) β note: positional args, NOT --task / --file+npx -y [email protected] hooks init --pretrain --build-agents quality+npx -y [email protected] hooks route "description"+npx -y [email protected] hooks route-enhanced "description"+npx -y [email protected] hooks ast-analyze src/module.ts+npx -y [email protected] hooks diff-analyze HEAD+npx -y [email protected] hooks diff-classify HEAD+npx -y [email protected] hooks coverage-route src/module.ts+npx -y [email protected] hooks security-scan src/++# Brain (collective knowledge β requires @ruvector/pi-brain)+npm install @ruvector/pi-brain+npx -y [email protected] brain status+npx -y [email protected] brain search "query"+npx -y [email protected] brain list++# SONA (Self-Optimizing Neural Architecture)+npx -y [email protected] sona status+npx -y [email protected] sona patterns "query"+npx -y [email protected] sona stats++# System diagnostics+npx -y [email protected] doctor+npx -y [email protected] info```### MCP Integration-ruvector exposes 103 MCP tools. Add as MCP server for direct tool access:[email protected] exposes 103 MCP tools. Register the MCP server with the pinned version:```bash-claude mcp add ruvector -- npx ruvector mcp start+claude mcp add ruvector -- npx -y [email protected] mcp start```+Verify after registration: `claude mcp list | grep ruvector`.+Key tool categories:- `hooks_route`, `hooks_route_enhanced` β smart agent routing- `hooks_ast_analyze`, `hooks_ast_complexity` β code structure analysis@@ -50,21 +60,33 @@ Key tool categories:- `hooks_graph_mincut`, `hooks_graph_cluster` β code boundaries- `hooks_security_scan` β vulnerability detection- `hooks_rag_context` β semantic context retrieval-- `brain_search`, `brain_share`, `brain_status` β shared brain knowledge-- `brain_agi_status`, `brain_sona_stats` β AGI diagnostics--### Search Capabilities (ruvector v2.1+)--| Feature | Description | Improvement |-|---------|-------------|-------------|-| FlashAttention-3 | IO-aware tiled attention, O(N) memory | Replaces O(N^2) |-| Graph RAG | Knowledge graph + community detection | 30-60% better multi-hop |-| Hybrid Search | Sparse + dense with RRF fusion | 20-49% better retrieval |-| DiskANN / Vamana | SSD-friendly ANN with PQ compression | Large-scale search |-| ColBERT | Per-token late interaction (MaxSim) | Fine-grained matching |-| Matryoshka | Adaptive-dimension with cascade | Flexible precision |-| MLA | Multi-Head Latent Attention | ~93% KV-cache compression |-| TurboQuant | 2-4 bit KV-cache quantization | 6-8x memory reduction |+- `brain_search`, `brain_share`, `brain_status` β shared brain knowledge (needs `@ruvector/pi-brain`)+- `sona_status`, `sona_patterns`, `sona_stats` β SONA learning (needs `@ruvector/ruvllm`)+- `attention_list`, `attention_compute` β attention mechanism dispatch+- `gnn_info`, `gnn_layer`, `gnn_search` β graph neural net ops+- `rvf_create`, `rvf_query`, `rvf_status` β cognitive container management++### Attention Mechanisms (verified via `attention list` on 0.2.25)++```bash+npx -y [email protected] attention list+```+Reports the available mechanisms. Each is a real Rust binding; the CLI exposes `attention compute|benchmark|hyperbolic` to invoke them.++| Mechanism | Complexity | CLI surface |+|---|---|---|+| `DotProductAttention` | O(nΒ²) | `attention compute` |+| `MultiHeadAttention` | O(nΒ²) | `attention compute` |+| `FlashAttention` | O(nΒ²) IO-optimized | `attention compute` / `attention benchmark` |+| `HyperbolicAttention` | O(nΒ²) | `attention hyperbolic` |+| `LinearAttention` | O(n) | `attention compute` |+| `MoEAttention` | O(n*k) | `attention compute` |+| `GraphRoPeAttention` | O(nΒ²) | `attention compute` |+| `EdgeFeaturedAttention` | O(nΒ²) | `attention compute` |+| `DualSpaceAttention` | O(nΒ²) | `attention compute` |+| `LocalGlobalAttention` | O(n*k) | `attention compute` |++> Earlier docs claimed ruvector exposed `Graph RAG`, `Hybrid Search`, `DiskANN`, `ColBERT`, `Matryoshka`, `MLA`, `TurboQuant` as standalone search modes. As of 0.2.25 the **CLI does not surface them as subcommands**. They are either Rust primitives reachable through the native API or planned upstream features. Use `hooks rag-context` for the closest CLI-level RAG capability.### HNSW Parameters Guide@@ -78,26 +100,49 @@ Key tool categories:ruvector's 9-phase pretrain pipeline:```bash-npx ruvector hooks init --pretrain --build-agents quality+npx -y [email protected] hooks init --pretrain --build-agents quality```Phases: AST analysis, diff embeddings, coverage routing, neural training, graph analysis, security scanning, co-edit pattern learning, agent building, RAG context indexing.-### Embedding Operations+### Embedding Operations ([email protected])```bash# Single text embedding (ONNX all-MiniLM-L6-v2, 384-dim)-npx ruvector embed "your text here"--# Batch embedding-npx ruvector embed --batch --glob "src/**/*.ts"--# Similarity search-npx ruvector search "query text" --limit 10--# Compare two texts-npx ruvector compare "text1" "text2"+# NOTE: subcommand is `embed text`, text is positional. There is no `embed "TEXT"` form.+npx -y [email protected] embed text "your text here"+npx -y [email protected] embed text "your text" --adaptive --domain code -o vec.json++# Batch β no built-in glob; loop yourself:+for f in src/**/*.ts; do+ npx -y [email protected] embed text "$(cat "$f")" -o "${f}.vec.json"+done++# Similarity search β requires an existing database and a JSON-encoded query vector+npx -y [email protected] create my.db -d 384 -m cosine+npx -y [email protected] insert my.db vectors.json+npx -y [email protected] search my.db -v '[0.1,0.2,...]' -k 10++# Compare two texts β no top-level `compare` subcommand exists in 0.2.25.+# Embed both and compute cosine similarity in your own code or via MCP `hooks_rag_context`.```+### Removed / Renamed CLI Surface (was in older docs, NOT in 0.2.25)++| Old form (broken) | Replacement |+|-------------------|-------------|+| `ruvector embed "TEXT"` | `ruvector embed text "TEXT"` |+| `ruvector embed --file F` | Read F yourself, pass content as text arg |+| `ruvector embed --batch --glob G` | Shell loop over glob |+| `ruvector compare A B` | Embed both, compute cosine in user code |+| `ruvector index create N` | `ruvector create <path> -d 384` |+| `ruvector index stats N` | `ruvector stats <path>` |+| `ruvector cluster --namespace N --k K` | `ruvector hooks graph-cluster <files>` |+| `ruvector embed --model poincare T` | Embed normally, project to Poincare in user code |+| `ruvector hooks route --task X` | `ruvector hooks route "X"` (positional) |+| `ruvector hooks ast-analyze --file F` | `ruvector hooks ast-analyze F` (positional) |+| `ruvector brain agi status` | `ruvector brain status` (needs `@ruvector/pi-brain`) |+| `ruvector midstream status` | (no replacement β command not present) |+### Performance (ruvector benchmarks)| Operation | Latency | Throughput |@@ -108,18 +153,23 @@ npx ruvector compare "text1" "text2"| Insert | - | 52,000+ vectors/sec || Memory per vector | ~50 bytes | - |-### Clustering+### Clustering (code graph only in 0.2.25)-- **k-means**: `npx ruvector cluster --namespace patterns --k 5`-- **Density (DBSCAN)**: `npx ruvector cluster --namespace patterns --density`+The top-level `cluster` subcommand is reserved for distributed cluster ops ("Coming Soon"). For actual community detection over a code graph use:+```bash+npx -y [email protected] hooks graph-cluster <files...> # spectral / Louvain+npx -y [email protected] hooks graph-mincut <files...> # min-cut boundaries+```+For namespaced k-means / DBSCAN over arbitrary embeddings, run the algorithm in your own code against vectors stored in AgentDB.### Hyperbolic Embeddings (Poincare Ball)-For hierarchical data (dependency trees, taxonomies, module structures):[email protected] has no `--model poincare` flag. For hierarchical data, embed normally and project to the Poincare ball in your own code:```bash-npx ruvector embed --model poincare "hierarchical concept"-npx ruvector search --model poincare "query" --limit 10+npx -y [email protected] embed text "hierarchical concept" -o concept.vec.json+# then normalize to live inside the unit ball: x_i / (||x|| * (1 + epsilon))```+The experimental neural substrate (`embed neural --help`) may expose richer projections in future versions.### Memory Persistencediff --git a/plugins/ruflo-ruvector/commands/vector.md b/plugins/ruflo-ruvector/commands/vector.mdindex 8c78a7c55d..cb501f01d5 100644--- a/plugins/ruflo-ruvector/commands/vector.md+++ b/plugins/ruflo-ruvector/commands/vector.md@@ -1,67 +1,155 @@---name: vector-description: RuVector operations via npx ruvector β embedding, search, clustering, indexing, hyperbolic, hooks, brain AGI+description: RuVector operations via npx [email protected] β embedding, search, RVF cognitive containers, GNN, attention, hooks, brain, sona, edge, identity---$ARGUMENTS-Vector operations via the `ruvector` npm package. Parse subcommand from $ARGUMENTS.+Vector operations via the `ruvector` npm package (pinned to 0.2.25). Parse subcommand from $ARGUMENTS.-Usage: /vector <subcommand> [options]--Subcommands:--1. For **embed `<text>`**:- Run: `npx ruvector embed "TEXT"`- For files: `npx ruvector embed --file src/module.ts`- Return the 384-dim vector and confirm storage.--2. For **batch `<glob-pattern>`**:- Run: `npx ruvector embed --batch --glob "PATTERN"`- Report count of vectors inserted and index size.+Pinned version: `[email protected]` β every command below uses `npx -y [email protected] ...`.-3. For **search `<query>` [--limit N]**:- Run: `npx ruvector search "QUERY" --limit N`- Present results ranked by similarity score.- For hybrid search: `npx ruvector search "QUERY" --hybrid`- For Graph RAG: `npx ruvector search "QUERY" --graph-rag`--4. For **compare `<text1>` `<text2>`**:- Run: `npx ruvector compare "TEXT1" "TEXT2"`- Report cosine similarity as decimal and percentage.--5. For **cluster `<namespace>` [--k N]**:- Run: `npx ruvector cluster --namespace NAMESPACE --k N`- Without --k, uses density clustering: `npx ruvector cluster --namespace NAMESPACE --density`- Present cluster summaries with labels, counts, and cohesion.--6. For **index create `<name>`**:- Run: `npx ruvector index create NAME --M 16 --efConstruction 200`- Confirm creation with parameters.+Usage: /vector <subcommand> [options]-7. For **index stats `<name>`**:- Run: `npx ruvector index stats NAME`- Report vector count, dimension, M, efConstruction, memory usage.+## Embedding++1. **embed `<text>`** β `npx -y [email protected] embed text "TEXT"`+ 384-dim ONNX vector. If `ONNX WASM files not bundled`, run `/vector setup`.+2. **embed-adaptive `<text>`** β `npx -y [email protected] embed text "TEXT" --adaptive --domain code`+ LoRA-adapted embedding tuned to a domain.+3. **embed-file `<path>`** β Read file, then `npx -y [email protected] embed text "$(cat <path>)" -o <path>.vec.json`+4. **embed-benchmark** β `npx -y [email protected] embed benchmark` (compares base vs adaptive).++## Database lifecycle++5. **db create `<path>`** β `npx -y [email protected] create <path> -d 384 -m cosine`+6. **db stats `<path>`** β `npx -y [email protected] stats <path>`+7. **insert `<database>` `<json-file>`** β `npx -y [email protected] insert <database> <json-file>`+8. **search `<database>` `<vector-json>` [-k N]** β `npx -y [email protected] search <database> -v '[0.1,...]' -k N`+9. **export `<database>` [-o file] [-f json|binary|parquet] [--compress]** β `npx -y [email protected] export <database> -o backup.json`+10. **import `<file>` [-d database]** β `npx -y [email protected] import <file> -d <database> [--merge|--replace]`++## RVF (cognitive containers)++11. **rvf create `<path>`** β `npx -y [email protected] rvf create <path>`+12. **rvf ingest `<path>`** β `npx -y [email protected] rvf ingest <path>`+13. **rvf query `<path>`** β `npx -y [email protected] rvf query <path>` (nearest neighbors)+14. **rvf status `<path>`** β `npx -y [email protected] rvf status <path>`+15. **rvf segments `<path>`** β `npx -y [email protected] rvf segments <path>`+16. **rvf derive `<parent>` `<child>`** β `npx -y [email protected] rvf derive <parent> <child>` (lineage tracking)+17. **rvf compact `<path>`** β `npx -y [email protected] rvf compact <path>` (reclaim deleted space)+18. **rvf examples** β `npx -y [email protected] rvf examples` (45 reference stores)+19. **rvf download `<name>`** β `npx -y [email protected] rvf download <name>` (e.g. `agent_memory`, `swarm_knowledge`)++## GNN (Graph Neural Networks)++20. **gnn info** β `npx -y [email protected] gnn info`+21. **gnn layer** β `npx -y [email protected] gnn layer` (build/test a multi-head attention GNN layer)+22. **gnn search** β `npx -y [email protected] gnn search` (differentiable soft-attention search)+23. **gnn compress** β `npx -y [email protected] gnn compress` (5-level adaptive tensor compression)++## Attention mechanisms++24. **attention list** β `npx -y [email protected] attention list`+ Lists ALL available mechanisms: DotProduct, MultiHead, Flash, Hyperbolic, Linear, MoE, GraphRoPe, EdgeFeatured, DualSpace, LocalGlobal.+25. **attention compute** β `npx -y [email protected] attention compute`+26. **attention benchmark** β `npx -y [email protected] attention benchmark`+27. **attention hyperbolic** β `npx -y [email protected] attention hyperbolic` (Poincare-ball geometry ops; the real hyperbolic surface in 0.2.25)+28. **attention info** β `npx -y [email protected] attention info`++## Code intelligence (hooks)++29. **hooks init** β `npx -y [email protected] hooks init --pretrain --build-agents quality`+30. **hooks stats** β `npx -y [email protected] hooks stats` (Q-learning patterns, vector memories, trajectories)+31. **hooks route `<task>`** β `npx -y [email protected] hooks route "DESCRIPTION"` (positional)+32. **hooks route-enhanced `<task>`** β `npx -y [email protected] hooks route-enhanced "DESCRIPTION"`+33. **hooks suggest-context** β `npx -y [email protected] hooks suggest-context`+34. **hooks ast-analyze `<file>`** β `npx -y [email protected] hooks ast-analyze <file>` (positional)+35. **hooks ast-complexity `<files...>`** β `npx -y [email protected] hooks ast-complexity <files...>`+36. **hooks diff-analyze [commit]** β `npx -y [email protected] hooks diff-analyze HEAD`+37. **hooks diff-classify [commit]** β `npx -y [email protected] hooks diff-classify HEAD`+38. **hooks diff-similar** β `npx -y [email protected] hooks diff-similar`+39. **hooks coverage-route `<file>`** β `npx -y [email protected] hooks coverage-route <file>`+40. **hooks coverage-suggest `<files...>`** β `npx -y [email protected] hooks coverage-suggest <files...>`+41. **hooks graph-cluster `<files...>`** β `npx -y [email protected] hooks graph-cluster <files...>` (spectral/Louvain)+42. **hooks rag-context `<query>`** β `npx -y [email protected] hooks rag-context "QUERY"`+43. **hooks security-scan `<files...>`** β `npx -y [email protected] hooks security-scan <files...>` (run `hooks init` first)+44. **hooks remember `<content>`** β `npx -y [email protected] hooks remember "CONTENT"`+45. **hooks recall `<query>`** β `npx -y [email protected] hooks recall "QUERY"`+46. **hooks coedit-record / coedit-suggest** β record + retrieve files edited together.+47. **hooks error-record / error-suggest** β learn errorβfix pairs and retrieve.+48. **hooks trajectory-begin / trajectory-step / trajectory-end** β record an execution trajectory.+49. **hooks pre-edit / post-edit / pre-command / post-command / session-start / session-end** β Claude Code hook lifecycle.++> **Known bugs in 0.2.25 hooks:** `force-learn` raises `intel.tick is not a function`; `graph-mincut` raises `Cannot read properties of undefined`; `git-churn` fails outside a git repo. Avoid these or run inside a git repo with seeded intelligence state.++## Native + workers (background analysis)++50. **native list** β `npx -y [email protected] native list` (worker types: security, analysis, learning)+51. **native run `<type>`** β `npx -y [email protected] native run security` (or analysis|learning)+52. **native benchmark** β `npx -y [email protected] native benchmark`+53. **native compare** β `npx -y [email protected] native compare`+54. **workers triggers / presets / phases / dispatch / status / stats / cleanup / cancel / run / create / init-config** β all available via `npx -y [email protected] workers <subcmd>`. First invocation auto-installs `agentic-flow` (slow).++## Collective knowledge (brain) β needs `@ruvector/pi-brain`++55. **brain status** β `npx -y [email protected] brain status`+56. **brain search `<query>`** β `npx -y [email protected] brain search "QUERY"`+57. **brain share `<title>`** β `npx -y [email protected] brain share "TITLE"`+58. **brain list / get / vote / delete / drift / partition / transfer / sync / page** β full Brainpedia + LoRA-weight management.++## SONA (Self-Optimizing Neural Architecture) β needs `@ruvector/ruvllm`++59. **sona status / info / stats** β `npx -y [email protected] sona status`+60. **sona patterns `<query>`** β `npx -y [email protected] sona patterns "QUERY"`+61. **sona train `<data>`** β `npx -y [email protected] sona train <data>` (record a training trajectory)+62. **sona export** β `npx -y [email protected] sona export` (export learned weights)++## LLM orchestration β needs `@ruvector/ruvllm`++63. **llm models** β `npx -y [email protected] llm models`+64. **llm embed `<text>`** β `npx -y [email protected] llm embed "TEXT"` (RuvLLM-backed embeddings)+65. **llm benchmark** β `npx -y [email protected] llm benchmark`+66. **llm info** β `npx -y [email protected] llm info`++## Identity (pi key for brain/edge/MCP)++67. **identity generate** β `npx -y [email protected] identity generate` (creates a 64-hex-char pi key)+68. **identity show** β `npx -y [email protected] identity show`+69. **identity export `-o file`** β `npx -y [email protected] identity export -o key.enc` (encrypted backup)+70. **identity import `<file>`** β `npx -y [email protected] identity import <file>`++## Edge compute network++71. **edge status** β `npx -y [email protected] edge status`+72. **edge balance [nodeId]** β `npx -y [email protected] edge balance` (rUv balance)+73. **edge tasks** β `npx -y [email protected] edge tasks`+74. **edge join** β `npx -y [email protected] edge join` (join the network as a node)+75. **edge dashboard** β `npx -y [email protected] edge dashboard` (opens in browser)++## Server / Decompile / Demo-8. For **hyperbolic embed `<text>`**:- Run: `npx ruvector embed --model poincare "TEXT"`- Return Poincare ball coordinates.+76. **server [-p 8080] [-g 50051] [-d data-dir]** β `npx -y [email protected] server -p 8080`+77. **decompile `<target>` [-o dir] [-f modules|single|json]** β `npx -y [email protected] decompile <npm-pkg-or-file-or-url>`+78. **demo --basic | --gnn | --graph** β `npx -y [email protected] demo --basic` (interactive tutorial)++## System++79. **doctor** β `npx -y [email protected] doctor` (Node, npm, bindings, Rust)+80. **info** β `npx -y [email protected] info`+81. **benchmark** β `npx -y [email protected] benchmark` (known issue: fails with `Missing field 'dimensions'` on some installs; use `gnn search` or `attention benchmark` as alternatives)+82. **install [pkg|--all]** β `npx -y [email protected] install --all` (lists/installs optional add-ons)+83. **setup** β `npx -y [email protected] setup` (Setup Guide)-9. For **hooks init**:- Run: `npx ruvector hooks init --pretrain --build-agents quality`- Initialize self-learning with 9-phase pretrain pipeline.+## Setup helper-10. For **hooks route `<task>`**:- Run: `npx ruvector hooks route --task "DESCRIPTION"`- Return smart agent routing recommendation.+For first-run users hitting `ONNX WASM files not bundled`, `Brain commands require @ruvector/pi-brain`, or `SONA not available`, invoke the `vector-setup` skill: `/vector-setup`.-11. For **ast `<file>`**:- Run: `npx ruvector hooks ast-analyze --file FILE`- Return AST analysis with symbols, complexity, imports.+## MCP server (103 tools)-12. For **brain status**:- Run: `npx ruvector brain agi status`- Show AGI subsystem diagnostics.+- Register once: `claude mcp add ruvector -- npx -y [email protected] mcp start`+- Verify: `claude mcp list | grep ruvector`+- Then call MCP tools directly (e.g. `hooks_route`, `hooks_ast_analyze`, `hooks_rag_context`, `brain_search`, `attention_list`).++## Not in 0.2.25 (do not invoke)-13. For **midstream status**:- Run: `npx ruvector midstream status`- Show streaming analysis platform overview.+`compare`, top-level `index`, `midstream`, `embed --file`, `embed --batch --glob`, `cluster --namespace --k` (top-level `cluster` is "Coming Soon"), `embed --model poincare`, `optimize` (per its own message: "not yet shipped in this release"), `brain agi *` (use `brain status` directly).diff --git a/plugins/ruflo-ruvector/docs/adrs/0001-pin-ruvector-0.2.25.md b/plugins/ruflo-ruvector/docs/adrs/0001-pin-ruvector-0.2.25.mdnew file mode 100644index 0000000000..f1d2e9ff02--- /dev/null+++ b/plugins/ruflo-ruvector/docs/adrs/0001-pin-ruvector-0.2.25.md@@ -0,0 +1,122 @@+---+id: ADR-0001+title: Pin ruflo-ruvector plugin to [email protected] with optional add-on packages+status: Accepted+date: 2026-05-04+authors:+ - reviewer (Claude Code)+tags: [plugin, ruvector, versioning, mcp, dependencies]+---++## Context++The `ruflo-ruvector` plugin wraps the `ruvector` npm package as a Claude Code plugin. The plugin's documentation (README, agent file, skills, command spec) drifted from the actual CLI surface in two ways:++1. **Aspirational features.** Older docs referenced `FlashAttention-3`, `Graph RAG`, `Hybrid Search`, `DiskANN`, `ColBERT`, `Matryoshka`, `MLA`, `TurboQuant`, `Brain AGI`, and `Midstream` as if they were invokable CLI subcommands. The native Rust bindings expose primitives for most of these, but **no CLI subcommand wires them up** β only `attention list` enumerates the mechanisms.+2. **Unspecified version.** The plugin invoked `npx ruvector ...` without a version pin, so a user with `[email protected]` resolved would silently get a different surface (no `brain`, no `route`, no `sona`) than a user on `[email protected]`.++Concretely, this caused:++- `npx ruvector embed "TEXT"` β `unknown command 'TEXT'` (real form is `embed text "TEXT"`)+- `npx ruvector compare A B` β command does not exist+- `npx ruvector cluster --namespace ... --k N` β `cluster` is for distributed cluster ops, not k-means+- `npx ruvector hooks route --task X` β unknown option `--task` (positional)+- `npx ruvector brain agi status` β no `agi` subgroup+- `npx ruvector midstream status` β command does not exist+- `npx ruvector index create N` β command does not exist (use `create <path>`)++A live audit against `[email protected]` confirmed which subcommands work, which require optional add-on packages, and which are upstream bugs.++## Decision++The plugin pins to `[email protected]` and documents the optional add-on packages required for full functionality.++### 1. Pin every CLI invocation++All `npx` calls in the plugin (README, agent, skills, commands, scripts) MUST be of the form:++```bash+npx -y [email protected] <subcommand> [args]+```++Rationale: the `-y` flag suppresses the npm interactive prompt; the version pin prevents a future ruvector release from breaking the plugin's contract without our knowledge.++### 2. Treat add-ons as opt-in extensions, not required deps++| Package | Enables | Plugin subcommands gated on it |+|---------|---------|------------------------------|+| `ruvector-onnx-embeddings-wasm` | ONNX runtime | `embed text`, `embed adaptive`, `llm embed` |+| `@ruvector/pi-brain` | Collective brain | `brain *` |+| `@ruvector/ruvllm` | RuvLLM + SONA JS fallback | `sona *`, `llm *` |+| `@ruvector/graph-node` | Graph database (Cypher) | `graph -q ...` |+| `@ruvector/router` | Semantic router | `router --route ...` |++Rationale: these are heavy dependencies (ONNX runtime alone is large). Forcing them at install time penalizes users who only want hooks routing or RVF storage. Instead we provide a `vector-setup` skill and document the precise error message β install command mapping.++### 3. Register MCP server with the same pin++```bash+claude mcp add ruvector -- npx -y [email protected] mcp start+```++Rationale: the MCP transport layer changes between minor versions of ruvector. Pinning the MCP command keeps the 103 exposed tools stable for downstream agents.++### 4. Removed surface stays removed++The plugin MUST NOT reintroduce the following invocations even if upstream re-adds equivalents under different names without prior coordination:++- `compare`, `midstream`, top-level `index` (replaced by `create <path>` / `stats <path>`)+- `embed --file`, `embed --batch --glob`, `embed --model poincare` (no equivalent flags exist)+- `cluster --namespace --k` (replaced by `hooks graph-cluster <files>`)+- `hooks route --task`, `hooks ast-analyze --file` (use positional arguments)+- `brain agi *` (replaced by `brain status`, `brain search`, etc.)++A future ADR may relax this if upstream introduces a stable equivalent and we update the smoke test accordingly.++### 5. Smoke test as the contract++`scripts/smoke.sh` verifies the contracted surface against any installed `[email protected]`. It must remain green on every plugin change. Tests cover:++- Version pin (`--version` returns `0.2.25`)+- Top-level subcommand visibility (`hooks`, `embed`, `rvf`, `attention`, `gnn`, `brain`, `sona`, `create`, `stats`, `search`, `insert`)+- `hooks route` accepts a positional task argument+- `hooks ast-analyze` accepts a positional file argument+- `hooks ast-complexity`, `attention list`, `rvf examples`, `gnn info`, `info`, `doctor` work+- Removed surface (`compare`, `midstream`, `index`) returns `unknown command`++### 6. Plugin version policy++The plugin's own `version` field in `.claude-plugin/plugin.json` is bumped (patch) on every change to the CLI contract β regardless of whether the change is additive (new subcommand exposed) or a fix. This makes plugin version differences observable to downstream consumers.++## Consequences++**Positive:**++- Every documented invocation in the plugin matches a real CLI surface that is verified by a smoke test.+- New users hit a deterministic `vector-setup` flow instead of cryptic ONNX/Brain/SONA errors.+- Future ruvector releases can be evaluated by running the smoke test against the new version before bumping the pin.+- The "Capabilities" table in README is now a contract, not a wishlist.++**Negative:**++- Bumping the pin requires a deliberate test pass. New ruvector features land in the plugin only after a manual review.+- Add-on packages (`ruvector-onnx-embeddings-wasm`, `@ruvector/pi-brain`, `@ruvector/ruvllm`) must be installed manually or via `/vector-setup`. Users who skip this and try `embed text` will hit the documented error.++**Neutral:**++- The plugin's "Search Capabilities" feature table now reflects the actual CLI surface. FlashAttention-3 et al. are listed under `attention list` rather than as standalone search modes.++## Verification++```bash+# Plugin contract check+bash plugins/ruflo-ruvector/scripts/smoke.sh+# Expected: "11 passed, 0 failed"+```++## Related++- `commands/vector.md` β full subcommand mapping+- `skills/vector-setup/SKILL.md` β first-run installer+- `agents/vector-engineer.md` β agent contract with replacement table+- Upstream issue 401 (`optimize` not yet shipped)diff --git a/plugins/ruflo-ruvector/scripts/smoke.sh b/plugins/ruflo-ruvector/scripts/smoke.shnew file mode 100755index 0000000000..ea7c3e6601--- /dev/null+++ b/plugins/ruflo-ruvector/scripts/smoke.sh@@ -0,0 +1,76 @@+#!/usr/bin/env bash+# Smoke test for ruflo-ruvector plugin against [email protected].+# Exits non-zero if any contracted CLI surface is missing or behaves+# differently from documented. Run after `npm install [email protected]`+# (or rely on the npx fetch).+set -u+PIN="[email protected]"+PASS=0+FAIL=0+WORKDIR="$(mktemp -d -t ruvector-smoke.XXXXXX)"+trap 'rm -rf "$WORKDIR"' EXIT+cd "$WORKDIR" || exit 2++step() { printf "β %s ... " "$1"; }+ok() { printf "PASS\n"; PASS=$((PASS+1)); }+bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }++run() { npx -y "$PIN" "$@" 2>&1; }++step "version pin"+# --version output may include npm warnings; take the last non-empty line.+ver=$(run --version | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | tail -1)+[[ "$ver" == "0.2.25" ]] && ok || bad "expected 0.2.25, got '$ver'"++step "top-level help mentions hooks/embed/rvf/attention/gnn/brain/sona"+help=$(run --help)+missing=""+for c in hooks embed rvf attention gnn brain sona create stats search insert; do+ grep -qE "^[[:space:]]+$c( |\$)" <<<"$help" || missing="$missing $c"+done+[[ -z "$missing" ]] && ok || bad "missing:$missing"++step "hooks route is positional"+out=$(run hooks route "test task")+grep -q '"recommended"' <<<"$out" && ok || bad "no JSON 'recommended' field β got: $out"++step "hooks ast-analyze on a sample TS file"+echo 'export const x = 1;' > sample.ts+out=$(run hooks ast-analyze sample.ts)+grep -q "AST Analysis" <<<"$out" && ok || bad "ast-analyze did not return summary"++step "hooks ast-complexity returns JSON"+out=$(run hooks ast-complexity sample.ts)+grep -q '"cyclomatic"' <<<"$out" && ok || bad "ast-complexity output unexpected"++step "attention list shows mechanisms"+out=$(run attention list)+grep -q "FlashAttention" <<<"$out" && ok || bad "attention list missing FlashAttention"++step "rvf examples lists at least 10 stores"+out=$(run rvf examples)+n=$(grep -cE '^\s+[a-z_]+\s+[0-9]' <<<"$out")+[[ $n -ge 10 ]] && ok || bad "expected β₯10 RVF examples, got $n"++step "gnn info reports Available"+out=$(run gnn info)+grep -q "Status:.*Available" <<<"$out" && ok || bad "gnn info did not report Available"++step "info reports CLI Version 0.2.25"+out=$(run info)+grep -q "CLI Version: 0.2.25" <<<"$out" && ok || bad "info did not report 0.2.25"++step "doctor exits 0"+run doctor >/dev/null && ok || bad "doctor returned non-zero"++step "removed surface stays removed (compare/midstream/index)"+fail_removed=""+for c in compare midstream index; do+ # Don't pass --help β Commander will show top-level help instead of the error.+ out=$(npx -y "$PIN" "$c" 2>&1)+ grep -q "unknown command '$c'" <<<"$out" || fail_removed="$fail_removed $c"+done+[[ -z "$fail_removed" ]] && ok || bad "still present:$fail_removed"++printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"+[[ $FAIL -eq 0 ]] || exit 1diff --git a/plugins/ruflo-ruvector/skills/vector-cluster/SKILL.md b/plugins/ruflo-ruvector/skills/vector-cluster/SKILL.mdindex 40a1138813..10d5afd5ea 100644--- a/plugins/ruflo-ruvector/skills/vector-cluster/SKILL.md+++ b/plugins/ruflo-ruvector/skills/vector-cluster/SKILL.md@@ -1,6 +1,6 @@---name: vector-cluster-description: Cluster vectors by similarity using npx ruvector k-means or density-based methods with labeled group summaries+description: Cluster code by graph community detection via npx [email protected] hooks graph-cluster (spectral / Louvain)argument-hint: "<namespace> [--k N]"allowed-tools: Bash Read mcp__claude-flow__memory_search mcp__claude-flow__memory_store mcp__claude-flow__memory_list---@@ -15,28 +15,27 @@ Use this skill when you have a collection of embeddings and want to discover nat## Steps-1. **Ensure ruvector is available**:+1. **Ensure [email protected] is available**:```bash- npm ls ruvector 2>/dev/null || npm install ruvector+ npm ls ruvector 2>/dev/null | grep '0.2.25' || npm install [email protected]```-2. **Run clustering**:- - With known cluster count: `npx ruvector cluster --namespace NAMESPACE --k N`- - With auto-detection: `npx ruvector cluster --namespace NAMESPACE --density`-3. **Review output** -- ruvector reports: cluster ID, label, member count, cohesion score, and outliers (for density mode)+2. **Run clustering** β in [email protected] the only working clustering is via `hooks graph-cluster` (spectral/Louvain over a code graph). The top-level `cluster` command is reserved for distributed cluster ops and is currently "Coming Soon" upstream.+ ```bash+ npx -y [email protected] hooks graph-cluster <files...>+ npx -y [email protected] hooks graph-mincut <files...>+ ```+3. **Review output** β JSON with cluster assignments, community labels, and edges. If you see `"graph.nodes is not iterable"`, run `hooks init` first to seed the graph state.4. **Store results**:- `mcp__claude-flow__memory_store({ key: "clusters-NAMESPACE-TIMESTAMP", value: "CLUSTER_ASSIGNMENTS", namespace: "vector-clusters" })`+ `mcp__claude-flow__memory_store({ key: "clusters-PROJECT-TIMESTAMP", value: "CLUSTER_ASSIGNMENTS", namespace: "vector-clusters" })`## Interpreting results- **High cohesion** (>0.85): tight, well-defined cluster- **Medium cohesion** (0.6-0.85): related but diverse content-- **Low cohesion** (<0.6): loose grouping, try higher k-- **Outliers**: novel or anomalous entries worth investigating+- **Low cohesion** (<0.6): loose grouping, try higher resolution+- **Outliers**: novel or anomalous files worth investigating-## Graph-based clustering (ruvector v2.1+)+## Caveats-ruvector supports Louvain community detection and spectral clustering for graph-structured data:-```bash-npx ruvector hooks graph-cluster --namespace NAMESPACE-npx ruvector hooks graph-mincut --namespace NAMESPACE-```+- `cluster --namespace ... --k N` and `cluster --density` are **not** valid in [email protected] β those flags fall through to the distributed-cluster command, which only accepts `--status`, `--join`, `--leave`, `--nodes`, `--leader`, `--info`.+- For namespaced k-means over arbitrary embeddings, run k-means in your own code against vectors stored in AgentDB.diff --git a/plugins/ruflo-ruvector/skills/vector-embed/SKILL.md b/plugins/ruflo-ruvector/skills/vector-embed/SKILL.mdindex bfefded3df..66d3f56153 100644--- a/plugins/ruflo-ruvector/skills/vector-embed/SKILL.md+++ b/plugins/ruflo-ruvector/skills/vector-embed/SKILL.md@@ -1,6 +1,6 @@---name: vector-embed-description: Generate embeddings via npx ruvector (ONNX all-MiniLM-L6-v2, 384-dim), normalize, and store in HNSW index+description: Generate embeddings via npx [email protected] embed text (ONNX all-MiniLM-L6-v2, 384-dim), normalize, and store in HNSW indexargument-hint: "<text-or-file>"allowed-tools: Bash Read mcp__claude-flow__memory_store mcp__claude-flow__memory_search---@@ -15,29 +15,33 @@ Use this skill to embed text, code, or documents into 384-dimensional vectors fo## Steps-1. **Ensure ruvector is available**:+1. **Ensure [email protected] is available**:```bash- npm ls ruvector 2>/dev/null || npm install ruvector+ npm ls ruvector 2>/dev/null | grep '0.2.25' || npm install [email protected]```-2. **Embed the input**:- - For text: `npx ruvector embed "your text here"`- - For a file: `npx ruvector embed --file src/module.ts`- - For batch: `npx ruvector embed --batch --glob "src/**/*.ts"`-3. **Normalization** -- ruvector L2-normalizes by default (unit sphere, cosine similarity). Alternatives: `--norm l1`, `--norm minmax`, `--norm zscore`-4. **Confirm** -- report vector ID, dimension (384), norm, and index stored in+ If `embed text` later reports `ONNX WASM files not bundled`, also run:+ ```bash+ npm install ruvector-onnx-embeddings-wasm+ ```+2. **Embed the input** (use the `text` subcommand, with text as a positional arg):+ - Single string: `npx -y [email protected] embed text "your text here"`+ - With output file: `npx -y [email protected] embed text "your text here" -o vec.json`+ - For a file: read its content via the Read tool, then pass it as the positional argument.+ - For batch: loop over files in shell β [email protected] has no built-in `--batch`/`--glob` flags.+3. **Adaptive (LoRA) variant**: `npx -y [email protected] embed text "..." --adaptive --domain code`+4. **Confirm** β report vector dimension (384), norm, and any output path written.5. **Store metadata** in AgentDB if needed:`mcp__claude-flow__memory_store({ key: "embed-SOURCE", value: "VECTOR_METADATA", namespace: "vector-patterns" })`## MCP alternative-If ruvector MCP server is connected (`claude mcp add ruvector -- npx ruvector mcp start`):-- `hooks_rag_context` β semantic context retrieval-- `brain_search` β shared brain knowledge search--## Batch embedding-+Register the MCP server once with the pinned version:```bash-npx ruvector embed --batch --glob "src/**/*.ts"+claude mcp add ruvector -- npx -y [email protected] mcp start```+Then call MCP tools directly: `hooks_rag_context` (semantic context), `brain_search` (collective brain), `hooks_ast_analyze`, `hooks_route`.++## Caveats-Reports total vectors inserted and index growth.+- The `embed --batch --glob` and `embed --file` flags do **not** exist in [email protected]; only `embed text <text>` is supported. Read files yourself and call `embed text` per file.+- ONNX runtime is not bundled by default. If embedding fails, install `ruvector-onnx-embeddings-wasm` or run `npx -y [email protected] doctor` to diagnose.diff --git a/plugins/ruflo-ruvector/skills/vector-hyperbolic/SKILL.md b/plugins/ruflo-ruvector/skills/vector-hyperbolic/SKILL.mdindex 999114febd..9bcb6482a4 100644--- a/plugins/ruflo-ruvector/skills/vector-hyperbolic/SKILL.md+++ b/plugins/ruflo-ruvector/skills/vector-hyperbolic/SKILL.md@@ -1,6 +1,6 @@---name: vector-hyperbolic-description: Embed hierarchical data in hyperbolic space via npx ruvector Poincare ball model, compute geodesic distances+description: Embed hierarchical data via npx [email protected] embed text and project into the Poincare ball in user code (no --model poincare flag in 0.2.25)argument-hint: "<text> [--model poincare]"allowed-tools: Bash Read mcp__claude-flow__memory_store mcp__claude-flow__memory_search---@@ -15,24 +15,29 @@ Use this skill when your data has inherent hierarchy β dependency trees, modul## Steps-1. **Ensure ruvector is available**:+1. **Ensure [email protected] is available**:```bash- npm ls ruvector 2>/dev/null || npm install ruvector+ npm ls ruvector 2>/dev/null | grep '0.2.25' || npm install [email protected]```-2. **Embed in Poincare ball**:+2. **Generate a base ONNX embedding** ([email protected] does not expose a `--model poincare` flag on `embed text`):```bash- npx ruvector embed --model poincare "hierarchical concept"+ npx -y [email protected] embed text "hierarchical concept" -o concept.vec.json```- Coordinates near origin = generic/root; near boundary = specific/leaf.-3. **Search in hyperbolic space**:+3. **Project into the Poincare ball** in your own code (or via the experimental neural substrate):```bash- npx ruvector search --model poincare "query" --limit 10+ npx -y [email protected] embed neural --help```+ For an ad-hoc projection, normalize the 384-dim vector to live inside the unit ball (`x_i / (||x|| * (1 + epsilon))`) and persist the projected coordinates alongside the original embedding.4. **Geodesic distance**: `d(u, v) = arcosh(1 + 2 * ||u-v||^2 / ((1-||u||^2)(1-||v||^2)))`Distance grows logarithmically with tree depth, preserving hierarchy.5. **Store results**:`mcp__claude-flow__memory_store({ key: "hyperbolic-CONCEPT", value: "COORDINATES_AND_NEIGHBORS", namespace: "hyperbolic-embeddings" })`+## Caveats++- [email protected] has no first-class Poincare ball CLI flag. Treat hyperbolic projection as a post-processing step over a standard ONNX embedding.+- If you need a hyperbolic search index, store projected coordinates in AgentDB and compute geodesic distance in your own retrieval code.+## Poincare ball properties| Property | Meaning |diff --git a/plugins/ruflo-ruvector/skills/vector-setup/SKILL.md b/plugins/ruflo-ruvector/skills/vector-setup/SKILL.mdnew file mode 100644index 0000000000..2758c79e27--- /dev/null+++ b/plugins/ruflo-ruvector/skills/vector-setup/SKILL.md@@ -0,0 +1,82 @@+---+name: vector-setup+description: First-run setup for [email protected] β installs ONNX/Brain/SONA add-ons, registers the MCP server, and verifies the install via `doctor`+argument-hint: "[--full]"+allowed-tools: Bash Read+---++# Vector Setup++Bootstraps `[email protected]` and its optional add-ons so every `/vector` subcommand actually works on first run.++## Why this exists++Out of the box, several `/vector` subcommands fail with a confusing dep error:++| Error | Missing package |+|-------|-----------------|+| `ONNX WASM files not bundled. The onnx/ directory is missing.` | `ruvector-onnx-embeddings-wasm` |+| `Brain commands require @ruvector/pi-brain` | `@ruvector/pi-brain` |+| `SONA not available. Native error: Cannot find module '/.../@ruvector/sona/index.js'` | `@ruvector/ruvllm` (JS fallback) |+| `LLM commands require @ruvector/ruvllm` | `@ruvector/ruvllm` |++This skill installs them in one pass.++## Steps++1. **Pin ruvector**:+ ```bash+ npm install [email protected]+ ```+2. **Install the add-ons** (idempotent β only what's missing):+ ```bash+ npm install ruvector-onnx-embeddings-wasm \+ @ruvector/pi-brain \+ @ruvector/ruvllm+ ```+ For a leaner install, pass `--full` to also pull `@ruvector/graph-node` and `@ruvector/router`:+ ```bash+ npm install ruvector-onnx-embeddings-wasm \+ @ruvector/pi-brain \+ @ruvector/ruvllm \+ @ruvector/graph-node \+ @ruvector/router+ ```+3. **Verify the binary**:+ ```bash+ npx -y [email protected] doctor+ npx -y [email protected] info+ ```+4. **Register the MCP server**:+ ```bash+ claude mcp add ruvector -- npx -y [email protected] mcp start+ claude mcp list | grep ruvector+ ```+5. **Sanity check** the most common subcommands:+ ```bash+ npx -y [email protected] hooks route "test"+ npx -y [email protected] attention list+ npx -y [email protected] rvf examples+ ```+6. **(Optional) Generate a pi identity** for brain + edge:+ ```bash+ npx -y [email protected] identity generate+ npx -y [email protected] identity show+ ```++## Smoke test++For a deterministic verification of the install, run the plugin's bundled smoke script:+```bash+bash plugins/ruflo-ruvector/scripts/smoke.sh+```++It checks: version pin, top-level subcommand visibility, `hooks ast-analyze`, `hooks route`, `attention list`, `rvf examples`, and `info`. Exits non-zero if any drift from the contracted surface is detected.++## What this does not install++- Native Rust toolchain (optional; only needed for source builds)+- Platform-specific native bindings (auto-detected by `@ruvector/core`)+- `@ruvector/sona` native binding (the JS fallback via `@ruvector/ruvllm` is sufficient on macOS arm64; Linux x64 has its own native binding)++If `doctor` still reports a problem after this skill runs, paste its output verbatim and ask.