Memory Configuration

Complete reference for memory system configuration including graph stores, quality scores, and embedders

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

python

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:

bash

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

python

# 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"
}

# Dakera Provider
# Requires: pip install "praisonaiagents[dakera]"
dakera_config = {
    "provider": "dakera",
    "config": {
        "url": "http://localhost:3000",
        "api_key": "dk-...",
        "agent_id": "my-agent",
        "short_term_type": "working",
        "long_term_type": "episodic",
        "default_importance": 0.5,
    }
}

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

Graph Store Configuration

Graph Database Setup

python

# 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

python

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

python

# 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

python

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

python

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

python

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

python

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

python

# 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
}

python

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

Multi-Modal Embedding

python

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

python

storage_config = {
    # SQLite databases
    "db_path": "/tmp/team-memory.db",   # single-file alias → both short_db + long_db
    "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"
    }
}

SQLite `db_path` single-file alias

Point two or more agents at one SQLite file so they share short-term and long-term memory.

Option	Type	Default	Description
`db_path`	`str`	`None`	sqlite backend only. Single-file alias — maps to both `short_db` and `long_db`. Explicit `short_db` / `long_db` still win. Use to share one SQLite file across Agent instances for cross-instance recall.

Precedence: Explicit short_db / long_db > db_path > Per-user default paths (per-tier — set short_db explicitly and let long_db fall back to db_path).

python

# Share one SQLite file across agents
from praisonaiagents import Agent
from praisonaiagents.config.feature_configs import MemoryConfig

agent = Agent(
    name="Writer",
    instructions="Share one SQLite file across agents.",
    memory=MemoryConfig(backend="sqlite", config={"db_path": "/tmp/team-memory.db"}),
)

See the writer/reader walkthrough in Advanced Memory. Added in PraisonAI PR #5711 (fixes #5710).

Chroma Collection Name

Set collection_name at the top level of the memory config to give this instance its own Chroma collection:

python

memory_config = {
    "provider": "rag",
    "short_db": "./memory/short_term.db",
    "long_db": "./memory/long_term.db",
    "rag_db_path": "./memory/chroma_db",
    "collection_name": "team_alpha_memory",   # NEW: opt-in; default "memory_store"
}

Option	Type	Default	Description
`collection_name`	`str`	`"memory_store"`	Top-level Chroma collection name for the built-in RAG memory

This top-level collection_name is distinct from the nested vector_db.collection_name used inside a provider block above.

Memory Persistence

python

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

python

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

python

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

python

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

python

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

bash

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

# Dakera memory provider (DAKERA_URL and DAKERA_API_URL are both accepted)
export DAKERA_URL="http://localhost:3000"
# export DAKERA_API_URL="http://localhost:3000"  # alias for DAKERA_URL
export DAKERA_API_KEY="dk-..."
export DAKERA_AGENT_ID="my-agent"

# 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

python

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

Memory retrieval too slow

python

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

Quality scores too low

python

# 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