8.3 KiB
AgentDB Simulation Quick Start Guide
Reading Time: 5 minutes Prerequisites: Node.js 18+, npm or yarn Target Audience: New users
Get up and running with AgentDB simulations in 5 minutes. This guide covers installation, running your first simulation, and understanding the results.
🚀 Installation
Option 1: Global Installation (Recommended)
npm install -g agentdb
agentdb --version
Option 2: Local Development
git clone https://github.com/ruvnet/agentic-flow.git
cd agentic-flow/packages/agentdb
npm install
npm run build
npm link
Verify Installation
agentdb simulate --help
You should see the simulation command help with available scenarios.
🎯 Run Your First Simulation (3 Methods)
Method 1: Interactive Wizard (Easiest) ⭐
The wizard guides you through simulation creation step-by-step:
agentdb simulate --wizard
What you'll see:
🧙 AgentDB Simulation Wizard
? What would you like to do?
❯ 🎯 Run validated scenario (recommended)
🔧 Build custom simulation
📊 View past reports
? Choose a simulation scenario:
❯ ⚡ HNSW Exploration (8.2x speedup)
🧠 Attention Analysis (12.4% improvement)
🎯 Traversal Optimization (96.8% recall)
🔄 Self-Organizing (97.9% uptime)
...
? Number of nodes: 100000
? Vector dimensions: 384
? Number of runs (for coherence): 3
? Use optimal validated configuration? Yes
📋 Simulation Configuration:
Scenario: hnsw
Nodes: 100,000
Dimensions: 384
Iterations: 3
✅ Using optimal validated parameters
? Start simulation? Yes
🚀 Running simulation...
Method 2: Quick Command (Fastest)
Run a validated scenario with optimal defaults:
agentdb simulate hnsw --iterations 3
What happens:
- Executes HNSW graph topology simulation
- Runs 3 iterations for coherence validation
- Uses optimal configuration (M=32, ef=200)
- Generates markdown report in
./reports/
Method 3: Custom Configuration (Advanced)
Build your own simulation from components:
agentdb simulate --custom \
--backend ruvector \
--attention-heads 8 \
--search beam 5 \
--cluster louvain \
--self-healing mpc \
--iterations 3
👉 See Custom Simulations Guide for all options →
📊 Understanding the Output
Console Output
During execution, you'll see real-time progress:
🚀 AgentDB Latent Space Simulation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 Scenario: HNSW Graph Topology Exploration
⚙️ Configuration: M=32, efConstruction=200, efSearch=100
🔄 Iteration 1/3
├─ Building graph... [████████████] 100% (2.3s)
├─ Running queries... [████████████] 100% (1.8s)
├─ Analyzing topology... [████████████] 100% (0.4s)
└─ ✅ Complete: 61.2μs latency, 96.8% recall
🔄 Iteration 2/3
└─ ✅ Complete: 60.8μs latency, 96.9% recall
🔄 Iteration 3/3
└─ ✅ Complete: 61.4μs latency, 96.7% recall
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Simulation Complete!
📊 Summary:
Average Latency: 61.2μs (8.2x vs baseline)
Recall@10: 96.8%
Coherence: 98.4% (highly consistent)
Memory: 151 MB
📄 Report saved: ./reports/hnsw-exploration-2025-11-30.md
Report File Structure
The generated markdown report contains:
# HNSW Graph Topology Exploration - Results
## Executive Summary
- Speedup: 8.2x vs hnswlib
- Latency: 61.2μs average
- Recall@10: 96.8%
## Configuration
[Details of M, ef parameters]
## Performance Metrics
[Latency distribution, QPS, memory]
## Graph Properties
- Small-world index (σ): 2.84 ✅
- Clustering coefficient: 0.39
- Average path length: 5.1 hops
## Coherence Analysis
[Variance across 3 runs]
## Recommendations
[Production deployment suggestions]
🎓 Understanding Key Metrics
Latency
What it means: How long one search query takes Good value: <100μs for real-time applications Your result: 61.2μs ✅ Excellent
Recall@10
What it means: % of correct results in top 10 Good value: >95% Your result: 96.8% ✅ High accuracy
Speedup
What it means: How many times faster than baseline (hnswlib) Good value: >2x Your result: 8.2x ✅ Industry-leading
Coherence
What it means: Consistency across multiple runs Good value: >95% Your result: 98.4% ✅ Highly reproducible
Small-World Index (σ)
What it means: Graph has "small-world" properties (fast navigation) Good value: 2.5-3.5 Your result: 2.84 ✅ Optimal range
🏆 What You Accomplished
You just:
- ✅ Installed AgentDB simulation CLI
- ✅ Ran a production-grade vector database benchmark
- ✅ Validated that RuVector is 8.2x faster than industry baseline
- ✅ Generated a comprehensive performance report
Total time: ~5 minutes (including 4.5s simulation execution)
📈 Next Steps
Explore Other Scenarios
Try the other 7 validated scenarios:
# Multi-head attention analysis (12.4% improvement)
agentdb simulate attention
# Search strategy optimization (96.8% recall)
agentdb simulate traversal
# 30-day self-healing simulation (97.9% uptime)
agentdb simulate self-organizing
# Full neural augmentation (29.4% boost)
agentdb simulate neural
Build Custom Configurations
Learn to compose optimal configurations:
# Memory-constrained setup
agentdb simulate --custom \
--backend ruvector \
--attention-heads 8 \
--neural-edges \
--cluster louvain
# Latency-critical setup
agentdb simulate --custom \
--backend ruvector \
--search beam 5 \
--search dynamic-k \
--neural-navigation
👉 See Custom Simulations Guide →
Deep Dive into Results
Understand the research behind the numbers:
- Master Synthesis Report - Cross-simulation analysis
- Individual Reports - Detailed findings for each scenario
- Optimization Strategy - How to tune for your use case
🛠️ Common Options
Change Dataset Size
agentdb simulate hnsw --nodes 1000000 --dimensions 768
Run More Iterations (Better Coherence)
agentdb simulate hnsw --iterations 10
Custom Report Path
agentdb simulate hnsw --output ./my-reports/
JSON Output
agentdb simulate hnsw --format json
Verbose Logging
agentdb simulate hnsw --verbose
👉 See Complete CLI Reference →
❓ Troubleshooting
"Command not found: agentdb"
# Verify installation
npm list -g agentdb
# Reinstall if needed
npm install -g agentdb --force
Simulation Runs Too Slowly
# Reduce dataset size for faster testing
agentdb simulate hnsw --nodes 10000 --iterations 1
Out of Memory Errors
# Use smaller dimensions or fewer nodes
agentdb simulate hnsw --nodes 50000 --dimensions 128
👉 See Full Troubleshooting Guide →
📚 Learn More
User Guides
- Wizard Guide - Interactive simulation builder
- Custom Simulations - Component reference
- CLI Reference - All commands and options
Technical Docs
- Simulation Architecture - TypeScript implementation
- Optimization Strategy - Performance tuning
Research
- Latent Space Reports - Executive summary
- Master Synthesis - Complete analysis
🎉 You're Ready!
You now have the tools to:
- ✅ Run production-grade vector database benchmarks
- ✅ Validate performance optimizations
- ✅ Compare configurations
- ✅ Generate comprehensive reports
Start exploring: Try different scenarios and configurations to find the optimal setup for your use case.
Questions? Check the Troubleshooting Guide → or open an issue on GitHub.