AgenticDB Quick Start Guide

Get started with Ruvector's AgenticDB API in 5 minutes.

Installation

# Add to Cargo.toml
[dependencies]
ruvector-core = "0.1"

Basic Usage

use ruvector_core::{AgenticDB, DbOptions, Result};
use std::collections::HashMap;

fn main() -> Result<()> {
    // 1. Initialize database
    let db = AgenticDB::with_dimensions(128)?;

    // 2. Store a learning episode
    let episode_id = db.store_episode(
        "Learn to optimize code".to_string(),
        vec!["analyzed bottleneck".to_string(), "applied optimization".to_string()],
        vec!["code 2x faster".to_string()],
        "Profiling first helps identify real bottlenecks".to_string(),
    )?;
    println!("Stored episode: {}", episode_id);

    // 3. Retrieve similar past experiences
    let similar = db.retrieve_similar_episodes("code optimization", 5)?;
    println!("Found {} similar experiences", similar.len());

    // 4. Create a reusable skill
    let skill_id = db.create_skill(
        "Code Profiler".to_string(),
        "Profile code to find performance bottlenecks".to_string(),
        HashMap::new(),
        vec!["run profiler".to_string(), "analyze hotspots".to_string()],
    )?;
    println!("Created skill: {}", skill_id);

    // 5. Add causal knowledge
    db.add_causal_edge(
        vec!["inefficient loop".to_string()],
        vec!["slow performance".to_string()],
        0.9,
        "Performance analysis".to_string(),
    )?;

    // 6. Start RL training
    let session = db.start_session("Q-Learning".to_string(), 4, 2)?;
    db.add_experience(&session, vec![1.0; 4], vec![1.0; 2], 1.0, vec![0.0; 4], false)?;
    
    // 7. Get predictions
    let prediction = db.predict_with_confidence(&session, vec![1.0; 4])?;
    println!("Predicted action: {:?}", prediction.action);

    Ok(())
}

Five Core APIs

1. Reflexion Memory

Learn from past mistakes:

// Store mistake
db.store_episode(task, actions, observations, critique)?;

// Learn from history
let similar = db.retrieve_similar_episodes("similar situation", 5)?;

2. Skill Library

Build reusable patterns:

// Create skill
db.create_skill(name, description, params, examples)?;

// Find relevant skills
let skills = db.search_skills("what I need to do", 5)?;

3. Causal Memory

Understand cause and effect:

// Add relationship (supports multiple causes → multiple effects)
db.add_causal_edge(
    vec!["cause1", "cause2"],
    vec!["effect1", "effect2"],
    confidence,
    context,
)?;

// Query with utility function
let results = db.query_with_utility(query, k, 0.7, 0.2, 0.1)?;

4. Learning Sessions

Train RL models:

// Start training
let session = db.start_session("DQN", state_dim, action_dim)?;

// Add experience
db.add_experience(&session, state, action, reward, next_state, done)?;

// Make predictions
let pred = db.predict_with_confidence(&session, current_state)?;

5. Vector Search

Fast similarity search:

// All text is automatically embedded and indexed
// Just use the high-level APIs above!

Complete Example

See examples/agenticdb_demo.rs for a full demonstration.

Documentation

Full API reference: docs/AGENTICDB_API.md
Implementation details: docs/PHASE3_SUMMARY.md

Performance

10-100x faster than original agenticDB
O(log n) search with HNSW index
SIMD-optimized distance calculations
Concurrent access with lock-free reads

Next Steps

Try the example: cargo run --example agenticdb_demo
Read the API docs: docs/AGENTICDB_API.md
Run tests: cargo test -p ruvector-core agenticdb
Build your agentic AI system!

3.6 KiB Raw Blame History