RuVector

Persistent, adaptive memory for AI agents

RuVector is a Rust native memory substrate for agents that need to remember across sessions. It combines local semantic embeddings, persistent vector retrieval, graph relationships, explicit feedback learning, memory lifecycle controls, and optional shared memory.

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.

Remember and recall in 30 seconds

No database server or API key is required.

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

Memory is stored under the current project and remains available to later processes. The first semantic command downloads and caches the local all-MiniLM-L6-v2 model. Keep one embedding model and dimension per store; use npx ruvector hooks reembed before changing an existing store from hash to semantic embeddings. Use npx ruvector hooks stats to inspect the store.

Embed persistent memory in Node.js

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.

The memory loop

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.

What memory means in RuVector

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.

| Memory class | Representation | RuVector surface | | --- | --- | --- | | Working and session | Current task, scratchpad, tool cache, turns, namespace, TTL | WorkingMemory, SessionStateIndex | | Episodic and Reflexion | Trajectory, task, action, observation, critique, outcome | EpisodicMemory, ReflexionEpisode | | Semantic | Facts, confidence, source, tags, relations, collection | VectorDB, SemanticFact | | Procedural | Skills, actions, triggers, examples, policies, Q values | ProceduralSkill, PolicyMemoryStore | | Causal and relational | Nodes, edges, hyperedges, Cypher paths | ruvector-graph | | Learning | Trajectories, rewards, adapters, EWC state | SONA | | Shared | Contributions, provenance, voting, transfer | mcp-brain | | Auditable | Hash linked entries, snapshots, RVF witnesses | WitnessLog, ruvector-snapshot, RVF |

Capability map

Capture and encode

| Capability | What it enables | Surface | | --- | --- | --- | | Local semantic embeddings | Text memory without a per query API fee | OnnxEmbedder | | External embeddings | Bring an existing embedding model or provider | EmbeddingProvider | | Embedding provenance | Track model, dimension, normalization, and query or passage role | ADR 210 | | Batch and parallel embedding | Higher throughput during memory ingestion | ONNX implementation |

Persist and organize

| Capability | What it enables | Surface | | --- | --- | --- | | Durable vector storage | Vectors, metadata, deletes, and restart recovery | ruvector-core | | Unified four type runtime memory | Working, episodic, semantic, and procedural recall | AgenticMemory | | Typed persistent agent records | Reflexion episodes, skills, causal edges, policy state, sessions, and witness logs | AgenticDB | | HNSW and flat indexes | Approximate or exact local similarity search | ruvector-core | | Collections and aliases | Separate schemas and namespaces by workload | ruvector-collections | | Graph and hypergraph storage | Explicit relationships and multi-hop memory | ruvector-graph | | High write ingestion | Mutable L0 memory plus background L1 and L2 compaction | ruvector-lsm-ann | | Edge and embedded persistence | Lightweight local vector storage through the RVF Core Profile | rvlite | | PostgreSQL extension | Keep vector memory beside relational data | ruvector-postgres |

Recall and reconstruct

| Capability | Best use | Surface | | --- | --- | --- | | Dense similarity | General semantic recall | VectorDB::search | | Metadata filtering | Simple structured narrowing | SearchQuery | | Sparse and dense fusion | Exact terms plus semantic meaning | ruvector-hybrid, ADR 256 | | Predicate aware ANN | Selective filters without post filter recall collapse | ruvector-acorn | | Temporal decay | Prefer recent memories when the domain changes | ruvector-temporal-coherence, ADR 211 | | Coherence gating | Prefer memories supported by related observations | ruvector-temporal-coherence | | Graph reconstruction | Follow Cue, Tag, and Content associations instead of retrieving one flat chunk | MRAgent example, ADR 269 | | Multi-vector MaxSim | Late interaction over token or passage vectors | ruvector-maxsim, ADR 252 | | GNN reranking | Rerank a noisy candidate graph | ruvector-gnn-rerank, ADR 194 | | Matryoshka funnel | Coarse to fine se