Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

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.json
index 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.md
index 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.md
index 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:
```bash
claude 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.md
index 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
```bash
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. **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 cases
diff --git a/v3/@claude-flow/cli/__tests__/embeddings-hyperbolic-distance-4159.test.ts b/v3/@claude-flow/cli/__tests__/embeddings-hyperbolic-distance-4159.test.ts
new file mode 100644
index 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.ts
index 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 similarity
function 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',
],
};
}