## 1. What is ruvector

`ruvector` (github.com/ruvnet/ruvector) is a large Rust + npm monorepo built around a custom vector storage/search engine (RuVector) plus an agent-orchestration and multi-agent-coordination layer. The indexed knowledge base covers 278 components/packages, 47,138 public symbols, and 383 entrypoint commands across two ecosystems (Rust and npm), built from 37,600 indexed passages spanning source, docs, and ADRs. It ships as many separately publishable crates and npm packages rather than one monolithic library — core storage engines, language bindings (Node native, WASM), a CLI, and a family of agent-role definitions all live in the same tree.

## 2. What can it do for you

- **Vector storage and similarity search**: create a vector store, insert embeddings, and run top-k search via the `ruvector` CLI (`ruvector create --dimensions 384 --path ./vectors.db`, `ruvector insert --input embeddings.json`, `ruvector search --query "[...]" --top-k 10`, `ruvector benchmark --queries 1000`).
- **Graph-aware and clustered retrieval**: components for graph search, clustering, DiskANN-style indexing, GNN reranking, and distributed serving via Raft consensus and replication (`ruvector-graph`, `ruvector-cluster`, `ruvector-diskann`, `ruvector-gnn`, `ruvector-gnn-rerank`, `ruvector-raft`, `ruvector-replication`).
- **Coherence / proof / consensus checking**: a dedicated stack (`ruvector-coherence`, `ruvector-mincut`, `cognitum-gate-kernel`, `ruvector-proof-gate`, `ruvector-cognitive-container`, `ruvector-bench`) for validating graph/agent state rather than pure ANN search.
- **Attention and LLM-adjacent inference**: `ruvector-attention` (built on `ruvector-math`) and `ruvllm` (which depends on both `ruvector-attention` and `ruvector-core`) suggest an inference/routing layer sitting on top of the vector primitives, alongside a separate `ruvector-router-*` family (core/cli/ffi/wasm).
- **Multi-agent orchestration**: the indexed KB includes concrete agent-role definitions — `code-analyzer`, `system-architect`, `byzantine-coordinator`, `crdt-synchronizer`, `base-template-generator` — each with YAML frontmatter (triggers, capabilities, hooks) and prose responsibilities, plus working JS implementations of CRDT primitives (G-Counter, OR-Set, LWW-Register) with vector-clock-based conflict resolution for eventually-consistent state sync between agents.
- **Edge/hardware acceleration**: `ruvector-hailo` and `ruvector-hailo-cluster` depend on `hailort-sys` (Hailo AI accelerator bindings) and reference `ruvector-mmwave`, pointing to an edge-deployment path combining the vector core with dedicated hardware.
- **Embeddable bindings**: Node-native bindings (`ruvector-node`, `ruvector-graph-node`, `ruvector-gnn-node`, `ruvector-mincut-node`, `ruvector-attention-node`) and WASM bindings (`ruvector-wasm`, `ruvector-acorn-wasm`, `ruvector-graph-wasm`, `ruvector-gnn-wasm`, `ruvector-mincut-wasm`, `ruvector-cnn-wasm`, `ruvector-attention-wasm`) let the same core logic run in Node or the browser.
- **Cloud/production integration deps**: `@google-cloud/*` (compute, storage, pub/sub, redis, cloud-sql-connector, logging, monitoring), `@grpc/*`, `@anthropic-ai/sdk`, `@google/generative-ai`, `@modelcontextprotocol/sdk`, and `@claude-flow/memory` are all external dependencies, indicating this is wired for real cloud deployment and MCP-server integration, not just a local library.
- **A trading-domain consumer**: the external-deps list includes an extensive `@neural-trader/*` family (backtesting, brokers, market-data, portfolio, risk, prediction-markets, accounting, MCP). The brief doesn't establish the exact relationship — whether it's a bundled example or a separate consuming product — so treat it as "present in the dependency graph," not confirmed first-party.

## 3. What is it made of (the components)

Grouping the 278 components by what the internal dependency graph shows them wired to:

- **Core storage/search**: `ruvector-core` (the shared foundation — nearly everything depends on it), `ruvector-collections`, `ruvector-filter`, `ruvector-metrics`, `ruvector-node`, `ruvector-wasm`, `ruvector-cli`.
- **Graph, clustering, distribution**: `ruvector-graph` (→ `ruvector-cluster`, `ruvector-raft`, `ruvector-replication`, `ruvector-core`), `ruvector-diskann`, `ruvector-mincut` (→ `ruvector-core`, `ruvector-graph`), plus node/wasm variants of graph and mincut.
- **GNN**: `ruvector-gnn` (→ `ruvector-core`, `ruvector-diskann`), `ruvector-gnn-rerank`, `ruvector-gnn-node`, `ruvector-gnn-wasm`.
- **Coherence / proof / quality-gate stack**: `ruvector-coherence`, `ruvector-coherence-hnsw`, `cognitum-gate-kernel` (→ `ruvector-mincut`), `ruvector-cognitive-container`, `ruvector-proof-gate`, `ruvector-bench` (ties together `cognitum-gate-kernel`, `ruvector-cognitive-container`, `ruvector-coherence`, `ruvector-core`, `ruvector-mincut`).
- **ACORN / RabitQ (indexing/quantization variants)**: `ruvector-acorn`, `ruvector-acorn-wasm`, `ruvector-rabitq`, `ruvector-rabitq-wasm`, `ruvector-rulake` (→ `ruvector-rabitq`).
- **Router**: `ruvector-router-core`, `ruvector-router-cli`, `ruvector-router-ffi`, `ruvector-router-wasm`.
- **Attention / LLM layer**: `ruvector-math`, `ruvector-attention` (→ `ruvector-math`), `ruvector-attention-wasm`, `ruvector-attention-node`, `ruvllm` (→ `ruvector-attention`, `ruvector-core`).
- **Tiny-dancer**: `ruvector-tiny-dancer-core`, `-wasm`, `-node`.
- **Server / persistence**: `ruvector-server`, `ruvector-snapshot` (both → `ruvector-core`).
- **Edge / hardware**: `ruvector-hailo` (→ `hailort-sys`, `ruvector-core`), `ruvector-hailo-cluster` (→ `ruvector-core`, `ruvector-hailo`, `ruvector-mmwave`, `ruvllm`).
- **Other named crates seen in commands but not in the enumerated component/dep list**: `ruvector-lsm-ann`, `ruvector-temporal-coherence`, `ruvector-capgated`, `ruvector-matryoshka`, `rvagent-backends` — referenced via `cargo run`/`cargo test` entrypoints, so they exist in the workspace even though their dependency wiring wasn't in the sampled graph.
- **Agent-role library**: markdown/YAML agent definitions (`code-analyzer`, `system-architect`, `byzantine-coordinator`, `crdt-synchronizer`, `base-template-generator`) plus JS CRDT implementations (`CRDTSynchronizer`, `GCounter`, `ORSet`, `LWWRegister`) — this is a documentation/behavior layer rather than a compiled crate, but it's a first-class part of what's indexed.

## 4. How it works

The Rust side is layered: `ruvector-core` is the shared foundation almost everything else builds on. `ruvector-collections`/`ruvector-filter`/`ruvector-metrics` extend it directly; `ruvector-node` and `ruvector-wasm` wrap core+collections+filter to expose the same engine to JS and the browser; `ruvector-cli` wraps core+gnn+graph as the top-level command surface. Higher-level capabilities (graph search, clustering, GNN reranking, coherence/consensus checking) are each separate crates that depend back down into `ruvector-core`, rather than being built into it — so you pull in only the pieces you need. The coherence/proof-gate group (`cognitum-gate-kernel`, `ruvector-cognitive-container`, `ruvector-proof-gate`, `ruvector-bench`) forms a distinct validation pipeline layered on top of `ruvector-mincut` and `ruvector-core`, separate from the plain ANN-search path.

The attention/LLM branch (`ruvector-math` → `ruvector-attention` → `ruvllm`) and the edge-hardware branch (`ruvector-hailo` → `ruvector-hailo-cluster`, which also pulls in `ruvllm` and `ruvector-mmwave`) both terminate back at `ruvector-core`, suggesting the vector engine is the common substrate under inference and edge-sensor workloads alike.

On the npm side, most packages follow a standard per-package pattern of `build` → `build:esm`/`build:cjs`/`build:napi`/`build:wasm` → `typecheck`/`lint` → `test` → `prepublishOnly`, indicating many independently versioned/published packages (seen directly in install commands like `npm install @ruvector/core@0.1.14 ruvector@0.1.20`) rather than a single package.

Separately, the repo carries a multi-agent coordination layer: agent-role definitions (YAML frontmatter + markdown instructions) describe specialized agents (code quality analysis, system architecture, Byzantine fault-tolerant consensus, CRDT-based state sync), and there are working CRDT implementations (G-Counter, OR-Set, LWW-Register) using per-node vector clocks for merge/conflict resolution — this is the mechanism referenced by `byzantine-coordinator` and `crdt-synchronizer` for keeping distributed agent state consistent.

## 5. How do I install and use it

**npm (JS/TS side)**:
```
npm install ruvector
npm install --save-exact ruvector
npm install @ruvector/core@0.1.14 ruvector@0.1.20
npm install @ruvector/wasm
npm install -g ruvector-cli
npm install ruvector ruvector-extensions
```

**CLI usage** (via `npx ruvector` or the global `ruvector-cli`):
```
npx ruvector --help
npx ruvector info
npx ruvector create --dimensions 384 --path ./vectors.db
npx ruvector insert --input embeddings.json
npx ruvector search --query "[0.1, 0.2, 0.3, ...]" --top-k 10
npx ruvector benchmark --queries 1000
```

**Rust side**:
```
cargo build --release --workspace
cargo test --workspace
cargo bench -p ruvector-core
cargo bench --workspace
cargo run --release -p ruvector-lsm-ann --bin benchmark
cargo run --release -p ruvector-temporal-coherence --bin tcd-benchmark
cargo run --release -p ruvector-capgated --bin benchmark
cargo run --release -p ruvector-matryoshka --bin benchmark
```
There's also a dedicated sandbox/security test path (`cargo test -p rvagent-backends sandbox`, `cargo test --test sandbox_security_tests`), and WASM/native builds via `npm run build:wasm`, `build:wasm:bundler`, `build:wasm:node`, and `npx napi build --platform --release` (needs `@napi-rs/cli`).

**Benchmarking**: a fairly elaborate harness under `scripts/benchmark/` — `single-dataset-harness.ts`, `sweep-harness.ts`, `pareto-visualizer.ts`, `retrieval-harness.ts`, `vdb-bench-workloads.ts`, `witness-signer.ts`, `darwin-harness.ts`, `check-regression.js` — plus `npm run benchmark:sift1m:smoke` and `npm run benchmark:download-datasets`, indicating standard ANN-benchmark-style evaluation (SIFT1M is referenced by name) is part of the repo's own QA, not just something you'd bolt on.

**Semantic hooks / memory**:
```
npx ruvector hooks remember --semantic --type decision \
npx ruvector hooks recall --semantic --top-k 3 \
```

**Swarm/orchestration** (via `@claude-flow/cli`, which this repo's tooling integrates with):
```
npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized
npx @claude-flow/cli@latest memory search --query "authentication patterns"
npx @claude-flow/cli@latest memory store --key "pattern-auth" --value "JWT with refresh" --namespace patterns
npx @claude-flow/cli@latest hooks route --task "..."
npx @claude-flow/cli@latest doctor --fix
```

**Per-package dev loop**: most packages support `npm run dev`, `npm run build`, `npm test`/`test:watch`/`test:coverage`, `npm run lint`, and `npm run typecheck`; several expose `npm run deploy` or region-specific deploy scripts (`deploy:us-east`, `deploy:us-west`, `deploy:eu-west`, `deploy:asia-east`).

## 6. Honest scope and limits

- This is a summary of an indexed KB (37,600 passages across 278 components), not a hand-audited read of every file — at this scale, no primer can be exhaustive, and some detail is necessarily left out.
- The sampled KB passages skew heavily toward generic Claude-Flow-style agent role templates (`code-analyzer`, `system-architect`) that repeat near-verbatim across multiple indexed chunks (visible duplication in the sample: entries 1/6, 2/7, 8/10, 9/11). That repetition is a property of the sample, not evidence about how much of the repo is agent templates vs. core engine code — the component/dependency lists are the more reliable signal for "what this repo is."
- No performance numbers, benchmark results, accuracy figures, or throughput claims are given in the brief beyond the specific package version pins shown in the install commands and the 384-dimension figure — none are asserted here, and none should be assumed.
- A handful of crates appear only in command entrypoints (`ruvector-lsm-ann`, `ruvector-temporal-coherence`, `ruvector-capgated`, `ruvector-matryoshka`, `rvagent-backends`) without corresponding entries in the sampled component/dependency lists — they're real (referenced by `cargo run`/`cargo test`), just not further described here.
- The relationship between the core RuVector engine and the `@neural-trader/*` dependency family (backtesting, brokers, risk, prediction markets, accounting) isn't established by the brief — it shows up as an external dependency set, not as a documented first-party feature, so its role (example app vs. separate consuming product) is left open rather than guessed at.
- This primer is generated from an automated repo index, not reviewed by the project's maintainers — treat it as a starting map, not authoritative documentation.
