🌊 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(cli,ruflo-ruvector): embeddings_hyperbolic distance refuses off-ball points; skill stops claiming norm encodes depth (#4159)
r497bf91db432
diff --git a/plugins/ruflo-ruvector/.claude-plugin/plugin.json b/plugins/ruflo-ruvector/.claude-plugin/plugin.jsonindex ff16552ca5..6c53178a3f 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.6",+ "version": "0.3.7","author": {"name": "ruvnet","url": "https://github.com/ruvnet"diff --git a/plugins/ruflo-ruvector/CHANGELOG.md b/plugins/ruflo-ruvector/CHANGELOG.mdindex 7e8b42c51d..e8b254953b 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.7 — 2026-10-14+- fix: `vector-hyperbolic` no longer claims a normalised text embedding encodes depth (every unit-norm vector lands at the same radius); it now says to set radius from depth and measure on your own tree (#4159, thanks @ronmikailov)+## 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)diff --git a/plugins/ruflo-ruvector/agents/vector-engineer.md b/plugins/ruflo-ruvector/agents/vector-engineer.mdindex f3f75e581b..eb409a76e3 100644--- a/plugins/ruflo-ruvector/agents/vector-engineer.md+++ b/plugins/ruflo-ruvector/agents/vector-engineer.md@@ -1,6 +1,6 @@---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, 97 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---@@ -45,7 +45,7 @@ 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 97 MCP tools (verified via `ruvector mcp tools`). Register the MCP server with the pinned version:```bashclaude mcp add ruvector -- npx -y [email protected] mcp start```diff --git a/plugins/ruflo-ruvector/skills/vector-hyperbolic/SKILL.md b/plugins/ruflo-ruvector/skills/vector-hyperbolic/SKILL.mdindex 493ff6f097..2f9c7529f4 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.3.3)+description: Place hierarchical data in the Poincare ball using depth for the radius and npx [email protected] embed text for direction (a unit-norm text embedding alone has no depth)argument-hint: "<text> [--model poincare]"allowed-tools: Bash Read mcp__plugin_ruflo-core_ruflo__memory_store mcp__plugin_ruflo-core_ruflo__memory_search---@@ -19,33 +19,29 @@ Use this skill when your data has inherent hierarchy — dependency trees, modul```bashnpm 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. **Know what a text embedding can and cannot give you.** ONNX sentence embeddings (all-MiniLM-L6-v2) are unit-norm. Rescaling or exp-mapping a unit vector puts every point at the same radius (the MCP `embeddings_hyperbolic convert` gives tanh(0.5) = 0.4621 for all of them), so the radius carries no depth and parent/child distances come out nearly the same as cross-branch distances. Projecting a text embedding does not create hierarchy.+3. **Put the hierarchy in yourself.** Choose each node's radius from its depth in the tree (root near 0, leaves near 1, for example r = tanh(depth * k)), and take its direction from the text embedding, or use embeddings trained on the tree's edges. Measure on your own tree: parent-child distance should be clearly smaller than cross-branch distance.```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 # direction only```-3. **Project into the Poincare ball** in your own code (or via the experimental neural substrate):- ```bash- npx -y [email protected] embed neural --help- ```- For an ad-hoc projection, normalize the 384-dim vector to live inside the unit ball (`x_i / (||x|| * (1 + epsilon))`) and persist the projected coordinates alongside the original embedding.-4. **Geodesic distance**: `d(u, v) = arcosh(1 + 2 * ||u-v||^2 / ((1-||u||^2)(1-||v||^2)))`- Distance grows logarithmically with tree depth, preserving hierarchy.+4. **Geodesic distance** for points strictly inside the unit ball: `d(u, v) = arcosh(1 + 2 * ||u-v||^2 / ((1-||u||^2)(1-||v||^2)))`. The MCP `embeddings_hyperbolic distance` computes it (curvature -1) and returns `success: false` for a point on or outside the ball rather than a null distance.5. **Store results**:`mcp__plugin_ruflo-core_ruflo__memory_store({ key: "hyperbolic-CONCEPT", value: "COORDINATES_AND_NEIGHBORS", namespace: "hyperbolic-embeddings" })`## Caveats-- [email protected] has no first-class Poincare ball CLI flag. Treat hyperbolic projection as a post-processing step over a standard ONNX embedding.-- If you need a hyperbolic search index, store projected coordinates in AgentDB and compute geodesic distance in your own retrieval code.+- [email protected] has no `--model poincare` flag; `attention hyperbolic` is the Poincare-ball attention op, not a text-embedding projector.+- "Norm encodes depth" only holds when you set the radius from depth yourself (step 3). It does not come from the embedding.+- If you need a hyperbolic search index, store the placed coordinates in AgentDB and compute geodesic distance in your own retrieval code.-## Poincare ball properties+## Poincare ball properties (for points you placed by depth)| Property | Meaning ||----------|---------|-| Norm close to 0 | Generic, root-level concept |-| Norm close to 1 | Specific, leaf-level concept |-| Small geodesic distance | Closely related in hierarchy |-| Large geodesic distance | Distant or different subtrees |+| Norm close to 0 | Root-level concept (only if you assigned radius by depth) |+| Norm close to 1 | Leaf-level concept (same condition) |+| Small geodesic distance | Close in the hierarchy you encoded |+| Large geodesic distance | Distant subtrees in the hierarchy you encoded |## Use casesdiff --git a/v3/@claude-flow/cli/__tests__/embeddings-hyperbolic-distance-4159.test.ts b/v3/@claude-flow/cli/__tests__/embeddings-hyperbolic-distance-4159.test.tsnew file mode 100644index 0000000000..8237bc36a7--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/embeddings-hyperbolic-distance-4159.test.ts@@ -0,0 +1,82 @@+/**+ * #4159: `embeddings_hyperbolic distance` returned `{success:true, distance:null}`+ * for points on or outside the Poincaré ball (acosh of a NaN/negative argument,+ * which JSON.stringify turns into null), and `convert` was presented as if it+ * encoded hierarchy although it gives every unit-norm input the same radius.+ *+ * Numbers below were computed by hand, not copied from the implementation:+ * d((0,0),(0.5,0)) = 2*atanh(0.5) = ln 3 = 1.0986122887+ * convert(any unit vector), c=1 -> tanh(0.5) = 0.4621171572+ */+import { describe, it, expect, beforeEach, afterEach } from 'vitest';+import * as fs from 'fs';+import * as os from 'os';+import * as path from 'path';+import { embeddingsTools } from '../src/mcp-tools/embeddings-tools.js';++const tool = embeddingsTools.find((t) => t.name === 'embeddings_hyperbolic')!;+let prev: string;+let dir: string;++beforeEach(() => {+ prev = process.cwd();+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'hyp4159-'));+ fs.mkdirSync(path.join(dir, '.claude-flow'));+ fs.writeFileSync(+ path.join(dir, '.claude-flow', 'embeddings.json'),+ JSON.stringify({+ model: 'all-MiniLM-L6-v2', modelPath: '', dimension: 2, cacheSize: 1,+ hyperbolic: { enabled: true, curvature: -1, epsilon: 1e-5, maxNorm: 0.99 },+ neural: { enabled: false, driftThreshold: 0.3, decayRate: 0.01 },+ initialized: new Date().toISOString(),+ }),+ );+ process.chdir(dir);+});+afterEach(() => {+ process.chdir(prev);+ fs.rmSync(dir, { recursive: true, force: true });+});++const run = async (input: Record<string, unknown>) =>+ (await tool.handler(input)) as Record<string, any>;++describe('#4159 embeddings_hyperbolic', () => {+ it('computes the true Poincaré distance for points inside the ball', async () => {+ const r = await run({ action: 'distance', embedding1: [0, 0], embedding2: [0.5, 0] });+ expect(r.success).toBe(true);+ expect(r.distance).toBeCloseTo(Math.log(3), 9);+ });++ it('refuses unit-norm (on-ball) points instead of returning a huge or null distance', async () => {+ const r = await run({ action: 'distance', embedding1: [1, 0], embedding2: [0, 1] });+ expect(r.success).toBe(false);+ expect(String(r.error)).toMatch(/inside the (unit )?ball|convert/i);+ });++ it('refuses points outside the ball (norm > 1), the case that produced null', async () => {+ const r = await run({ action: 'distance', embedding1: [1.0000001, 0], embedding2: [0, 0.3] });+ expect(r.success).toBe(false);+ expect(JSON.stringify(r)).not.toMatch(/"distance":null/);+ });++ it('never reports success with a non-finite distance', async () => {+ for (const pair of [[[0.999999999, 0], [0, 0.999999999]], [[0, 0], [0, 0]]]) {+ const r = await run({ action: 'distance', embedding1: pair[0], embedding2: pair[1] });+ if (r.success) expect(Number.isFinite(r.distance)).toBe(true);+ }+ });++ it('convert gives every unit-norm input the same radius, and says so', async () => {+ const a = await run({ action: 'convert', embedding: [1, 0] });+ const b = await run({ action: 'convert', embedding: [0.6, 0.8] });+ expect(a.poincareNorm).toBeCloseTo(Math.tanh(0.5), 9);+ expect(b.poincareNorm).toBeCloseTo(a.poincareNorm, 9);+ expect(String(a.note ?? '')).toMatch(/same radius|does not encode|hierarchy/i);+ });++ it('status no longer claims the projection preserves tree structure', async () => {+ const r = await run({ action: 'status' });+ expect(JSON.stringify(r)).not.toMatch(/Preserves tree-like structures/);+ });+});diff --git a/v3/@claude-flow/cli/src/mcp-tools/embeddings-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/embeddings-tools.tsindex 993eb5cc52..28f27f0d18 100644--- a/v3/@claude-flow/cli/src/mcp-tools/embeddings-tools.ts+++ b/v3/@claude-flow/cli/src/mcp-tools/embeddings-tools.ts@@ -154,20 +154,35 @@ function toPoincare(euclidean: number[], curvature: number): number[] {return euclidean.map(x => x * factor);}-// Poincaré distance+// #4159: a point is usable only strictly inside the ball of radius 1/sqrt(c).+function insidePoincareBall(p: number[], curvature: number): boolean {+ const c = Math.abs(curvature);+ return c * p.reduce((sum, x) => sum + x * x, 0) < 1;+}++// Poincaré distance, d_c(a,b) = acosh(1 + 2c|a-b|^2 / ((1-c|a|^2)(1-c|b|^2))) / sqrt(c).+// Returns NaN for a point on or outside the ball (the formula is undefined there);+// callers must check Number.isFinite before reporting it.function poincareDistance(a: number[], b: number[], curvature: number): number {const c = Math.abs(curvature);+ if (a.length !== b.length || !insidePoincareBall(a, curvature) || !insidePoincareBall(b, curvature)) {+ return NaN;+ }const diffSq = a.reduce((sum, _, i) => sum + (a[i] - b[i]) ** 2, 0);const normASq = a.reduce((sum, x) => sum + x * x, 0);const normBSq = b.reduce((sum, x) => sum + x * x, 0);- const denom = (1 - normASq) * (1 - normBSq);- const delta = 2 * diffSq / (denom + 1e-15);+ const denom = (1 - c * normASq) * (1 - c * normBSq);+ const delta = (2 * c * diffSq) / denom;return (1 / Math.sqrt(c)) * Math.acosh(1 + delta);}+const HYPERBOLIC_RADIUS_NOTE =+ 'convert is an exponential map at the origin: it preserves the input norm ordering, so unit-norm text embeddings all land at the same radius. ' ++ 'It does not encode hierarchy; depth/tree structure has to come from the hierarchy itself (for example depth chosen as the radius, or embeddings trained on the tree edges).';+// Cosine similarityfunction cosineSimilarity(a: number[], b: number[]): number {const dot = a.reduce((sum, _, i) => sum + a[i] * b[i], 0);@@ -413,6 +428,9 @@ export const embeddingsTools: MCPTool[] = [const poinc1 = toPoincare(emb1, config.hyperbolic.curvature);const poinc2 = toPoincare(emb2, config.hyperbolic.curvature);distance = poincareDistance(poinc1, poinc2, config.hyperbolic.curvature);+ if (!Number.isFinite(distance)) {+ return { success: false, error: 'Hyperbolic distance is undefined for these inputs (a converted point reached the ball boundary).' };+ }similarity = 1 / (1 + distance);break;@@ -822,6 +840,7 @@ export const embeddingsTools: MCPTool[] = [poincare,curvature,poincareNorm: Math.sqrt(poincare.reduce((sum, x) => sum + x * x, 0)),+ note: HYPERBOLIC_RADIUS_NOTE,};case 'distance':@@ -831,6 +850,13 @@ export const embeddingsTools: MCPTool[] = [return { success: false, error: 'embedding1 and embedding2 required for distance action' };}const dist = poincareDistance(emb1, emb2, curvature);+ if (!Number.isFinite(dist)) {+ return {+ success: false,+ error: 'Poincaré distance needs two points of equal length strictly inside the ball (|x| < 1/sqrt(c)); got a point on or outside it, or mismatched lengths. Run convert on Euclidean vectors first.',+ curvature,+ };+ }return {success: true,action: 'distance',@@ -866,11 +892,10 @@ export const embeddingsTools: MCPTool[] = [epsilon: config.hyperbolic.epsilon,maxNorm: config.hyperbolic.maxNorm,},+ note: HYPERBOLIC_RADIUS_NOTE,benefits: [- 'Better hierarchical data representation',- 'Exponential capacity in low dimensions',- 'Preserves tree-like structures',- 'Natural for taxonomy embeddings',+ 'Exponential capacity in low dimensions when the points are placed by hierarchy (for example by depth)',+ 'Natural geometry for taxonomy embeddings that are trained or constructed for it',],};}