One core does the searching, the syncing, and the coordinating

Say you're building something that has to remember a lot — every product a shopper looked at, every support ticket ever filed, every paragraph in a document library — and instantly bring back the handful of items relevant to what someone just asked. A plain list won't do that. Comparing a new question against a million old records one at a time gets slower every day the pile grows, until a search that should take a blink takes seconds, then minutes.

Now say the app also can't go down. If it runs on one machine and that machine dies, every user waiting on it waits with it. Keeping a second, third, or tenth copy of the same data — all correct, all in agreement, even when the network between them is unreliable — is a different kind of hard problem than search. It's the kind where two machines can each believe they hold the truth, disagree, and quietly corrupt the data if nobody catches it.

And say part of the job is better done by more than one worker at once — one piece reviewing code for problems, another piece deciding how the system should fit together, a third piece checking the result before it ships. Coordinating several AI helpers so they don't duplicate work, forget what the others found, or overwrite each other's output is a third problem again, with its own ways to fail.

None of these three problems shares an off-the-shelf answer. Most teams solve them with three or four different open-source projects, glued together by hand, built by people who never talked to each other and never tested their seams under real failure.

ruvector is what's usually called a vector search engine: a system built to compare those numeric fingerprints and return the closest matches, fast, out of collections that can run into the millions. That's its core.

Around that core, the same project ships a distributed database layer — the part that spreads a copy of your data across more than one machine, so one machine going offline doesn't take your search down with it — built from the same underlying pieces as the search engine itself, not bolted on afterward.

It also ships a set of AI agents: small, specialized AI programs with a defined job, ready to be assigned work and report back — one reviews code for quality problems, another designs how a system should fit together — instead of leaving one assistant to do everything in sequence.

All of it lives in one repository: 278 components, individually buildable pieces in Rust or as npm packages, sharing one dependency structure — so the search engine, the reliability layer, and the agents are built to expect each other, not discovered as compatible by accident.

Look at how the pieces connect, and a pattern falls out: nearly everything else in the repo — the layer that spreads data across machines, even the layer that double-checks an answer — is built directly on the same core module that runs the basic search.

That's not a coincidence of naming. The same underlying structure that lets the search core jump toward close matches without checking everything is reused to let the reliability layer decide who agrees with whom, and reused again by the layer that re-checks results before they're returned. One fix or speed-up in that shared core lifts every layer built on it, instead of three separate projects each needing their own tuning.

It also explains why the AI agents aren't bolted onto the database as an afterthought — they're built to read and write against the same store the search engine uses, so what an agent finds becomes searchable data immediately, not a note left in a separate system.

The aha

The search engine and the reliability engine aren't cousins — they're the same engine, doing two different jobs.

A handful of specific mechanisms carry most of the weight. Each is defined here, once, in plain words, at first use.

The search core is a graph-shaped index — imagine a map where every fingerprint is a landmark linked to its nearest neighbors, so a query starts at one landmark and hops toward closer and closer matches instead of checking the whole map. That shape has a name, HNSW (hierarchical navigable small world), and it's what lets a match come back out of millions of records without scanning all of them; the component is named directly in the repo, ruvector-coherence-hnsw.

Keeping copies of data in agreement uses two strategies depending on how much trust you can assume. Raft is a consensus protocol — a set of rules that lets a group of machines agree on one order of updates by electing a leader and following it (ruvector-raft). CRDTs — conflict-free replicated data types — take the opposite approach: structures built so two machines can each update their own copy independently and always merge back to the same result automatically, without asking permission first; the repo's own synchronizer implements the standard shapes, including a counter that only ever grows, a set that tracks additions and removals separately, and a register that resolves conflicting writes by timestamp [16][17][18][19][20]. For the harder case — some machines not just slow but actively wrong — there's Byzantine fault-tolerant consensus, built to keep a decision correct even when part of the group is lying [14].

The AI agent layer ships as role definitions, not one general-purpose assistant: a code-quality reviewer with a defined job description and trigger conditions [2], a system architect explicitly marked as needing human sign-off on major decisions [9], and others. Above the raw search results, a graph neural network — a model that reasons by passing information along the connections between related items — re-ranks matches (ruvector-gnn-rerank), and an attention layer (ruvector-attention, feeding an inference runtime called ruvllm) weighs which parts of a result matter most before anything is returned.

Data flow

Three shapes of problem, one project underneath each.

In the real world

There's a real CLI here, not just a library — every command below comes straight from the project's own listed commands.

npm install -g ruvector-cli

1. Check your prerequisites You need Node.js and npm (Node's package installer) on your machine — run npm -v in a terminal; any version printing back means you're ready. No database, no Docker, nothing else to stand up first.
2. Install the CLI Run npm install -g ruvector-cli. This gives you the ruvector command everywhere on your machine — the project also lists plain npm install ruvector for using it purely as a library, without the CLI.
3. Create a store Run npx ruvector create --dimensions 384 --path ./vectors.db. You'll see a new, empty index file appear at ./vectors.db, sized to hold 384-number fingerprints — a common size for small AI models.
4. Load data in Run npx ruvector insert --input embeddings.json, pointing at a JSON file of your own numeric fingerprints. The CLI reports back how many records it added to the store.
5. Search it Run npx ruvector search --query "[0.1, 0.2, 0.3, ...]" --top-k 10. A ranked list of the 10 closest matches prints straight to your terminal — this is the moment the whole idea becomes visible.
6. Confirm it holds up, then wire it in Run npx ruvector benchmark --queries 1000 for real throughput numbers on your machine, or npx ruvector info to inspect what you just built. You now have a working, queryable local index — next, call it from code with @ruvector/wasm in a browser or the Node.js bindings pulled in by the ruvector package, or clone the repo and run cargo build --release --workspace to work in the Rust source directly.

Everything above was grounded in a full pass over ruvector's source: 37,600 passages across 278 components, indexed so it can be searched and cited rather than guessed at.