Session Debug
Session ID: {sessionId}
Active Step: {orchestrationState.activeStep || 'None'}
Tools Used: {orchestrationState.recentlyUsedTools.join(', ')}
Sequence Position: {orchestrationState.sequenceIndex}
0.1,0.2
0.3,0.4"] C --> E["FTS5
deadline
friday"] C --> F["Metadata
semantic
episodic"] D --> G["Hybrid Scoring
70% vector + 30% text"] E --> G F --> G G --> H["Results
Sarah deadline memory
related project memories"] style A fill:#f9f9f9 style B fill:#e1f5fe style C fill:#fff3e0 style G fill:#f3e5f5 style H fill:#e8f5e8 ``` **Key Features**: - Hybrid vector + text search - Specialized memory adapters for PostgreSQL and SQLite - Community-extensible adapters available for ChromaDB, Pinecone, and Qdrant - Memory type specialization - Performance: <50ms recall ## Architecture Flow ```mermaid graph TD A[User Message] --> B[PRIME Extraction] B --> C[Memory Storage] C --> D[Vector Indexing] C --> E[Text Indexing] F[User Query] --> G[Embedding Generation] G --> H[Vector Search] F --> I[Text Search] H --> J[Hybrid Fusion] I --> J J --> K[Ranked Results] style B fill:#e1f5fe style G fill:#f3e5f5 style J fill:#e8f5e8 ``` ## Advanced Features ### PRIME Extraction - **Rule-based guidance**: Natural language extraction rules - **Tier optimization**: Auto-select model based on complexity - **Cost intelligence**: Budget tracking with <$20/month for 100k operations ### Memory Retrieval (Enhanced) - **Vector-first**: Semantic similarity using text-embedding-3-small - **Hybrid search**: Combines vector (70%) + text (30%) scoring - **Multi-adapter**: PostgreSQL ts_rank_cd + SQLite FTS5 BM25 - **Performance**: <50ms recall, >95% accuracy - **Configurable hops**: 1-3 connection hops based on recall preset - **Temporal boost**: Relevance boost for time-pattern matches - **Evolution tracking**: Access events logged automatically ## Key Technical Differentiators **Four-Layer Memory Architecture**: Unlike single-layer systems, AgentDock mirrors human cognition with working, episodic, semantic, and procedural memory types, each optimized for different information patterns and retrieval scenarios. **PRIME Extraction Intelligence**: Intelligent 2-tier model selection with rule-based guidance reduces extraction costs by 60% while maintaining quality. Most systems use expensive models for all extractions. **Hybrid Vector-Text Search**: Pure vector search fails on specialized terminology. Our research-validated 70/30 vector/text split prevents catastrophic failures while maintaining semantic understanding across domains. **Memory Connection Graph**: SQL-based graph operations without dedicated graph databases. 5 research-backed connection types (similar, related, causes, part_of, opposite) with intelligent relationship traversal up to 3 hops deep. **Progressive Enhancement Connection Discovery**: Tiered approach (embeddings → rules → LLM) reduces connection discovery costs by 65% while maintaining quality. Smart triage automatically classifies 65% of connections without LLM calls. **Automatic Memory Consolidation**: Episodic-to-semantic conversion with merge, synthesize, and hierarchy strategies. Reduces storage while improving recall quality through intelligent memory lifecycle management. **Lazy Memory Decay System**: On-demand decay calculation with configurable half-lives per memory type. 65-100% write avoidance through batch processing and access reinforcement patterns. **Temporal Intelligence Integration**: Built-in pattern analysis, time-based memory relationships, and temporal influence on decay/recall. Statistical approach with optional LLM enhancement for behavioral insights. **Multi-Adapter Architecture**: Single API works with PostgreSQL, SQLite, ChromaDB, Pinecone, and Qdrant without vendor lock-in. Managed service compatibility without database extensions. **Cost-Optimized Operations**: Built-in budget tracking, smart triage, lazy calculations, and transparent cost reporting. Designed for production deployment with predictable costs under $20/month for 100k operations. **Production-Ready Persistence**: SQL-based storage with optional vector enhancements. Transaction management, encryption support, and no complex graph database management requirements. ## Intelligence Layer: Advanced Memory Processing **Purpose**: Enhance memory system with intelligent analysis and connections ### Memory Connections & Graph - **MemoryConnectionManager**: Language-agnostic connection discovery - **ConnectionGraph**: Graph operations for relationship traversal - **5 core connection types**: similar, related, causes, part_of, opposite - **Smart triage**: 40% auto-similar, 25% auto-related, 35% LLM classification - **Progressive enhancement**: embeddings → user rules → LLM analysis ### Memory Consolidation - **MemoryConsolidator**: Convert episodic → semantic memories - **Strategies**: merge, synthesize, hierarchy - **Language-agnostic**: Uses embeddings, optional LLM enhancement - **Batch processing**: Efficient consolidation operations ### Temporal Pattern Analysis (Production Ready) - **TemporalPatternAnalyzer**: Analyze memory access patterns - **Pattern detection**: hourly, weekly, burst patterns - **Activity clusters**: Identify periods of high memory activity - **Statistical approach**: Optional LLM enhancement - **Pattern storage**: Results stored in memory metadata as `temporalInsights` - **Recall boost**: Daily patterns boost relevance during peak hours - **Decay influence**: Burst patterns slow decay by 30% - **Connection detection**: Temporal relationships between memories ```mermaid graph TD A[Memory Storage] --> B[Temporal Pattern Analysis] B --> C[Pattern Detection] C --> D[Daily Patterns] C --> E[Weekly Patterns] C --> F[Burst Patterns] D --> G[Store in Memory Metadata] E --> G F --> G G --> H[Recall Boost] G --> I[Decay Influence] G --> J[Connection Detection] style A fill:#f9f9f9 style B fill:#e1f5fe style G fill:#fff3e0 style H fill:#e8f5e8 style I fill:#f3e5f5 style J fill:#e8f5e8 ``` ### Memory Evolution Tracking (Basic Implementation) - **Event logging**: Track memory lifecycle (created, accessed) - **Storage**: Via `storage.evolution.trackEvent()` interface - **Batched processing**: Efficient event handling - **Sources**: BaseMemoryType, MemoryManager, RecallService - **Note**: Basic events only - full PRD compliance pending ## Supporting Services ### Lazy Memory Decay - **LazyDecayCalculator**: On-demand decay calculation - **LazyDecayBatchProcessor**: Efficient batch updates - **Access reinforcement**: Frequently used memories stay strong - **Configurable half-lives**: Different decay rates per memory type - **Archival threshold**: Low-resonance memory management ### Encryption Service - **Column-level encryption**: PostgreSQL pgcrypto integration - **Key rotation support**: Secure key management - **Batch operations**: Performance-optimized encryption - **Multiple providers**: ENV, AWS KMS, Vault support ### Cost Tracking - **CostTracker**: Real-time operation cost monitoring - **Budget enforcement**: Configurable spending limits - **Cost breakdown**: Track by extractor type - **Transparent reporting**: Clear cost visibility ### Transaction Management - **MemoryTransaction**: Atomic operations with rollback - **Consistency guarantee**: Multi-step operation safety - **Scope helpers**: Automatic transaction management - **Error recovery**: Graceful failure handling ## Workflow Learning Service (Built, Not Wired) **Status**: Foundation implemented, awaiting integration with commercial product support **Purpose**: Learn and suggest tool execution patterns ```typescript // Located at: /orchestration/workflow-learning/WorkflowLearningService.ts // PRD: Phase 1 ✅ COMPLETED - Service built // PRD: Phase 2-3 🔧 PENDING - Integration with LLMOrchestrationService ``` **Key Features**: - Pattern recognition for tool sequences - Success tracking and confidence scoring - Configurable learning thresholds - Pattern merging and optimization - Storage via procedural memory type ## Summary **PRIME**: Intelligent extraction from conversations **Memory System**: Fast, accurate memory retrieval **Intelligence Layer**: Connections, consolidation, pattern analysis **Supporting Services**: Encryption, transactions, cost tracking, decay **Workflow Learning**: Built foundation, awaiting commercial integration **Together**: Complete memory pipeline from raw text to connected knowledge, enabling **Conversational RAG** through agent runtime memory injection AgentDock provides clean architectural separation with no content duplication across memory types while maintaining production-ready performance. ## Related Documentation - [Memory System README](./README.md) - Getting started with the memory system - [Memory Connections](./memory-connections.md) - Detailed connection system explanation - [Graph Architecture](./graph-architecture.md) - Technical graph implementation - [Conversational RAG Guide](./retrieval-augmented-generation.md) - RAG implementation details - [Complete Configuration Guide](./complete-configuration-guide.md) - Configuration examples ## Complete AgentDock Configuration Guide ## **THE 3-SECOND SETUP** ```bash # 1. Set your API key export OPENAI_API_KEY=sk-xxx # 2. That's it! ``` ```typescript // 3. Start using AgentDock import { createMemorySystem } from 'agentdock-core'; const memory = await createMemorySystem(); // METHOD 1: Manual Direct Storage (bypasses PRIME) await memory.store('user-123', 'User prefers dark mode'); // METHOD 2: Automatic PRIME Extraction (AI-powered) const extractedMemories = await memory.addMessage('user-123', { id: 'msg-123', agentId: 'default', content: 'I love dark mode and high contrast themes', role: 'user', timestamp: Date.now() }); // Recall memories (works with both methods) const results = await memory.recall('user-123', 'user preferences'); ``` --- ## **Quick Start Options** ### Option 1: Zero Configuration (Recommended) ```typescript // Uses smart defaults - perfect for 95% of use cases const memory = await createMemorySystem(); ``` ### Option 2: Choose Your Environment ```typescript // Local development (SQLite) const memory = await createMemorySystem({ environment: 'local' }); // Production (PostgreSQL) const memory = await createMemorySystem({ environment: 'production', databaseUrl: process.env.DATABASE_URL }); ``` ### Option 3: Choose Your Use Case ```typescript // Medical/Legal (High Precision) const memory = await createMemorySystem({ environment: 'production', recallPreset: 'precision', databaseUrl: process.env.DATABASE_URL }); // Customer Support (High Performance) const memory = await createMemorySystem({ environment: 'production', recallPreset: 'performance', databaseUrl: process.env.DATABASE_URL }); // Research/Analysis (Deep Understanding) const memory = await createMemorySystem({ environment: 'production', recallPreset: 'research', databaseUrl: process.env.DATABASE_URL }); ``` --- ## **Memory Creation Methods** The memory system provides two distinct methods for creating memories: ### **Method 1: Manual Direct Storage** Use when you know exactly what memory to create. Bypasses AI extraction. ```typescript // Direct storage with full control await memoryManager.store( 'user-123', // userId 'agent-456', // agentId 'User is allergic to peanuts', // content MemoryType.SEMANTIC, // type: semantic, episodic, working, procedural { timestamp: Date.now(), // Optional: custom timestamp neverDecay: true, // Optional: prevent decay customHalfLife: 365 // Optional: days before 50% decay } ); ``` **Best for:** - Critical information (medical conditions, legal requirements) - Pre-processed or validated data - Migration from other systems - Testing and debugging ### **Method 2: Automatic PRIME Extraction** AI analyzes messages to extract multiple relevant memories automatically. ```typescript // Let AI determine what's important const memories = await memory.addMessage('user-123', { id: 'msg-789', agentId: 'agent-456', content: 'I work night shifts so I prefer afternoon meetings. Also, I\'m lactose intolerant.', role: 'user', timestamp: Date.now() }); // Returns: Array of extracted memories with AI-determined types and importance ``` **Best for:** - Natural conversations - Complex messages with multiple facts - When you want AI to determine importance - Real-time chat applications ### **Comparison** | Feature | Manual Storage | PRIME Extraction | |---------|---------------|------------------| | AI Processing | None | Full analysis | | Control | Complete | AI-guided | | Speed | Fastest | Slower (AI processing) | | Cost | Storage only | Storage + AI tokens | | Memory Count | 1 per call | 0-N per message | | Use Case | Known facts | Conversations | --- ## **Environment Variables That Actually Work** ### **Minimal Setup (Just Works™)** ```bash # Only one required: OPENAI_API_KEY=sk-xxx ``` ### **Force Quality Models** ```bash # Always use premium models (costs more, better quality) OPENAI_API_KEY=sk-xxx PRIME_DEFAULT_TIER=advanced # ✅ VERIFIED WORKING CONNECTION_ALWAYS_ADVANCED=true # ✅ VERIFIED WORKING ``` ### **Force Single Model Everywhere** ```bash # Use same model for everything (simple & predictable) OPENAI_API_KEY=sk-xxx PRIME_MODEL=gpt-4.1 # ✅ VERIFIED WORKING CONNECTION_MODEL=gpt-4.1 # ✅ VERIFIED WORKING ``` ### **Cost Optimization** ```bash # Use cheapest models (save money) OPENAI_API_KEY=sk-xxx PRIME_MODEL=gpt-4.1-mini # ✅ VERIFIED WORKING CONNECTION_MODEL=gpt-4.1-mini # ✅ VERIFIED WORKING ``` ### **Smart Balance (Default)** ```bash # Auto-optimize cost vs quality (recommended) OPENAI_API_KEY=sk-xxx # No other variables needed - system chooses best model per task ``` --- ## **Available Presets** | Environment | Description | Database | Use Case | |-------------|-------------|----------|----------| | `local` | **Default** | SQLite | Development, testing | | `production` | Optimized | PostgreSQL | Live applications | | Recall Preset | Description | Best For | |---------------|-------------|----------| | `default` | **Recommended** | General purpose | | `precision` | High accuracy | Medical, legal, finance | | `performance` | Fast response | Customer support | | `research` | Deep analysis | Academic, content discovery | --- ## **Real-World Examples** ### Example 1: Startup (Simple & Cheap) ```typescript // Perfect for MVP, prototypes, small teams const memory = await createMemorySystem(); ``` **Environment Variables:** ```bash OPENAI_API_KEY=sk-xxx PRIME_MODEL=gpt-4.1-mini # Saves ~80% on costs CONNECTION_MODEL=gpt-4.1-mini ``` ### Example 2: Medical App (Safety First) ```typescript // High precision for safety-critical applications const memory = await createMemorySystem({ environment: 'production', recallPreset: 'precision', databaseUrl: process.env.DATABASE_URL }); ``` **Environment Variables:** ```bash OPENAI_API_KEY=sk-xxx PRIME_DEFAULT_TIER=advanced # Always use best models CONNECTION_ALWAYS_ADVANCED=true # Safety first PRIME_PROVIDER=openai # Industry standard provider ``` ### Example 3: Customer Support (High Volume) ```typescript // Optimized for speed and throughput const memory = await createMemorySystem({ environment: 'production', recallPreset: 'performance', databaseUrl: process.env.DATABASE_URL }); ``` **Environment Variables:** ```bash OPENAI_API_KEY=sk-xxx PRIME_ADVANCED_MIN_CHARS=1000 # Rarely use expensive models CONNECTION_AUTO_SIMILAR=0.7 # More auto-classification (cheaper) ``` ### Example 4: Research Platform (Deep AI) ```typescript // Maximum intelligence and connection discovery const memory = await createMemorySystem({ environment: 'production', recallPreset: 'research', databaseUrl: process.env.DATABASE_URL }); ``` **Environment Variables:** ```bash OPENAI_API_KEY=sk-xxx PRIME_ADVANCED_MIN_CHARS=200 # Use advanced models more often CONNECTION_PREFER_QUALITY=true # Bias toward quality ``` ### Example 5: Enterprise (Balanced Production) ```typescript // Production-ready with smart cost optimization const memory = await createMemorySystem({ environment: 'production', databaseUrl: process.env.DATABASE_URL }); ``` **Environment Variables:** ```bash OPENAI_API_KEY=sk-xxx NODE_ENV=production # Uses smart defaults - auto-optimizes cost vs quality ``` --- ## **Advanced Customization** Only use this if the presets don't meet your needs: ```typescript const memory = await createMemorySystem({ environment: 'production', databaseUrl: process.env.DATABASE_URL, overrides: { // Custom PRIME configuration prime: { primeConfig: { provider: 'openai', standardModel: 'gpt-4.1-mini', advancedModel: 'gpt-4.1', autoTierSelection: true, tierThresholds: { advancedMinChars: 300, // Custom threshold advancedMinRules: 3 // Custom threshold } } }, // Custom memory configuration memory: { working: { maxTokens: 8000, // Larger context ttlSeconds: 7200 // 2-hour TTL } }, // Custom recall configuration recall: { defaultLimit: 20, // More results cacheResults: true, cacheTTL: 600, // 10-minute cache defaultConnectionHops: 2 // Graph traversal depth: 1=direct, 2=friends-of-friends, 3=research-depth }, // Intelligence layer configuration intelligence: { temporal: { enabled: true }, // Enable temporal pattern analysis connectionDetection: { enabled: true, // Enable memory connections method: 'embedding-only' // Cost-optimized connection discovery } }, // Custom storage configuration for pgvector storage: { type: 'postgresql-vector', config: { connectionString: process.env.DATABASE_URL, enableVector: true, defaultDimension: 1536, // OpenAI embeddings defaultMetric: 'cosine', // Best for semantic similarity // Production pgvector tuning ivfflat: { lists: 100, // Number of clusters (sqrt(rows) is good start) probes: 10 // Clusters to search (10 = 94% recall) } } } } }); ``` --- ## **Intelligence Layer Configuration** The intelligence layer adds advanced memory features like temporal patterns and connection discovery: ### **Temporal Pattern Analysis** ```typescript intelligence: { temporal: { enabled: true } // Analyzes memory access patterns over time } ``` - **What it does**: Detects daily, weekly, and burst patterns in memory creation - **Benefits**: Provides relevance boost during peak activity hours - **Storage**: Patterns stored as `temporalInsights` in memory metadata - **Performance**: Statistical analysis with optional LLM enhancement ### **Connection Discovery** ```typescript intelligence: { connectionDetection: { enabled: true, method: 'embedding-only' // Cost-optimized approach } } ``` - **What it does**: Automatically discovers relationships between memories - **Methods**: `embedding-only` (fast, cheap) or `enhanced` (includes LLM analysis) - **Connection types**: similar, related, causes, part_of, opposite - **Performance**: 65% cost reduction through smart triage ### **Connection Hops Configuration** ```typescript recall: { defaultConnectionHops: 2 // How deep to traverse memory connections } ``` - **1 hop**: Direct connections only (fastest) - **2 hops**: Friends-of-friends (balanced) - **3 hops**: Research depth (most comprehensive) - **Presets**: Default/Performance/Precision use 1, Research uses 3 ### **Evolution Tracking** Evolution tracking is automatically enabled when storage supports it: ```typescript // Events tracked: created, accessed, updated, connected // Storage: via storage.evolution.trackEvent() interface // Performance: Batched processing for efficiency ``` --- ## **Environment Variables Reference** ### **Core System Variables** ```bash # Embedding Configuration EMBEDDING_PROVIDER=openai # Provider: openai EMBEDDING_MODEL=text-embedding-3-small # Model for embeddings # Recall Cache Configuration (Performance Optimization) RECALL_CACHE_HIGH_WATER=1000 # Cache cleanup trigger (when cache hits this size) RECALL_CACHE_LOW_WATER=900 # Target cache size after cleanup # Example: When cache reaches 1000 items, it cleans down to 900 items ``` ### **PRIME System (Memory Extraction)** ```bash # Provider & API Keys PRIME_PROVIDER=openai # LLM provider PRIME_API_KEY=sk-xxx # Dedicated API key OPENAI_API_KEY=sk-xxx # Fallback API key # 2-Tier Model Control ✅ VERIFIED PRIME_MODEL=gpt-4.1 # Override both tiers PRIME_STANDARD_MODEL=gpt-4.1-mini # Standard tier only PRIME_ADVANCED_MODEL=gpt-4.1 # Advanced tier only PRIME_DEFAULT_TIER=standard # Force tier (standard|advanced) # Smart Thresholds PRIME_ADVANCED_MIN_CHARS=500 # Use advanced for content >N chars PRIME_ADVANCED_MIN_RULES=5 # Use advanced for >N active rules PRIME_MAX_TOKENS=4000 # Maximum tokens per request # Cost Control PRIME_ENABLE_COST_TRACKING=true # Track costs PRIME_COST_THRESHOLD=10.00 # Daily limit ($USD) ``` ### **CONNECTION System (Memory Connections)** ```bash # Provider & API Keys (inherits from PRIME by default) CONNECTION_PROVIDER=openai # Override provider CONNECTION_API_KEY=sk-xxx # Override API key # 2-Tier Model Control ✅ VERIFIED CONNECTION_MODEL=gpt-4.1 # Override both tiers CONNECTION_STANDARD_MODEL=gpt-4.1-mini # Standard tier only CONNECTION_ENHANCED_MODEL=gpt-4.1 # Advanced tier only CONNECTION_ALWAYS_ADVANCED=false # Force advanced (true|false) CONNECTION_PREFER_QUALITY=false # Bias toward quality in production # Smart Triage (Cost Optimization) CONNECTION_AUTO_SIMILAR=0.8 # Auto "similar" threshold (40% FREE) CONNECTION_AUTO_RELATED=0.6 # Auto "related" threshold (25% FREE) CONNECTION_LLM_REQUIRED=0.3 # LLM analysis threshold (35% PAID) ``` ### **Database Configuration** ```bash # PostgreSQL (Production) DATABASE_URL=postgresql://... # Full connection string POSTGRES_HOST=localhost POSTGRES_PORT=5432 POSTGRES_DB=agentdock POSTGRES_USER=postgres POSTGRES_PASSWORD=xxx # SQLite (Development) SQLITE_PATH=./agentdock.db # Database file path ENABLE_SQLITE_VEC=true # Vector support ``` ### **Database Configuration** ```bash # PostgreSQL with pgvector (PRODUCTION-READY) DATABASE_URL=postgresql://... # Full connection string ENABLE_PGVECTOR=true # Enable vector search # pgvector Performance Tuning (PRODUCTION-READY) PGVECTOR_IVFFLAT_LISTS=100 # Index clusters (default: sqrt(n) rows) PGVECTOR_IVFFLAT_PROBES=10 # Search probes (accuracy vs speed) # Production Guidelines: # - Lists: Start with sqrt(expected_rows). 100 = good for ~10k vectors # - Probes: 10 = 94% recall, 20 = 97% recall, 50 = 99% recall # - For 100k+ vectors: lists=316, probes=15-20 # - Rebuild index when doubling vector count # pgvector Index Creation (run manually in production): # CREATE INDEX ON memories USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100); ``` ### **System Configuration** ```bash # Environment NODE_ENV=production # Environment mode LOG_LEVEL=info # Logging level DEBUG_MEMORY=false # Enable memory debug logs DEBUG_STORAGE=false # Enable storage debug logs # Memory System MEMORY_MAX_TOKENS=10000 # Max context tokens MEMORY_TTL=86400 # Memory TTL (seconds) MEMORY_ENCRYPTION_KEY=xxx # Encryption key for PII ``` --- ## **Advanced Recall Features** ### **Connection Graph Configuration** ```typescript // Use memory connections to find related memories const results = await memory.recall('user-123', 'JavaScript', { // Connection Graph Features (Brief Explanation) useConnections: true, // Find connected memories (default: true) connectionHops: 2, // How deep to traverse (1 = direct, 2 = friends of friends) connectionTypes: ['similar', 'causes'], // Filter connection types boostCentralMemories: true // Prioritize highly-connected memories }); ``` ## **Storage Adapter Priority** | Adapter | Status | Use Case | Performance | |---------|--------|----------|-------------| | **pgvector** | **PRODUCTION-READY** | **Primary choice** - PostgreSQL with vectors | 10k+ QPS with proper indexing | | **postgresql** | Production-Ready | PostgreSQL without vectors | High performance | | **sqlite-vec** | Supported | Local development with vectors | Good for <50k vectors | | **sqlite** | Supported | Local development | Fast for small datasets | | **memory** | Testing Only | No persistence | In-memory only | | ChromaDB/Pinecone/Qdrant | Community Extensible | Base classes for extension | Varies | ## **Troubleshooting** ### "No API key found" ```bash # Fix: Set a provider API key export OPENAI_API_KEY=sk-xxx ``` ### "High API costs" ```bash # Fix: Use cheaper models export PRIME_MODEL=gpt-4.1-mini export CONNECTION_MODEL=gpt-4.1-mini ``` ### "Storage connection failed" ```bash # Fix: Check database URL and credentials export DATABASE_URL=postgresql://user:pass@host:5432/dbname ``` ### "Poor memory quality" ```bash # Fix: Use higher quality models export PRIME_DEFAULT_TIER=advanced export CONNECTION_ALWAYS_ADVANCED=true ``` ### "pgvector performance issues" ```bash # Fix: Tune index parameters based on dataset export PGVECTOR_IVFFLAT_LISTS=200 # Increase for larger datasets export PGVECTOR_IVFFLAT_PROBES=20 # Increase for better accuracy ``` ### "Memory decay configuration" ```bash # Fix: Configure memory lifecycle for your use case # See Memory Lifecycle Examples section below ``` --- ## **Memory Lifecycle Configuration Examples** ### **Therapy Agent: Never Forget Critical Information** ```typescript // Critical patient information protected from decay const memory = await createMemorySystem({ environment: 'production', overrides: { lifecycle: { decayConfig: { defaultDecayRate: 0.02, // Slow decay (60 day half-life) deleteThreshold: 0.05, // Keep memories longer rules: [{ id: 'critical-info', condition: 'importance > 0.8', neverDecay: true, // Protect critical memories enabled: true }] } } } }); // Store protected memory await memory.store('user-123', 'Patient has severe allergy to penicillin', { importance: 1.0, neverDecay: true // This memory will never decay }); ``` ### **Business Agent: Fresh Data Priority** ```typescript // Recent market data prioritized, old data expires quickly const memory = await createMemorySystem({ environment: 'production', overrides: { lifecycle: { decayConfig: { defaultDecayRate: 0.1, // Fast decay (14 day half-life) deleteThreshold: 0.2, // Remove old data quickly rules: [{ id: 'recent-data', condition: 'accessCount > 5', decayRate: 0.05, // Slower decay for accessed data enabled: true }] } } } }); ``` ### **Assistant: Balanced Memory** ```typescript // Standard balanced configuration const memory = await createMemorySystem({ environment: 'production', overrides: { lifecycle: { decayConfig: { defaultDecayRate: 0.05, // 30 day half-life deleteThreshold: 0.1, rules: [{ id: 'user-preferences', condition: 'type = "semantic" AND importance > 0.7', customHalfLife: 90, // User preferences last 90 days enabled: true }] } } } }); ``` --- ## **Best Practices** 1. **Start Simple**: Use `createMemorySystem()` with no options first 2. **Environment Variables First**: Set API keys in environment, not code 3. **Pick Your Use Case**: Choose the right `recallPreset` for your domain 4. **Monitor Costs**: Start with defaults, then optimize based on usage 5. **Test Locally**: Use `environment: 'local'` for development --- ## **Related Documentation** - [Architecture Overview](./architecture-overview.md) - [Memory Connections](./memory-connections.md) --- **That's it! You now have everything you need to configure AgentDock. Start with the 3-second setup and expand as needed.** ## Memory Consolidation Guide Memory consolidation in AgentDock is an intelligent optimization system that prevents memory bloat while improving knowledge quality through automatic conversion, deduplication, and synthesis. ## What is Memory Consolidation? Memory consolidation transforms raw memories into refined knowledge through three key processes: 1. **Episodic → Semantic Conversion**: Converts time-specific experiences into general knowledge 2. **Memory Deduplication**: Finds and merges similar memories to reduce redundancy 3. **Hierarchical Abstraction**: Creates higher-level concepts from detailed memories This mirrors how human memory works - we don't remember every detail of every experience, but we extract patterns and knowledge that serve us better over time. ## Why Memory Consolidation Matters Without consolidation, memory systems face critical challenges: - **Memory Bloat**: Storing every interaction leads to exponential growth - **Redundancy**: Similar information stored multiple times - **Poor Recall**: Too many memories make finding relevant ones harder - **No Learning**: Raw events don't become actionable knowledge Consolidation solves these by creating a more efficient, intelligent memory structure. ## Resource Usage ### What Uses Server Resources Only - Database queries - CPU processing for comparisons - Memory allocation - Text concatenation ### What Costs Extra Money - LLM API calls (OpenAI) - Cloud embedding services - External API usage ## How Consolidation Works ### 1. Episodic to Semantic Conversion After a configurable age threshold (default: 7 days), important episodic memories are converted to semantic knowledge: ```mermaid flowchart LR A["Episodic Memory
User said I prefer email over phone on Jan 1"] B["Age Check
7+ days old?"] C["Importance Check
≥ 0.5?"] D["Extract Knowledge
LLM or Simple"] E["Semantic Memory
User prefers email communication"] F["Archive/Delete
Original"] A --> B B -->|Yes| C C -->|Yes| D D --> E E --> F style A fill:#ffebee style E fill:#e8f5e9 ``` **Example Conversion:** ```typescript // Before (Episodic) { type: 'episodic', content: 'During our meeting on Monday, the client mentioned they always check email first thing in the morning but rarely answer phone calls before noon', timestamp: '2024-01-01T10:30:00Z', importance: 0.7 } // After (Semantic) { type: 'semantic', content: 'Client prefers email communication and checks it first thing in the morning. Avoids phone calls before noon.', importance: 0.8, // Boosted by 0.1 metadata: { convertedFrom: 'episodic-123', conversionDate: '2024-01-08T00:00:00Z' } } ``` ### 2. Memory Deduplication The consolidator identifies and merges similar memories using multiple similarity metrics: ```mermaid flowchart TD A[Semantic Memories] B[Similarity Analysis] C{Similarity > 0.85?} D[Merge Memories] E[Create Consolidated] F[Delete Originals
Optional] A --> B B --> C C -->|Yes| D D --> E E --> F style B fill:#fff3e0 style E fill:#e1f5fe ``` **Similarity Metrics:** - **Vector Embedding Similarity**: Semantic meaning comparison - **Keyword Overlap**: Shared important terms - **Metadata Similarity**: Same categories, entities, or topics - **Temporal Proximity**: Memories created around the same time - **Temporal Pattern Matching**: Memories from similar activity patterns (daily routines, burst periods) **Example Merge:** ```typescript // Memory 1 "User prefers Python for data science projects" // Memory 2 "User likes using Python for machine learning" // Memory 3 "User mentioned Python is their go-to for analytics" // Consolidated Result "User primarily uses Python for data science, machine learning, and analytics projects" ``` ### 3. Consolidation Strategies The system supports multiple strategies that can be combined: | Strategy | Description | Use Case | Preserves Detail | |----------|-------------|----------|------------------| | **Merge** | Simple concatenation of similar content | High similarity (>0.9) | Low | | **Synthesize** | LLM creates new summary from multiple | Medium similarity (0.7-0.9) | Medium | | **Abstract** | Extract high-level patterns | Pattern recognition | Low | | **Hierarchy** | Create parent-child relationships | Categorical organization | High | ### Temporal Pattern Integration Consolidation now considers temporal patterns when grouping memories: ```typescript // Memories from the same burst period are prioritized for consolidation const burstMemories = memories.filter(m => m.metadata.temporalInsights?.patterns?.some(p => p.type === 'burst') ); // Daily patterns inform consolidation timing const dailyPatterns = getTemporalPatterns(memories, 'daily'); if (dailyPatterns.length > 0) { // Schedule consolidation during low-activity periods scheduleConsolidation(offPeakHours); } ``` **Benefits:** - **Burst Memory Consolidation**: Memories from intense activity periods are consolidated together - **Pattern-Aware Grouping**: Similar temporal patterns help identify related memories - **Optimal Timing**: Consolidation runs during low-activity periods for better performance ## Configuration ### Basic Configuration ```typescript const memoryConfig = { consolidation: { enabled: true, similarityThreshold: 0.85, // Minimum similarity for merging maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days in milliseconds preserveOriginals: false, // Delete after consolidation strategies: ['merge', 'synthesize'], batchSize: 20 // Process in batches } }; ``` ### Advanced Configuration with LLM ```typescript const advancedConfig = { consolidation: { enabled: true, similarityThreshold: 0.85, maxAge: 7 * 24 * 60 * 60 * 1000, preserveOriginals: true, // Keep originals for safety strategies: ['merge', 'synthesize', 'abstract'], batchSize: 20, enableLLMSummarization: true, // Use AI for better synthesis llmConfig: { provider: 'openai', model: 'gpt-4.1-mini', // Cost-effective model maxTokensPerSummary: 200, temperature: 0.3, // Low for consistency costPerToken: 0.0000002 } } }; ``` ## Safety and Balance ### Preventing Over-Consolidation The system includes multiple safeguards: 1. **Time Delays**: Only consolidate memories older than `maxAge` 2. **Importance Threshold**: Only memories with importance ≥ 0.5 3. **Confidence Scores**: Skip low-confidence consolidations 4. **Batch Limits**: Process small batches to prevent runaway operations 5. **Cost Controls**: Monthly budget limits for LLM usage ### Transaction Safety All consolidation operations are atomic: ```typescript try { // 1. Create consolidated memory const consolidated = await createConsolidated(memories); // 2. Store successfully await storage.setMemory(consolidated); // 3. Only then delete originals (if configured) if (!preserveOriginals) { await storage.deleteMemories(originals); } } catch (error) { // Originals remain untouched on any failure } ``` ## Cost Management ### LLM Usage Optimization The consolidator intelligently manages LLM usage: ```typescript // Skip LLM if embeddings are very similar if (embeddingSimilarity > 0.9) { return simpleTextMerge(memories); // No API calls, but uses CPU } // Cost tracking if (monthlySpend + estimatedCost > monthlyBudget) { return simpleTextMerge(memories); // Fallback to local compute only } // Use LLM only for complex synthesis return llmSynthesize(memories); ``` ### Cost Configuration ```typescript costControl: { monthlyBudget: 50.00, // $50/month limit preferEmbeddingWhenSimilar: true, // Skip LLM for high similarity maxLLMCallsPerBatch: 5, // Limit per batch trackTokenUsage: true // Monitor consumption } ``` ## Best Practices ### 1. Start Conservative Begin with high thresholds and preservation: ```typescript { similarityThreshold: 0.9, // Very similar only preserveOriginals: true, // Keep everything initially strategies: ['merge'], // Simple strategy first enableLLMSummarization: false } ``` ### 2. Monitor and Adjust Track consolidation metrics: - Number of memories consolidated - Storage space saved - Recall accuracy changes - User feedback on missing information ### 3. Schedule Wisely Run consolidation during low-activity periods: - Nightly batch jobs - After user sessions end - During maintenance windows ### 4. Test Configurations Test consolidation settings in development: ```typescript // Aggressive for testing const testConfig = { maxAge: 1 * 24 * 60 * 60 * 1000, // 1 day similarityThreshold: 0.7, // Lower threshold preserveOriginals: false // Delete originals }; ``` ## Performance Considerations ### Processing Time - **Similarity calculation**: ~5ms per memory pair - **LLM synthesis**: 500-2000ms per consolidation - **Batch of 20 memories**: 5-30 seconds total ### Storage Impact Typical consolidation ratios: - **Episodic → Semantic**: 3:1 reduction - **Deduplication**: 2:1 to 5:1 reduction - **Overall**: 60-80% storage reduction ### Memory Quality Consolidation improves retrieval: - **Faster searches**: Fewer memories to scan - **Better relevance**: Consolidated knowledge matches queries better - **Reduced noise**: Eliminates redundant information ## Integration with Memory System The consolidator integrates seamlessly with other memory components: 1. **With Decay System**: Important memories survive, trivial ones fade 2. **With Connections**: Consolidated memories maintain relationships 3. **With Search**: Better recall through refined knowledge 4. **With PRIME**: Extraction rules guide what becomes semantic ## Troubleshooting ### Common Issues 1. **Too Much Consolidation** - Increase `similarityThreshold` - Enable `preserveOriginals` - Reduce `batchSize` 2. **Not Enough Consolidation** - Decrease `maxAge` requirement - Lower `similarityThreshold` - Add more strategies 3. **High LLM Costs** - Reduce `maxLLMCallsPerBatch` - Lower `monthlyBudget` - Use simpler model ## Summary Memory consolidation is a powerful feature that: - Prevents memory bloat through intelligent optimization - Improves knowledge quality through synthesis - Reduces costs through deduplication - Maintains system performance at scale When configured properly, it creates a self-organizing memory system that gets better over time - just like human memory. ## Memory Graph Architecture > **Technical documentation for developers and architects** This document provides the technical rationale and implementation details behind AgentDock's decision to use a hybrid SQL + in-memory graph approach instead of a dedicated graph database. ## Executive Summary AgentDock implements a hybrid approach to memory connections, combining relational database persistence with in-memory graph operations. This architecture provides graph-like functionality while maintaining the operational simplicity of traditional databases. ## Technical Overview Rather than using a dedicated graph database (Neo4j, ArangoDB, etc.), AgentDock stores memory connections in relational tables and performs graph operations through a combination of SQL recursive CTEs and in-memory algorithms. This approach balances performance, reliability, and operational complexity. ## Why We Chose SQL Over Graph Databases: Technical Analysis ### 1. Scale Reality Check **Agent Memory Characteristics:** ``` - Nodes per agent: 100-10,000 memories - Edges per node: 2-10 connections average - Graph diameter: 3-5 hops typical - Cross-agent queries: None (isolated graphs) - Update frequency: ~1-10 Hz per agent ``` **Conclusion**: These are tiny graphs by graph database standards. Facebook's social graph has billions of nodes with thousands of edges each. Our use case is 6-7 orders of magnitude smaller. ### 2. Query Pattern Analysis **Our Actual Query Needs:** - 90% queries: Direct connections (1 hop) - 9% queries: 2-3 hop traversals - 1% queries: Complex patterns - 0% queries: Global graph algorithms **SQL Performance for These Patterns:** - 1 hop: Native JOIN - extremely fast - 2-3 hops: Recursive CTE - still fast - Complex: Load subgraph to memory - acceptable ### 3. Operational Cost-Benefit **Graph Database Hidden Costs:** - Separate infrastructure management - Specialized backup/restore procedures - Limited cloud provider support - Requires graph query expertise - Complex high availability setup - Vendor lock-in concerns **SQL Advantages We Leverage:** - Runs on existing PostgreSQL/SQLite - Standard backup/restore tools - Available on all cloud providers - SQL expertise is ubiquitous - Built-in HA solutions - No vendor lock-in ### 4. Feature Requirements Analysis **What We Actually Need:** - Store connections with metadata (type, strength, reason) - Traverse relationships 1-3 levels deep - Combine with vector similarity search - Maintain ACID consistency - Handle 100-10,000 memories per agent - Support user-isolated graphs **What We Don't Need:** - Complex graph algorithms (PageRank, community detection) - Massive parallel graph processing - Cross-user graph traversal - Real-time graph updates at scale - Billions of nodes/edges - Sub-millisecond traversal of deep graphs ## Architecture Components ### 1. Relational Storage Layer Memory connections are persisted in standard relational tables: ```mermaid erDiagram memories { uuid id PK text content vector embedding float importance timestamp created_at } memory_connections { uuid id PK uuid source_memory_id FK uuid target_memory_id FK enum connection_type float strength text reason } memories ||--o{ memory_connections : has_source memories ||--o{ memory_connections : has_target ``` **Actual SQL Schema:** ```sql CREATE TABLE memory_connections ( id UUID PRIMARY KEY, source_memory_id UUID REFERENCES memories(id), target_memory_id UUID REFERENCES memories(id), connection_type ENUM('similar', 'related', 'causes', 'part_of', 'opposite'), strength FLOAT, -- 0.0 to 1.0 reason TEXT, -- Why this connection exists created_at TIMESTAMP, -- Ensure unique connections UNIQUE(source_memory_id, target_memory_id), -- Indexes for fast lookups INDEX idx_source (source_memory_id, strength DESC), INDEX idx_target (target_memory_id, strength DESC) ); ``` ### 2. SQL-Based Graph Traversal For simple graph operations, we use SQL recursive Common Table Expressions (CTEs): **Direct Connection Query:** ```sql -- Find direct connections (1 hop) SELECT m.* FROM memories m JOIN memory_connections mc ON m.id = mc.target_memory_id WHERE mc.source_memory_id = :memory_id AND mc.strength > 0.5 ORDER BY mc.strength DESC; ``` **Multi-Hop Traversal:** ```sql -- Find all memories connected within 3 hops WITH RECURSIVE connected_memories AS ( -- Base case: direct connections SELECT target_memory_id as memory_id, 1 as depth, strength FROM memory_connections WHERE source_memory_id = :starting_memory_id UNION ALL -- Recursive case: connections of connections SELECT mc.target_memory_id, cm.depth + 1, cm.strength * mc.strength as combined_strength FROM memory_connections mc JOIN connected_memories cm ON mc.source_memory_id = cm.memory_id WHERE cm.depth < 3 ) SELECT DISTINCT * FROM connected_memories ORDER BY combined_strength DESC; ``` **Alternative Multi-Hop Query (from original implementation):** ```sql -- Multi-hop traversal using recursive CTE WITH RECURSIVE connected AS ( SELECT target_memory_id, strength, 1 as depth FROM memory_connections WHERE source_memory_id = :memory_id UNION ALL SELECT mc.target_memory_id, c.strength * mc.strength, c.depth + 1 FROM memory_connections mc JOIN connected c ON mc.source_memory_id = c.target_memory_id WHERE c.depth < 3 ) SELECT * FROM connected WHERE strength > 0.3; ``` ### 3. In-Memory Graph Engine For complex graph algorithms, we load relevant subgraphs into memory: ```mermaid graph LR A[SQL Database] -->|Load Subgraph| B[ConnectionGraph] B --> C[BFS Traversal] B --> D[Shortest Path] B --> E[Cluster Detection] B --> F[Centrality Analysis] style B fill:#f9f,stroke:#333,stroke-width:2px ``` **ConnectionGraph Implementation:** ```typescript class ConnectionGraph { // Basic operations addNode(id: string, metadata: any): void addEdge(from: string, to: string, type: string, strength: number): void // Path finding findPath(from: string, to: string): string[] getConnectionPath(sourceId: string, targetId: string): string[] // Graph analysis detectCommunity(nodeId: string): Set
Character count: 87"] C["Fast Tier Selected
< 100 characters
gpt-4.1-mini"] D["Extract Memories
with Zod validation"] end subgraph "Four Memory Types Created" E["Working Memory
'Current cooking conversation'"] F["Episodic Memory
'Made risotto again, too much wine'"] G["Semantic Memory
'User cooks risotto, learning wine balance'"] H["Procedural Memory
'When wine too strong → reduce amount next time'"] end subgraph "Memory Connections" I["MemoryConnectionManager
Progressive Enhancement:
• Embedding similarity
• User-defined rules
• LLM analysis
• Temporal patterns"] end A --> B B --> C C --> D C --> E C --> F C --> G C --> H E --> I F --> I G --> I H --> I ``` **The Four-Layer Architecture** ensures each type of information is stored optimally: - **Working Memory** maintains conversation context - **Episodic Memory** preserves the specific experience - **Semantic Memory** extracts general knowledge - **Procedural Memory** learns patterns for future recommendations See [Architecture Overview](./architecture-overview.md) for complete technical details. ## Storage Architecture AgentDock follows a **configurable storage strategy** optimized for different environments: ### **Why SQL + In-Memory Instead of Graph Databases?** AgentDock deliberately uses a **hybrid SQL + in-memory graph approach** rather than dedicated graph databases (Neo4j, ArangoDB). This architectural decision provides graph-like functionality while maintaining operational simplicity: - **No additional infrastructure** - Works with your existing PostgreSQL or SQLite database - **Optimized for agent scale** - Perfect for 100-10,000 memories per agent (not billions like social networks) - **Fast common queries** - Most agent queries are 1-3 hops, where SQL performs excellently - **Operational simplicity** - Standard backup, monitoring, and deployment procedures For the complete technical analysis of this decision, see [Graph Architecture Deep-Dive](./graph-architecture.md). ```mermaid graph TB subgraph "Development" A["SQLite + sqlite-vec
Zero-configuration setup
Local vector search
Perfect for prototyping"] end subgraph "Production" B["PostgreSQL + pgvector
Production-grade performance
ACID compliance
Optimized for memory operations"] end subgraph "Memory Layer" C["MemoryManager"] D["Memory Types"] E["Connection Discovery"] end subgraph "Configuration" F["User Configs"] end A --> C B --> C C --> D C --> E F --> C ``` ## Core Features ### **Research-Based Design** Based on established cognitive science principles, AgentDock implements proven memory concepts: - **Spreading Activation**: Related memories activate automatically - **Episodic-Semantic Interdependence**: Experiences become general knowledge over time - **Connection Types**: Grounded in semantic network theory (similar, causal, temporal, hierarchical) See [Research Foundations](./research-foundations.md) for scientific background. ### **PRIME Extraction System** Intelligent, cost-optimized memory extraction: - **Character-based tier selection**: Automatically routes to optimal model (standard/advanced) - **Budget controls**: Monthly spending limits and usage tracking - **Validated output**: Type-safe memory creation with Zod schema validation - **Graceful degradation**: Falls back to pattern-based extraction when needed ### **Progressive Memory Connections** Multi-tier relationship discovery that balances cost and capability: 1. **Embedding similarity**: Vector-based semantic relationships 2. **User-defined rules**: Custom pattern matching for domain logic 3. **LLM enhancement** (optional): AI-powered deep relationship analysis 4. **Temporal patterns**: Time-based connection heuristics Uses hybrid SQL + in-memory graph approach for simplicity without sacrificing functionality. See [Memory Connections Guide](./memory-connections.md) for details and [Graph Architecture](./graph-architecture.md) for technical implementation. ### **Conversational RAG** Infrastructure-level retrieval-augmented generation: - **Hybrid search**: Research-validated 30% text + 70% vector prevents failure modes - **Four-dimensional fusion**: Vector + text + temporal + procedural relevance scoring - **Automatic injection**: Agent runtime integration without manual prompt construction See [Conversational RAG Guide](./retrieval-augmented-generation.md) for complete implementation details. ### **Memory Recall Presets** Ready-made configurations for different agent types: - **Default**: Balanced for general-purpose applications - **Precision**: Exact terminology for medical/legal/financial agents - **Performance**: Optimized for high-volume customer support - **Research**: Enhanced connection discovery for analysis and content discovery ### **Production-Ready Architecture** - **Configurable memory decay**: Human-like forgetting with rule-based protection - **Specialized memory adapters**: Production-ready implementations for PostgreSQL (pgvector) and SQLite. - **Community-extensible adapters**: Base classes available for ChromaDB, Pinecone, and Qdrant. - **User isolation**: Complete data separation with proper security - **Cost tracking**: Built-in monitoring and budget controls See [Architecture Overview](./architecture-overview.md) for complete technical reference. ## Use Cases AgentDock memory enables agents that learn and evolve across conversations: ### **Customer Support Evolution** **Day 1**: Customer reports account lock issue **Day 15**: "Hi, it's John again, different issue with billing" **Agent Response**: "Hi John! I see you had an account issue before. How can I help with billing?" The agent recalls previous interactions, communication preferences, and successful resolution patterns. ### **Coaching Agent Development** **Session 1**: User reports stress, sleep issues, recent divorce **Session 5**: User shares presentation success and exercise progress **Agent Learning**: Connects stress patterns to life changes, identifies effective coping strategies, reinforces positive behaviors **Procedural Memory Development**: - When user reports anxiety → suggest proven breathing exercises - When presentations mentioned → recall past successes - When progress reported → reinforce positive patterns ### **Research Assistant Growth** **Month 1**: Tracks literature on specific topics **Month 3**: Identifies patterns across research domains **Month 6**: Suggests novel connections and research directions based on accumulated knowledge See detailed implementation examples in [Architecture Overview](./architecture-overview.md). ## Quick Start ### **Simple Setup with Presets** ```typescript import { createMemorySystem } from 'agentdock-core'; // Development setup const memory = await createMemorySystem({ environment: 'local' }); // Production with preset optimization const memory = await createMemorySystem({ environment: 'production', recallPreset: 'precision', // For medical/legal/financial databaseUrl: process.env.DATABASE_URL }); // Two primary methods for adding memories: // METHOD 1: Manual Direct Storage (bypasses PRIME extraction) // Use when you know exactly what memory to create const manualMemoryId = await memoryManager.store( 'user-123', 'agent-456', 'User prefers dark mode interfaces', MemoryType.SEMANTIC // or 'semantic' string ); // METHOD 2: Automatic PRIME Extraction (AI-powered) // Processes messages to intelligently extract multiple memories const extractedMemories = await memory.addMessage('user-123', { id: 'msg-789', agentId: 'agent-456', content: 'I prefer email notifications over SMS and usually check my email in the morning', role: 'user', timestamp: Date.now() }); // Returns array of memories extracted by AI // Advanced: Batch conversation processing with PRIME import { PRIMEOrchestrator } from 'agentdock-core'; const result = await primeOrchestrator.processMessages( 'user-123', 'agent-456', conversationMessages // Array of messages ); // Advanced: Historical memory injection with custom timestamps // Note: Custom timestamps only work with vector-enabled storage const historicalMemoryId = await memoryManager.store( 'user-123', 'agent-456', 'User completed onboarding last year', MemoryType.EPISODIC, { timestamp: Date.now() - (365 * 24 * 60 * 60 * 1000) } ); ``` ### **Storage Options** - **Development**: SQLite + sqlite-vec (zero configuration) - **Production**: PostgreSQL + pgvector (managed service compatible) - **Alternative**: ChromaDB, Pinecone, Qdrant adapters available ### **Memory Recall Presets** - **Default**: Balanced for general use - **Precision**: Exact terminology (medical, legal, financial) - **Performance**: High-volume customer support - **Research**: Enhanced connection discovery See [Architecture Overview](./architecture-overview.md) for detailed configuration examples and deployment guides. ## Memory Architecture Details ### **Four-Layer Memory System** - **Working Memory**: Recent conversation context (immediate access, TTL-based) - **Episodic Memory**: Time-ordered experiences with temporal decay - **Semantic Memory**: Knowledge and facts with confidence scoring - **Procedural Memory**: Learned patterns with reinforcement-based evolution Each layer has specific configuration options for retention, decay rates, confidence thresholds, and learning parameters. See [Architecture Overview](./architecture-overview.md) for complete configuration reference. ## Memory Lifecycle Management **Lazy Memory Decay**: Efficient on-demand decay calculation that scales with usage, not data size - **65-100% write avoidance**: Only update memories that are actually accessed - **Exponential decay formula**: Human-like forgetting with configurable half-lives - **Rule-based protection**: Prevent critical information from decaying (neverDecay flag) - **Access reinforcement**: Frequently recalled memories stay strong - **Automatic cleanup**: Remove memories below relevance threshold - **No scheduled jobs**: Eliminates batch processing failures and resource bottlenecks Example configurations: Never decay medical allergies, slow decay for user preferences (90 days), faster decay for casual conversations (7 days). **Performance Benefits**: - Scales with memory access patterns, not total memory count - Sub-second processing for typical workloads - Eliminates the scalability bottleneck of processing millions of memories daily See [Architecture Overview](./architecture-overview.md) for complete decay configuration examples. ## Memory Connections **Progressive relationship discovery** that potentially revolutionizes how agents understand context: ### **Connection Types** - **Similar**: Semantically related content (stress patterns, topic clustering) - **Causal**: One thing leads to another (actions → outcomes) - **Temporal**: Time-based relationships (events before/after patterns) - **References**: Explicit mentions and callbacks - **Hierarchical**: Part-of relationships (details → concepts) ### **Discovery Process** 1. **Embedding similarity**: Vector-based semantic relationships 2. **User-defined rules**: Custom pattern matching for domain logic 3. **LLM analysis** (optional): AI-powered deep relationship discovery 4. **Temporal patterns**: Time-based connection heuristics ### **Real-World Impact** **Month 1**: Agent handles individual queries **Month 6**: "I remember this pattern... Your parents visit in 2 weeks. How are you and Lisa doing? I know family stress affects how you interact." The agent learns to connect stress patterns, relationship dynamics, and temporal cues for contextual understanding. See [Memory Connections Guide](./memory-connections.md) for detailed examples and [Graph Architecture](./graph-architecture.md) for technical implementation. ## Production Deployment ### **Development Setup** - **SQLite + sqlite-vec**: Zero-configuration local development - **Automatic vector search**: Built-in embedding support - **Simple installation**: Works with existing SQLite tooling ### **Production Setup** - **PostgreSQL + pgvector**: Enterprise-grade vector search - **Managed service compatible**: Works with RDS, Supabase, Neon - **Optimized indexing**: IVFFlat and HNSW support for large datasets - **Connection pooling**: Efficient resource management See [Architecture Overview](./architecture-overview.md) for complete deployment guides, database setup instructions, and production optimization examples. ## Security and Performance ### **Data Protection** - **User isolation**: Complete data separation with database-level user ID constraints - **Session scoping**: Working memory isolated by session ID - **Configurable encryption**: PostgreSQL field-level encryption support - **Memory decay**: Automatic cleanup of old memories based on relevance thresholds ### **Performance Characteristics** - **Retrieval speed**: Sub-100ms for typical queries (100-10,000 memories per user) - **Vector search**: Optimized with configurable similarity thresholds - **Caching**: Built-in result caching with configurable TTL - **Batch processing**: Efficient bulk operations for large conversations ### **Production Considerations** This is an open-source framework. Users are responsible for: - Authentication and authorization implementation - API key and database credential security - Network security and access controls - Regular security audits and monitoring ### **Architecture Philosophy** **Configurable Determinism**: Reliable, predictable behavior with intelligent fallbacks - Consistent memory recall based on configured parameters - AI-powered processing with pattern-based fallbacks - User-controlled behavior through comprehensive configuration - Cost tracking and budget controls throughout the system --- ## Documentation Navigation - **[Complete Configuration Guide](./complete-configuration-guide.md)** - **START HERE** - ALL configuration options including 2-tier models, storage, presets, and environment variables - **[Architecture Overview](./architecture-overview.md)** - Technical architecture and implementation details - **[Conversational RAG](./retrieval-augmented-generation.md)** - RAG implementation and hybrid retrieval strategy - **[Memory Connections](./memory-connections.md)** - **INCLUDES TLDR** - Complete guide to connection discovery with simplified overview - **[Graph Architecture](./graph-architecture.md)** - Technical implementation of connection system - **[Memory Consolidation](./consolidation-guide.md)** - Memory optimization and lifecycle management - **[Research Foundations](./research-foundations.md)** - Scientific background and cognitive science principles --- **The AgentDock Memory System transforms AI agents from stateless tools into intelligent, learning companions with human-like memory capabilities.** ## Research Foundations of Memory Connections > **Scientific basis for AgentDock's memory connection system** AgentDock's memory architecture is informed by established cognitive science principles on how human memory works. This document explains the theoretical foundations behind our design decisions. ## Core Research Principles ### 1. Spreading Activation Theory Based on **Collins & Loftus (1975)**, memories are interconnected nodes that activate related memories when accessed. ```mermaid graph TD A[Activated Memory:
'Customer complaint'] --> B[Related Memory:
'Product issue'] A --> C[Similar Memory:
'Support ticket'] B --> D[Causal Memory:
'Bug fix deployed'] C --> E[Part-of Memory:
'Q3 feedback summary'] style A fill:#ff9999,stroke:#333,stroke-width:3px style B fill:#ffcc99,stroke:#333,stroke-width:2px style C fill:#ffcc99,stroke:#333,stroke-width:2px style D fill:#fff0cc,stroke:#333,stroke-width:1px style E fill:#fff0cc,stroke:#333,stroke-width:1px ``` **Key Insight**: When one memory is activated, related memories become more accessible through spreading activation. ### 2. Episodic-Semantic Interdependence **Tulving (1972)** established the distinction between: - **Episodic Memory**: Time-stamped personal experiences - **Semantic Memory**: General knowledge and facts **Greenberg & Verfaellie (2010)** showed these systems are interdependent: ```mermaid flowchart LR subgraph "Episodic Memories" E1["Met client at conference"] E2["Client mentioned AI needs"] E3["Follow-up call scheduled"] end subgraph "Semantic Knowledge" S1["Client works in healthcare"] S2["Healthcare AI compliance rules"] S3["Our AI solutions portfolio"] end E1 -.->|extracts| S1 E2 -.->|enriches| S2 S3 -.->|informs| E3 style E1 fill:#e1f5fe,stroke:#01579b style E2 fill:#e1f5fe,stroke:#01579b style E3 fill:#e1f5fe,stroke:#01579b style S1 fill:#f3e5f5,stroke:#4a148c style S2 fill:#f3e5f5,stroke:#4a148c style S3 fill:#f3e5f5,stroke:#4a148c ``` ### 3. Conceptual Graphs **Sowa (1984)** formalized knowledge representation using typed relationships: ```mermaid graph TB subgraph "Connection Types (Research-Based)" A[Memory Node] -->|similar| B[Semantic Similarity] A -->|causes| C[Causal Relationship] A -->|part_of| D[Hierarchical Structure] A -->|opposite| E[Contradictory Information] A -->|related| F[General Association] end ``` ## How Research Informs Our Design ### Connection Discovery Pipeline Our progressive enhancement approach follows the cognitive principle of **graded activation**: ```mermaid flowchart TD A[New Memory] --> B{Embedding
Similarity} B -->|High Similarity| C[Strong Connection] B -->|Medium| D{Apply
User Rules} B -->|Low| E{LLM
Analysis} D -->|Match| C D -->|No Match| E E -->|Found| C E -->|None| F[No Connection] style B fill:#90caf9,stroke:#1565c0 style D fill:#fff59d,stroke:#f57f17 style E fill:#ffab91,stroke:#d84315 ``` 1. **Fast Path** (Embedding): Like automatic memory associations 2. **Rule Path** (User Rules): Like learned patterns 3. **Deep Path** (LLM): Like conscious reasoning ### 4. Temporal Pattern Detection Our system implements practical temporal pattern analysis to identify usage patterns and memory activity clustering: **Conway (2009)** provided insights into episodic memory structure that inform our approach to temporal pattern detection. ```mermaid gantt title Memory Activity Patterns (Research-Based) dateFormat HH:mm axisFormat %H:%M section Daily Pattern Morning standup :active, 09:00, 30m Code review :10:30, 45m Afternoon debug :14:00, 90m section Burst Detection Incident response :crit, 16:00, 120m Related memories :active, 16:30, 90m section Temporal Clustering Learning session :done, 11:00, 2h Follow-up practice :done, 13:30, 1h ``` **Key Insights:** - **Burst periods** of high activity strengthen memory formation - **Daily patterns** reflect natural cognitive rhythms - Temporal proximity influences connection strength - Pattern detection enables intelligent memory organization ## Scientific Validation Our approach aligns with established cognitive principles: | Principle | Research | Our Implementation | |-----------|----------|-------------------| | **Connection Networks** | Collins & Loftus, 1975 | Multi-hop graph traversal | | **Semantic Networks** | Sowa, 1984 | Typed connection relationships | | **Memory Interdependence** | Greenberg & Verfaellie, 2010 | Episodic→Semantic promotion | | **Temporal Patterns** | Conway, 2009 | Activity pattern detection | ## Key Insights for Developers 1. **Not Random**: Connection types based on established cognitive science principles 2. **Biologically Inspired**: Mimics human memory organization 3. **Computationally Efficient**: Leverages known patterns from cognitive science 4. **Proven Effective**: These principles power human intelligence ## References - Collins, A. M., & Loftus, E. F. (1975). A spreading-activation theory of semantic processing. *Psychological Review*, 82(6), 407-428. - Conway, M. A. (2009). Episodic memories. *Neuropsychologia*, 47(11), 2305-2313. - Greenberg, D. L., & Verfaellie, M. (2010). Interdependence of episodic and semantic memory. *Journal of the International Neuropsychological Society*, 16(5), 748-753. - Sowa, J. F. (1984). *Conceptual Structures: Information Processing in Mind and Machine*. Addison-Wesley. - Tulving, E. (1972). Episodic and semantic memory. In *Organization of memory* (pp. 381-403). Academic Press. ## Related Documentation - **[Memory Connections](./memory-connections.md)** - See these research principles implemented in AgentDock's connection system - **[Graph Architecture](./graph-architecture.md)** - Technical implementation of spreading activation and semantic networks - **[Architecture Overview](./architecture-overview.md)** - How the four-layer memory system reflects cognitive science principles ## AgentDock: Conversational Retrieval-Augmented Generation (RAG) > The AgentDock Recall Service implements **Conversational RAG** (Retrieval-Augmented Generation) specifically optimized for agent memory and real-time knowledge augmentation. AgentDock implements a sophisticated **Conversational Retrieval-Augmented Generation (RAG)** system specifically optimized for agent memory and real-time knowledge augmentation. Unlike traditional document-based RAG systems, AgentDock provides dynamic memory retrieval that evolves with ongoing conversations. ## What is RAG? **Retrieval-Augmented Generation (RAG)** enhances Large Language Models (LLMs) by: 1. **Retrieving** relevant information from a knowledge base 2. **Augmenting** the LLM prompt with retrieved context 3. **Generating** responses informed by both the model's training and retrieved knowledge Traditional RAG focuses on static document retrieval. AgentDock implements **Conversational RAG** with dynamic, personalized memory. ## How to Choose the Right Memory Configuration AgentDock provides ready-made presets so you don't have to guess at the right settings: ### **When to Use Each Preset:** **Default Preset** - Start here for most applications: - General-purpose conversational agents - Mixed content types (questions, facts, casual chat) - When you're not sure what your agent will primarily handle **Precision Preset** - When exactness matters: - Medical agents (drug names, dosages, symptoms) - Legal assistants (case citations, statutes, regulations) - Financial advisors (account numbers, tax codes, regulations) - Technical support (error codes, product models, procedures) **Performance Preset** - When speed matters: - High-volume customer support - Real-time chat applications - Simple FAQ bots - When you need fast responses over deep understanding **Research Preset** - When connections and insights matter: - Academic research assistants - Content discovery and analysis - Creative writing helpers - Strategic planning and brainstorming ### **Simple Usage Examples:** ```typescript // Medical assistant - use precision for exact terminology const medicalMemory = await createMemorySystem({ environment: 'production', recallPreset: 'precision', databaseUrl: process.env.DATABASE_URL }); // Customer support - use performance for speed const supportMemory = await createMemorySystem({ recallPreset: 'performance' }); // Research assistant - use research for connections const researchMemory = await createMemorySystem({ recallPreset: 'research', overrides: { recall: { minRelevanceThreshold: 0.1 // Even more permissive for discovery } } }); ``` ## AgentDock's RAG Architecture ```mermaid graph TB subgraph "AgentDock Recall Service (Conversational RAG Pipeline)" A["User Query"] --> B["RecallService.recall()"] B --> C["4-Layer Memory Search"] subgraph "Parallel Memory Retrieval" C --> D["Working Memory"] C --> E["Episodic Memory"] C --> F["Semantic Memory"] C --> G["Procedural Memory"] end subgraph "Hybrid Search (30% Text + 70% Vector)" D --> H["Text + Vector Fusion"] E --> H F --> H G --> H end subgraph "Memory Fusion & Enhancement" H --> I["Apply Hybrid Scoring"] I --> J["Enhance with Connections"] J --> K["Filter by Relevance"] K --> L["Apply Limits"] end L --> M["Ranked Memory Results"] M --> N["Agent Runtime Injection"] N --> O["Memory-Enhanced Response"] end ``` ### **Hybrid Retrieval Strategy (RAG-Enhanced Recall)** The AgentDock Recall Service uses **hybrid search** combining: - **70% Vector Search**: Semantic understanding for conceptual queries - **30% Text Search**: Exact matching for precise terms, codes, names This split aligns with natural query patterns: ~75% of user queries benefit from semantic understanding, while ~25% require exact matching for critical precision (medical dosages, error codes, legal citations). #### Implementation Details **PostgreSQL**: Weighted score fusion with 70%/30% default weights: ```sql SELECT *, (0.7 * vector_similarity + 0.3 * text_score) as combined_score ``` **SQLite**: Reciprocal Rank Fusion (RRF) with k=60 constant: ```typescript const score = vectorWeight * (1 / (60 + vectorRank)) + textWeight * (1 / (60 + textRank)) ``` ## AgentDock vs Traditional RAG | Aspect | Traditional RAG | AgentDock Conversational RAG | |--------|-----------------|-------------------------------| | **Knowledge Source** | Static documents | Dynamic 4-layer memory system | | **Retrieval Strategy** | Document chunks | Memory types + connections | | **Context Awareness** | Query-level | Conversation-level | | **Learning** | No learning | Continuous memory formation | | **Personalization** | Generic responses | Agent-specific knowledge | | **Connection Discovery** | None | Progressive memory linking | | **Search Method** | Vector-only/Text-only | Hybrid retrieval (30-70 split) | ## Four-Layer Memory Fusion The RecallService implements sophisticated memory fusion combining different relevance signals: ```typescript // Configurable weights for hybrid scoring hybridSearchWeights: { vector: 0.4, // Semantic similarity text: 0.3, // Exact text matching temporal: 0.2, // Time-based relevance procedural: 0.1 // Pattern matching } ``` Each memory type contributes specialized knowledge: - **Working Memory**: Recent conversation context - **Episodic Memory**: Time-ordered experiences with temporal relevance - **Semantic Memory**: Facts and knowledge with confidence weighting - **Procedural Memory**: Learned patterns with success rate scoring SQL adapters handle the storage layer independently: - PostgreSQL uses weighted score fusion for optimal performance - SQLite uses RRF (Reciprocal Rank Fusion) for consistent ranking - All adapters support the same memory operations interface ### **Memory Connections (Graph RAG)** AgentDock enhances retrieved memories with stored connections: - **Embedding similarity**: Vector-based semantic relationships - **User-defined rules**: Custom pattern matching - **LLM enhancement**: AI-powered relationship discovery - **Temporal patterns**: Time-based connection heuristics ## Conversational RAG Benefits Unlike document RAG that treats each query independently, AgentDock maintains conversational context: **Traditional Document RAG**: ``` Query: "How do I reset my password?" → Retrieves: Generic password reset documentation → Response: Standard password reset instructions ``` **AgentDock Conversational RAG**: ``` Query: "How do I reset my password?" → Retrieves: User's previous login issues + current account status + successful solutions → Response: "I see you had trouble with two-factor auth last time. Let me walk you through the reset process that worked for your account setup..." ``` ## Production Use Cases ### **Customer Support RAG** ```typescript // Agent recalls customer history, preferences, and previous solutions const memories = await recallService.recall({ userId: 'customer_123', agentId: 'support_agent', query: 'billing issue', memoryTypes: [MemoryType.EPISODIC, MemoryType.PROCEDURAL] }); // Result: Previous billing conversations + successful resolution patterns ``` ### **Code Assistant RAG** ```typescript // Agent remembers project context, coding patterns, and debugging history const memories = await recallService.recall({ userId: 'developer_456', agentId: 'code_assistant', query: 'database connection error', memoryTypes: [MemoryType.SEMANTIC, MemoryType.PROCEDURAL] }); // Result: Project-specific database config + proven debugging steps ``` ### **Research Assistant RAG** ```typescript // Agent builds on previous research, tracks sources, and connects findings const memories = await recallService.recall({ userId: 'researcher_789', agentId: 'research_assistant', query: 'climate change adaptation strategies', memoryTypes: [MemoryType.SEMANTIC, MemoryType.EPISODIC], includeRelated: true }); // Result: Previously researched papers + related findings + source connections ``` ## Implementation: RAG Through Agent Runtime Integration AgentDock implements conversational RAG through automatic memory injection at the agent runtime level: ```typescript // Agent automatically enhances system prompts with recalled memories const memoryRecall = await recallService.recall({ userId: options.userId, agentId: this.id, query: messages[messages.length - 1].content, limit: 10 }); // Automatic context augmentation if (memoryRecall.conversationContext) { finalSystemPrompt = `${finalSystemPrompt}\n\nPrevious conversation context:\n${memoryRecall.conversationContext}`; } if (memoryRecall.memories && memoryRecall.memories.length > 0) { const memoryContext = memoryRecall.memories.map(m => `- ${m.content}`).join('\n'); finalSystemPrompt = `${finalSystemPrompt}\n\nRelevant memories:\n${memoryContext}`; } ``` This provides **infrastructure-level RAG** where: - **Retrieval**: RecallService performs hybrid search across 4 memory layers - **Augmentation**: Agent runtime automatically injects memories into system prompt - **Generation**: LLM receives enhanced context without manual prompt construction The agent naturally incorporates memory context without requiring explicit RAG instructions, creating seamless conversational continuity. ### **Advanced RAG Features** - **Multi-Agent RAG**: Coordinated memory sharing across agents - **Federated RAG**: Privacy-preserving distributed memory - **Real-time RAG**: Streaming memory updates during conversations - **Contextual RAG**: Session-aware memory retrieval - **Connection-enhanced RAG**: Graph-like memory relationships ## Mathematical Foundation: Why BEIR Benchmarks Align Well with 30-70 Split The 30% text + 70% vector configuration emerges from BEIR benchmark analysis that aligns well with natural query patterns: **Query Distribution Analysis** (verified across multiple studies): - 25% of queries require exact matching (medical codes, legal citations, error codes) - 75% benefit from semantic understanding (conceptual questions, natural language) **BEIR Benchmark Performance** (calculated from 18 diverse datasets): - Text search advantage on exact-match tasks: +10.7% average - Vector search advantage on semantic tasks: +16.7% average - 30-70 configuration balances both query types effectively **Practical Robustness**: - Prevents catastrophic failures on most specialized domains - BEIR benchmarks show consistent hybrid search advantages - Production systems benefit from balanced approach over pure methods - Some extreme cases (like Touche-2020 arguments) may still show degradation, demonstrating the value of configurable weights ## Conclusion AgentDock represents the next evolution of RAG technology: **Conversational Retrieval-Augmented Generation**. By focusing on dynamic, personalized memory rather than static document retrieval, AgentDock enables agents that truly learn and grow with each interaction. Unlike traditional RAG systems optimized for knowledge lookup, AgentDock's memory-augmented generation creates agents with persistent, evolving understanding that improves through continued interaction. **Key Advantages**: - **Conversational continuity** through persistent memory - **Production-ready** hybrid retrieval with managed service compatibility - **BEIR benchmark validation** with consistent hybrid search advantages - **Enterprise scalability** with configurable performance tiers - **Zero infrastructure overhead** - works with existing PostgreSQL/SQLite - **Enhanced relevance** with temporal patterns and configurable connection traversal AgentDock transforms RAG from a document lookup system into an intelligent memory companion for conversational AI. Enhanced with temporal patterns and configurable connection traversal - see [Memory Connections](./memory-connections.md) for advanced recall features. ## See Also - [Memory Architecture Overview](./architecture-overview.md) - Complete technical reference - [Memory Connections Guide](./memory-connections.md) - User-friendly relationship explanation - [Graph Architecture Deep-Dive](./graph-architecture.md) - SQL vs graph database analysis - [Research Foundations](./research-foundations.md) - Scientific background and validation ## Custom Node Development This guide explains how to create custom nodes for AgentDock Core. ## Overview AgentDock provides two main approaches to extending its capabilities through custom nodes: 1. **Core Extension**: Extending BaseNode from AgentDock Core (covered in this guide) 2. **Tool Implementation**: Creating tools in the open source reference implementation (see [Custom Tool Development](./custom-tool-development.md)) ## Advanced Node Development For extending the AgentDock Core directly: ### Extending BaseNode ```typescript import { BaseNode, NodeMetadata, NodePort } from 'agentdock-core'; import { NodeCategory } from 'agentdock-core/types/node-category'; interface MyNodeConfig { parameter: string; } export class MyCustomNode extends BaseNode
< 5ms overhead] F --> G[Async Queue] G --> H[Batch Processor] H --> I[Time-Series Storage] end subgraph "Analytics & Insights" I --> J[Real-time Metrics] I --> K[Historical Analysis] I --> L[Predictive Insights] J --> M[Traceability Dashboard] K --> M L --> M end subgraph "Integration Points" N[WorkflowLearningService] --> E O[TemporalPatternAnalyzer] --> E P[MemoryConnectionManager] --> E Q[PRIMEExtractor] --> E end ``` ## Core Tracking Capabilities ### Evolution Event Structure ```typescript interface MemoryEvolutionEvent { // Core identification id: string; memoryId: string; userId: string; agentId: string; timestamp: number; // Change details changeType: MemoryChangeType; previousValue: any; newValue: any; // Context and reasoning source: string; // Component that triggered change reason: string; // Human-readable explanation // Performance and cost tracking metadata?: { cost?: number; duration?: number; llmUsed?: boolean; modelTier?: 'standard' | 'advanced'; [key: string]: any; }; } ``` ### Comprehensive Change Types - **`creation`**: New memory extracted or manually created - **`update`**: Content or metadata modifications - **`importance`**: Importance score adjustments - **`resonance`**: Decay or reinforcement events - **`consolidation`**: Memories merged or synthesized - **`connection`**: New relationships discovered - **`type_change`**: Episodic → Semantic conversions - **`archival`**: Memory moved to cold storage - **`access`**: Recall events that may trigger changes ## Integration with Existing Systems ### WorkflowLearningService Integration Track how procedural patterns evolve and improve: ```typescript // Automatic tracking when patterns are learned await this.evolutionTracker.trackEvolution(pattern.id, { changeType: 'creation', source: 'WorkflowLearningService', reason: `New ${pattern.sequence.length}-step pattern learned from successful execution`, metadata: { successRate: pattern.successRate, toolSequence: pattern.sequence.map(t => t.tool), averageDuration: pattern.avgDuration } }); ``` ### Temporal Pattern Enhancement Leverage underutilized temporal analysis for richer insights: ```typescript // Track temporal pattern discoveries const patterns = await this.temporalAnalyzer.analyzePatterns(agentId); const activityClusters = await this.temporalAnalyzer.detectActivityClusters(agentId); // Store pattern insights for evolution tracking await this.evolutionTracker.trackBatch(patterns.map(pattern => ({ memoryId: `temporal:${agentId}:${pattern.type}`, changeType: 'update', source: 'TemporalPatternAnalyzer', reason: `${pattern.type} pattern detected with ${pattern.confidence} confidence`, metadata: { patternType: pattern.type, peakHours: pattern.metadata.peakTimes, activityClusters: activityClusters.length } }))); ``` ### Graph Traversal Optimization Enhanced graph utilization for performance: ```typescript // Preload frequently accessed subgraphs await this.evolutionTracker.trackEvolution('graph:preload', { changeType: 'update', source: 'ConnectionGraph', reason: 'Preloaded high-traffic memory subgraph', metadata: { nodeCount: graph.getStats().nodeCount, edgeCount: graph.getStats().edgeCount, preloadDuration: loadTime } }); ``` ## Analytics and Insights ### Real-Time Metrics Dashboard ```typescript interface RealtimeEvolutionMetrics { // Learning velocity memoriesPerHour: number; patternsDiscoveredToday: number; consolidationRate: number; // System health averageDecayRate: number; connectionDensity: number; activeMemoryCount: number; // Cost tracking llmCallsToday: number; embeddingCostToday: number; storageGrowthRate: number; } ``` ### Historical Analysis Reports ```typescript interface AgentEvolutionReport { // Learning patterns knowledgeGrowthTrend: TrendData; topicSpecialization: TopicAnalysis; patternSuccessRates: PatternMetrics; // Memory health decayPatterns: DecayAnalysis; consolidationEffectiveness: number; connectionGraphDensity: GraphMetrics; // Behavioral insights temporalActivityPatterns: ActivityAnalysis; workflowImprovements: WorkflowMetrics; adaptabilityScore: number; } ``` ### Predictive Intelligence ```typescript interface PredictiveInsights { // Forecasting projectedMemoryGrowth: GrowthProjection; decayPredictions: DecayForecast; patternSuccessProbability: PatternPrediction; // Recommendations suggestedConsolidations: ConsolidationSuggestion[]; optimalDecaySettings: DecayConfiguration; connectionDiscoveryOpportunities: ConnectionOpportunity[]; } ``` ## Performance Characteristics ### Tracking Overhead - **Event Creation**: <5ms async operation - **Batch Processing**: 100 events/batch, 5-second intervals - **Storage Impact**: <10% of memory data size - **Query Performance**: <2s for 30-day analytics ### Scalability Design - **Horizontal Scaling**: Partition by user/agent for distributed processing - **Time-Series Optimization**: Automatic rollups for historical data - **Compression**: Event data compressed by 70% on average - **Retention Policies**: Configurable data lifecycle management ## Integration with Traceability Suite The Memory Evolution Tracker seamlessly integrates with the broader **AgentDock Traceability Suite**: ### Unified Observability - **Single Dashboard**: Memory evolution alongside system metrics - **Correlated Insights**: Link memory patterns to performance impacts - **Cost Attribution**: Track memory costs by user, agent, and operation - **Anomaly Detection**: Alert on unusual evolution patterns ### Developer Experience ```typescript // Debugging with full context const evolution = await tracker.getEvolutionHistory(memoryId, { includeRelated: true, timeRange: { start: issueStart, end: now } }); // Generate audit report const auditReport = await tracker.generateAuditReport({ userId: 'user-123', agentId: 'agent-456', changeTypes: ['creation', 'consolidation', 'deletion'], timeRange: { start: auditPeriodStart, end: auditPeriodEnd } }); ``` ## Implementation Roadmap ### Phase 1: Core Infrastructure (Weeks 1-2) - [ ] Implement MemoryEvolutionTracker with async event processing - [ ] Add tracking hooks to all memory mutation points - [ ] Set up time-series storage with partitioning - [ ] Create event batching and compression pipeline ### Phase 2: System Integration (Weeks 3-4) - [ ] Integrate with WorkflowLearningService for pattern tracking - [ ] Enhance TemporalPatternAnalyzer with evolution events - [ ] Add graph traversal optimization tracking - [ ] Implement connection evolution monitoring ### Phase 3: Analytics Engine (Weeks 5-6) - [ ] Build real-time metrics aggregation - [ ] Create historical analysis queries - [ ] Implement predictive insights algorithms - [ ] Add cost tracking and attribution ### Phase 4: Traceability Integration (Weeks 7-8) - [ ] Design unified dashboard UI - [ ] Implement cross-system correlation - [ ] Add alerting and anomaly detection - [ ] Create developer debugging tools ## Success Metrics ### Technical Excellence - **Tracking Overhead**: <5ms for 99.9% of operations - **Zero Data Loss**: 100% event capture with at-least-once delivery - **Query Performance**: <2s for complex analytics queries - **Storage Efficiency**: <10% overhead with compression ### Business Impact - **Debugging Efficiency**: 90% reduction in memory issue resolution time - **Optimization Velocity**: 50% faster algorithm improvements - **User Satisfaction**: 95% positive feedback on transparency - **Compliance Ready**: 100% audit trail coverage ### User Outcomes - **Agent Transparency**: Users understand how their agents learn - **Performance Insights**: Clear visibility into memory health - **Cost Control**: Detailed breakdown of memory operation costs - **Trust Building**: Complete audit trails for sensitive applications ## Security and Privacy ### Data Protection - **User Isolation**: Complete separation of evolution data by user ID - **Encryption**: Event data encrypted at rest and in transit - **Access Control**: Role-based access to evolution analytics - **PII Handling**: Automatic redaction of sensitive information ### Compliance Features - **Audit Trails**: Immutable event log for regulatory compliance - **Data Retention**: Configurable retention with automatic cleanup - **Export Capabilities**: Generate compliance reports on demand - **Right to Erasure**: Support for GDPR data deletion requests ## Future Enhancements ### Advanced Analytics - **Cross-Agent Learning**: Compare evolution patterns across agents - **A/B Testing Framework**: Test memory algorithms with control groups - **ML-Powered Optimization**: Use evolution data to auto-tune parameters - **Behavioral Clustering**: Identify agent personality types ### Integration Expansions - **External Analytics**: Export to Datadog, New Relic, Grafana - **Webhook System**: Real-time notifications for evolution events - **Public API**: Allow custom evolution event tracking - **Mobile SDK**: Track evolution in edge deployments --- **The Memory Evolution Tracker transforms the AgentDock memory system from an opaque intelligence layer into a transparent, optimizable, and debuggable foundation for next-generation AI agents.** ## Memory & Storage Testing System PRD **Product Requirements Document** **Version**: 1.0 **Date**: July 9, 2025 **Status**: Draft **Owner**: AgentDock Core Team ## Executive Summary The Memory & Storage Testing System ensures production-ready reliability, performance, and accuracy of AgentDock's core memory infrastructure. This system validates hybrid vector+text search, cross-adapter compatibility, and real-world performance scenarios across PostgreSQL, SQLite, and vector-enabled variants. ### Business Impact - **Risk Mitigation**: Prevent memory system failures in production deployments - **Performance Assurance**: Guarantee <200ms response times for memory operations - **Compatibility Validation**: Ensure seamless operation across managed and self-hosted databases - **Developer Confidence**: Enable rapid feature development with comprehensive safety nets ## Problem Statement ### Current State - **Incomplete Test Coverage**: PostgreSQL Vector adapter has zero tests - **Missing E2E Validation**: No real embedding pipeline testing - **Performance Unknowns**: No load testing for 10K+ memory scenarios - **Adapter Inconsistency**: Different storage adapters lack unified test suites - **Production Gaps**: Managed service compatibility untested ### Success Metrics - **Test Coverage**: 95% function coverage across all memory operations - **Performance SLA**: <200ms response time for hybrid search operations - **Reliability**: 99.9% uptime in production memory operations - **Accuracy**: ≥85% relevance in hybrid search results vs pure vector search ## Product Overview ### Core Components #### 1. Storage Adapter Test Suite Comprehensive testing for all storage adapters with unified test contracts. **Adapters Covered**: - PostgreSQL (with ts_rank_cd text search) - PostgreSQL Vector (with pgvector + hybrid search) - SQLite (with FTS5) - SQLite Vec (with vec0 + FTS5 BM25) #### 2. Memory Operations Validation End-to-end testing of memory lifecycle operations across all storage types. **Operations Tested**: - Store, Recall, Update, Delete (CRUD) - Batch operations and transactions - Connection discovery and graph traversal - Decay calculations and archival #### 3. Vector & Hybrid Search Testing Validation of vector similarity and hybrid search accuracy. **Search Types**: - Pure vector similarity (cosine, euclidean, dot product) - Pure text search (FTS5 BM25, ts_rank_cd) - Hybrid search (70% vector + 30% text) - Reciprocal Rank Fusion (RRF) algorithms #### 4. Performance & Scale Testing Load testing and performance validation for production scenarios. **Scale Scenarios**: - 10K+ memories with concurrent access - 100+ concurrent users - Large batch operations (1K+ memories) - Connection discovery across large graphs ## User Stories ### Memory System Developer **As a** memory system developer **I want** comprehensive test coverage for all storage adapters **So that** I can confidently deploy new memory features without breaking existing functionality **Acceptance Criteria**: - [ ] All storage adapters pass identical test suites - [ ] Test failures clearly indicate the root cause - [ ] Tests can be run locally with minimal setup - [ ] CI/CD pipeline runs all tests automatically ### DevOps Engineer **As a** DevOps engineer deploying AgentDock **I want** performance and compatibility validation **So that** I can ensure reliable operation in production environments **Acceptance Criteria**: - [ ] Performance tests validate SLA requirements - [ ] Compatibility tests cover managed services (RDS, Supabase) - [ ] Load tests simulate realistic production scenarios - [ ] Resource usage is measured and documented ### AI Application Developer **As an** AI application developer using AgentDock **I want** reliable memory operations **So that** my agents maintain consistent conversational context **Acceptance Criteria**: - [ ] Memory recall accuracy is ≥85% for semantic queries - [ ] Response times are consistently <200ms - [ ] Cross-session memory persistence works reliably - [ ] Memory connections enhance recall relevance ## Functional Requirements ### FR1: Storage Adapter Test Framework **Priority**: P0 (Critical) #### FR1.1: Unified Test Contracts - All storage adapters implement identical test suites - Test isolation prevents cross-contamination - Graceful degradation when extensions unavailable - Error handling validation for all failure modes #### FR1.2: Memory Operations Testing ```typescript // Test contract example interface MemoryOperationsTestSuite { testBasicCRUD(): Promise
Chat Messages] end subgraph "API Routes" A --> C[Chat API] C --> D[Session Manager] D --> E[Storage Factory] E --> F{Storage Provider} F --> G[Memory
Development] F --> H[Redis/Upstash
Session Cache] F --> I[Vercel KV
Vercel Deployments] F --> J[SQLite
Local Default] F --> K[PostgreSQL/Supabase
Production Data] F --> L[PG Vector
AI Memory] end style A fill:#f9f,stroke:#333,stroke-width:2px style J fill:#9f9,stroke:#333,stroke-width:2px style K fill:#99f,stroke:#333,stroke-width:2px style H fill:#9ff,stroke:#333,stroke-width:2px ``` ## Current Implementation Status ### What's Actually Built - **Storage Abstraction Layer**: Complete with 15 adapters - **Session Management**: Working with any storage backend (requires persistent storage for survival across restarts) - **Orchestration State**: Persisted via SessionManager - **Client-Side Chat History**: Stored in browser localStorage only ### What's NOT Built Yet - **Server-Side Chat Persistence**: Messages are only in localStorage, not persisted server-side - **AI Memory System**: Storage adapters support vectors, but no memory implementation exists - **User Accounts**: No authentication or user management - **Multi-Tenancy**: Basic namespace support exists, but no tenant management - **Automatic Backups**: Depends on your storage provider (e.g., Supabase has backups) ### Architecture for Future Features When these features are built, the architecture would support: ```mermaid graph LR subgraph "Future State - Local Development" A1[AgentDock App] --> B1[SQLite
Everything] B1 --> C1[Sessions
Messages
History] end subgraph "Future State - Production" A2[AgentDock App] --> B2[Redis/Upstash
Sessions] A2 --> B3[PostgreSQL/Supabase
Accounts & Messages] A2 --> B4[PG Vector
AI Memory] B2 --> C2[Fast Session Access] B3 --> C3[Persistent Data] B4 --> C4[Semantic Search] end style A1 fill:#f9f,stroke:#333,stroke-width:2px style A2 fill:#f9f,stroke:#333,stroke-width:2px style B3 fill:#99f,stroke:#333,stroke-width:2px style B2 fill:#9ff,stroke:#333,stroke-width:2px ``` ## Storage Defaults ### Current Implementation - **Default Storage**: Memory (non-persistent, resets on restart) - **Chat Messages**: Browser localStorage only - **Sessions**: Can persist with configured storage backend - **Development**: SQLite auto-enabled for persistence ## Available Storage Adapters ### Core Adapters (Always Available) These three adapters are built into the core and always available: 1. **Memory** - In-memory storage (default, non-persistent) 2. **Redis/Upstash** - Redis-compatible storage via Upstash client 3. **Vercel KV** - Vercel's KV storage (Redis under the hood) ### Auto-Registered Adapters These adapters are automatically registered by the application when conditions are met: 4. **SQLite** - Auto-registered when `NODE_ENV=development` or `ENABLE_SQLITE=true` 5. **SQLite-vec** - Auto-registered when `NODE_ENV=development` or `ENABLE_SQLITE_VEC=true` 6. **PostgreSQL** - Auto-registered when `DATABASE_URL` is set 7. **PostgreSQL Vector** - Auto-registered when `DATABASE_URL` is set and `ENABLE_PGVECTOR=true` ### Additional Adapters (Manual Registration Required) These adapters require manual registration in your API routes: 8. **MongoDB** - Document storage (optional, not recommended for memory systems) 9. **S3** - Object storage for files 10. **DynamoDB** - AWS NoSQL database 11. **Cloudflare KV** - Edge key-value storage 12. **Cloudflare D1** - Edge SQL database 13. **Pinecone** - Vector database 14. **Qdrant** - Vector database 15. **ChromaDB** - Vector database ## Adapter Pattern Compliance ### StorageProvider Interface All storage adapters in AgentDock Core implement the `StorageProvider` interface, ensuring consistent behavior across different backends: ```typescript interface StorageProvider { // Core KV Operations get