.env.example

# =============================================================================
# MemEvolve Environment Configuration
# =============================================================================
# Copy this file to .env and update values for your environment
#
# PRIMARY DESIGN PRINCIPLE:
# - All meaningful defaults come from this file (.env)
# - config.py only has minimal fallbacks (0, "", False)
# - Evolution hierarchy: evolution_state.json → .env → minimal fallbacks
# =============================================================================

# =============================================================================
# CORE API SERVICES
# =============================================================================
# -----------------------------------------------------------------------------
# UPSTREAM LLM API (REQUIRED)
# -----------------------------------------------------------------------------
# Your primary OpenAI-compatible LLM service
MEMEVOLVE_UPSTREAM_BASE_URL=
MEMEVOLVE_UPSTREAM_API_KEY=
MEMEVOLVE_UPSTREAM_MODEL=
MEMEVOLVE_UPSTREAM_AUTO_RESOLVE_MODELS=true
MEMEVOLVE_UPSTREAM_TIMEOUT=720
# Maximum tokens for upstream LLM processing (empty = auto-resolve)
# Common values: 4096, 8192, 16384, 32768 depending on model
MEMEVOLVE_UPSTREAM_MAX_TOKENS=

# -----------------------------------------------------------------------------
# EMBEDDING API (OPTIONAL)
# -----------------------------------------------------------------------------
# Separate embedding service if different from upstream
MEMEVOLVE_EMBEDDING_BASE_URL=
MEMEVOLVE_EMBEDDING_API_KEY=
MEMEVOLVE_EMBEDDING_MODEL=
MEMEVOLVE_EMBEDDING_AUTO_RESOLVE_MODELS=true
MEMEVOLVE_EMBEDDING_TIMEOUT=60
# Maximum tokens for embedding generation (empty = auto-resolve)
# Most embedding models: 512, 8192 for newer models
MEMEVOLVE_EMBEDDING_MAX_TOKENS=
MEMEVOLVE_EMBEDDING_DIMENSION=

# -----------------------------------------------------------------------------
# ENCODER LLM API (OPTIONAL)
# -----------------------------------------------------------------------------
# Dedicated LLM for encoder operations
MEMEVOLVE_ENCODER_BASE_URL=
MEMEVOLVE_ENCODER_API_KEY=
MEMEVOLVE_ENCODER_MODEL=
MEMEVOLVE_ENCODER_AUTO_RESOLVE_MODELS=true
MEMEVOLVE_ENCODER_TIMEOUT=120
# Maximum tokens for encoder operations (empty = auto-resolve)
# Encoder operations typically need less: 2048, 4096 are common
MEMEVOLVE_ENCODER_MAX_TOKENS=

# =============================================================================
# GLOBAL API SETTINGS
# =============================================================================
# Applied to all API endpoints
MEMEVOLVE_API_MAX_RETRIES=3
MEMEVOLVE_DEFAULT_TOP_K=3

# =============================================================================
# API SERVER CONFIGURATION
# =============================================================================
MEMEVOLVE_API_ENABLE=true
MEMEVOLVE_API_HOST=127.0.0.1
MEMEVOLVE_API_PORT=11436
MEMEVOLVE_API_MEMORY_INTEGRATION=true

# =============================================================================
# STORAGE & DATA MANAGEMENT
# =============================================================================
# -----------------------------------------------------------------------------
# ROOT DIRECTORIES
# -----------------------------------------------------------------------------
MEMEVOLVE_DATA_DIR=./data
MEMEVOLVE_CACHE_DIR=./cache
MEMEVOLVE_LOGS_DIR=./logs

# -----------------------------------------------------------------------------
# STORAGE BACKEND (json, vector, graph)
# -----------------------------------------------------------------------------
MEMEVOLVE_STORAGE_BACKEND_TYPE=vector

# -----------------------------------------------------------------------------
# STORAGE INDEX (vector storage only)
# -----------------------------------------------------------------------------
MEMEVOLVE_STORAGE_INDEX_TYPE=ivf

# -----------------------------------------------------------------------------
# IVF OPTIMIZATION SETTINGS (adaptive vector index)
# -----------------------------------------------------------------------------
# Maximum number of units in vector store
MEMEVOLVE_STORAGE_MAX_UNITS=50000
# Warning threshold as percentage (0.8 = 80% = 40,000 units)
MEMEVOLVE_STORAGE_WARNING_THRESHOLD=0.81
# Target vectors per IVF centroid for optimal performance (39+ recommended)
MEMEVOLVE_STORAGE_VECTORS_PER_CENTROID=39
# Enable automatic retraining when performance degrades
MEMEVOLVE_STORAGE_ENABLE_AUTO_RETRAIN=true
# Minimum training vectors for IVF index quality
MEMEVOLVE_STORAGE_MIN_TRAINING_VECTORS=100

# -----------------------------------------------------------------------------
# NEO4J CONNECTION (graph storage only)
# -----------------------------------------------------------------------------
MEMEVOLVE_GRAPH_DISABLE_NEO=true
MEMEVOLVE_NEO4J_URI=bolt://localhost:7687
MEMEVOLVE_NEO4J_USER=neo4j
MEMEVOLVE_NEO4J_PASSWORD=password
MEMEVOLVE_NEO4J_TIMEOUT=30
MEMEVOLVE_NEO4J_MAX_RETRIES=3

# =============================================================================
# GLOBAL LOGGING CONFIGURATION  
# =============================================================================
# -----------------------------------------------------------------------------
# LOG LEVEL SELECTION  
# -----------------------------------------------------------------------------
# Separate levels for console and file output
#------------------------------------------------------------------------------
# Choose from: ERROR, WARNING, INFO, DEBUG
# DEBUG = Most verbose (all messages)
# INFO  = Normal operation messages  
# WARNING = Important events only
# ERROR = Critical errors only
#
# Console output: What you see in terminal
# File output: What gets stored in ./logs/ directory
#==============================================================================
MEMEVOLVE_LOGGING_ENABLE=true
MEMEVOLVE_LOGGING_MAX_LOG_SIZE_MB=1024
MEMEVOLVE_LOG_CONSOLE_LEVEL=INFO
MEMEVOLVE_LOG_FILE_LEVEL=DEBUG

# =============================================================================
# MEMORY SYSTEM BEHAVIOR
# =============================================================================
# -----------------------------------------------------------------------------
# MEMORY INJECTION FILTERING
# -----------------------------------------------------------------------------
MEMEVOLVE_MEMORY_RELEVANCE_THRESHOLD=0.44

# -----------------------------------------------------------------------------
# RETRIEVAL CONFIGURATION
# -----------------------------------------------------------------------------
MEMEVOLVE_RETRIEVAL_STRATEGY_TYPE=hybrid
MEMEVOLVE_RETRIEVAL_ENABLE_CACHING=true
MEMEVOLVE_RETRIEVAL_CACHE_SIZE=1024
MEMEVOLVE_RETRIEVAL_ENABLE_FILTERS=false

# -----------------------------------------------------------------------------
# HYBRID RETRIEVAL WEIGHTS
# -----------------------------------------------------------------------------
MEMEVOLVE_RETRIEVAL_HYBRID_SEMANTIC_WEIGHT=0.7
MEMEVOLVE_RETRIEVAL_HYBRID_KEYWORD_WEIGHT=0.3

# -----------------------------------------------------------------------------
# RETRIEVAL FEATURES
# -----------------------------------------------------------------------------
MEMEVOLVE_RETRIEVAL_SEMANTIC_CACHE_ENABLED=true
MEMEVOLVE_RETRIEVAL_KEYWORD_CASE_SENSITIVE=false
MEMEVOLVE_RETRIEVAL_SEMANTIC_EMBEDDING_MODEL=


# MEMORY MANAGEMENT
# -----------------------------------------------------------------------------
MEMEVOLVE_MANAGEMENT_ENABLE_AUTO_MANAGEMENT=true
MEMEVOLVE_MANAGEMENT_AUTO_PRUNE_THRESHOLD=40000
MEMEVOLVE_MANAGEMENT_PRUNE_MAX_COUNT=1000
MEMEVOLVE_MANAGEMENT_PRUNE_BY_TYPE=
MEMEVOLVE_MANAGEMENT_AUTO_CONSOLIDATE_INTERVAL=10000
MEMEVOLVE_MANAGEMENT_DEDUPLICATE_THRESHOLD=0.9
MEMEVOLVE_MANAGEMENT_FORGETTING_STRATEGY=lru
MEMEVOLVE_MANAGEMENT_MAX_MEMORY_AGE_DAYS=365
MEMEVOLVE_MANAGEMENT_STRATEGY_TYPE=simple
MEMEVOLVE_MANAGEMENT_CONSOLIDATE_ENABLED=true
MEMEVOLVE_MANAGEMENT_CONSOLIDATE_MIN_UNITS=2
MEMEVOLVE_MANAGEMENT_DEDUPLICATE_ENABLED=true
MEMEVOLVE_MANAGEMENT_FORGETTING_PERCENTAGE=0.1

# -----------------------------------------------------------------------------
# BUSINESS VALUE CALCULATION WEIGHTS
# -----------------------------------------------------------------------------
# Weights for calculating business value of memory-enhanced responses
# Token efficiency focuses on reducing response token usage
# Response quality focuses on response completeness and usefulness
# Weights should ideally sum to 1.0 for proper normalization
MEMEVOLVE_BUSINESS_VALUE_EFFICIENCY_WEIGHT=0.7
MEMEVOLVE_BUSINESS_VALUE_QUALITY_WEIGHT=0.3

# -----------------------------------------------------------------------------
# ENCODER INTEGRATION CONFIGURATION
# -----------------------------------------------------------------------------
MEMEVOLVE_ENCODER_ENCODING_STRATEGIES=lesson,skill,tool,abstraction
MEMEVOLVE_ENCODER_ENABLE_ABSTRACTIONS=true
MEMEVOLVE_ENCODER_ENABLE_TOOL_EXTRACTION=true
MEMEVOLVE_ENCODER_ABSTRACTION_THRESHOLD=10
MEMEVOLVE_ENCODER_BATCH_SIZE=10
MEMEVOLVE_ENCODER_TEMPERATURE=0.7
MEMEVOLVE_ENCODER_MIN_ABSTRACTION_UNITS=3
MEMEVOLVE_ENCODER_INJECTION_PROMPT=MEMORY_PREFIX="Retrieved Memory (self-generated priors):\nHeuristic summaries from prior inference; epistemically uncertain.\nApply only if they reduce uncertainty."


# -----------------------------------------------------------------------------
# ENCODING PROMPTS
# -----------------------------------------------------------------------------
MEMEVOLVE_CHUNK_PROCESSING_INSTRUCTION="Extract key insight from this experience chunk as JSON array.\n\nReturn format: [{\"type\": \"lesson|skill|tool|abstraction\", \"content\": \"specific insight\"}]\n\nRULES:\n- Single insight per chunk (array with one object)\n- Use exact type: \"lesson\", \"skill\", \"tool\", or \"abstraction\"\n- Focus on the specific action, insight, or learning from this chunk\n- No extra fields, no metadata, no tags"
MEMEVOLVE_CHUNK_CONTENT_INSTRUCTION="Provide the specific insight from this chunk in 1-2 sentences. Focus on what was learned or discovered in this specific part of the experience."
MEMEVOLVE_CHUNK_STRUCTURE_EXAMPLE="[{\"type\": \"lesson\", \"content\": \"Specific insight from this chunk\"}]"

MEMEVOLVE_ENCODING_INSTRUCTION="Extract ALL meaningful insights from this experience as separate memory units.\n\nReturn a JSON array where each insight is its own memory object:\n[\n  {\"type\": \"lesson|skill|tool|abstraction\", \"content\": \"first insight\"},\n  {\"type\": \"skill\", \"content\": \"second insight\"},\n  {\"type\": \"tool\", \"content\": \"third insight\"}\n]\n\nRULES FOR MULTIPLE INSIGHTS:\n1. SEPARATE UNITS: Each insight becomes its own memory object\n2. MAX 5 INSIGHTS: Limit to 5 insights to maintain quality\n3. REQUIRED FIELDS: Each object needs \"type\" and \"content\" only\n4. NO NESTING: Flat objects, no complex structures\n5. VALID TYPES: \"type\" must be: \"lesson\", \"skill\", \"tool\", \"abstraction\"\n\nSINGLE INSIGHT EXAMPLE:\n[\n  {\"type\": \"lesson\", \"content\": \"Regular testing prevents production bugs\"}\n]\n\nMULTIPLE INSIGHTS EXAMPLE:\n[\n  {\"type\": \"lesson\", \"content\": \"Early testing reveals bugs when code is immature\"},\n  {\"type\": \"skill\", \"content\": \"Use systematic test coverage to catch edge cases\"},\n  {\"type\": \"tool\", \"content\": \"Implement automated testing framework for consistent validation\"}\n]\n\nINSIGHT PRIORITIZATION:\n1. Most important lesson/skill first\n2. Complementary insights next\n3. Practical tools last"
MEMEVOLVE_CONTENT_INSTRUCTION="Extract all distinct insights from the experience. For each insight:\n\n1. Identify if it's a lesson, skill, tool, or abstraction\n2. Write the insight clearly and specifically\n3. Ensure each insight is actionable and valuable\n4. Limit to 5 most important insights per experience\n\nFormat each insight as: \"Clear, specific statement about what was learned or discovered.\"\n\nGoal: Create multiple searchable memory units rather than one complex object."
MEMEVOLVE_STRUCTURE_EXAMPLE="[{\"type\": \"lesson\", \"content\": \"Early testing reveals bugs when code is immature\"}, {\"type\": \"skill\", \"content\": \"Use systematic test coverage to catch edge cases\"}]"

# -----------------------------------------------------------------------------
# ENCODING TYPE DESCRIPTIONS
# -----------------------------------------------------------------------------
MEMEVOLVE_TYPE_DESCRIPTIONS=lesson:generalizable insight,skill:actionable technique,tool:reusable function/algorithm,abstraction:high-level concept

# =============================================================================
# EVOLUTION SYSTEM
# =============================================================================
# -----------------------------------------------------------------------------
# EVOLUTION CONTROL
# -----------------------------------------------------------------------------
MEMEVOLVE_ENABLE_EVOLUTION=false

# -----------------------------------------------------------------------------
# EVOLUTION CYCLE TRIGGERS (when to start evolution cycles)
# -----------------------------------------------------------------------------
MEMEVOLVE_CYCLE_EVOLUTION_DEGRADATION=0.2
MEMEVOLVE_CYCLE_EVOLUTION_PLATEAU=5
MEMEVOLVE_CYCLE_EVOLUTION_HOURS=24
MEMEVOLVE_CYCLE_EVOLUTION_CYCLE_SECONDS=1800
MEMEVOLVE_CYCLE_EVOLUTION_MIN_REQUESTS_PER_CYCLE=32

# -----------------------------------------------------------------------------
# EVOLUTION PARAMETERS
# -----------------------------------------------------------------------------
MEMEVOLVE_EVOLUTION_POPULATION_SIZE=10
MEMEVOLVE_EVOLUTION_GENERATIONS=20
MEMEVOLVE_EVOLUTION_MUTATION_RATE=0.1
MEMEVOLVE_EVOLUTION_CROSSOVER_RATE=0.5
MEMEVOLVE_EVOLUTION_SELECTION_METHOD=pareto
MEMEVOLVE_EVOLUTION_TOURNAMENT_SIZE=3

# -----------------------------------------------------------------------------
# FITNESS WEIGHTS
# -----------------------------------------------------------------------------
MEMEVOLVE_FITNESS_HISTORY_SIZE=64
MEMEVOLVE_FITNESS_WEIGHT_SUCCESS=0.4
MEMEVOLVE_FITNESS_WEIGHT_TOKENS=0.3
MEMEVOLVE_FITNESS_WEIGHT_TIME=0.2
MEMEVOLVE_FITNESS_WEIGHT_RETRIEVAL=0.1

# -----------------------------------------------------------------------------
# EVOLUTION PARAMETER BOUNDARIES
# -----------------------------------------------------------------------------
# Evolution will test different max_tokens values within these ranges
MEMEVOLVE_EVOLUTION_MAX_TOKENS_MIN=256
MEMEVOLVE_EVOLUTION_MAX_TOKENS_MAX=8192
# Note: Evolution will respect individual endpoint max_tokens limits
# EVOLUTION_MAX_TOKENS applies to encoder operations only
MEMEVOLVE_EVOLUTION_TOP_K_MIN=2
MEMEVOLVE_EVOLUTION_TOP_K_MAX=10
MEMEVOLVE_EVOLUTION_RELEVANCE_THRESHOLD_MIN=0.3
MEMEVOLVE_EVOLUTION_RELEVANCE_THRESHOLD_MAX=0.8
MEMEVOLVE_EVOLUTION_TEMPERATURE_MIN=0.0
MEMEVOLVE_EVOLUTION_TEMPERATURE_MAX=1.0
MEMEVOLVE_EVOLUTION_FORGETTING_PERCENTAGE_MIN=0.05
MEMEVOLVE_EVOLUTION_FORGETTING_PERCENTAGE_MAX=0.3
MEMEVOLVE_EVOLUTION_COST_THRESHOLD_MIN=0.5
MEMEVOLVE_EVOLUTION_COST_THRESHOLD_MAX=0.95

# -----------------------------------------------------------------------------
# EVOLUTION MUTATION OPTIONS
# -----------------------------------------------------------------------------
MEMEVOLVE_EVOLUTION_RETRIEVAL_STRATEGIES=keyword,semantic,hybrid,llm_guided
MEMEVOLVE_EVOLUTION_HYBRID_WEIGHT_MIN=0.0
MEMEVOLVE_EVOLUTION_HYBRID_WEIGHT_MAX=1.0
MEMEVOLVE_EVOLUTION_ENCODING_STRATEGIES=lesson|skill|tool|abstraction|lesson,skill|lesson,tool|lesson,abstraction|skill,tool|skill,abstraction|tool,abstraction|lesson,skill,tool|lesson,skill,abstraction|lesson,tool,abstraction|skill,tool,abstraction|lesson,skill,tool,abstraction
MEMEVOLVE_EVOLUTION_BATCH_SIZE_MIN=5
MEMEVOLVE_EVOLUTION_BATCH_SIZE_MULTIPLIER=2.0
MEMEVOLVE_EVOLUTION_TOKEN_STEP_SIZE=256
MEMEVOLVE_EVOLUTION_STRATEGY_ADDITION_PROBABILITY=0.5
MEMEVOLVE_EVOLUTION_TEMPERATURE_DELTA=0.1

# -----------------------------------------------------------------------------
# EVOLUTION MANAGEMENT MUTATION OPTIONS
# -----------------------------------------------------------------------------
MEMEVOLVE_EVOLUTION_MANAGEMENT_STRATEGIES=simple,advanced
MEMEVOLVE_EVOLUTION_FORGETTING_STRATEGIES=lru,lfu,random,cost_based

# =============================================================================
# MEMEVOLVE PROJECT SETTINGS
# =============================================================================
#
# MAX_TOKENS CONFIGURATION STRATEGY:
# - Each API endpoint can have its own max_tokens limit
# - Priority: .env value > auto-resolved value > unlimited (None)
# - If both .env and auto-resolve exist: use LOWER of the two values
# - This prevents exceeding actual model capabilities
#
# DEFAULT VALUES EXPLANATION:
# - When a setting is left empty (""), the system will:
#   1. Try to auto-resolve from the service (if AUTO_RESOLVE_MODELS=true)
#   2. Fall back to sensible defaults if auto-resolution fails
#   3. Never crash due to missing configuration
#
# EXCEPTION: Required values marked as "(REQUIRED)" must be provided
# =============================================================================
MEMEVOLVE_PROJECT_NAME=MemEvolve-API
MEMEVOLVE_PROJECT_ROOT=.