ruvnet--ruflo/v3/docs/adr/ADR-087-graph-node-native-backend.md

ADR-087: Wire @ruvector/graph-node as Native Graph Backend

Status: Accepted — Implemented (graph-backend.ts wrapper wired into agent spawn, causal edges, swarm topology, and MCP/CLI status) Date: 2026-04-07 · Updated: 2026-05-09

Context

The codebase has @ruvector/graph-node@2.0.3 installed (native Rust bindings, 10x faster than WASM) but 0 references in source code. Meanwhile, causal edges and agent relationships are stored only in the AgentDB bridge with no graph-native operations like k-hop neighbor queries or hyperedge support.

Available @ruvector packages evaluated

Package	Status	Result
@ruvector/graph-node	Works	createNode, createEdge, createHyperedge, kHopNeighbors, stats — all functional
@ruvector/gnn	Broken	All NAPI functions fail with type conversion errors
@ruvector/rvf	Broken	Backend resolution fails, no native bindings found

graph-node API requirements (discovered via testing)

• createNode({ id, type, embedding }) — embedding required (Float32Array)
• createEdge({ from, to, label, description, embedding, properties }) — all fields required
• createHyperedge({ nodes[], label, description, embedding, properties }) — all fields required
• kHopNeighbors(nodeId, k) — returns string[] of neighbor node IDs
• stats() — returns { totalNodes, totalEdges, avgDegree }
• GraphDatabase(path?) — optional path for persistence
• All methods are async (return Promises)

Decision

Wire @ruvector/graph-node as the native graph backend for agent relationships, causal edges, task dependencies, and swarm topology.

New module: src/ruvector/graph-backend.ts

Provides a clean wrapper over the raw graph-node API:

• isGraphBackendAvailable() — check if native backend loaded
• addNode(data) — add agent/task/pattern node
• addEdge(data) — add relationship edge
• addHyperedge(nodeIds, label) — create multi-node relationship
• getNeighbors(nodeId, hops) — k-hop neighbor query
• getGraphStats() — node/edge/degree statistics
• recordCausalEdge(src, tgt, relation) — causal edge recording
• recordCollaboration(agentId, agentType, taskId) — agent-task assignment
• recordSwarmTeam(agentIds, topology) — swarm team hyperedge

Auto-generates minimal embeddings (8-dim hash) for graph structure operations.

Files modified

1. src/ruvector/graph-backend.ts (new) — Native graph database wrapper
2. src/mcp-tools/agentdb-tools.ts — agentdb_causal-edge tries graph-node first, falls back to bridge
3. src/mcp-tools/agent-tools.ts — agent_spawn records agent node in graph
4. src/mcp-tools/hooks-tools.ts — hooks_intelligence adds graphDatabase component status
5. src/mcp-tools/hooks-tools.ts — hooks_intelligence_stats adds graph stats to ruvllm section
6. src/mcp-tools/hooks-tools.ts — implementationStatus.working includes graph-database
7. src/mcp-tools/ruvllm-tools.ts — ruvllm_status includes graph backend status
8. src/commands/neural.ts — neural status shows Graph Database row in status table

Non-goals

• Not replacing AgentDB bridge (graph-node supplements it)
• Not integrating @ruvector/gnn (NAPI broken) or @ruvector/rvf (backend missing)
• Not adding Cypher query interface (graph-node querySync untested)

Consequences

Positive

• Native Rust graph operations (10x faster than WASM)
• k-hop neighbor queries for agent relationship discovery
• Hyperedge support for swarm team representation
• Causal edges stored in both graph-node and AgentDB for redundancy
• Agent spawn automatically builds relationship graph
• Graph stats visible in neural status, hooks_intelligence, ruvllm_status

Negative

• Minimal 8-dim hash embeddings are not semantic (sufficient for graph structure)
• Persistence path (/tmp/rv-graph-persist.db) reports null (graph-node quirk), but data persists

Risks

• graph-node requires embedding on all operations — mitigated by auto-generated mini-embeddings
• graph-node persistence path returns null — mitigated by in-memory fallback
• CJS-only package — mitigated by createRequire bridge pattern

Test Coverage

• __tests__/graph-backend.test.ts — 9 tests covering exports, graceful degradation, CJS pattern
• Full suite: 32 files, 1762 tests passing

Implementation status (2026-05-09)

All 8 files listed in the Decision shipped in a single commit (same as ADR-086).

Component	Status	Files	Commit(s)
graph-backend.ts — native graph wrapper (addNode, addEdge, addHyperedge, getNeighbors, recordCausalEdge, recordCollaboration, recordSwarmTeam)	Implemented	v3/@claude-flow/cli/src/ruvector/graph-backend.ts (new)	7eb505d22 feat: native ruvllm + graph-node intelligence backends (ADR-086, ADR-087)
agentdb-tools.ts — agentdb_causal-edge graph-node first, AgentDB bridge fallback	Implemented	v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts	7eb505d22
agent-tools.ts — agent_spawn records agent node in graph	Implemented	v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts	7eb505d22
hooks-tools.ts — hooks_intelligence + hooks_intelligence_stats graph component + stats	Implemented	v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts	7eb505d22
ruvllm-tools.ts — ruvllm_status graph backend status	Implemented	v3/@claude-flow/cli/src/mcp-tools/ruvllm-tools.ts	7eb505d22
neural.ts — neural status Graph Database row	Implemented	v3/@claude-flow/cli/src/commands/neural.ts	7eb505d22
Test coverage — 9 tests, graceful degradation, CJS import pattern	Implemented	v3/@claude-flow/cli/__tests__/graph-backend.test.ts	7eb505d22

Non-goals confirmed

@ruvector/gnn (NAPI broken) and @ruvector/rvf (backend missing) were evaluated and rejected. Cypher query interface (querySync) not added (untested).