🧠 RuvNet Brain

🧠 RuvNet Brain —

A portable, source-grounded brain over Reuven Cohen's (rUv's) RuvNet stack — delivered as a Claude Code plugin that makes Claude use the stack instead of fighting it.

Three independent things version separately here — by design, not drift. Every number below is live (read straight from its real source, never hand-typed), so none of them can go stale:

• plugin (badge above) — the Claude Code plugin itself: SKILL.md, the grounding hooks, the MCP server. Read live from plugin/.claude-plugin/plugin.json. Updates often — this is where behavior fixes land.
• installer (npm) (badge above) — the npx ruvnet-brain setup script. Read live from the npm registry. Only moves when the installer script itself changes — rare.
• Brain Release (the downloadable 512MB knowledge bundle, linked from the "download" badge above) — always resolves to releases/latest, currently v0.5.0-dev. Only moves when the underlying knowledge base is rebuilt — separate again from the two above.

_{Built by Stuart Kerr at Isovision.ai · free & fair use, to help everyone leverage the high end of agentic coding.}

▶ Come see it visually explained

_{An interactive, animated walkthrough of what you can actually build — click the preview to open it.}

---

The one thing to understand first

Reuven Cohen (rUv) builds about nine months ahead of the state of the art. His RuvNet building blocks — Ruflo, RuVector, AgentDB, agentic-flow, SPARC and ~20 more — are the working prototypes of what becomes mainstream AI tooling three quarters later. This is the actual front edge.

But Claude was trained on classical software development. Point it at rUv's stack and it doesn't recognize the work: it drifts, it doubts real capabilities (“ruflo can't edit files,” “RuvNet has no vector DB — use Pinecone”), and it quietly falls back to the patterns it knows (pgvector, LangChain, a hand-rolled cosine loop). A newcomer gets the worst of both worlds — a revolutionary toolset with no instruction manual, and an assistant that talks them out of using it.

RuvNet Brain is the missing instruction manual. It reads rUv's real source, hands Claude the answer key, and removes Claude's permission to make things up about the stack. Install it once, aim it at any repo, and a newcomer can build ~9 months ahead — without being rUv.

The novelty is enforcement, not retrieval. Plain RAG only decides what to add to context; it never stops a model from overriding good context with a stronger prior. This ships a UserPromptSubmit hook that injects a grounding directive on every RuvNet-relevant turn, consumed structurally by the harness — so grounding is non-optional. RAG decides what to add; this decides what the model isn't allowed to make up.

---

The problem it solves

You know the failure mode. You ask Claude to build with Ruflo or RuVector, and instead of reading rUv's actual code it reaches for its training priors: “let's just use pgvector,” “I'll hand-roll cosine similarity,” “I don't think ruflo can edit files.” It skims, it guesses, it doubts tools that work perfectly well — and the result drifts off the very stack you chose.

ASCII version (for AI / accessibility)

WITHOUT the brain — drift          |   WITH RuvNet Brain — grounded
                                   |
 You: build with Ruflo/RuVector    |    You: the same request
            |                      |              |
            v                      |              v
 Claude falls back to priors       |    Enforcement hook grounds the turn
            |                      |              |
            v                      |              v
 "just use pgvector"               |    search_ruvnet -> cited rUv source
 hand-rolls cosine similarity      |    (whole files, labeled repo + path)
 "ruflo can't edit files"          |              |
            |                      |              v
            v                      |    Builds ON the stack (RVF/HNSW, swarms)
 Drifts OFF the stack              |

---

Install — one line

npx ruvnet-brain

That single command runs the whole setup, narrating what it's doing and why at each step: it downloads the brain (~512 MB) from the latest GitHub Release, unpacks it to ~/.cache/ruvnet-brain/kb, installs its local reader (no cloud calls, no API keys), and wires the Claude Code plugin — the search_ruvnet MCP tool + the UserPromptSubmit grounding hook — at user scope. The installer and the search_ruvnet tool run on macOS, Linux, and Windows; the grounding/enforcement hooks are POSIX shell, so they fire on macOS, Linux, and Windows-via-WSL/Git-Bash (on native Windows without WSL the search tool still works, but the auto-grounding hooks don't fire — a Node port of the hooks is on the roadmap). It's safe to re-run, and the brain itself always fetches the current Release regardless of which install path you use — you install once; you don't keep re-downloading.

Want the bleeding-edge installer, even ahead of the last npm publish? npx github:stuinfla/ruvnet-brain always runs straight off the latest GitHub commit.

Manual install (what the one-liner automates)

claude plugin marketplace add stuinfla/ruvnet-brain
claude plugin install ruvnet-brain@ruvnet-brain --scope user

Registers the search_ruvnet MCP tool, the grounding skill, and the UserPromptSubmit enforcement hook — globally, at user scope. The plugin expects the brain at ~/.cache/ruvnet-brain/kb (or point RUVNET_BRAIN_KB at your own copy). The first install may show a one-time trust prompt for the hook.

Then just ask. “How does Ruflo orchestrate agent swarms, and what implements it?” The hook grounds the turn, Claude calls search_ruvnet, and it answers from cited source — down to the function body.

---

✨ What's new in v0.5.0-dev — it now knows the stack down to the code

Earlier versions knew the docs and architecture. v0.5.0-dev re-indexes the code-rich repos to full function bodies, against each repo's real source layout — so “how is this actually implemented?” returns the implementation, not a summary:

Repo	Full-body code passages
agentic-flow	296 → 984	model-routing, ReasoningBank
ruv-fann	52 → 779	ruv-swarm, cuda-wasm, neuro-divergent
qudag	→ 531	post-quantum crypto core, exchange, MCP
daa	→ 266	orchestrator, economy, rules, swarm
safla	0 → 136	the metacognitive / self-modification layer

Plus: the “take the wheel” behavioral pipeline (below), a 4-level behavioral test harness, a build-integrity fix (empty files no longer pollute the index), and the private-store fence that keeps unpublished repos out of the public bundle.

---

How it works

The expensive work happens once, at build time: every covered repo is deep-walked (whole files, full function bodies, plus a symbol index), embedded into two vector variants (MiniLM-384 for edge/portability, bge-768 for depth) stored on-disk in RVF / HNSW, and distilled into a concepts + capability layer of per-repo primers and cards. That's 90,842 source chunks. At query time, search_ruvnet searches every repo's store at once, pools the hits, and runs them through one cross-encoder rerank on a common scale — so the truly relevant file wins regardless of which repo it lives in — then returns whole source files, each labeled by repo and path.

• Per-repo RVF stores — each repo gets its own HNSW graph; the tool queries across them and normalizes.
• Dual embeddings + cross-encoder — MiniLM-384 for edge/portability, bge-768 for depth; a single cross-encoder rerank puts every candidate on one comparable scale. (The cross-encoder — a third model reading query+passage together — is the real quality lever, not a fusion of the two embedders.)
• Concepts / capability layer — per-repo primers and capability cards let the model ground capability claims and route a described need to the right repo, not just do file lookups.

---

How it changes Claude's behavior — it takes the wheel

Grounding is enforced, not suggested. On a RuvNet-relevant prompt the UserPromptSubmit hook injects a directive into context; Claude calls search_ruvnet, gets whole source files labeled by repo and path, and answers from them. Because the hook's stdout is consumed by the harness every turn, it's structural — Claude can't quietly skip it.

And on a build request, the brain doesn't wait to be told each step — it runs the process the way Ruv would:

Propose the architecture first → one go/no-go → then execute end-to-end: SPARC (Spec → Pseudocode → Architecture → Refinement → Completion) · model the domain (DDD) and capture ADRs · spin up parallel Ruflo swarms · persist decisions to AgentDB · treat design as a build step (frontend-design + AI image generation, never “working but ugly”) · test → score 1–100 → loop to ≥98 · and it asks for an API key when a step needs one instead of silently skipping it.

The downstream effect: Claude prefers RuvNet building blocks over generic defaults (RVF/HNSW over pgvector/Pinecone, Ruflo swarms over hand-rolled orchestration) and drives the whole assess → build → verify → score loop rather than answering one question at a time.

---

Capability-confidence routing

The brain answers both kinds of questions. Name the repo or ask something specific and it resolves to the right repo (47/48, 98%). Describe a need without naming the repo — the way a newcomer would — and it still lands the right repo (26/28, 93%). That newcomer path used to be the weak spot (33% before the fix); adding capability cards — a capability-phrased passage per building block — closed the gap.

---

What it covers

~21 of rUv's building-block repos in the ruvnet org — the reusable pieces you'd actually compose into a system — each deep-walked, embedded in both variants, symbol-indexed, and given a capability card.

Repo	What it gives you	Repo	What it gives you
ruflo	Agent orchestration / swarms	ruvector	RVF + on-disk HNSW vectors
agentdb	Agent memory + graph/Cypher	rulake	Vector cache layer
ruview	Camera-free WiFi/CSI sensing (presence, pose, vitals)	agentic-flow	Cheap multi-provider model routing
agenticow	Copy-on-write agent memory (branch 1M vectors in ~162 B)	sparc	5-phase build methodology
qudag	Quantum-resistant DAG messaging	safla	Self-aware feedback loop
ruv-fann	Fast neural nets (Rust/WASM) + ruv-swarm	daa	Decentralized autonomous agents
synthlang	Prompt compression (~75% token cut)	rupixel	On-device visual embeddings
dspy.ts	DSPy-style programmable LLM pipelines in TS	fact	Fast-Access Cached Tools + circuit breaker
cve-bench	Security-fix benchmark	agent-harness-generator	Harness scaffolding / metaharness
rvm	Proof-gated capability microhypervisor	rUv-dev · open-claude-code	Dev workflow + agent tooling

Not in the public brain: rUv's private Cognitum One repos (seed, v0-appliance, platform-docs) are fenced out of the download by design — verified zero-leak in every build. Helix (rUv's local-first health app) is a finished product, not a building block, so it's out too.

---

Testing & proof

Everything below is re-runnable — the proof is the output of a command, not a claim.

bash scripts/gate.sh                              # the pass/fail routing gate
node scripts/behavioral-l1-l4.mjs                 # the 4-level behavioral harness
node plugin/test/run-tests.mjs                    # full plugin QA over real JSON-RPC

Test	Result	What it proves
Named / specific routing	47 / 48 (98%)	name the tool → right repo
Described-need routing	26 / 28 (93%)	describe the need, no name → right repo (was 33% before capability cards)
Context-scenario routing	7 / 8 (88%)	full-scenario prompts route correctly
L1–L4 behavioral harness	all pass	route · deep-recall (returns code) · implement (cites the API) · orchestrate (the hook drives the full pipeline)
Plugin QA	26 / 26	manifests, hook firing, MCP initialize/tools/list, capability battery
Clean-room install	3 / 3	download the published 512 MB bundle fresh → unzip → query → grounded, cited answers

Two honest residuals, not hidden: one described question (“route to cheaper models to cut cost”) still leans ruflo over agentic-flow (orchestration/cost overlap); one unnamed “methodology” question routes to synthlang instead of sparc. Proof reports land in PROOF.md, DESCRIBED-PROOF.md, and HELIX-DEMO-NOHELIX.md.

Query it directly (CLI):

cd kb
export KB_MODEL_CACHE=/path/to/models-cache
node forge-ask-all.mjs --dir . --q "How does RuVector implement HNSW vector search?" --k 3

Cross-repo answer quality requires the cross-encoder, which requires npm i in the bundle. Without it, search falls back to raw vectors and ranks poorly.

---

Honest status

This is v0.5.0-dev — we don't claim “done,” “complete,” or “zero hallucinations.” Where it stands:

• ✅ The grounding brain is real and proven — ~21 building-block repos, 90,842 chunks, dual embeddings, cross-encoder rerank, plugin (MCP tool + enforcement hook + skill), all re-runnable.
• ✅ Code-level depth — the code-rich repos are indexed to full function bodies; “how is it implemented?” returns the implementation. Verified in the shipped bundle (clean-room 3/3).
• ✅ Routing holds — named 47/48, described 26/28, scenario 7/8; behavioral L1–L4 all pass; private stores fenced out of the public bundle (zero-leak verified).
• ⚠️ Two routing residuals (above) — surfaced, not hidden.
• ✅ Published on npm — npx ruvnet-brain (short form); npx github:stuinfla/ruvnet-brain always tracks the latest commit if you want it even fresher.
• ⏳ The fully-autonomous engineering loop (ADR-0008) — the behavioral hook drives the assess → SPARC → ADR/DDD → QA → score loop; a generalized always-loops-to-≥98 engine is the next phase.

---

What's in the box

• kb/ — the brain: per-repo .rvf + .big.rvf stores, full-passage sidecars, symbol indexes, per-repo primers, the concepts store, and the forge-* query tools (CLI + MCP search_ruvnet).
• plugin/ — the Claude Code plugin (MCP server, grounding skill, UserPromptSubmit enforcement hook, marketplace manifest, test suite).
• scripts/ — gate.sh (routing gate), behavioral-l1-l4.mjs (behavioral harness), prove.mjs, build-bundle.mjs, brain-stamp.mjs.
• docs/ — VISION.md (the why), adr/ (locked decisions incl. ADR-0008), DDD.md.
• explainer/ — the source of the live explainer.
• SPEC.md · PROGRESS.md — the master spec and the living, timestamped build log.

The brain binaries ship via the Release, not git — a fresh clone is lightweight; npx fetches the 512 MB bundle.

---

Links

• ▶ Live explainer: https://ruvnet-brain.vercel.app
• Download / Release: https://github.com/stuinfla/ruvnet-brain/releases/tag/v0.5.0-dev
• rUv's RuvNet org: https://github.com/ruvnet
• Built by: Stuart Kerr — Isovision.ai

_{MIT licensed · free & fair use · grounded in rUv's real source, cited every time.}