# RuVector

> A Rust vector store built as persistent memory for agents

- Category: Retrieval & Knowledge (RAG) / Vector Databases
- Language: Rust
- Licence: MIT
- Repository: https://github.com/ruvnet/RuVector
- Website: https://cognitum.one/ruvector
- Canonical page: https://ai-tldr.dev/tools/ruvector/

## In short

RuVector is a vector store written in Rust and aimed squarely at one job: giving an agent memory that survives between sessions. It sits in the Vector Databases category of the Retrieval & Knowledge (RAG) tools and is open-source, written in Rust and licensed MIT. To get started: remember and recall from the shell.

## Overview

RuVector is a vector store written in Rust and aimed squarely at one job: giving an agent memory that survives between sessions. It combines local semantic embeddings, persistent vector retrieval, graph relationships between records, explicit feedback learning and memory lifecycle controls in a single embeddable library rather than a server you have to operate.

The default retrieval path runs entirely on the local machine. The first semantic command downloads and caches an all-MiniLM-L6-v2 model, so there is no database server to start and no API key to configure; hosted services are optional and, as the project puts it, create a separate data boundary. Learning is driven by recorded outcomes and feedback rather than by reads alone.

Three interfaces sit on the same core: a Rust crate (ruvector-core), a Node.js package with an OnnxEmbedder and VectorDB class, and an npx-runnable CLI whose hooks subcommands remember and recall directly from the shell. Storage is a file you point at, and reopening the same path recovers the vectors, metadata, configuration and searchability. The project is MIT-licensed.

## What it does

- Local semantic embeddings from a bundled ONNX all-MiniLM-L6-v2 model, cached on first use — no embedding API required
- Persistent on-disk store: reopen the same path in another process and vectors, metadata and configuration come back
- Metadata filters and graph relationships alongside plain similarity search, so recall can be scoped by tenant, kind or time
- Feedback learning that adapts ranking from recorded outcomes rather than from reads
- Three surfaces over one engine — Rust crate, Node.js package and an npx CLI with remember/recall hooks
- Memory lifecycle controls and optional shared memory for multi-agent setups

## Getting started

Nothing needs to be installed or provisioned to try it: the CLI runs through npx and needs no database server or API key.

1. Remember and recall from the shell

   The first semantic command downloads and caches the local embedding model. Memory is stored under the current project and stays available to later processes.

```bash
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?"
```

2. Inspect the store

   Keep one embedding model and dimension per store; run reembed before switching an existing store from hash to semantic embeddings.

```bash
npx ruvector hooks stats
```

3. Embed it in Node.js

   Initialise the embedder, open a VectorDB at a storage path, insert vectors with metadata, then search with a filter. Scores are distances, so lower is closer.

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

const embedder = new OnnxEmbedder();
await embedder.init();

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

const vector = await embedder.embedPassage('The Toronto pilot passed its privacy review on Tuesday.');
await db.insert({ id: 'episode-1', vector, metadata: { tenant: 'acme' } });

const query = await embedder.embedQuery('Where may the customer data be processed?');
const results = await db.search({ vector: query, k: 3, filter: { tenant: 'acme' } });
```

## When to use it

- Add cross-session memory to a coding agent without standing up a vector database service
- Keep embeddings and recall entirely on the local machine when the data cannot leave it
- Store decisions, episodes and procedures as typed records and retrieve them by similarity plus metadata filters
- Build a Rust agent that needs an embedded vector index rather than a network hop per query