Memory Configuration

This page provides comprehensive documentation for configuring the PraisonAI memory system, including graph database integration, quality scoring mechanisms, and embedder options.

Memory System Overview

The memory system in PraisonAI supports multiple storage backends and sophisticated retrieval mechanisms:

Short-term Memory: Recent interactions and context
Long-term Memory: Persistent knowledge storage
Entity Memory: Relationship and entity tracking
Graph Memory: Complex relationship networks
User Memory: User-specific preferences and history

Core Configuration

Basic Memory Setup

from praisonaiagents import Agent

agent = Agent(
    name="MemoryAgent",
    memory=True,  # Enable memory
    memory={
        "provider": "rag",
        "use_embedding": True,
        "embedding_model": "text-embedding-3-small",
        "quality_threshold": 0.7,
        "max_results": 10
    }
)

Installing Optional Providers

Most memory providers require optional dependencies:

pip install "praisonaiagents[memory]"

If you try to use a provider without the required packages, you’ll see:

ImportError: mem0ai is not installed. Run: pip install 'praisonaiagents[memory]'

When a provider is explicitly requested (e.g. "provider": "mem0"), PraisonAI will raise this error instead of silently falling back. The default provider ("provider": "rag") falls back gracefully to built-in storage.

Provider Configuration

# RAG Provider (Default)
rag_config = {
    "provider": "rag",
    "rag_db_path": "./memory/rag_db",
    "chunk_size": 1000,
    "chunk_overlap": 200,
    "use_semantic_chunking": True
}

# Mem0 Provider
# Requires: pip install "praisonaiagents[memory]"
mem0_config = {
    "provider": "mem0",
    "api_key": "your-mem0-key",
    "user_id": "user-123",
    "organization_id": "org-456"
}

# Custom Provider
custom_config = {
    "provider": "custom",
    "class": "myapp.CustomMemoryProvider",
    "connection_string": "custom://localhost:8080"
}

Graph Store Configuration

Graph Database Setup

# Neo4j Configuration
neo4j_config = {
    "graph_enabled": True,
    "graph_provider": "neo4j",
    "graph_uri": "bolt://localhost:7687",
    "graph_user": "neo4j",
    "graph_password": "password",
    "graph_database": "memories",
    "graph_config": {
        "max_connection_lifetime": 3600,
        "max_connection_pool_size": 50,
        "connection_acquisition_timeout": 60,
        "encrypted": True
    }
}

# Memgraph Configuration
memgraph_config = {
    "graph_enabled": True,
    "graph_provider": "memgraph",
    "graph_uri": "bolt://localhost:7687",
    "graph_user": "memgraph",
    "graph_password": "password",
    "graph_config": {
        "lazy": True,
        "ssl": False
    }
}

Graph Schema Definition

graph_schema = {
    "nodes": {
        "Entity": {
            "properties": ["name", "type", "description", "created_at"],
            "indexes": ["name", "type"]
        },
        "Concept": {
            "properties": ["name", "definition", "category"],
            "indexes": ["name", "category"]
        },
        "Event": {
            "properties": ["name", "timestamp", "description", "participants"],
            "indexes": ["timestamp"]
        }
    },
    "relationships": {
        "RELATES_TO": {
            "properties": ["strength", "context", "timestamp"]
        },
        "CAUSES": {
            "properties": ["probability", "mechanism"]
        },
        "PARTICIPATES_IN": {
            "properties": ["role", "duration"]
        }
    }
}

Advanced Graph Queries

# Complex graph query configuration
graph_query_config = {
    "retrieval_queries": {
        "find_related_entities": """
            MATCH (e1:Entity {name: $entity_name})-[r:RELATES_TO*1..3]-(e2:Entity)
            WHERE r.strength > $min_strength
            RETURN e2, r
            ORDER BY r.strength DESC
            LIMIT $limit
        """,
        "trace_causality": """
            MATCH path = (cause:Event)-[:CAUSES*1..5]->(effect:Event)
            WHERE cause.name = $event_name
            RETURN path
        """
    },
    "update_patterns": {
        "strengthen_relationship": """
            MATCH (e1:Entity {name: $entity1})-[r:RELATES_TO]-(e2:Entity {name: $entity2})
            SET r.strength = r.strength * $multiplier
            SET r.last_accessed = timestamp()
        """
    }
}

Quality Score Configuration

Quality Scoring System

quality_config = {
    "quality_threshold": 0.7,  # Minimum score for retrieval
    "scoring_weights": {
        "relevance": 0.4,
        "recency": 0.2,
        "frequency": 0.2,
        "confidence": 0.2
    },
    "scoring_functions": {
        "relevance": "cosine_similarity",
        "recency": "exponential_decay",
        "frequency": "log_normalization",
        "confidence": "source_reliability"
    }
}

Quality Score Components

Relevance Scoring

relevance_config = {
    "method": "hybrid",
    "components": {
        "semantic": {
            "weight": 0.6,
            "model": "text-embedding-3-small",
            "distance_metric": "cosine"
        },
        "keyword": {
            "weight": 0.3,
            "algorithm": "bm25",
            "parameters": {"k1": 1.2, "b": 0.75}
        },
        "structural": {
            "weight": 0.1,
            "factors": ["title_match", "section_match"]
        }
    }
}

Recency Scoring

recency_config = {
    "decay_function": "exponential",
    "half_life_days": 30,
    "boost_recent": {
        "last_hour": 2.0,
        "last_day": 1.5,
        "last_week": 1.2
    }
}

Confidence Scoring

confidence_config = {
    "source_weights": {
        "verified": 1.0,
        "agent_generated": 0.8,
        "external": 0.6,
        "unverified": 0.4
    },
    "consensus_threshold": 3,  # Number of sources for high confidence
    "contradiction_penalty": 0.5
}

Embedder Configuration

Embedder Options

# OpenAI Embedder
openai_embedder = {
    "provider": "openai",
    "model": "text-embedding-3-large",
    "dimensions": 3072,
    "api_key": "your-api-key",
    "batch_size": 100,
    "retry_config": {
        "max_retries": 3,
        "retry_delay": 1.0
    }
}

# Local Embedder
local_embedder = {
    "provider": "sentence-transformers",
    "model": "all-MiniLM-L6-v2",
    "device": "cuda",  # or "cpu"
    "normalize_embeddings": True,
    "batch_size": 32
}

# Custom Embedder
custom_embedder = {
    "provider": "custom",
    "class": "myapp.embedders.DomainSpecificEmbedder",
    "model_path": "/models/domain-embedder",
    "preprocessing": {
        "lowercase": True,
        "remove_punctuation": True,
        "custom_tokenizer": "medical"
    }
}

multimodal_config = {
    "embedders": {
        "text": {
            "provider": "openai",
            "model": "text-embedding-3-small",
            "weight": 0.6
        },
        "image": {
            "provider": "clip",
            "model": "openai/clip-vit-base-patch32",
            "weight": 0.4
        }
    },
    "fusion_method": "weighted_average",
    "normalize_before_fusion": True
}

Storage Configuration

Database Paths and Structure

storage_config = {
    # SQLite databases
    "short_db": "./memory/short_term.db",
    "long_db": "./memory/long_term.db",
    "entity_db": "./memory/entities.db",
    "user_db": "./memory/users.db",
    
    # Vector storage
    "vector_db": {
        "provider": "chromadb",
        "path": "./memory/vectors",
        "collection_name": "memories"
    },
    
    # Backup configuration
    "backup": {
        "enabled": True,
        "interval": "daily",
        "retention_days": 30,
        "path": "./memory/backups"
    }
}

Memory Persistence

persistence_config = {
    "auto_save": True,
    "save_interval": 300,  # seconds
    "compression": "gzip",
    "encryption": {
        "enabled": True,
        "algorithm": "AES-256",
        "key_derivation": "PBKDF2"
    },
    "migration": {
        "auto_migrate": True,
        "backup_before_migration": True
    }
}

Performance Optimization

Caching Configuration

cache_config = {
    "embedding_cache": {
        "enabled": True,
        "size": 10000,
        "ttl": 3600,  # seconds
        "eviction": "lru"
    },
    "query_cache": {
        "enabled": True,
        "size": 1000,
        "ttl": 1800,
        "cache_similarity_threshold": 0.95
    },
    "graph_cache": {
        "enabled": True,
        "cached_patterns": ["neighbors", "paths", "subgraphs"],
        "ttl": 900
    }
}

Indexing Strategy

indexing_config = {
    "vector_index": {
        "type": "hnsw",
        "parameters": {
            "m": 16,
            "ef_construction": 200,
            "ef_search": 100
        }
    },
    "text_index": {
        "type": "inverted",
        "analyzer": "standard",
        "features": ["positions", "frequencies"]
    },
    "rebuild_schedule": "weekly"
}

Memory Cleanup and Maintenance

Cleanup Configuration

cleanup_config = {
    "ttl": {
        "short_term": 86400,  # 1 day in seconds
        "long_term": 2592000,  # 30 days
        "entity": None,  # No expiry
        "user": 31536000  # 1 year
    },
    "cleanup_strategy": {
        "method": "quality_based",
        "min_quality_score": 0.3,
        "max_memory_size": "10GB",
        "cleanup_interval": "daily"
    },
    "compression": {
        "enabled": True,
        "threshold_days": 7,
        "algorithm": "zstd"
    }
}

Complete Configuration Example

from praisonaiagents import Agent

# Comprehensive memory configuration
memory_agent = Agent(
    name="AdvancedMemoryAgent",
    memory=True,
    memory={
        # Provider settings
        "provider": "rag",
        "use_embedding": True,
        
        # Storage paths
        "rag_db_path": "./memory/rag_db",
        "short_db": "./memory/short_term.db",
        "long_db": "./memory/long_term.db",
        
        # Graph configuration
        "graph_enabled": True,
        "graph_provider": "neo4j",
        "graph_uri": "bolt://localhost:7687",
        "graph_user": "neo4j",
        "graph_password": "password",
        
        # Quality scoring
        "quality_threshold": 0.7,
        "scoring_weights": {
            "relevance": 0.4,
            "recency": 0.2,
            "frequency": 0.2,
            "confidence": 0.2
        },
        
        # Embedder configuration
        "embedder_config": {
            "provider": "openai",
            "model": "text-embedding-3-small",
            "batch_size": 100
        },
        
        # Performance settings
        "cache_enabled": True,
        "max_results": 20,
        "parallel_retrieval": True,
        
        # Maintenance
        "cleanup_interval": "daily",
        "ttl": {
            "short_term": 86400,
            "long_term": 2592000
        }
    }
)

Environment Variables

# Memory provider
export PRAISONAI_MEMORY_PROVIDER="rag"
export PRAISONAI_MEMORY_PATH="./memory"

# Graph database
export PRAISONAI_GRAPH_ENABLED="true"
export PRAISONAI_GRAPH_URI="bolt://localhost:7687"
export PRAISONAI_GRAPH_USER="neo4j"
export PRAISONAI_GRAPH_PASSWORD="password"

# Quality settings
export PRAISONAI_MEMORY_QUALITY_THRESHOLD="0.7"
export PRAISONAI_MEMORY_MAX_RESULTS="10"

# Embedder
export PRAISONAI_EMBEDDER_PROVIDER="openai"
export PRAISONAI_EMBEDDER_MODEL="text-embedding-3-small"

# Performance
export PRAISONAI_MEMORY_CACHE_ENABLED="true"
export PRAISONAI_MEMORY_CACHE_SIZE="10000"

Troubleshooting

Common Issues

Graph connection failures

# Add connection retry logic
"graph_config": {
    "retry_attempts": 5,
    "retry_delay": 2,
    "health_check_interval": 60
}

Memory retrieval too slow

# Enable parallel retrieval and caching
"parallel_retrieval": True,
"cache_enabled": True,
"index_type": "hnsw"

Quality scores too low

# Adjust scoring weights and thresholds
"quality_threshold": 0.5,  # Lower threshold
"scoring_weights": {
    "relevance": 0.6,  # Increase relevance weight
    "recency": 0.2,
    "frequency": 0.1,
    "confidence": 0.1
}

​Memory Configuration

​Memory System Overview

​Core Configuration

​Basic Memory Setup

​Installing Optional Providers

​Provider Configuration

​Graph Store Configuration

​Graph Database Setup

​Graph Schema Definition

​Advanced Graph Queries

​Quality Score Configuration

​Quality Scoring System

​Quality Score Components

​Relevance Scoring

​Recency Scoring

​Confidence Scoring

​Embedder Configuration

​Embedder Options

​Multi-Modal Embedding

​Storage Configuration

​Database Paths and Structure

​Memory Persistence

​Performance Optimization

​Caching Configuration

​Indexing Strategy

​Memory Cleanup and Maintenance

​Cleanup Configuration

​Complete Configuration Example

​Environment Variables

​Troubleshooting

​Common Issues

​See Also