π 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(ruflo-ruvector): pin ruvector 0.3.3, which bundles the ONNX wasm (#4158)
r839d00731e17
diff --git a/plugins/ruflo-ruvector/.claude-plugin/plugin.json b/plugins/ruflo-ruvector/.claude-plugin/plugin.jsonindex 41bacdb960..ff16552ca5 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 [email protected] β HNSW, adaptive LoRA embeddings, code-graph clustering, hooks routing, brain/SONA, 103 MCP tools. As a mod (ADR-445): a write guard that keeps secrets out of the vector store and shared brain, /ruvector-mod, and a status file the console shows",- "version": "0.3.5",+ "description": "Self-learning vector database via npx [email protected] β HNSW, adaptive LoRA embeddings, code-graph clustering, hooks routing, brain/SONA, 103 MCP tools. As a mod (ADR-445): a write guard that keeps secrets out of the vector store and shared brain, /ruvector-mod, and a status file the console shows",+ "version": "0.3.6","author": {"name": "ruvnet","url": "https://github.com/ruvnet"diff --git a/plugins/ruflo-ruvector/CHANGELOG.md b/plugins/ruflo-ruvector/CHANGELOG.mdindex 9c1ac241cd..7e8b42c51d 100644--- a/plugins/ruflo-ruvector/CHANGELOG.md+++ b/plugins/ruflo-ruvector/CHANGELOG.md@@ -2,6 +2,9 @@Newest first. One `## <version> β <date>` heading per version, then `feat:`, `fix:`, `breaking:` and `chore:` bullets (ADR-478). Built from git history; older versions: `git log -- plugins/ruflo-ruvector`.+## 0.3.6 β 2026-10-14+- fix: pin [email protected], which bundles the ONNX wasm that 0.2.25 lacks, so `embed text` works with no add-on; drop the `ruvector-onnx-embeddings-wasm` remedy that never fixed it, and refresh the limitation tables against 0.3.3 (`optimize`, `force-learn`, `midstream` now run; 97 MCP tools) (#4158)+## 0.3.5 β 2026-10-12- fix: the shared text screen now catches `.env` and e-mailed credentials, no longer flags a model's token talk (`--max-tokens`, `/oauth/token`, "token usage"), and no longer flags values that only name where a secret lives (`./service-account.json`, `--set-secrets=NAME=NAME:latest`); every rule stays linear (#4094, thanks @proffesor-for-testing)diff --git a/plugins/ruflo-ruvector/README.md b/plugins/ruflo-ruvector/README.mdindex 94fa3ecdea..fc32c4535e 100644--- a/plugins/ruflo-ruvector/README.md+++ b/plugins/ruflo-ruvector/README.md@@ -1,8 +1,8 @@# ruflo-ruvector-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 91 MCP tools (verified via `ruvector mcp tools`).+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 97 MCP tools (verified via `ruvector 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.+> **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@@ -12,17 +12,16 @@ Wraps the `ruvector` npm package as a Ruflo plugin, providing vector embedding,```bash# Required-npm install [email protected]+npm install [email protected]# Optional add-ons (install as needed)-npm install ruvector-onnx-embeddings-wasm # required for `embed text` to worknpm install @ruvector/pi-brain # required for `brain` subcommandsnpm install @ruvector/ruvllm # required for `sona` subcommands (JS fallback)```Run a health check:```bash-npx -y [email protected] doctor+npx -y [email protected] doctor```## Installation@@ -35,7 +34,7 @@ claude --plugin-dir plugins/ruflo-ruvectorRegister with the pinned version:```bash-claude mcp add ruvector -- npx -y [email protected] 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, SONA learning.@@ -50,7 +49,7 @@ Key tool categories: hooks routing, AST analysis, diff classification, coverage| 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-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 |@@ -121,34 +120,34 @@ The full surface is documented in `commands/vector.md` (80+ subcommands). Quick/vector-setup# 1. Create a database-npx -y [email protected] create project.db -d 384 -m cosine+npx -y [email protected] create project.db -d 384 -m cosine# 2. Embed every TypeScript source file (loop β no built-in --batch)mkdir -p .vecfor f in $(find src -name '*.ts'); do- npx -y [email protected] embed text "$(cat "$f")" -o ".vec/${f//\//_}.json"+ 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+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+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+npx -y [email protected] stats project.db```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+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```-## Capabilities ([email protected], verified)+## Capabilities ([email protected], verified)| Feature | CLI | Notes ||---------|-----|-------|@@ -172,34 +171,32 @@ npx -y [email protected] rvf query project.rvf| 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+### Known limitations / bugs in 0.3.3| 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 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`, `midstream`, `embed --file/--batch/--glob/--model poincare` | Don't exist | see `commands/vector.md` for replacements |+| `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 |## Self-Learning Hooks```bash# Full pretrain pipeline + agent generation-npx -y [email protected] hooks init --pretrain --build-agents quality+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"+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/+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/```## Brain (Collective Knowledge)@@ -207,18 +204,18 @@ npx -y [email protected] hooks security-scan src/```bashnpm 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] 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```## SONA (Self-Optimizing Neural Architecture)```bash-npx -y [email protected] sona status-npx -y [email protected] sona patterns "auth refactor"-npx -y [email protected] sona stats+npx -y [email protected] sona status+npx -y [email protected] sona patterns "auth refactor"+npx -y [email protected] sona stats```## Performance@@ -232,16 +229,16 @@ npx -y [email protected] sona stats## 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.+- **ONNX runtime is bundled from 0.3.3** β `embed text` works with no add-on. Older ruvector (0.2.x) reports `ONNX WASM files not bundled`; this plugin pins 0.3.3 for that reason.+- **No `--batch`, `--glob`, `--namespace`, `--k`, `--task`, `--model poincare` flags** (`embed text` does take `--input-file` and `--stdin`) β these were in older docs but are not in 0.3.3. 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.**+- **`compare` and 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)+- [`ADR-0001` β Pin ruflo-ruvector to [email protected] with optional add-ons](./docs/adrs/0001-pin-ruvector-0.3.3.md)## Smoke testdiff --git a/plugins/ruflo-ruvector/agents/vector-engineer.md b/plugins/ruflo-ruvector/agents/vector-engineer.mdindex e910ef20bd..f3f75e581b 100644--- a/plugins/ruflo-ruvector/agents/vector-engineer.md+++ b/plugins/ruflo-ruvector/agents/vector-engineer.md@@ -1,53 +1,53 @@---name: vector-engineer-description: Vector operations specialist using npx [email protected] β HNSW indexing, adaptive LoRA embeddings, code-graph clustering, hooks routing, brain/SONA, 91 MCP tools. Use when the task involves generating/storing embeddings, semantic vector search, RVF cognitive containers, GNN clustering, or hyperbolic (Poincare) hierarchical embeddings.+description: Vector operations specialist using npx [email protected] β HNSW indexing, adaptive LoRA embeddings, code-graph clustering, hooks routing, brain/SONA, 91 MCP tools. Use when the task involves generating/storing embeddings, semantic vector search, RVF cognitive containers, GNN clustering, or hyperbolic (Poincare) hierarchical embeddings.model: sonnet---You are a vector engineer that orchestrates the `ruvector` npm package for embedding, indexing, search, clustering, and self-learning intelligence.-### Core Tool: npx [email protected] (PINNED)+### Core Tool: npx [email protected] (PINNED)-All vector operations go through the `ruvector` CLI, pinned to **0.2.25**. Install once, then always invoke with the version pin:+All vector operations go through the `ruvector` CLI, pinned to **0.3.3**. Install once, then always invoke with the version pin:```bash# Ensure pinned version installed-npm ls ruvector 2>/dev/null | grep '0.2.25' || npm install [email protected]+npm ls ruvector 2>/dev/null | grep '0.3.3' || npm install [email protected]# MCP server (register once with pinned version)-claude mcp add ruvector -- npx -y [email protected] mcp start+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/+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+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+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+npx -y [email protected] doctor+npx -y [email protected] info```### MCP Integration[email protected] exposes 91 MCP tools (verified via `ruvector mcp tools`). Register the MCP server with the pinned version:[email protected] exposes 91 MCP tools (verified via `ruvector mcp tools`). Register the MCP server with the pinned version:```bash-claude mcp add ruvector -- npx -y [email protected] mcp start+claude mcp add ruvector -- npx -y [email protected] mcp start```Verify after registration: `claude mcp list | grep ruvector`.@@ -66,10 +66,10 @@ Key tool categories:- `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)+### Attention Mechanisms (verified via `attention list` on 0.3.3)```bash-npx -y [email protected] attention list+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.@@ -86,7 +86,7 @@ Reports the available mechanisms. Each is a real Rust binding; the CLI exposes `| `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.+> Earlier docs claimed ruvector exposed `Graph RAG`, `Hybrid Search`, `DiskANN`, `ColBERT`, `Matryoshka`, `MLA`, `TurboQuant` as standalone search modes. As of 0.3.3 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@@ -100,33 +100,33 @@ Reports the available mechanisms. Each is a real Rust binding; the CLI exposes `ruvector's 9-phase pretrain pipeline:```bash-npx -y [email protected] 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 ([email protected])+### Embedding Operations ([email protected])```bash# Single text embedding (ONNX all-MiniLM-L6-v2, 384-dim)# 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+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"+ 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+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.+# Compare two texts β no top-level `compare` subcommand exists in 0.3.3.# 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)+### Removed / Renamed CLI Surface (was in older docs, NOT in 0.3.3)| Old form (broken) | Replacement ||-------------------|-------------|@@ -153,20 +153,20 @@ npx -y [email protected] search my.db -v '[0.1,0.2,...]' -k 10| Insert | - | 52,000+ vectors/sec || Memory per vector | ~50 bytes | - |-### Clustering (code graph only in 0.2.25)+### Clustering (code graph only in 0.3.3)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+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)[email protected] has no `--model poincare` flag. For hierarchical data, embed normally and project to the Poincare ball in your own code:[email protected] has no `--model poincare` flag. For hierarchical data, embed normally and project to the Poincare ball in your own code:```bash-npx -y [email protected] embed text "hierarchical concept" -o concept.vec.json+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.diff --git a/plugins/ruflo-ruvector/commands/vector.md b/plugins/ruflo-ruvector/commands/vector.mdindex 9a33e95a78..8557aaafde 100644--- a/plugins/ruflo-ruvector/commands/vector.md+++ b/plugins/ruflo-ruvector/commands/vector.md@@ -1,144 +1,144 @@---name: vector-description: RuVector operations via npx [email protected] β embedding, search, RVF cognitive containers, GNN, attention, hooks, brain, sona, edge, identity+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 (pinned to 0.2.25). Parse subcommand from $ARGUMENTS.+Vector operations via the `ruvector` npm package (pinned to 0.3.3). Parse subcommand from $ARGUMENTS.-Pinned version: `[email protected]` β every command below uses `npx -y [email protected] ...`.+Pinned version: `[email protected]` β every command below uses `npx -y [email protected] ...`.Usage: /vector <subcommand> [options]## Embedding-1. **embed `<text>`** β `npx -y [email protected] embed text "TEXT"`+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`+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).+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]`+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`)+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)+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`+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`+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.3.3)+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"`+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.+> **Known bugs in 0.3.3 hooks:** `force-learn` reports `skipped: no trajectories to process` until one is recorded; `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).+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"`+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)+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`+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>`+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)+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-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)+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)+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)## Setup helper@@ -146,10 +146,10 @@ For first-run users hitting `ONNX WASM files not bundled`, `Brain commands requi## MCP server (91 tools)-- Register once: `claude mcp add ruvector -- npx -y [email protected] mcp start`+- 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)+## Not in 0.3.3 (do not invoke)-`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).+`compare`, top-level `index`, `embed --file`, `embed --batch --glob`, `cluster --namespace --k` (top-level `cluster` is "Coming Soon"), `embed --model poincare`, `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.mdindex f1d2e9ff02..ad6f4e34db 100644--- 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.md@@ -1,6 +1,6 @@---id: ADR-0001-title: Pin ruflo-ruvector plugin to [email protected] with optional add-on packages+title: Pin ruflo-ruvector plugin to [email protected] with optional add-on packagesstatus: Accepteddate: 2026-05-04authors:@@ -25,18 +25,18 @@ Concretely, this caused:- `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.+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.+The plugin pins to `[email protected]` and documents the optional add-on packages required for full functionality.### 1. Pin every CLI invocationAll `npx` calls in the plugin (README, agent, skills, commands, scripts) MUST be of the form:```bash-npx -y [email protected] <subcommand> [args]+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.@@ -56,7 +56,7 @@ Rationale: these are heavy dependencies (ONNX runtime alone is large). Forcing t### 3. Register MCP server with the same pin```bash-claude mcp add ruvector -- npx -y [email protected] mcp start+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.@@ -75,9 +75,9 @@ A future ADR may relax this if upstream introduces a stable equivalent and we up### 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:+`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`)+- Version pin (`--version` returns `0.3.3`)- 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@@ -120,3 +120,16 @@ bash plugins/ruflo-ruvector/scripts/smoke.sh- `skills/vector-setup/SKILL.md` β first-run installer- `agents/vector-engineer.md` β agent contract with replacement table- Upstream issue 401 (`optimize` not yet shipped)++## Addendum (2026-10-14) β pin moved to ruvector 0.3.3 (#4158)++The 0.2.25 pin shipped without `dist/core/onnx/pkg`, so `embed text` failed+with `ONNX WASM files not bundled` and the documented remedy+(`ruvector-onnx-embeddings-wasm`) did not fix it. 0.3.3 bundles the wasm; in a+throwaway prefix `embed text` returned a 384-dim vector with no add-on. The pin+is now `[email protected]` and the ONNX add-on is no longer installed or+documented. Also re-verified on 0.3.3: `optimize` and `hooks force-learn` run,+`midstream` exists, `embed text` takes `--stdin`/`--input-file`, `hooks+graph-mincut` still fails, `compare` still does not exist, `mcp tools` lists 97.+`@ruvector/pi-brain` is still needed for `brain`; `sona` falls back to JS. The+filename keeps the original number so links stay valid.diff --git a/plugins/ruflo-ruvector/scripts/smoke.sh b/plugins/ruflo-ruvector/scripts/smoke.shindex 8a04721aec..634b1df4b0 100755--- a/plugins/ruflo-ruvector/scripts/smoke.sh+++ b/plugins/ruflo-ruvector/scripts/smoke.sh@@ -1,11 +1,11 @@#!/usr/bin/env bash-# Smoke test for ruflo-ruvector plugin against [email protected].+# 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]`+# differently from documented. Run after `npm install [email protected]`# (or rely on the npx fetch).set -uROOT="$(cd "$(dirname "$0")/.." && pwd)"-PIN="[email protected]"+PIN="[email protected]"PASS=0FAIL=0WORKDIR="$(mktemp -d -t ruvector-smoke.XXXXXX)"@@ -21,7 +21,7 @@ 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'"+[[ "$ver" == "0.3.3" ]] && ok || bad "expected 0.3.3, got '$ver'"step "top-level help mentions hooks/embed/rvf/attention/gnn/brain/sona"help=$(run --help)@@ -57,16 +57,16 @@ 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"+step "info reports CLI Version 0.3.3"out=$(run info)-grep -q "CLI Version: 0.2.25" <<<"$out" && ok || bad "info did not report 0.2.25"+grep -q "CLI Version: 0.3.3" <<<"$out" && ok || bad "info did not report 0.3.3"step "doctor exits 0"run doctor >/dev/null && ok || bad "doctor returned non-zero"-step "removed surface stays removed (compare/midstream/index)"+step "removed surface stays removed (compare/index)"fail_removed=""-for c in compare midstream index; do+for c in compare 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"diff --git a/plugins/ruflo-ruvector/skills/vector-cluster/SKILL.md b/plugins/ruflo-ruvector/skills/vector-cluster/SKILL.mdindex 40e3e3dfa1..9b2dcfb49e 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 code by graph community detection via npx [email protected] hooks graph-cluster (spectral / Louvain)+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__plugin_ruflo-core_ruflo__memory_search mcp__plugin_ruflo-core_ruflo__memory_store mcp__plugin_ruflo-core_ruflo__memory_list---@@ -15,14 +15,14 @@ Use this skill when you have a collection of embeddings and want to discover nat## Steps-1. **Ensure [email protected] is available**:+1. **Ensure [email protected] is available**:```bash- npm ls ruvector 2>/dev/null | grep '0.2.25' || npm install [email protected]+ npm ls ruvector 2>/dev/null | grep '0.3.3' || npm install [email protected]```-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.+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...>+ 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**:@@ -37,5 +37,5 @@ Use this skill when you have a collection of embeddings and want to discover nat## Caveats-- `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`.+- `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 af09e26a63..4a2bc53c63 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 [email protected] embed text (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__plugin_ruflo-core_ruflo__memory_store mcp__plugin_ruflo-core_ruflo__memory_search---@@ -15,20 +15,17 @@ Use this skill to embed text, code, or documents into 384-dimensional vectors fo## Steps-1. **Ensure [email protected] is available**:+1. **Ensure [email protected] is available**:```bash- npm ls ruvector 2>/dev/null | grep '0.2.25' || npm install [email protected]- ```- If `embed text` later reports `ONNX WASM files not bundled`, also run:- ```bash- npm install ruvector-onnx-embeddings-wasm+ npm ls ruvector 2>/dev/null | grep '0.3.3' || npm install [email protected]```+ ruvector 0.3.3 bundles the ONNX runtime; no add-on is needed. If `embed text` reports `ONNX WASM files not bundled`, an older ruvector (0.2.x) is being resolved β rerun with the pinned `npx -y [email protected]`.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`+ - 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`+ - 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__plugin_ruflo-core_ruflo__memory_store({ key: "embed-SOURCE", value: "VECTOR_METADATA", namespace: "vector-patterns" })`@@ -37,11 +34,11 @@ Use this skill to embed text, code, or documents into 384-dimensional vectors foRegister the MCP server once with the pinned version:```bash-claude mcp add ruvector -- npx -y [email protected] mcp start+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-- 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.+- The `embed --batch --glob` flags do **not** exist in [email protected]. `embed text` accepts one text, `--stdin`, or `--input-file <path>` (keeps sensitive text off argv); call it per file.+- If embedding fails, 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 bc420c4982..493ff6f097 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 via npx [email protected] embed text and project into the Poincare ball in user code (no --model poincare flag in 0.2.25)+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.3.3)argument-hint: "<text> [--model poincare]"allowed-tools: Bash Read mcp__plugin_ruflo-core_ruflo__memory_store mcp__plugin_ruflo-core_ruflo__memory_search---@@ -15,17 +15,17 @@ Use this skill when your data has inherent hierarchy β dependency trees, modul## Steps-1. **Ensure [email protected] is available**:+1. **Ensure [email protected] is available**:```bash- npm ls ruvector 2>/dev/null | grep '0.2.25' || npm install [email protected]+ npm ls ruvector 2>/dev/null | grep '0.3.3' || npm install [email protected]```-2. **Generate a base ONNX embedding** ([email protected] does not expose a `--model poincare` flag on `embed text`):+2. **Generate a base ONNX embedding** ([email protected] does not expose a `--model poincare` flag on `embed text`):```bash- npx -y [email protected] embed text "hierarchical concept" -o concept.vec.json+ npx -y [email protected] embed text "hierarchical concept" -o concept.vec.json```3. **Project into the Poincare ball** in your own code (or via the experimental neural substrate):```bash- npx -y [email protected] embed neural --help+ 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)))`@@ -35,7 +35,7 @@ Use this skill when your data has inherent hierarchy β dependency trees, modul## Caveats-- [email protected] has no first-class Poincare ball CLI flag. Treat hyperbolic projection as a post-processing step over a standard ONNX embedding.+- [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 propertiesdiff --git a/plugins/ruflo-ruvector/skills/vector-setup/SKILL.md b/plugins/ruflo-ruvector/skills/vector-setup/SKILL.mdindex 2758c79e27..3183ab5819 100644--- a/plugins/ruflo-ruvector/skills/vector-setup/SKILL.md+++ b/plugins/ruflo-ruvector/skills/vector-setup/SKILL.md@@ -1,13 +1,13 @@---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`+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.+Bootstraps `[email protected]` and its optional add-ons so every `/vector` subcommand actually works on first run.## Why this exists@@ -15,7 +15,7 @@ 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` |+| `ONNX WASM files not bundled. The onnx/ directory is missing.` | none β upgrade to ruvector 0.3.3, which bundles it (0.2.x lacks it) || `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` |@@ -26,42 +26,40 @@ This skill installs them in one pass.1. **Pin ruvector**:```bash- npm install [email protected]+ npm install [email protected]```2. **Install the add-ons** (idempotent β only what's missing):```bash- npm install ruvector-onnx-embeddings-wasm \- @ruvector/pi-brain \+ npm install @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 \+ npm install @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+ 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 add ruvector -- npx -y [email protected] mcp startclaude 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+ 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+ npx -y [email protected] identity generate+ npx -y [email protected] identity show```## Smoke test