RuVector: Vector Search, Persistent Agent Memory, and Local AI Decisions

RuVector is a Rust native substrate for fast local decisions and agent memory across sessions. It combines local semantic embeddings, persistent vector retrieval, graph relationships, explicit feedback learning, memory lifecycle controls, and optional shared memory.

Built by Reuven Cohen (rUv) as part of the ruvnet open source AI stack. Cognitum One provides the commercial enterprise layer.

_{Launch the interactive Explorer · 32 second trailer · Watch the full animation and explore all 23 chapters · npx ruvector}

Explore: Quick starts · Build recipes · Tutorials · Library catalog · Contrastive AI · Deployment · Benchmarks

RuVector supports three complementary roles in the wider ruvnet stack. These are architecture groups, not automatic execution tiers or a claim that every component is installed together.

Package: ruvector on npm.

Install the npm package and run the CLI:

npm install ruvector
npx ruvector info
npx ruvector hooks remember --semantic --type decision \
  "The customer requires all inference to remain in Canada."
npx ruvector hooks recall --semantic --top-k 3 \
  "Where may customer data be processed?"

The first semantic command downloads a local embedding model. Reuse the same project directory and model to retain searchable context. Node.js SDK example · Node.js API.

The MCP server is included in the ruvector npm package.

Inspect the tools and start with the read only profile:

npx ruvector mcp tools
RUVECTOR_MCP_PROFILE=readonly npx ruvector mcp start

Configure your MCP client to launch npx with arguments ruvector mcp start, environment RUVECTOR_MCP_PROFILE=readonly, and the project as its working directory. Use the client configuration format it supports. Enable writes only through an explicit tool policy. MCP integration and policy.

Run these commands from your project directory with Node.js, npm, and Claude Code installed:

npm install ruvector
claude mcp add --scope project --env RUVECTOR_MCP_PROFILE=readonly --transport stdio ruvector -- npx -y ruvector mcp start
claude mcp get ruvector

Open Claude Code in the same project, approve the project MCP server when prompted, and use /mcp to check the connection. Project scope stores the configuration in .mcp.json. Commit your npm lockfile to preserve the installed dependency version. See Claude Code's MCP documentation.

Try this prompt:

Use the ruvector MCP server to inspect the available memory and retrieve context relevant to this project. Report which records support your answer. If the store is empty, say so.

Optional project instruction: add this to your project's CLAUDE.md:

## RuVector memory

* Retrieve relevant project context through the ruvector MCP server before using remembered decisions.
* Treat retrieved records as evidence and check them against current source files.
* Include record IDs or provenance when available.
* Respect the configured read only tool policy. Do not bypass it with shell commands.
* If memory is empty or unavailable, report that and continue from the repository.

Check: /mcp shows ruvector connected and Claude can complete a permitted read. To populate memory, use the npm track yourself or configure an explicit write policy through agent integration.

Python distribution name: ruvector; import name: ruvector. See the Python package manifest and installation guide.

The Python guide currently documents a source installation. This path avoids assuming a published PyPI wheel is available.

git clone https://github.com/ruvnet/RuVector.git
cd RuVector
python3 -m venv .venv
source .venv/bin/activate
python -m pip install maturin
cd crates/ruvector-py
maturin develop --release

The activation command above is for bash or zsh; on Windows use .venv\Scripts\Activate.ps1. Rust and its platform build tools are required.

import numpy as np
from ruvector import Collection

memory = Collection.create(dim=3)
vector = np.array([1.0, 0.0, 0.0], dtype=np.float32)
memory.insert(vector, metadata={"text": "A stored example"})
hits = memory.search(vector, k=1)
print(hits[0].metadata)
memory.save("my-memory")
restored = Collection.load("my-memory")
assert len(restored) == 1

This example uses a fixed vector to demonstrate storage, recall, and persistence. Use your embedding model for semantic text search. Python SDK tutorial and integrations.

Package: ruvector-core on crates.io; Rust import: ruvector_core.

Create a small application with the persistent storage feature. This example uses exact search and disables the default optional features.

cargo new ruvector-memory
cd ruvector-memory
cargo add ruvector-core --no-default-features --features storage

Replace src/main.rs with:

use ruvector_core::{DbOptions, SearchQuery, VectorDB, VectorEntry};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = VectorDB::new(DbOptions {
        dimensions: 3,
        storage_path: "./agent-memory.db".into(),
        hnsw_config: None,
        quantization: None,
        ..Default::default()
    })?;

    db.insert(VectorEntry {
        id: Some("example-1".into()),
        vector: vec![1.0, 0.0, 0.0],
        metadata: None,
    })?;

    let hits = db.search(SearchQuery {
        vector: vec![1.0, 0.0, 0.0],
        k: 1,
        filter: None,
        ef_search: None,
    })?;

    assert_eq!(hits[0].id, "example-1");
    println!("Nearest memory: {} (score: {})", hits[0].id, hits[0].score);
    Ok(())
}

cargo run --release

The fixed vector demonstrates insertion and retrieval; supply embeddings for semantic search. Keep Cargo.lock for reproducible dependency resolution. Rust API reference · Current core types · Storage and search implementation.

Contrastive AI spans these groups: learn useful distinctions in System 1, apply them to bounded System 0 decisions, and evaluate their use in System 2 workflows. Representation learning, graph diagnostics, and promotion policy are distinct mechanisms.

Watch rUv's illustrated contrastive AI walkthrough. Contrastive losses do not establish factual truth; graph coherence does not replace task evaluation, access control, or promotion approval. These components require explicit integration and are not all enabled in the default search path.

Choose one outcome, follow its guide, and check the result before adding more components.

The application connects these components. Keep source IDs with retrieved evidence, record the outcome of an action, and evaluate any proposed learning change before retaining it. See contrastive AI for the distinction between representation learning, graph diagnostics, and promotion policy.

Quick start · Memory loop · Limitations · Reproducible benchmarks

The default retrieval path runs locally. Learning happens from recorded outcomes and feedback, not from reads alone. Hosted services remain optional and create a separate data boundary.

@ruvector/typesafe turns text into typed choice, score, and noul decisions using local embeddings and native decision heads, with a WASM fallback. It returns confidence and abstention information, supports labeled examples and evaluation, and can serve a Jev-compatible HTTP API. Use it for bounded tasks such as ticket routing, intent classification, and urgency assessment where a full language model call is unnecessary. The decision engine is a separate package; installing the root ruvector package does not enable it automatically.

On the documented 150-ticket test split, the local ONNX decision engine reports 4–10 ms p95 for its campaign configurations, with 77.3–84.0% department accuracy; the Jev replay reference reports 231 ms p95 and 85.3% accuracy. Those are workload-specific measurements, not a universal speed or quality guarantee. The default hash embedder is a test double and is not calibrated for production decisions. See the typed decision quick start and benchmark details.

The npm quick start stores memory under the current project for later processes. The first semantic command downloads and caches all-MiniLM-L6-v2. Keep one embedding model and dimension per store; use npx ruvector hooks reembed before changing an existing store from hash to semantic embeddings. Inspect it with npx ruvector hooks stats.

npm install ruvector

const { OnnxEmbedder, VectorDB } = require('ruvector');

async function main() {
  const embedder = new OnnxEmbedder();
  await embedder.init();

  const db = new VectorDB({
    dimensions: 384,
    distanceMetric: 'cosine',
    storagePath: './agent-memory.db',
  });

  const memories = [
    {
      id: 'decision-1',
      text: 'The customer requires all inference to remain in Canada.',
      kind: 'decision',
    },
    {
      id: 'episode-1',
      text: 'The Toronto pilot passed its privacy review on Tuesday.',
      kind: 'episode',
    },
    {
      id: 'procedure-1',
      text: 'Escalate production access through the security owner.',
      kind: 'procedure',
    },
  ];

  for (const memory of memories) {
    const vector = await embedder.embedPassage(memory.text);
    await db.insert({
      id: memory.id,
      vector,
      metadata: {
        text: memory.text,
        kind: memory.kind,
        tenant: 'acme',
        createdAt: Date.now(),
      },
    });
  }

  const query = await embedder.embedQuery(
    'Where may the customer data be processed?',
  );

  const results = await db.search({
    vector: query,
    k: 3,
    filter: { tenant: 'acme' },
  });

  console.log(results.map(({ score, metadata }) => ({ score, ...metadata })));
}

main().catch(console.error);

Reopen the same storagePath in another process to recover the stored vectors, metadata, configuration, and searchability. Search score is a distance, so lower values are closer. See the Node.js API and Rust API for the complete interfaces.

Follow the complete Node.js write and reopen tutorial, Python SDK and integration guide, or Rust persistence tutorial. The examples hub groups browser, graph, contrastive learning, runtime, and deployment examples by System 0, 1, and 2.

flowchart TD
    A[Capture an event, fact, or outcome] --> B[Create a local or external embedding]
    B --> C[Persist vectors, metadata, and relationships]
    C --> D[Recall by similarity, filters, time, or graph]
    D --> E[Use memory in an agent decision]
    E --> F[Record outcome and feedback]
    F --> G[Adapt ranking or learning state]
    G --> C
    C --> H[Compact, snapshot, branch, or replicate]

RuVector provides primitives for this loop. Your application remains responsible for deciding what is worth remembering, which evidence is trusted, when a memory expires, and which actions recalled context may influence.

Memory classes are application semantics over vectors, metadata, and graphs. The core store is general purpose. RuVector currently exposes two typed layers:

1. ruvllm::context::AgenticMemory combines working, episodic, semantic, and procedural memory behind one runtime API. It is implemented, but its unified manager is currently in memory and its cross type consolidation method is not complete.

2. ruvector-core::AgenticDB persists Reflexion episodes, skills, causal edges, learning sessions, policy state, session turns, and a hash linked witness log. Its typed memory APIs support ONNX, Candle, and API embedding providers for semantic retrieval.