RuVector: a Rust memory substrate for agents that need to remember across sessions

The problem RuVector targets: memory that survives the session boundary

Most agent stacks treat memory as a prompt trick. You paste prior turns into the context window, and when the process exits, the state is gone. RuVector takes the opposite position: memory is a substrate you write to and read from, stored under the current project and available to later processes. The README frames the project as a "Rust native memory substrate for agents that need to remember across sessions," and the two-command example is built around that claim. You record a decision, then later ask a question in natural language and get the decision back.

The intended audience is narrow. This is for people building agents that accumulate state over days or weeks: decisions, episodes, procedures, outcomes. It is not a general analytics warehouse and it is not trying to be a hosted service. The README is explicit that the default retrieval path runs locally, that hosted services remain optional, and that using them creates a separate data boundary. If your data cannot leave the machine, that sentence is the whole pitch.

The other half of the design is that learning comes from recorded outcomes and feedback, not from reads. That distinction matters because it rules out a common expectation. A vector database that only counts queries will not improve; RuVector wants you to write back what happened.

How the recall loop actually works

The README publishes a flowchart of the memory loop, and it is worth reading as an architecture statement rather than a diagram. An event, fact or outcome is captured. An embedding is created locally or externally. Vectors, metadata and relationships are persisted. Recall happens by similarity, filters, time or graph. The recalled context feeds an agent decision. The outcome and feedback are recorded. Ranking or learning state adapts. Then the loop returns to persistence, with a side branch to compact, snapshot, branch or replicate.

The important structural detail is that the cycle closes on the store, not on the model. Adaptation changes ranking or learning state, which is a property of the index. Nothing in the diagram implies retraining a language model.

The storage layer itself is conventional. In the Node.js example, a VectorDB is constructed with dimensions: 384, distanceMetric: 'cosine' and a storagePath. Documents are inserted with an id, a vector and a metadata object. Search takes a vector, a k and a filter. The README notes that search score is a distance, so lower values are closer. That is a small sentence with real consequences: if you sort descending out of habit, you will get the worst matches first.

Above the raw store sit typed layers. ruvector-core::AgenticDB persists Reflexion episodes, skills, causal edges, learning sessions, policy state, session turns and a hash linked witness log. ruvllm::context::AgenticMemory puts working, episodic, semantic and procedural memory behind one runtime API. The README states plainly that the latter is implemented but its unified manager is currently in memory and its cross type consolidation method is not complete. Read that as a warning label, not a footnote.

Installing RuVector and running a first recall

The fastest path needs no database server and no API key. The CLI ships through npm, so npx will fetch it on first use. The first semantic command downloads and caches the local all-MiniLM-L6-v2 model, which means the initial run is slower than later ones and needs network access once.

npx ruvector hooks remember --semantic --type decision \
  "The customer requires all inference to remain in Canada."

That writes one memory of type decision into the store for the current project. Then recall it by asking a question in ordinary language rather than by matching a keyword.

npx ruvector hooks recall --semantic --top-k 3 \
  "Where may customer data be processed?"

You should get the Canadian inference decision among the top results, because the embedding places the question near the stored sentence. Run npx ruvector hooks stats to inspect the store and confirm what landed.

For programmatic use, install the package and drive the embedder and store directly. The README example constructs an OnnxEmbedder, initializes it, opens a VectorDB at ./agent-memory.db with 384 dimensions and cosine distance, then inserts three memories with kinds decision, episode and procedure. It embeds passages with embedPassage and the query with embedQuery, then searches with a tenant filter. Reopening the same storagePath in another process recovers the vectors, metadata, configuration and searchability. Note the asymmetry in the API: passages and queries use different embedding methods, which is standard for retrieval models but easy to get wrong.

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('Escalate production access through the security owner.');
await db.insert({ id: 'procedure-1', vector, metadata: { kind: 'procedure', tenant: 'acme' } });

Building from source is a different exercise. The root package.json exposes npm run build, npm run build:node, npm run build:wasm and npm run build:graph, and the CLI through cargo run -p ruvector-cli. Expect the workspace build to be the long pole.

Where RuVector gets in your way

The embedding model and dimension are effectively a schema decision you make on day one and regret later. The README warns to keep one embedding model and dimension per store, and to run npx ruvector hooks reembed before changing an existing store from hash to semantic embeddings. That is a migration step, not a config toggle, and the README does not document rollback if reembedding goes wrong.

The typed memory situation is the sharper limitation. Two layers are exposed, and they do not have the same maturity. ruvllm::context::AgenticMemory has an in-memory unified manager and an incomplete cross type consolidation method, per the README. If your design assumes that working, episodic, semantic and procedural memory consolidate automatically, you are building on the part the project says is unfinished. The persisted option is ruvector-core::AgenticDB, which is a different API with a different set of guarantees.

Scope is also a constraint. The README states that RuVector provides primitives for the loop and that 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. There is no opinionated retention policy handed to you. If you wanted a system that decides what to forget, this is the wrong tool.

Finally, the repository layout signals that not everything builds by default. The workspace Cargo.toml excludes crates including ruvector-postgres, rvf, mcp-brain-server, sonic-ct and ruos-thermal, with comments explaining that some are standalone workspaces and that the pgrx-based Postgres extension needs cargo-pgrx and cargo pgrx init. A clean cargo build --workspace does not mean every crate in the tree compiled.

RuVector compared with a plain vector database

The obvious alternative is a general purpose vector database, and the honest difference is not speed. It is what the project expects you to store.

A plain vector store gives you collections, upserts and similarity search, and stops there. You bring your own schema, your own notion of what a record means, and your own feedback loop, if any. RuVector keeps the same primitive underneath (a VectorDB with dimensions, a distance metric, a storage path, metadata filters) but ships opinions on top: memory classes mapped to concrete types, a Reflexion episode shape with task, action, observation, critique and outcome, procedural skills with triggers and Q values, causal edges queryable through Cypher paths, and a hash linked witness log for auditability.

That is more surface area and more to learn. The trade is that the shapes you would otherwise invent are already named. If you are building a Reflexion-style agent, the episode type is a head start. If you are building a product search index, all of that vocabulary is dead weight and a plain vector store will be simpler to operate.

The graph side is the other real difference. ruvector-graph exposes nodes, edges, hyperedges and Cypher paths, and the root package.json has separate build targets for the graph Node and WASM bindings plus example scripts for cypher queries and hybrid search. A vector-only store cannot answer a path question; RuVector treats graph traversal as a first class recall mode alongside similarity, filters and time.

Maintenance, licence and what upgrading costs

The repository is not archived, and the last push was on 2026-09-15. The most recent release listed is ruvector-v0.2.40 on 2026-07-29, tagged "MetaHarness, Darwin, and Flywheel," with a security package refresh and rvf-v0.3.4 both on 2026-07-28. The npm package version in the repository's package.json is 0.1.2, which does not match the release tag, and the README's own version badges point at crates.io and npm. If you pin a version, check the registry rather than the repository file.

Upgrade cost is dominated by two things: the embedding model and dimension per store, and the excluded crates. Changing the model means running npx ruvector hooks reembed against existing data. The excluded crate list in Cargo.toml also carries comments describing work still in progress, including ruos-thermal as a "Pi 5 thermal supervisor skeleton" that joins the workspace once daemon mode and a Unix socket protocol land. Treat the workspace boundary as a stability signal about which parts are meant to build together.

Licence is MIT, per the README badge and the LICENSE file at the repository root. MIT is permissive: it allows commercial use and modification with the copyright notice and permission notice retained, and it comes with no warranty. That last clause is the one that matters for a store holding agent state. Nothing here is legal advice; if you are embedding RuVector in a product, have your own counsel read the LICENSE file rather than a badge.

Editorial conclusion

Adopt RuVector if you want agent memory that stays on the machine, runs without a server or API key, and persists to a single file you can reopen in another process. Do not adopt it if you need a mature, uniformly finished typed memory API: the README states that ruvllm's unified manager is in memory and its cross type consolidation is incomplete, and the repository's own Cargo.toml keeps several crates out of the default workspace. Verify two things first: that the MiniLM download and cache work in your environment, and that your existing store was created with the embedding model and dimension you intend to keep, because switching from hash to semantic embeddings requires npx ruvector hooks reembed.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. ruvnet/RuVector on GitHub