Vector & RAG - Vizra ADK Documentation

Understanding Vector Memory 🧠

Think of vector memory as your agent's superpower! It transforms text into mathematical representations that capture meaning, enabling your agent to find semantically similar content even when the exact words don't match. 🚀

🎯 Semantic Search

Find content by meaning, not just keywords

⚡ Efficient Retrieval

Lightning-fast similarity searches at scale

📚 Scalable Storage

Handle millions of documents with ease

🔧 Context Augmentation

Enhance responses with relevant knowledge

Setting Up Vector Memory 🛠️

Let's get your vector memory up and running! It's easier than you might think. 💪

Configuration

First, configure vector memory in your .env file:

# Vector Memory Driver (pgvector, meilisearch)
AGENT_ADK_VECTOR_DRIVER=pgvector

# OpenAI for embeddings
OPENAI_API_KEY=your-api-key

# PostgreSQL with pgvector
DB_CONNECTION=pgsql
DB_DATABASE=your_database

Database Setup

# Run migrations for vector memory tables
php artisan migrate

# For PostgreSQL, ensure pgvector extension is installed
CREATE EXTENSION IF NOT EXISTS vector;

Storing Documents 📄

Time to give your agent some knowledge! Let's store documents and watch your agent become smarter with each piece of information. 🎓

Basic Document Storage

use Vizra\VizraADK\Services\VectorMemoryManager;

$vectorManager = app(VectorMemoryManager::class);

// Store a document with automatic chunking
$memories = $vectorManager->addDocument(
    'documentation_agent',
    'Vizra ADK is a Laravel package for building AI agents. It provides tools, memory management, and workflow orchestration...',
    [
        'category' => 'overview',
        'version' => '1.0'
    ],
    'default', // namespace
    'docs',    // source
    'overview-page' // source_id
);

Adding Individual Chunks

// Add a single chunk without automatic chunking
$memory = $vectorManager->addChunk(
    'my_agent',
    'This is a specific piece of information to store.',
    ['type' => 'fact'],
    'default',
    'manual-entry'
);

Document Chunking Configuration

💡 Pro tip: Adjust chunk sizes based on your content type. Smaller chunks for FAQs, larger for narrative content!

// Configure chunking in config/vizra-adk.php
'vector_memory' => [
    'chunking' => [
        'size' => 1000,      // Characters per chunk
        'overlap' => 100,    // Overlap between chunks
        'separators' => ["\n\n", "\n", ". ", ", ", " "],
        'keep_separators' => true,
    ],
];

Searching Vector Memory 🔍

Here's where the magic happens! Watch your agent find exactly what it needs, even when users ask questions in completely different words. 🎯

Basic Search

// Search for similar content
$results = $vectorManager->search(
    'documentation_agent',
    'How do I create an agent?',
    'default', // namespace
    5,         // limit
    0.7        // threshold
);

foreach ($results as $result) {
    echo $result->content . "\n";
    echo "Similarity: " . $result->similarity . "\n\n";
}

RAG Context Generation

🚀 RAG (Retrieval-Augmented Generation) combines the power of vector search with LLM generation for incredibly accurate responses!

// Generate context for RAG
$ragContext = $vectorManager->generateRagContext(
    'documentation_agent',
    'How to configure agents?',
    'default',
    5,
    0.7
);

// Returns structured context
[
    'context' => 'Relevant content concatenated...',
    'sources' => [/* source references */],
    'query' => 'How to configure agents?',
    'total_results' => 5
]

RAG in Agents 🤖

Transform your agents into knowledge powerhouses! Here's how to integrate RAG for context-aware, accurate responses. 💡

Manual RAG Implementation

class RagEnabledAgent extends BaseLlmAgent
{
    protected VectorMemoryManager $vectorManager;

    public function __construct()
    {
        $this->vectorManager = app(VectorMemoryManager::class);
    }

    public function run(mixed $input, AgentContext $context): mixed
    {
        // Generate RAG context
        $ragContext = $this->vectorManager->generateRagContext(
            $this->name,
            $input,
            'default',
            5,
            0.7
        );

        // Augment input with context
        $augmentedInput = "Context:\n" . $ragContext['context'] .
                         "\n\nQuestion: " . $input;

        return parent::run($augmentedInput, $context);
    }
}

RAG Configuration

// Configure RAG in config/vizra-adk.php
'vector_memory' => [
    'rag' => [
        'context_template' => "Based on the following context:\n{context}\n\nAnswer this question: {query}",
        'max_context_length' => 4000,
        'include_metadata' => true,
    ],
],

Embedding Providers 🌐

🎯 OpenAI (Default)

OPENAI_API_KEY=your-api-key

# In config/vizra-adk.php
'embedding_models' => [
    'openai' => 'text-embedding-3-small'
]

📊 Supported Models

• text-embedding-3-small (1536 dims)
• text-embedding-3-large (3072 dims)
• text-embedding-ada-002 (1536 dims)

🔧 Custom Provider

Implement EmbeddingProviderInterface to add custom embedding providers

Vector Memory Management 🎛️

Keep your vector memory clean and efficient! Here's how to manage, monitor, and optimize your knowledge base. 🧹

Managing Memories

// Delete memories by namespace
$count = $vectorManager->deleteMemories(
    'my_agent',
    'default'
);

// Delete memories by source
$count = $vectorManager->deleteMemoriesBySource(
    'my_agent',
    'old-docs',
    'default'
);

Memory Statistics

// Get statistics for an agent
$stats = $vectorManager->getStatistics(
    'my_agent',
    'default'
);

// Returns:
[
    'total_memories' => 150,
    'total_tokens' => 12500,
    'providers' => ['openai' => 150],
    'sources' => ['docs' => 100, 'manual' => 50]
]

Using the VectorMemory Model

use Vizra\VizraADK\Models\VectorMemory;

// Query memories directly
$memories = VectorMemory::forAgent('my_agent')
    ->inNamespace('default')
    ->fromSource('docs')
    ->get();

// Calculate similarity (for non-pgvector)
$similarity = $memory->cosineSimilarity($queryEmbedding);

Vector Storage Drivers 📦

🐘 PostgreSQL with pgvector

High-performance vector similarity search with native PostgreSQL integration.

# Install pgvector extension
CREATE EXTENSION IF NOT EXISTS vector;

# Configure in .env
AGENT_ADK_VECTOR_DRIVER=pgvector
DB_CONNECTION=pgsql

🔍 Meilisearch

Lightning-fast, typo-tolerant search engine with built-in vector support.

# Configure for Meilisearch
AGENT_ADK_VECTOR_DRIVER=meilisearch
MEILISEARCH_HOST=http://localhost:7700
MEILISEARCH_KEY=your-master-key

Console Commands 💻

Powerful CLI tools to manage your vector memory right from the terminal! 🎯

Available Commands

# Store content from a file
php artisan vector:store my_agent /path/to/document.txt

# Search vector memory
php artisan vector:search my_agent "search query"

# Get statistics
php artisan vector:stats my_agent

🚀 Vector Memory Best Practices

🗂️ Organization

✓ Use namespaces to organize content
✓ Include descriptive metadata
✓ Use content hashing to avoid duplicates

⚙️ Optimization

✓ Choose appropriate chunk sizes
✓ Monitor token counts for costs
✓ Use pgvector for production

🎯 Strategy

✓ Match chunking to content type
✓ Select models for your use case
✓ Clean up old memories regularly

📋 Remember

✓ Test similarity thresholds
✓ Balance context size vs accuracy
✓ Consider hybrid search approaches

Next: Evaluations →

Learn about testing and evaluating agents

Sessions & Memory →

Review memory management

Vector Memory & RAG