admin/ruflo
1
0 Fork 0
mirror of https://github.com/ruvnet/ruflo.git synced 2026-10-23 03:47:00 +09:00
Code Issues Packages Projects Releases Wiki Activity

fix(ruflo-ruvector): pin ruvector 0.3.3, which bundles the ONNX wasm (#4158)

Browse Source 
0.2.25 ships without dist/core/onnx/pkg, so embed text failed and the
ruvector-onnx-embeddings-wasm remedy never fixed it. Verified in a throwaway
prefix that 0.3.3 embeds 384 dims with no add-on; refreshed the limitation
tables against 0.3.3 and bumped the plugin to 0.3.6.

Co-Authored-By: RuFlo <ruv@ruv.net>
This commit is contained in:
randRuFlo committed 2026-10-14 05:37:35 -04:00
1 parent ae13e393d2
commit 839d00731e
11 files changed
+235 -227
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

plugins/ruflo-ruvector/.claude-plugin/plugin.json
+2 -2
View File
@@ -1,7 +1,7 @@
{
"name": "ruflo-ruvector",
"description": "Self-learning vector database via npx ruvector@0.2.25 — 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 ruvector@0.3.3 — 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"
plugins/ruflo-ruvector/CHANGELOG.md
+3
View File
@@ -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 ruvector@0.3.3, 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)
plugins/ruflo-ruvector/README.md
+37 -40
View File
@@ -1,8 +1,8 @@
# ruflo-ruvector
Self-learning vector database powered by [`ruvector@0.2.25`](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 [`ruvector@0.3.3`](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 `ruvector@0.2.25`. 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 `ruvector@0.3.3`. Earlier 0.1.x versions are missing several commands (`brain`, `route`, `sona`); some legacy docs referenced 2.x features that do not exist on npm. Always invoke with the pin.
## Overview
@@ -12,17 +12,16 @@ Wraps the `ruvector` npm package as a Ruflo plugin, providing vector embedding,
```bash
# Required
npm install ruvector@0.2.25
npm install ruvector@0.3.3
# 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 ruvector@0.2.25 doctor
npx -y ruvector@0.3.3 doctor
```
## Installation
@@ -35,7 +34,7 @@ claude --plugin-dir plugins/ruflo-ruvector
Register with the pinned version:
```bash
claude mcp add ruvector -- npx -y ruvector@0.2.25 mcp start
claude mcp add ruvector -- npx -y ruvector@0.3.3 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 `ruvector@0.2.25`, adds ONNX/Brain/SONA/router add-ons, registers MCP, runs `doctor` |
| `vector-setup` | `/vector-setup [--full]` | First-run installer: pins `ruvector@0.3.3`, adds ONNX/Brain/SONA/router add-ons, registers MCP, runs `doctor` |
| `vector-embed` | `/vector-embed <text>` | ONNX embeddings (384-dim) via `embed text` |
| `vector-cluster` | `/vector-cluster <files...>` | Spectral/Louvain code-graph clustering via `hooks graph-cluster` |
| `vector-hyperbolic` | `/vector-hyperbolic <text>` | Standard ONNX embed + Poincare projection in user code |
@@ -121,34 +120,34 @@ The full surface is documented in `commands/vector.md` (80+ subcommands). Quick
/vector-setup
# 1. Create a database
npx -y ruvector@0.2.25 create project.db -d 384 -m cosine
npx -y ruvector@0.3.3 create project.db -d 384 -m cosine
# 2. Embed every TypeScript source file (loop — no built-in --batch)
mkdir -p .vec
for f in $(find src -name '*.ts'); do
npx -y ruvector@0.2.25 embed text "$(cat "$f")" -o ".vec/${f//\//_}.json"
npx -y ruvector@0.3.3 embed text "$(cat "$f")" -o ".vec/${f//\//_}.json"
done
# 3. Insert all embeddings (assumes a JSON array of {id, vector, metadata})
jq -s '[.[] | {id: input_filename, vector: .vector}]' .vec/*.json > corpus.json
npx -y ruvector@0.2.25 insert project.db corpus.json
npx -y ruvector@0.3.3 insert project.db corpus.json
# 4. Search by query embedding
QV=$(npx -y ruvector@0.2.25 embed text "JWT refresh-token rotation" --output -)
npx -y ruvector@0.2.25 search project.db -v "$QV" -k 5
QV=$(npx -y ruvector@0.3.3 embed text "JWT refresh-token rotation" --output -)
npx -y ruvector@0.3.3 search project.db -v "$QV" -k 5
# 5. Inspect index health
npx -y ruvector@0.2.25 stats project.db
npx -y ruvector@0.3.3 stats project.db
```
For an alternative store format with lineage tracking, replace steps 1–3 with:
```bash
npx -y ruvector@0.2.25 rvf create project.rvf
npx -y ruvector@0.2.25 rvf ingest project.rvf < corpus.json
npx -y ruvector@0.2.25 rvf query project.rvf
npx -y ruvector@0.3.3 rvf create project.rvf
npx -y ruvector@0.3.3 rvf ingest project.rvf < corpus.json
npx -y ruvector@0.3.3 rvf query project.rvf
```
## Capabilities (ruvector@0.2.25, verified)
## Capabilities (ruvector@0.3.3, verified)
| Feature | CLI | Notes |
|---------|-----|-------|
@@ -172,34 +171,32 @@ npx -y ruvector@0.2.25 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 ruvector@0.2.25 hooks init --pretrain --build-agents quality
npx -y ruvector@0.3.3 hooks init --pretrain --build-agents quality
# Smart agent routing (positional task!)
npx -y ruvector@0.2.25 hooks route "implement OAuth flow"
npx -y ruvector@0.2.25 hooks route-enhanced "fix CVE-2025-1234"
npx -y ruvector@0.3.3 hooks route "implement OAuth flow"
npx -y ruvector@0.3.3 hooks route-enhanced "fix CVE-2025-1234"
# Code analysis (positional file!)
npx -y ruvector@0.2.25 hooks ast-analyze src/module.ts
npx -y ruvector@0.2.25 hooks diff-analyze HEAD
npx -y ruvector@0.2.25 hooks coverage-route src/module.ts
npx -y ruvector@0.2.25 hooks security-scan src/
npx -y ruvector@0.3.3 hooks ast-analyze src/module.ts
npx -y ruvector@0.3.3 hooks diff-analyze HEAD
npx -y ruvector@0.3.3 hooks coverage-route src/module.ts
npx -y ruvector@0.3.3 hooks security-scan src/
```
## Brain (Collective Knowledge)
@@ -207,18 +204,18 @@ npx -y ruvector@0.2.25 hooks security-scan src/
```bash
npm install @ruvector/pi-brain # required dependency
npx -y ruvector@0.2.25 brain status
npx -y ruvector@0.2.25 brain search "authentication patterns"
npx -y ruvector@0.2.25 brain list
npx -y ruvector@0.2.25 brain drift code # knowledge drift for a domain
npx -y ruvector@0.3.3 brain status
npx -y ruvector@0.3.3 brain search "authentication patterns"
npx -y ruvector@0.3.3 brain list
npx -y ruvector@0.3.3 brain drift code # knowledge drift for a domain
```
## SONA (Self-Optimizing Neural Architecture)
```bash
npx -y ruvector@0.2.25 sona status
npx -y ruvector@0.2.25 sona patterns "auth refactor"
npx -y ruvector@0.2.25 sona stats
npx -y ruvector@0.3.3 sona status
npx -y ruvector@0.3.3 sona patterns "auth refactor"
npx -y ruvector@0.3.3 sona stats
```
## Performance
@@ -232,16 +229,16 @@ npx -y ruvector@0.2.25 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 ruvector@0.2.25 with optional add-ons](./docs/adrs/0001-pin-ruvector-0.2.25.md)
- [`ADR-0001` — Pin ruflo-ruvector to ruvector@0.3.3 with optional add-ons](./docs/adrs/0001-pin-ruvector-0.3.3.md)
## Smoke test
plugins/ruflo-ruvector/agents/vector-engineer.md
+41 -41
View File
@@ -1,53 +1,53 @@
---
name: vector-engineer
description: Vector operations specialist using npx ruvector@0.2.25 — 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 ruvector@0.3.3 — 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 ruvector@0.2.25 (PINNED)
### Core Tool: npx ruvector@0.3.3 (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 ruvector@0.2.25
npm ls ruvector 2>/dev/null | grep '0.3.3' || npm install ruvector@0.3.3
# MCP server (register once with pinned version)
claude mcp add ruvector -- npx -y ruvector@0.2.25 mcp start
claude mcp add ruvector -- npx -y ruvector@0.3.3 mcp start
# Hooks system (self-learning) — note: positional args, NOT --task / --file
npx -y ruvector@0.2.25 hooks init --pretrain --build-agents quality
npx -y ruvector@0.2.25 hooks route "description"
npx -y ruvector@0.2.25 hooks route-enhanced "description"
npx -y ruvector@0.2.25 hooks ast-analyze src/module.ts
npx -y ruvector@0.2.25 hooks diff-analyze HEAD
npx -y ruvector@0.2.25 hooks diff-classify HEAD
npx -y ruvector@0.2.25 hooks coverage-route src/module.ts
npx -y ruvector@0.2.25 hooks security-scan src/
npx -y ruvector@0.3.3 hooks init --pretrain --build-agents quality
npx -y ruvector@0.3.3 hooks route "description"
npx -y ruvector@0.3.3 hooks route-enhanced "description"
npx -y ruvector@0.3.3 hooks ast-analyze src/module.ts
npx -y ruvector@0.3.3 hooks diff-analyze HEAD
npx -y ruvector@0.3.3 hooks diff-classify HEAD
npx -y ruvector@0.3.3 hooks coverage-route src/module.ts
npx -y ruvector@0.3.3 hooks security-scan src/
# Brain (collective knowledge — requires @ruvector/pi-brain)
npm install @ruvector/pi-brain
npx -y ruvector@0.2.25 brain status
npx -y ruvector@0.2.25 brain search "query"
npx -y ruvector@0.2.25 brain list
npx -y ruvector@0.3.3 brain status
npx -y ruvector@0.3.3 brain search "query"
npx -y ruvector@0.3.3 brain list
# SONA (Self-Optimizing Neural Architecture)
npx -y ruvector@0.2.25 sona status
npx -y ruvector@0.2.25 sona patterns "query"
npx -y ruvector@0.2.25 sona stats
npx -y ruvector@0.3.3 sona status
npx -y ruvector@0.3.3 sona patterns "query"
npx -y ruvector@0.3.3 sona stats
# System diagnostics
npx -y ruvector@0.2.25 doctor
npx -y ruvector@0.2.25 info
npx -y ruvector@0.3.3 doctor
npx -y ruvector@0.3.3 info
```
### MCP Integration
ruvector@0.2.25 exposes 91 MCP tools (verified via `ruvector mcp tools`). Register the MCP server with the pinned version:
ruvector@0.3.3 exposes 91 MCP tools (verified via `ruvector mcp tools`). Register the MCP server with the pinned version:
```bash
claude mcp add ruvector -- npx -y ruvector@0.2.25 mcp start
claude mcp add ruvector -- npx -y ruvector@0.3.3 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 ruvector@0.2.25 attention list
npx -y ruvector@0.3.3 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 ruvector@0.2.25 hooks init --pretrain --build-agents quality
npx -y ruvector@0.3.3 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 (ruvector@0.2.25)
### Embedding Operations (ruvector@0.3.3)
```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 ruvector@0.2.25 embed text "your text here"
npx -y ruvector@0.2.25 embed text "your text" --adaptive --domain code -o vec.json
npx -y ruvector@0.3.3 embed text "your text here"
npx -y ruvector@0.3.3 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 ruvector@0.2.25 embed text "$(cat "$f")" -o "${f}.vec.json"
npx -y ruvector@0.3.3 embed text "$(cat "$f")" -o "${f}.vec.json"
done
# Similarity search — requires an existing database and a JSON-encoded query vector
npx -y ruvector@0.2.25 create my.db -d 384 -m cosine
npx -y ruvector@0.2.25 insert my.db vectors.json
npx -y ruvector@0.2.25 search my.db -v '[0.1,0.2,...]' -k 10
npx -y ruvector@0.3.3 create my.db -d 384 -m cosine
npx -y ruvector@0.3.3 insert my.db vectors.json
npx -y ruvector@0.3.3 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 ruvector@0.2.25 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 ruvector@0.2.25 hooks graph-cluster <files...> # spectral / Louvain
npx -y ruvector@0.2.25 hooks graph-mincut <files...> # min-cut boundaries
npx -y ruvector@0.3.3 hooks graph-cluster <files...> # spectral / Louvain
npx -y ruvector@0.3.3 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)
ruvector@0.2.25 has no `--model poincare` flag. For hierarchical data, embed normally and project to the Poincare ball in your own code:
ruvector@0.3.3 has no `--model poincare` flag. For hierarchical data, embed normally and project to the Poincare ball in your own code:
```bash
npx -y ruvector@0.2.25 embed text "hierarchical concept" -o concept.vec.json
npx -y ruvector@0.3.3 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.
plugins/ruflo-ruvector/commands/vector.md
+85 -85
View File
@@ -1,144 +1,144 @@
---
name: vector
description: RuVector operations via npx ruvector@0.2.25 — embedding, search, RVF cognitive containers, GNN, attention, hooks, brain, sona, edge, identity
description: RuVector operations via npx ruvector@0.3.3 — 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: `ruvector@0.2.25` — every command below uses `npx -y ruvector@0.2.25 ...`.
Pinned version: `ruvector@0.3.3` — every command below uses `npx -y ruvector@0.3.3 ...`.
Usage: /vector <subcommand> [options]
## Embedding
1. **embed `<text>`** — `npx -y ruvector@0.2.25 embed text "TEXT"`
1. **embed `<text>`** — `npx -y ruvector@0.3.3 embed text "TEXT"`
384-dim ONNX vector. If `ONNX WASM files not bundled`, run `/vector setup`.
2. **embed-adaptive `<text>`** — `npx -y ruvector@0.2.25 embed text "TEXT" --adaptive --domain code`
2. **embed-adaptive `<text>`** — `npx -y ruvector@0.3.3 embed text "TEXT" --adaptive --domain code`
LoRA-adapted embedding tuned to a domain.
3. **embed-file `<path>`** — Read file, then `npx -y ruvector@0.2.25 embed text "$(cat <path>)" -o <path>.vec.json`
4. **embed-benchmark** — `npx -y ruvector@0.2.25 embed benchmark` (compares base vs adaptive).
3. **embed-file `<path>`** — Read file, then `npx -y ruvector@0.3.3 embed text "$(cat <path>)" -o <path>.vec.json`
4. **embed-benchmark** — `npx -y ruvector@0.3.3 embed benchmark` (compares base vs adaptive).
## Database lifecycle
5. **db create `<path>`** — `npx -y ruvector@0.2.25 create <path> -d 384 -m cosine`
6. **db stats `<path>`** — `npx -y ruvector@0.2.25 stats <path>`
7. **insert `<database>` `<json-file>`** — `npx -y ruvector@0.2.25 insert <database> <json-file>`
8. **search `<database>` `<vector-json>` [-k N]** — `npx -y ruvector@0.2.25 search <database> -v '[0.1,...]' -k N`
9. **export `<database>` [-o file] [-f json|binary|parquet] [--compress]** — `npx -y ruvector@0.2.25 export <database> -o backup.json`
10. **import `<file>` [-d database]** — `npx -y ruvector@0.2.25 import <file> -d <database> [--merge|--replace]`
5. **db create `<path>`** — `npx -y ruvector@0.3.3 create <path> -d 384 -m cosine`
6. **db stats `<path>`** — `npx -y ruvector@0.3.3 stats <path>`
7. **insert `<database>` `<json-file>`** — `npx -y ruvector@0.3.3 insert <database> <json-file>`
8. **search `<database>` `<vector-json>` [-k N]** — `npx -y ruvector@0.3.3 search <database> -v '[0.1,...]' -k N`
9. **export `<database>` [-o file] [-f json|binary|parquet] [--compress]** — `npx -y ruvector@0.3.3 export <database> -o backup.json`
10. **import `<file>` [-d database]** — `npx -y ruvector@0.3.3 import <file> -d <database> [--merge|--replace]`
## RVF (cognitive containers)
11. **rvf create `<path>`** — `npx -y ruvector@0.2.25 rvf create <path>`
12. **rvf ingest `<path>`** — `npx -y ruvector@0.2.25 rvf ingest <path>`
13. **rvf query `<path>`** — `npx -y ruvector@0.2.25 rvf query <path>` (nearest neighbors)
14. **rvf status `<path>`** — `npx -y ruvector@0.2.25 rvf status <path>`
15. **rvf segments `<path>`** — `npx -y ruvector@0.2.25 rvf segments <path>`
16. **rvf derive `<parent>` `<child>`** — `npx -y ruvector@0.2.25 rvf derive <parent> <child>` (lineage tracking)
17. **rvf compact `<path>`** — `npx -y ruvector@0.2.25 rvf compact <path>` (reclaim deleted space)
18. **rvf examples** — `npx -y ruvector@0.2.25 rvf examples` (45 reference stores)
19. **rvf download `<name>`** — `npx -y ruvector@0.2.25 rvf download <name>` (e.g. `agent_memory`, `swarm_knowledge`)
11. **rvf create `<path>`** — `npx -y ruvector@0.3.3 rvf create <path>`
12. **rvf ingest `<path>`** — `npx -y ruvector@0.3.3 rvf ingest <path>`
13. **rvf query `<path>`** — `npx -y ruvector@0.3.3 rvf query <path>` (nearest neighbors)
14. **rvf status `<path>`** — `npx -y ruvector@0.3.3 rvf status <path>`
15. **rvf segments `<path>`** — `npx -y ruvector@0.3.3 rvf segments <path>`
16. **rvf derive `<parent>` `<child>`** — `npx -y ruvector@0.3.3 rvf derive <parent> <child>` (lineage tracking)
17. **rvf compact `<path>`** — `npx -y ruvector@0.3.3 rvf compact <path>` (reclaim deleted space)
18. **rvf examples** — `npx -y ruvector@0.3.3 rvf examples` (45 reference stores)
19. **rvf download `<name>`** — `npx -y ruvector@0.3.3 rvf download <name>` (e.g. `agent_memory`, `swarm_knowledge`)
## GNN (Graph Neural Networks)
20. **gnn info** — `npx -y ruvector@0.2.25 gnn info`
21. **gnn layer** — `npx -y ruvector@0.2.25 gnn layer` (build/test a multi-head attention GNN layer)
22. **gnn search** — `npx -y ruvector@0.2.25 gnn search` (differentiable soft-attention search)
23. **gnn compress** — `npx -y ruvector@0.2.25 gnn compress` (5-level adaptive tensor compression)
20. **gnn info** — `npx -y ruvector@0.3.3 gnn info`
21. **gnn layer** — `npx -y ruvector@0.3.3 gnn layer` (build/test a multi-head attention GNN layer)
22. **gnn search** — `npx -y ruvector@0.3.3 gnn search` (differentiable soft-attention search)
23. **gnn compress** — `npx -y ruvector@0.3.3 gnn compress` (5-level adaptive tensor compression)
## Attention mechanisms
24. **attention list** — `npx -y ruvector@0.2.25 attention list`
24. **attention list** — `npx -y ruvector@0.3.3 attention list`
Lists ALL available mechanisms: DotProduct, MultiHead, Flash, Hyperbolic, Linear, MoE, GraphRoPe, EdgeFeatured, DualSpace, LocalGlobal.
25. **attention compute** — `npx -y ruvector@0.2.25 attention compute`
26. **attention benchmark** — `npx -y ruvector@0.2.25 attention benchmark`
27. **attention hyperbolic** — `npx -y ruvector@0.2.25 attention hyperbolic` (Poincare-ball geometry ops; the real hyperbolic surface in 0.2.25)
28. **attention info** — `npx -y ruvector@0.2.25 attention info`
25. **attention compute** — `npx -y ruvector@0.3.3 attention compute`
26. **attention benchmark** — `npx -y ruvector@0.3.3 attention benchmark`
27. **attention hyperbolic** — `npx -y ruvector@0.3.3 attention hyperbolic` (Poincare-ball geometry ops; the real hyperbolic surface in 0.3.3)
28. **attention info** — `npx -y ruvector@0.3.3 attention info`
## Code intelligence (hooks)
29. **hooks init** — `npx -y ruvector@0.2.25 hooks init --pretrain --build-agents quality`
30. **hooks stats** — `npx -y ruvector@0.2.25 hooks stats` (Q-learning patterns, vector memories, trajectories)
31. **hooks route `<task>`** — `npx -y ruvector@0.2.25 hooks route "DESCRIPTION"` (positional)
32. **hooks route-enhanced `<task>`** — `npx -y ruvector@0.2.25 hooks route-enhanced "DESCRIPTION"`
33. **hooks suggest-context** — `npx -y ruvector@0.2.25 hooks suggest-context`
34. **hooks ast-analyze `<file>`** — `npx -y ruvector@0.2.25 hooks ast-analyze <file>` (positional)
35. **hooks ast-complexity `<files...>`** — `npx -y ruvector@0.2.25 hooks ast-complexity <files...>`
36. **hooks diff-analyze [commit]** — `npx -y ruvector@0.2.25 hooks diff-analyze HEAD`
37. **hooks diff-classify [commit]** — `npx -y ruvector@0.2.25 hooks diff-classify HEAD`
38. **hooks diff-similar** — `npx -y ruvector@0.2.25 hooks diff-similar`
39. **hooks coverage-route `<file>`** — `npx -y ruvector@0.2.25 hooks coverage-route <file>`
40. **hooks coverage-suggest `<files...>`** — `npx -y ruvector@0.2.25 hooks coverage-suggest <files...>`
41. **hooks graph-cluster `<files...>`** — `npx -y ruvector@0.2.25 hooks graph-cluster <files...>` (spectral/Louvain)
42. **hooks rag-context `<query>`** — `npx -y ruvector@0.2.25 hooks rag-context "QUERY"`
43. **hooks security-scan `<files...>`** — `npx -y ruvector@0.2.25 hooks security-scan <files...>` (run `hooks init` first)
44. **hooks remember `<content>`** — `npx -y ruvector@0.2.25 hooks remember "CONTENT"`
45. **hooks recall `<query>`** — `npx -y ruvector@0.2.25 hooks recall "QUERY"`
29. **hooks init** — `npx -y ruvector@0.3.3 hooks init --pretrain --build-agents quality`
30. **hooks stats** — `npx -y ruvector@0.3.3 hooks stats` (Q-learning patterns, vector memories, trajectories)
31. **hooks route `<task>`** — `npx -y ruvector@0.3.3 hooks route "DESCRIPTION"` (positional)
32. **hooks route-enhanced `<task>`** — `npx -y ruvector@0.3.3 hooks route-enhanced "DESCRIPTION"`
33. **hooks suggest-context** — `npx -y ruvector@0.3.3 hooks suggest-context`
34. **hooks ast-analyze `<file>`** — `npx -y ruvector@0.3.3 hooks ast-analyze <file>` (positional)
35. **hooks ast-complexity `<files...>`** — `npx -y ruvector@0.3.3 hooks ast-complexity <files...>`
36. **hooks diff-analyze [commit]** — `npx -y ruvector@0.3.3 hooks diff-analyze HEAD`
37. **hooks diff-classify [commit]** — `npx -y ruvector@0.3.3 hooks diff-classify HEAD`
38. **hooks diff-similar** — `npx -y ruvector@0.3.3 hooks diff-similar`
39. **hooks coverage-route `<file>`** — `npx -y ruvector@0.3.3 hooks coverage-route <file>`
40. **hooks coverage-suggest `<files...>`** — `npx -y ruvector@0.3.3 hooks coverage-suggest <files...>`
41. **hooks graph-cluster `<files...>`** — `npx -y ruvector@0.3.3 hooks graph-cluster <files...>` (spectral/Louvain)
42. **hooks rag-context `<query>`** — `npx -y ruvector@0.3.3 hooks rag-context "QUERY"`
43. **hooks security-scan `<files...>`** — `npx -y ruvector@0.3.3 hooks security-scan <files...>` (run `hooks init` first)
44. **hooks remember `<content>`** — `npx -y ruvector@0.3.3 hooks remember "CONTENT"`
45. **hooks recall `<query>`** — `npx -y ruvector@0.3.3 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 ruvector@0.2.25 native list` (worker types: security, analysis, learning)
51. **native run `<type>`** — `npx -y ruvector@0.2.25 native run security` (or analysis|learning)
52. **native benchmark** — `npx -y ruvector@0.2.25 native benchmark`
53. **native compare** — `npx -y ruvector@0.2.25 native compare`
54. **workers triggers / presets / phases / dispatch / status / stats / cleanup / cancel / run / create / init-config** — all available via `npx -y ruvector@0.2.25 workers <subcmd>`. First invocation auto-installs `agentic-flow` (slow).
50. **native list** — `npx -y ruvector@0.3.3 native list` (worker types: security, analysis, learning)
51. **native run `<type>`** — `npx -y ruvector@0.3.3 native run security` (or analysis|learning)
52. **native benchmark** — `npx -y ruvector@0.3.3 native benchmark`
53. **native compare** — `npx -y ruvector@0.3.3 native compare`
54. **workers triggers / presets / phases / dispatch / status / stats / cleanup / cancel / run / create / init-config** — all available via `npx -y ruvector@0.3.3 workers <subcmd>`. First invocation auto-installs `agentic-flow` (slow).
## Collective knowledge (brain) — needs `@ruvector/pi-brain`
55. **brain status** — `npx -y ruvector@0.2.25 brain status`
56. **brain search `<query>`** — `npx -y ruvector@0.2.25 brain search "QUERY"`
57. **brain share `<title>`** — `npx -y ruvector@0.2.25 brain share "TITLE"`
55. **brain status** — `npx -y ruvector@0.3.3 brain status`
56. **brain search `<query>`** — `npx -y ruvector@0.3.3 brain search "QUERY"`
57. **brain share `<title>`** — `npx -y ruvector@0.3.3 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 ruvector@0.2.25 sona status`
60. **sona patterns `<query>`** — `npx -y ruvector@0.2.25 sona patterns "QUERY"`
61. **sona train `<data>`** — `npx -y ruvector@0.2.25 sona train <data>` (record a training trajectory)
62. **sona export** — `npx -y ruvector@0.2.25 sona export` (export learned weights)
59. **sona status / info / stats** — `npx -y ruvector@0.3.3 sona status`
60. **sona patterns `<query>`** — `npx -y ruvector@0.3.3 sona patterns "QUERY"`
61. **sona train `<data>`** — `npx -y ruvector@0.3.3 sona train <data>` (record a training trajectory)
62. **sona export** — `npx -y ruvector@0.3.3 sona export` (export learned weights)
## LLM orchestration — needs `@ruvector/ruvllm`
63. **llm models** — `npx -y ruvector@0.2.25 llm models`
64. **llm embed `<text>`** — `npx -y ruvector@0.2.25 llm embed "TEXT"` (RuvLLM-backed embeddings)
65. **llm benchmark** — `npx -y ruvector@0.2.25 llm benchmark`
66. **llm info** — `npx -y ruvector@0.2.25 llm info`
63. **llm models** — `npx -y ruvector@0.3.3 llm models`
64. **llm embed `<text>`** — `npx -y ruvector@0.3.3 llm embed "TEXT"` (RuvLLM-backed embeddings)
65. **llm benchmark** — `npx -y ruvector@0.3.3 llm benchmark`
66. **llm info** — `npx -y ruvector@0.3.3 llm info`
## Identity (pi key for brain/edge/MCP)
67. **identity generate** — `npx -y ruvector@0.2.25 identity generate` (creates a 64-hex-char pi key)
68. **identity show** — `npx -y ruvector@0.2.25 identity show`
69. **identity export `-o file`** — `npx -y ruvector@0.2.25 identity export -o key.enc` (encrypted backup)
70. **identity import `<file>`** — `npx -y ruvector@0.2.25 identity import <file>`
67. **identity generate** — `npx -y ruvector@0.3.3 identity generate` (creates a 64-hex-char pi key)
68. **identity show** — `npx -y ruvector@0.3.3 identity show`
69. **identity export `-o file`** — `npx -y ruvector@0.3.3 identity export -o key.enc` (encrypted backup)
70. **identity import `<file>`** — `npx -y ruvector@0.3.3 identity import <file>`
## Edge compute network
71. **edge status** — `npx -y ruvector@0.2.25 edge status`
72. **edge balance [nodeId]** — `npx -y ruvector@0.2.25 edge balance` (rUv balance)
73. **edge tasks** — `npx -y ruvector@0.2.25 edge tasks`
74. **edge join** — `npx -y ruvector@0.2.25 edge join` (join the network as a node)
75. **edge dashboard** — `npx -y ruvector@0.2.25 edge dashboard` (opens in browser)
71. **edge status** — `npx -y ruvector@0.3.3 edge status`
72. **edge balance [nodeId]** — `npx -y ruvector@0.3.3 edge balance` (rUv balance)
73. **edge tasks** — `npx -y ruvector@0.3.3 edge tasks`
74. **edge join** — `npx -y ruvector@0.3.3 edge join` (join the network as a node)
75. **edge dashboard** — `npx -y ruvector@0.3.3 edge dashboard` (opens in browser)
## Server / Decompile / Demo
76. **server [-p 8080] [-g 50051] [-d data-dir]** — `npx -y ruvector@0.2.25 server -p 8080`
77. **decompile `<target>` [-o dir] [-f modules|single|json]** — `npx -y ruvector@0.2.25 decompile <npm-pkg-or-file-or-url>`
78. **demo --basic | --gnn | --graph** — `npx -y ruvector@0.2.25 demo --basic` (interactive tutorial)
76. **server [-p 8080] [-g 50051] [-d data-dir]** — `npx -y ruvector@0.3.3 server -p 8080`
77. **decompile `<target>` [-o dir] [-f modules|single|json]** — `npx -y ruvector@0.3.3 decompile <npm-pkg-or-file-or-url>`
78. **demo --basic | --gnn | --graph** — `npx -y ruvector@0.3.3 demo --basic` (interactive tutorial)
## System
79. **doctor** — `npx -y ruvector@0.2.25 doctor` (Node, npm, bindings, Rust)
80. **info** — `npx -y ruvector@0.2.25 info`
81. **benchmark** — `npx -y ruvector@0.2.25 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 ruvector@0.2.25 install --all` (lists/installs optional add-ons)
83. **setup** — `npx -y ruvector@0.2.25 setup` (Setup Guide)
79. **doctor** — `npx -y ruvector@0.3.3 doctor` (Node, npm, bindings, Rust)
80. **info** — `npx -y ruvector@0.3.3 info`
81. **benchmark** — `npx -y ruvector@0.3.3 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 ruvector@0.3.3 install --all` (lists/installs optional add-ons)
83. **setup** — `npx -y ruvector@0.3.3 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 ruvector@0.2.25 mcp start`
- Register once: `claude mcp add ruvector -- npx -y ruvector@0.3.3 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).
plugins/ruflo-ruvector/docs/adrs/0001-pin-ruvector-0.2.25.md
+20 -7
View File
@@ -1,6 +1,6 @@
---
id: ADR-0001
title: Pin ruflo-ruvector plugin to ruvector@0.2.25 with optional add-on packages
title: Pin ruflo-ruvector plugin to ruvector@0.3.3 with optional add-on packages
status: Accepted
date: 2026-05-04
authors:
@@ -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 `ruvector@0.2.25` confirmed which subcommands work, which require optional add-on packages, and which are upstream bugs.
A live audit against `ruvector@0.3.3` confirmed which subcommands work, which require optional add-on packages, and which are upstream bugs.
## Decision
The plugin pins to `ruvector@0.2.25` and documents the optional add-on packages required for full functionality.
The plugin pins to `ruvector@0.3.3` 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 ruvector@0.2.25 <subcommand> [args]
npx -y ruvector@0.3.3 <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 ruvector@0.2.25 mcp start
claude mcp add ruvector -- npx -y ruvector@0.3.3 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 `ruvector@0.2.25`. It must remain green on every plugin change. Tests cover:
`scripts/smoke.sh` verifies the contracted surface against any installed `ruvector@0.3.3`. 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 `ruvector@0.3.3` 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.
plugins/ruflo-ruvector/scripts/smoke.sh
+8 -8
View File
@@ -1,11 +1,11 @@
#!/usr/bin/env bash
# Smoke test for ruflo-ruvector plugin against ruvector@0.2.25.
# Smoke test for ruflo-ruvector plugin against ruvector@0.3.3.
# Exits non-zero if any contracted CLI surface is missing or behaves
# differently from documented. Run after `npm install ruvector@0.2.25`
# differently from documented. Run after `npm install ruvector@0.3.3`
# (or rely on the npx fetch).
set -u
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
PIN="ruvector@0.2.25"
PIN="ruvector@0.3.3"
PASS=0
FAIL=0
WORKDIR="$(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"
plugins/ruflo-ruvector/skills/vector-cluster/SKILL.md
+7 -7
View File
@@ -1,6 +1,6 @@
---
name: vector-cluster
description: Cluster code by graph community detection via npx ruvector@0.2.25 hooks graph-cluster (spectral / Louvain)
description: Cluster code by graph community detection via npx ruvector@0.3.3 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 ruvector@0.2.25 is available**:
1. **Ensure ruvector@0.3.3 is available**:
```bash
npm ls ruvector 2>/dev/null | grep '0.2.25' || npm install ruvector@0.2.25
npm ls ruvector 2>/dev/null | grep '0.3.3' || npm install ruvector@0.3.3
```
2. **Run clustering** — in ruvector@0.2.25 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 ruvector@0.3.3 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 ruvector@0.2.25 hooks graph-cluster <files...>
npx -y ruvector@0.2.25 hooks graph-mincut <files...>
npx -y ruvector@0.3.3 hooks graph-cluster <files...>
npx -y ruvector@0.3.3 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 ruvector@0.2.25 — 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 ruvector@0.3.3 — 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.
plugins/ruflo-ruvector/skills/vector-embed/SKILL.md
+11 -14
View File
@@ -1,6 +1,6 @@
---
name: vector-embed
description: Generate embeddings via npx ruvector@0.2.25 embed text (ONNX all-MiniLM-L6-v2, 384-dim), normalize, and store in HNSW index
description: Generate embeddings via npx ruvector@0.3.3 embed text (ONNX all-MiniLM-L6-v2, 384-dim), normalize, and store in HNSW index
argument-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 ruvector@0.2.25 is available**:
1. **Ensure ruvector@0.3.3 is available**:
```bash
npm ls ruvector 2>/dev/null | grep '0.2.25' || npm install ruvector@0.2.25
```
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 ruvector@0.3.3
```
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 ruvector@0.3.3`.
2. **Embed the input** (use the `text` subcommand, with text as a positional arg):
- Single string: `npx -y ruvector@0.2.25 embed text "your text here"`
- With output file: `npx -y ruvector@0.2.25 embed text "your text here" -o vec.json`
- Single string: `npx -y ruvector@0.3.3 embed text "your text here"`
- With output file: `npx -y ruvector@0.3.3 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 — ruvector@0.2.25 has no built-in `--batch`/`--glob` flags.
3. **Adaptive (LoRA) variant**: `npx -y ruvector@0.2.25 embed text "..." --adaptive --domain code`
- For batch: loop over files in shell — ruvector@0.3.3 has no built-in `--batch`/`--glob` flags.
3. **Adaptive (LoRA) variant**: `npx -y ruvector@0.3.3 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 fo
Register the MCP server once with the pinned version:
```bash
claude mcp add ruvector -- npx -y ruvector@0.2.25 mcp start
claude mcp add ruvector -- npx -y ruvector@0.3.3 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 ruvector@0.2.25; 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 ruvector@0.2.25 doctor` to diagnose.
- The `embed --batch --glob` flags do **not** exist in ruvector@0.3.3. `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 ruvector@0.3.3 doctor` to diagnose.
plugins/ruflo-ruvector/skills/vector-hyperbolic/SKILL.md
+7 -7
View File
@@ -1,6 +1,6 @@
---
name: vector-hyperbolic
description: Embed hierarchical data via npx ruvector@0.2.25 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 ruvector@0.3.3 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 ruvector@0.2.25 is available**:
1. **Ensure ruvector@0.3.3 is available**:
```bash
npm ls ruvector 2>/dev/null | grep '0.2.25' || npm install ruvector@0.2.25
npm ls ruvector 2>/dev/null | grep '0.3.3' || npm install ruvector@0.3.3
```
2. **Generate a base ONNX embedding** (ruvector@0.2.25 does not expose a `--model poincare` flag on `embed text`):
2. **Generate a base ONNX embedding** (ruvector@0.3.3 does not expose a `--model poincare` flag on `embed text`):
```bash
npx -y ruvector@0.2.25 embed text "hierarchical concept" -o concept.vec.json
npx -y ruvector@0.3.3 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 ruvector@0.2.25 embed neural --help
npx -y ruvector@0.3.3 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
- ruvector@0.2.25 has no first-class Poincare ball CLI flag. Treat hyperbolic projection as a post-processing step over a standard ONNX embedding.
- ruvector@0.3.3 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
plugins/ruflo-ruvector/skills/vector-setup/SKILL.md
+14 -16
View File
@@ -1,13 +1,13 @@
---
name: vector-setup
description: First-run setup for ruvector@0.2.25 — installs ONNX/Brain/SONA add-ons, registers the MCP server, and verifies the install via `doctor`
description: First-run setup for ruvector@0.3.3 — 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 `ruvector@0.2.25` and its optional add-ons so every `/vector` subcommand actually works on first run.
Bootstraps `ruvector@0.3.3` 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 ruvector@0.2.25
npm install ruvector@0.3.3
```
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 ruvector@0.2.25 doctor
npx -y ruvector@0.2.25 info
npx -y ruvector@0.3.3 doctor
npx -y ruvector@0.3.3 info
```
4. **Register the MCP server**:
```bash
claude mcp add ruvector -- npx -y ruvector@0.2.25 mcp start
claude mcp add ruvector -- npx -y ruvector@0.3.3 mcp start
claude mcp list | grep ruvector
```
5. **Sanity check** the most common subcommands:
```bash
npx -y ruvector@0.2.25 hooks route "test"
npx -y ruvector@0.2.25 attention list
npx -y ruvector@0.2.25 rvf examples
npx -y ruvector@0.3.3 hooks route "test"
npx -y ruvector@0.3.3 attention list
npx -y ruvector@0.3.3 rvf examples
```
6. **(Optional) Generate a pi identity** for brain + edge:
```bash
npx -y ruvector@0.2.25 identity generate
npx -y ruvector@0.2.25 identity show
npx -y ruvector@0.3.3 identity generate
npx -y ruvector@0.3.3 identity show
```
## Smoke test