Architecture Decision Records
This directory contains Architecture Decision Records (ADRs) for ruvector's core technical decisions.
Decision Index
| ADR |
Title |
Status |
Summary |
| ADR-001 |
Core SIMD Optimization Strategy |
Accepted |
AVX-512/AVX2/NEON with runtime detection for 2.5x-18x speedup |
| ADR-002 |
Hyperbolic Embeddings for Hierarchical Data |
Accepted |
Poincare ball model for low-distortion tree embeddings |
| ADR-003 |
MCP Server Architecture and Transport |
Accepted |
JSON-RPC 2.0 over stdio/SSE/WebSocket for AI agent integration |
| ADR-004 |
RVF Cognitive Container Format |
Accepted |
Self-describing vector format with WASM kernels |
| ADR-005 |
Cross-Platform Bindings (WASM + NAPI-RS) |
Accepted |
WASM-first with native acceleration via NAPI-RS |
| ADR-006 |
SONA Self-Optimizing Architecture |
Accepted |
Online learning for automatic parameter tuning |
| ADR-007 |
Differential Privacy and Epsilon-Budget |
Accepted |
Privacy budget management for collective learning |
| ADR-008 |
Flash Attention Implementation |
Accepted |
Memory-efficient O(N) attention with block-sparse patterns |
ADR Template
When creating new ADRs, use this structure:
# ADR-XXX: Title
| Field | Value |
|-------|-------|
| **Status** | Proposed / Accepted / Deprecated / Superseded |
| **Date** | YYYY-MM-DD |
| **Authors** | Names |
| **Reviewers** | Names |
| **Supersedes** | ADR-XXX (if applicable) |
| **Related** | ADR-XXX, ADR-YYY |
## 1. Context
[Problem statement and background]
## 2. Decision
[The decision and its justification]
## 3. Rationale
[Why this decision over alternatives]
## 4. Consequences
[Benefits, costs, and tradeoffs]
## 5. Implementation
[Key implementation details]
## 6. Related Decisions
[Links to related ADRs]
## 7. References
[External references]
## 8. Revision History
[Change log]
Decision Categories
Core Performance
- ADR-001: SIMD optimization strategy (AVX-512/AVX2/NEON)
- ADR-008: Flash Attention for LLM inference
Data Representation
- ADR-002: Hyperbolic embeddings (Poincare ball model)
- ADR-004: RVF cognitive container format
System Architecture
- ADR-003: MCP protocol and transport choices
- ADR-005: Cross-platform bindings (WASM + NAPI-RS)
- ADR-006: SONA self-optimization
- ADR-007: Differential privacy architecture
Quick Reference
| Topic |
ADR |
Key Decision |
| Vector distance |
ADR-001 |
Hand-optimized SIMD for 2.5-18x speedup |
| Hierarchical data |
ADR-002 |
Poincare ball embeddings with c=1.0 default |
| AI agent protocol |
ADR-003 |
MCP with stdio (local) and SSE (remote) |
| File format |
ADR-004 |
RVF with 15 segment types, ML-DSA-65 signatures |
| Node.js bindings |
ADR-005 |
NAPI-RS native with WASM fallback |
| Self-optimization |
ADR-006 |
Temperature tracking, pattern learning, adaptive ef |
| Privacy |
ADR-007 |
Gaussian mechanism, epsilon-budget, PII stripping |
| Long context |
ADR-008 |
Flash Attention with 128K+ support |
Related Documentation
For more detailed ADRs, see the main /docs/adr/ directory which contains:
- ADR-001 through ADR-088+ covering specific implementation decisions
- Coherence Engine ADRs in
/docs/adr/coherence-engine/
- Project-specific ADRs in various crate directories
Status Definitions
| Status |
Meaning |
| Proposed |
Under discussion, not yet implemented |
| Accepted |
Decision made, implementation in progress or complete |
| Deprecated |
No longer recommended, retained for history |
| Superseded |
Replaced by a newer ADR |
Implementation Status
| ADR |
Crate |
Status |
| ADR-001 |
ruvector-core |
Complete |
| ADR-002 |
ruvector-core, ruvector-hyperbolic-hnsw |
Complete |
| ADR-003 |
mcp-brain, ruvector-cli |
Complete |
| ADR-004 |
rvf, rvf-kernel |
Complete |
| ADR-005 |
ruvector-wasm, ruvector-node |
Complete |
| ADR-006 |
ruvector-core |
Complete |
| ADR-007 |
pi-brain |
Complete |
| ADR-008 |
ruvllm |
Complete |
a2326c0449