# ruvnet/ruvector architecture

> Architecture diagram of the GitHub repository ruvnet/ruvector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ruvnet/ruvector
- Repository: https://github.com/ruvnet/ruvector

## Overview

RuVector is a Rust-centered substrate for local vector retrieval and persistent AI-agent memory, with Node.js and CLI surfaces. Its documented memory loop captures and embeds information, persists vectors and relationships, recalls relevant context, and uses outcomes for learning; memory lifecycle and shared-memory features extend that loop. The graph preserves major documented capabilities, including graph retrieval, SONA learning, and shared memory. Source excerpts are limited, so documented links cite the README; the CLI storage implementation and core storage behavior are the sampled source details.

Main entry points: [`crates/ruvector-core/src/storage.rs`](https://github.com/ruvnet/ruvector/blob/main/crates/ruvector-core/src/storage.rs) (Vector store), [`crates/ruvector-core`](https://github.com/ruvnet/ruvector/tree/main/crates/ruvector-core) (Embedding providers), [`npm/packages/cli/src/storage.ts`](https://github.com/ruvnet/ruvector/blob/main/npm/packages/cli/src/storage.ts) (Memory CLI), [`crates/ruvector-typesafe-core/src/engine.rs`](https://github.com/ruvnet/ruvector/blob/main/crates/ruvector-typesafe-core/src/engine.rs) (Typed decisions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and encoding"]
  node_embed["Embedding providers"]
  node_decision["Typed decisions<br/>[engine.rs]"]
end

subgraph group_memory["Memory and retrieval"]
  node_vector[("Vector store<br/>[storage.rs]")]
  node_graph[("Graph relationships<br/>[storage.rs]")]
  node_recall["Similarity retrieval"]
  node_agentmem["Typed agent memory"]
end

subgraph group_learning["Learning and lifecycle"]
  node_outcomes["Outcome feedback<br/>[engine.rs]"]
  node_sona["SONA learning<br/>[engine.rs]"]
  node_lifecycle["Memory lifecycle"]
  node_shared["Shared memory<br/>[pipeline.rs]"]
end

subgraph group_interfaces["User interfaces"]
  node_cli["Memory CLI<br/>[storage.ts]"]
  node_nodeapi["Node.js API"]
end

node_agent(("Agent or user"))
node_context(("Agent decision"))

node_agent -->|"captures"| node_cli
node_agent -->|"uses"| node_nodeapi
node_cli -->|"encodes text"| node_embed
node_nodeapi -->|"encodes text"| node_embed
node_embed -->|"produces vectors"| node_vector
node_cli -->|"persists memories"| node_vector
node_nodeapi -->|"inserts vectors"| node_vector
node_vector -->|"searches vectors"| node_recall
node_graph -->|"supports graph search"| node_recall
node_recall -->|"returns context"| node_context
node_context -->|"records outcomes"| node_outcomes
node_outcomes -->|"trains from feedback"| node_sona
node_sona -->|"adapts ranking"| node_vector
node_vector -->|"snapshots or compacts"| node_lifecycle
node_vector -->|"persists typed memory"| node_agentmem
node_agentmem -->|"uses providers"| node_embed
node_agent -->|"requests decision"| node_decision
node_decision -->|"embeds inputs"| node_embed
node_agentmem -.->|"contributes memory"| node_shared

click node_cli "https://github.com/ruvnet/ruvector/blob/main/npm/packages/cli/src/storage.ts"
click node_nodeapi "https://github.com/ruvnet/ruvector/tree/main/crates/ruvector-core"
click node_embed "https://github.com/ruvnet/ruvector/tree/main/crates/ruvector-core"
click node_decision "https://github.com/ruvnet/ruvector/blob/main/crates/ruvector-typesafe-core/src/engine.rs"
click node_vector "https://github.com/ruvnet/ruvector/blob/main/crates/ruvector-core/src/storage.rs"
click node_graph "https://github.com/ruvnet/ruvector/blob/main/crates/ruvector-graph/src/storage.rs"
click node_recall "https://github.com/ruvnet/ruvector/tree/main/crates/ruvector-core"
click node_agentmem "https://github.com/ruvnet/ruvector/tree/main/crates/ruvector-core"
click node_outcomes "https://github.com/ruvnet/ruvector/blob/main/crates/sona/src/engine.rs"
click node_sona "https://github.com/ruvnet/ruvector/blob/main/crates/sona/src/engine.rs"
click node_lifecycle "https://github.com/ruvnet/ruvector/tree/main/crates/ruvector-snapshot"
click node_shared "https://github.com/ruvnet/ruvector/blob/main/crates/mcp-brain/src/pipeline.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_embed,node_decision,node_agent toneBlue
class node_vector,node_graph,node_recall,node_agentmem toneAmber
class node_outcomes,node_sona,node_lifecycle,node_shared toneMint
class node_cli,node_nodeapi toneRose
class node_context toneIndigo
```

## Components

### Capture and encoding

- [Embedding providers](https://github.com/ruvnet/ruvector/tree/main/crates/ruvector-core): `crates/ruvector-core`
- [Typed decisions](https://github.com/ruvnet/ruvector/blob/main/crates/ruvector-typesafe-core/src/engine.rs): `crates/ruvector-typesafe-core/src/engine.rs`

### Memory and retrieval

- [Vector store](https://github.com/ruvnet/ruvector/blob/main/crates/ruvector-core/src/storage.rs): `crates/ruvector-core/src/storage.rs`
- [Graph relationships](https://github.com/ruvnet/ruvector/blob/main/crates/ruvector-graph/src/storage.rs): `crates/ruvector-graph/src/storage.rs`
- [Similarity retrieval](https://github.com/ruvnet/ruvector/tree/main/crates/ruvector-core): `crates/ruvector-core`
- [Typed agent memory](https://github.com/ruvnet/ruvector/tree/main/crates/ruvector-core): `crates/ruvector-core`

### Learning and lifecycle

- [Outcome feedback](https://github.com/ruvnet/ruvector/blob/main/crates/sona/src/engine.rs): `crates/sona/src/engine.rs`
- [SONA learning](https://github.com/ruvnet/ruvector/blob/main/crates/sona/src/engine.rs): `crates/sona/src/engine.rs`
- [Memory lifecycle](https://github.com/ruvnet/ruvector/tree/main/crates/ruvector-snapshot): `crates/ruvector-snapshot`
- [Shared memory](https://github.com/ruvnet/ruvector/blob/main/crates/mcp-brain/src/pipeline.rs): `crates/mcp-brain/src/pipeline.rs`

### User interfaces

- [Memory CLI](https://github.com/ruvnet/ruvector/blob/main/npm/packages/cli/src/storage.ts): `npm/packages/cli/src/storage.ts`
- [Node.js API](https://github.com/ruvnet/ruvector/tree/main/crates/ruvector-core): `crates/ruvector-core`

### Other components

- **Agent or user**
- **Agent decision**

## Connections

- Agent or user → Memory CLI: captures (evidence: `README.md`)
- Agent or user → Node.js API: uses (evidence: `README.md`)
- Memory CLI → Embedding providers: encodes text (evidence: `README.md`)
- Node.js API → Embedding providers: encodes text (evidence: `README.md`)
- Embedding providers → Vector store: produces vectors (evidence: `README.md`)
- Memory CLI → Vector store: persists memories (evidence: `README.md`)
- Node.js API → Vector store: inserts vectors (evidence: `README.md`)
- Vector store → Similarity retrieval: searches vectors (evidence: `README.md`)
- Graph relationships → Similarity retrieval: supports graph search (evidence: `README.md`)
- Similarity retrieval → Agent decision: returns context (evidence: `README.md`)
- Agent decision → Outcome feedback: records outcomes (evidence: `README.md`)
- Outcome feedback → SONA learning: trains from feedback (evidence: `README.md`)
- SONA learning → Vector store: adapts ranking (evidence: `README.md`)
- Vector store → Memory lifecycle: snapshots or compacts (evidence: `README.md`)
- Vector store → Typed agent memory: persists typed memory (evidence: `README.md`)
- Typed agent memory → Embedding providers: uses providers (evidence: `README.md`)
- Agent or user → Typed decisions: requests decision (evidence: `README.md`)
- Typed decisions → Embedding providers: embeds inputs (evidence: `README.md`)
- Typed agent memory → Shared memory: contributes memory (evidence: `README.md`)
