Vizra ADK Memory System

# Vizra ADK Memory System

Vizra ADK provides multiple memory types for agents to maintain context across conversations and sessions.

## Memory Types

| Type | Purpose | Persistence |
|------|---------|-------------|
| **Session Memory** | Conversation history within a session | Session lifetime |
| **User Memory** | Information tied to a specific user | Permanent |
| **Vector Memory** | Semantic search and RAG | Permanent |

## Basic Memory Usage

### Session-Based Memory

Conversation history persists within a session:

```php
use App\Agents\MyAgent;

$sessionId = 'conversation-123';

// First message in session
$response1 = MyAgent::run('My name is John')
    ->forUser($user)
    ->withSession($sessionId)
    ->go();

// Later in the same session - agent remembers context
$response2 = MyAgent::run('What is my name?')
    ->forUser($user)
    ->withSession($sessionId)
    ->go(); // Will remember "John"
```

### User-Based Memory

Memory persists across all sessions for a user:

```php
// First conversation
$response1 = MyAgent::run('I prefer dark mode and short responses')
    ->forUser($user)
    ->go();

// New conversation - user preferences are remembered
$response2 = MyAgent::run('Help me with my project')
    ->forUser($user)
    ->go(); // Agent remembers preferences
```

## Memory Tools

### MemoryTool

Allow agents to explicitly store and retrieve memories:

```php
use Vizra\VizraADK\Tools\MemoryTool;

class PersonalAssistantAgent extends BaseLlmAgent
{
    protected string $name = 'personal_assistant';
    protected string $instructions = <<<'INSTRUCTIONS'
        You are a personal assistant. Use the memory tool to:
        - Remember important facts the user tells you
        - Recall information when asked
        - Update memories when information changes
        INSTRUCTIONS;

    protected array $tools = [
        MemoryTool::class,
    ];
}
```

The agent can then use commands like:
- `remember: User's birthday is March 15`
- `recall: birthday`
- `forget: old address`

### VectorMemoryTool

Enable semantic search for RAG (Retrieval Augmented Generation):

```php
use Vizra\VizraADK\Tools\VectorMemoryTool;

class KnowledgeAgent extends BaseLlmAgent
{
    protected string $name = 'knowledge_agent';
    protected string $instructions = <<<'INSTRUCTIONS'
        You are a knowledge assistant with access to the company documentation.
        Use the vector memory tool to search for relevant information before answering questions.
        Always cite the source of information.
        INSTRUCTIONS;

    protected array $tools = [
        VectorMemoryTool::class,
    ];
}
```

## Programmatic Memory Access

### Storing Memories

```php
use Vizra\VizraADK\Services\MemoryManager;

$memoryManager = app(MemoryManager::class);

// Store a memory for a user
$memoryManager->store(
    userId: $user->id,
    key: 'preferences',
    value: [
        'theme' => 'dark',
        'language' => 'en',
        'notifications' => true
    ]
);

// Store with tags for organization
$memoryManager->store(
    userId: $user->id,
    key: 'project_alpha_notes',
    value: $notes,
    tags: ['projects', 'alpha', 'notes']
);
```

### Retrieving Memories

```php
// Get specific memory
$preferences = $memoryManager->get($user->id, 'preferences');

// Get all memories with a tag
$projectMemories = $memoryManager->getByTag($user->id, 'projects');

// Search memories
$results = $memoryManager->search($user->id, 'project deadline');
```

### Updating and Deleting

```php
// Update existing memory
$memoryManager->update(
    userId: $user->id,
    key: 'preferences',
    value: array_merge($currentPrefs, ['theme' => 'light'])
);

// Delete specific memory
$memoryManager->delete($user->id, 'old_data');

// Clear all user memories
$memoryManager->clearUser($user->id);
```

## Vector Memory for RAG

### Storing Documents

```php
use Vizra\VizraADK\Services\VectorMemoryManager;

$vectorManager = app(VectorMemoryManager::class);

// Store a document with automatic chunking
$vectorManager->store(
    content: $documentContent,
    metadata: [
        'source' => 'company_handbook',
        'section' => 'policies',
        'updated_at' => now()
    ]
);

// Store multiple documents
$vectorManager->storeMany([
    ['content' => $doc1, 'metadata' => ['type' => 'policy']],
    ['content' => $doc2, 'metadata' => ['type' => 'guide']],
]);
```

### Searching Vector Memory

```php
// Semantic search
$results = $vectorManager->search(
    query: 'What is the vacation policy?',
    limit: 5
);

// Search with metadata filter
$results = $vectorManager->search(
    query: 'onboarding process',
    limit: 5,
    filter: ['type' => 'guide']
);
```

### CLI Commands

```bash
# Store documents from file
php artisan vizra:vector:store --file=handbook.pdf

# Store directory of documents
php artisan vizra:vector:store --directory=docs/

# Search vector memory
php artisan vizra:vector:search "vacation policy"

# View statistics
php artisan vizra:vector:stats
```

## Memory Patterns

### Building User Profiles

```php
class ProfileBuildingAgent extends BaseLlmAgent
{
    protected string $instructions = <<<'INSTRUCTIONS'
        Build a comprehensive user profile by:
        1. Asking about their preferences gradually
        2. Remembering details they share
        3. Inferring preferences from behavior
        4. Updating profile as preferences change
        INSTRUCTIONS;

    protected array $tools = [
        MemoryTool::class,
    ];

    public function afterExecution($response, $context)
    {
        // Extract and store any preferences mentioned
        $this->extractAndStorePreferences($response, $context);
    }
}
```

### Context-Aware Responses

```php
class ContextAwareAgent extends BaseLlmAgent
{
    public function beforeExecution($input, $context)
    {
        // Load relevant memories before processing
        $memories = $this->loadRelevantMemories($context);

        // Inject into context
        $context->