mirror of
https://github.com/ruvnet/RuVector.git
synced 2026-05-25 06:36:37 +00:00
757f4fa226
- ADR-154: embodied connectome runtime on RuVector (graph-native,
structural coherence analysis, counterfactual cuts, auditable).
Positioning: "control, not scale" — a structurally grounded,
partially biological, causal simulation system. Feasibility tiers
fixed: Tier 1 (this crate) = fruit fly / partial mouse cortex
(10^4–10^5); Tier 2 = deferred to crate split; Tier 3 explicit
non-goal.
- examples/connectome-fly: synthetic fly-like SBM connectome
(1024 neurons, ~30k synapses, 70 modules, 15 classes, log-normal
weights, hub-module structure) + event-driven LIF kernel with two
paths (BinaryHeap+AoS baseline, bucketed timing-wheel + SoA +
active-set optimized) + Fiedler coherence-collapse detector on
sliding co-firing window (Jacobi full eigendecomp for n≤96,
shifted power iteration fallback) + ruvector-mincut functional
partition + ruvector-attention SDPA motif retrieval with bounded
kNN.
- Acceptance criteria (ADR-154 §3.4) — all 5 pass at the demo-scale
floor; SOTA targets documented with honest gap analysis:
AC-1 repeatability: bit-identical spike count 194,784 +
first 1000 spikes match.
AC-2 motif emergence: precision@5 proxy = 0.600 (SOTA 0.80).
AC-3 partition alignment: class_hist L1 = 1.545; mincut ARI ≈ 0
vs greedy baseline 0.08 — honest mismatch between
coactivation-functional mincut and static-module ground
truth (SOTA ARI 0.75 is for the production static path).
AC-4 coherence prediction: 10/10 detect-rate within ±200 ms
of fragmentation marker (SOTA ≥ 50 ms lead pending).
AC-5 causal perturbation: z_cut = 5.55, z_rand = 1.57 —
targeted-cut effect HITS the SOTA 5σ bound; random-cut
is 0.57σ above the 1σ bound. Core differentiating claim
holds at demo scale.
- Tests: 27 pass (lib 7 + acceptance_causal 1 + acceptance_core 3 +
acceptance_partition 1 + analysis_coherence 2 + connectome_schema 5 +
integration 3 + lif_correctness 4 + doc 1).
- Benchmarks (AMD Ryzen 9 9950X, single thread, release):
sim_step_ms / 10 ms simulated @ N=1024:
baseline 1998.6 µs (±17.1)
optimized 511.6 µs (±2.1) → 3.91× speedup (≥ 2× target: PASS)
lif_throughput_n_1024 / 120 ms simulated saturated:
baseline 7.49 s, optimized 7.39 s → 1.01× (active-set collapses
in saturated regime; documented in BENCHMARK.md §4.4).
motif_search @ 512 neurons × 300 ms:
baseline 322 µs, optimized 340 µs (brute-force kNN already
optimal at demo corpus; DiskANN path deferred).
- BENCHMARK.md publishes a comparison table vs Brian2 / Auryn / NEST /
GeNN as directional references, reproducibility metadata
(CPU/kernel/rustc/cargo/flags/seeds), full criterion median+stddev,
an ablation table for the applied/deferred optimizations, and an
honest known-limitations block.
- Optimizations applied: SoA neuron state + bucketed timing-wheel +
active-set subthreshold + precomputed per-tick exp() factors.
Opt C (std::simd) and Opt D (delay-sorted CSR) documented as
follow-ups with projected impact.
- File-size discipline: every source file < 500 lines (largest:
lif/engine.rs at 348). Source LOC: 2772; tests 816; benches 213.
- Rust only. No MuJoCo / NeuroMechFly bindings. No consciousness /
upload / digital-person language. No modifications to existing
crates — only the workspace Cargo.toml members list is extended
to include the new example.
Do NOT push.
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|---|---|---|
| .. | ||
| adr | ||
| analysis | ||
| api | ||
| architecture | ||
| benchmarks | ||
| cloud-architecture | ||
| cnn | ||
| code-reviews | ||
| dag | ||
| development | ||
| examples | ||
| gnn | ||
| guides | ||
| hnsw | ||
| hooks | ||
| implementation | ||
| integration | ||
| nervous-system | ||
| optimization | ||
| plans/subpolynomial-time-mincut | ||
| postgres | ||
| project-phases | ||
| publishing | ||
| research | ||
| reviews | ||
| ruvllm | ||
| rvagent | ||
| security | ||
| sparse-inference | ||
| sql | ||
| testing | ||
| training | ||
| .gitkeep | ||
| .nojekyll | ||
| agi-container.md | ||
| C2-shell-execution-hardening.md | ||
| C8_RESULT_VALIDATION_IMPLEMENTATION.md | ||
| consciousness-api.md | ||
| IMPLEMENTATION-C5.md | ||
| index.html | ||
| INDEX.md | ||
| moe-routing-optimization-analysis.md | ||
| README.md | ||
| REPO_STRUCTURE.md | ||
| research-openfang.md | ||
RuVector Documentation
Complete documentation for RuVector, the high-performance Rust vector database with global scale capabilities.
📚 Documentation Structure
docs/
├── adr/ # Architecture Decision Records
├── analysis/ # Research & analysis docs
├── api/ # API references (Rust, Node.js, Cypher)
├── architecture/ # System design docs
├── benchmarks/ # Performance benchmarks & results
├── cloud-architecture/ # Cloud deployment guides
├── code-reviews/ # Code review documentation
├── dag/ # DAG implementation
├── development/ # Developer guides
├── examples/ # SQL examples
├── gnn/ # GNN/Graph implementation
├── guides/ # User guides & tutorials
├── hnsw/ # HNSW index documentation
├── hooks/ # Hooks system documentation
├── implementation/ # Implementation details & summaries
├── integration/ # Integration guides
├── nervous-system/ # Nervous system architecture
├── optimization/ # Performance optimization guides
├── plans/ # Implementation plans
├── postgres/ # PostgreSQL extension docs
├── project-phases/ # Development phases
├── publishing/ # NPM publishing guides
├── research/ # Research documentation
├── ruvllm/ # RuVLLM documentation
├── security/ # Security audits & reports
├── sparse-inference/ # Sparse inference docs
├── sql/ # SQL examples
├── testing/ # Testing documentation
└── training/ # Training & LoRA docs
Getting Started
- guides/GETTING_STARTED.md - Getting started guide
- guides/BASIC_TUTORIAL.md - Basic tutorial
- guides/INSTALLATION.md - Installation instructions
- guides/AGENTICDB_QUICKSTART.md - AgenticDB quick start
- guides/wasm-api.md - WebAssembly API documentation
Architecture & Design
- architecture/ - System architecture details
- cloud-architecture/ - Global cloud deployment
- adr/ - Architecture Decision Records
- nervous-system/ - Nervous system architecture
API Reference
- api/RUST_API.md - Rust API reference
- api/NODEJS_API.md - Node.js API reference
- api/CYPHER_REFERENCE.md - Cypher query reference
Performance & Benchmarks
- benchmarks/ - Performance benchmarks & results
- optimization/ - Performance optimization guides
- analysis/ - Research & analysis docs
Security
- security/ - Security audits & reports
Implementation
- implementation/ - Implementation details & summaries
- integration/ - Integration guides
- code-reviews/ - Code review documentation
Specialized Topics
- gnn/ - GNN/Graph implementation
- hnsw/ - HNSW index documentation
- postgres/ - PostgreSQL extension docs
- ruvllm/ - RuVLLM documentation
- training/ - Training & LoRA docs
Development
- development/CONTRIBUTING.md - Contribution guidelines
- development/MIGRATION.md - Migration guide
- testing/ - Testing documentation
- publishing/ - NPM publishing guides
Research
- research/ - Research documentation
- cognitive-frontier/ - Cognitive frontier research
- gnn-v2/ - GNN v2 research
- latent-space/ - HNSW & attention research
- mincut/ - MinCut algorithm research
🚀 Quick Links
For New Users
- Start with Getting Started Guide
- Try the Basic Tutorial
- Review API Documentation
For Cloud Deployment
- Read Architecture Overview
- Follow Deployment Guide
- Apply Performance Optimizations
For Contributors
- Read Contributing Guidelines
- Review Architecture Decisions
- Check Migration Guide
For Performance Tuning
- Review Optimization Guide
- Run Benchmarks
- Check Analysis
📊 Documentation Status
| Category | Directory | Status |
|---|---|---|
| Getting Started | guides/ | ✅ Complete |
| Architecture | architecture/, adr/ | ✅ Complete |
| API Reference | api/ | ✅ Complete |
| Performance | benchmarks/, optimization/, analysis/ | ✅ Complete |
| Security | security/ | ✅ Complete |
| Implementation | implementation/, integration/ | ✅ Complete |
| Development | development/, testing/ | ✅ Complete |
| Research | research/ | 📚 Ongoing |
Total Documentation: 460+ documents across 60+ directories
🔗 External Resources
- GitHub Repository: https://github.com/ruvnet/ruvector
- Main README: ../README.md
- Changelog: ../CHANGELOG.md
- License: ../LICENSE
Last Updated: 2026-02-26 | Version: 2.0.4 (core) / 0.1.100 (npm) | Status: Production Ready