Configuration

SmartMemory consumer setup has two modes. Most users should choose one with sm setup (the sm CLI is the short form of the smartmemory command), not hand-wire a graph database.

Lite or Service

Lite runs entirely on your machine and Service connects to the managed backend. For the full comparison and how to pick one, see Lite or Service on the Installation page.

# Local Lite mode
sm setup

# Managed Service mode
sm setup --mode remote

For non-interactive Service setup, paste a key from the SmartMemory dashboard (Dashboard, then Settings, then API Keys):

sm setup --mode remote --api-key sk_...

Consumer Environment Variables

Service mode can also be configured with environment variables:

export SMARTMEMORY_API_URL="https://api.smartmemory.ai"
export SMARTMEMORY_API_KEY="sm_live_..."

Lite mode does not require any database, Docker service, or API key.

LLM Configuration

OpenAI

{
  "llm": {
    "provider": "openai",
    "model": "gpt-4",
    "api_key": "${OPENAI_API_KEY}",
    "temperature": 0.7,
    "max_tokens": 2000,
    "timeout": 30
  }
}

Azure OpenAI

{
  "llm": {
    "provider": "azure_openai",
    "api_key": "${AZURE_OPENAI_API_KEY}",
    "api_base": "${AZURE_OPENAI_ENDPOINT}",
    "api_version": "2023-05-15",
    "deployment_name": "gpt-4"
  }
}

Anthropic Claude

{
  "llm": {
    "provider": "anthropic",
    "model": "claude-3-opus-20240229",
    "api_key": "${ANTHROPIC_API_KEY}",
    "max_tokens": 2000
  }
}

Extraction Configuration

Entity and Relationship Extraction

{
  "extraction": {
    "spacy_model": "en_core_web_sm",
    "enable_entity_extraction": true,
    "enable_relationship_extraction": true,
    "entity_types": [
      "PERSON",
      "ORG",
      "GPE",
      "DATE",
      "TIME",
      "MONEY",
      "PRODUCT"
    ],
    "custom_patterns": [
      {
        "label": "SKILL",
        "pattern": [{"LOWER": {"IN": ["python", "javascript", "sql"]}}]
      }
    ]
  }
}

Advanced Extraction Settings

{
  "extraction": {
    "use_llm_extraction": true,
    "llm_extraction_prompt": "Extract entities and relationships from: {text}",
    "confidence_threshold": 0.8,
    "max_entities_per_item": 20,
    "enable_coreference_resolution": true
  }
}

Background Processing

Basic Configuration

{
  "background": {
    "enabled": true,
    "max_workers": 3,
    "queue_size": 1000,
    "batch_size": 10,
    "processing_interval": 5.0
  }
}

Advanced Processing Options

{
  "background": {
    "enabled": true,
    "max_workers": 5,
    "queue_size": 2000,
    "batch_size": 20,
    "processing_interval": 2.0,
    "retry_attempts": 3,
    "retry_delay": 1.0,
    "enable_priority_queue": true,
    "high_priority_types": ["episodic", "procedural"]
  }
}

Similarity Metrics

Weight Configuration

{
  "similarity": {
    "semantic_weight": 0.4,
    "content_weight": 0.3,
    "temporal_weight": 0.2,
    "metadata_weight": 0.1,
    "enable_adaptive_weighting": true
  }
}

Advanced Similarity Settings

{
  "similarity": {
    "semantic_model": "all-MiniLM-L6-v2",
    "content_similarity_method": "jaccard",
    "temporal_decay_factor": 0.1,
    "metadata_fields": ["memory_type", "user_id", "tags"],
    "similarity_threshold": 0.3
  }
}

The optional keys maximal_connectivity, rapid_enrichment, strategic_pruning, and hierarchical_organization select the experimental agent-optimized suite. They map to the MaximalConnectivityEvolver, RapidEnrichmentEvolver, StrategicPruningEvolver, and HierarchicalOrganizationEvolver classes that live in service_common/plugins/evolvers/optimized/ and are registered under those snake-case keys. They run aggressive connectivity, enrichment, pruning, and organization passes intended for agent workloads.

The core shipped evolvers in smartmemory/plugins/evolvers/:

Evolver	Purpose
`EpisodicToSemanticEvolver`	Promote stable episodic facts to semantic
`EpisodicToZettelEvolver`	Promote significant episodic memories to atomic Zettelkasten notes
`EpisodicDecayEvolver`	Decay confidence on aging episodic items
`SemanticDecayEvolver`	Decay confidence on aging semantic items
`SemanticToProceduralEvolver`	Promote repeated semantic patterns to procedures
`MemoryConsolidationEvolver`	Consolidate near-duplicate items
`OpinionSynthesisEvolver`	Synthesize opinion items from supporting evidence
`OpinionReinforcementEvolver`	Reinforce / weaken opinions on new evidence
`ObservationSynthesisEvolver`	Build entity observations from scattered facts
`DecisionConfidenceEvolver`	Update decision confidence from supporting/contradicting items
`ProceduralReinforcementEvolver`	Reinforce procedures on successful re-use
`ZettelPruneEvolver`	Prune low-value or orphaned Zettelkasten notes
`StaleMemoryEvolver`	Mark items stale when valid_end_time has passed
`AnchorReconciliationEvolver`	Reconcile session anchors with the live graph
`ResolutionChainEvolver`	Track resolution chains for follow-up questions
`QAHeuristicEvolver`	Heuristic Q&A pair detection for episodic→semantic promotion

Configure via the evolution block in your config:

{
  "evolution": {
    "enabled": true,
    "interval_seconds": 3600
  }
}

Per-evolver tuning lives on the evolver's Config model (e.g. EpisodicDecayConfig, OpinionSynthesisConfig). See the source files under smartmemory/plugins/evolvers/ for the authoritative parameter list.

Ontology Configuration

Basic Ontology Settings

{
  "ontology": {
    "enabled": true,
    "storage_backend": "FileSystemOntologyStorage",
    "storage_path": "./ontologies",
    "default_ontology": "general_knowledge"
  }
}

Advanced Ontology Management

{
  "ontology": {
    "enabled": true,
    "auto_inference": true,
    "inference_threshold": 0.7,
    "enable_hitl_validation": true,
    "validation_rules": [
      "entity_type_consistency",
      "relationship_constraints",
      "domain_validation"
    ]
  }
}

Performance Tuning

High-Performance Configuration

{
  "performance": {
    "enable_caching": true,
    "cache_size": 10000,
    "cache_ttl": 3600,
    "enable_batch_operations": true,
    "batch_size": 100,
    "connection_pool_size": 10,
    "query_timeout": 30
  }
}

Memory Optimization

{
  "memory_optimization": {
    "enable_lazy_loading": true,
    "max_memory_usage_mb": 2048,
    "garbage_collection_interval": 300,
    "enable_compression": true,
    "compression_algorithm": "gzip"
  }
}

Server Configuration

Lite and managed Service users do not configure or run server storage backends. Server configuration is provided to Enterprise BYOC customers during onboarding.

Configuration Loading

Programmatic Configuration

from smartmemory import SmartMemory
from smartmemory.configuration import MemoryConfig
from smartmemory.utils import get_config

# Load from file (recommended via environment variable SMARTMEMORY_CONFIG)
cfg = MemoryConfig(config_path="config.json")
cfg.validate()

# SmartMemory reads configuration via the configuration subsystem
memory = SmartMemory()

# Access configuration at runtime
vector_cfg = get_config('vector')
print(vector_cfg.get('backend'))

Runtime Configuration Updates

# Apply runtime config changes by editing the file, then either:
from smartmemory.configuration import MemoryConfig
cfg = MemoryConfig(config_path="config.json")
cfg.reload_if_stale(force=True)

# Or clear the cached config so subsequent get_config() calls reload
from smartmemory.utils import get_config, clear_config_cache
clear_config_cache()
current_config = get_config()
print(current_config.get('similarity'))

Environment Variables

Required at Runtime

# LLM API keys (required only for LLM-backed extraction)
export OPENAI_API_KEY="your-openai-api-key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"

# Service mode credentials
export SMARTMEMORY_API_KEY="sm_live_..."
export SMARTMEMORY_API_URL="https://api.smartmemory.ai"

`SMARTMEMORY_*`: Service mode clients

Read by the smartmemory package in Service mode. The Python client (smartmemory-client) also reads SMARTMEMORY_API_KEY and SMARTMEMORY_TEAM_ID, but takes the API URL as its base_url argument.

Variable	Purpose	Example
`SMARTMEMORY_API_URL`	Base URL of the SmartMemory hosted API. Overrides the `mode=remote` config default.	`https://api.smartmemory.ai`
`SMARTMEMORY_API_KEY`	Bearer token for API auth.	`sm_live_...`
`SMARTMEMORY_TEAM_ID`	Default `X-Team-Id` header for tenant scoping.	UUID

Debug / Logging

# Enable verbose debug logging (read by smartmemory-core)
export SMARTMEMORY_DEBUG="true"

Configuration Validation

SmartMemory automatically validates configuration on startup:

from smartmemory.configuration import MemoryConfig

# Validate configuration file
cfg = MemoryConfig(config_path="config.json")
cfg.validate()

Best Practices

Use environment variables for sensitive information like API keys
Use Lite when you want local, zero-infrastructure memory
Use Service when you want managed remote memory with nothing to operate
Separate configurations for different environments (dev, staging, prod)
Enable background processing in backend deployments for better performance
Configure appropriate worker counts based on your hardware
Monitor resource usage and adjust configuration accordingly

Troubleshooting

Common Configuration Issues

Invalid JSON syntax - Use a JSON validator to check your configuration
Missing environment variables - Ensure all required variables are set
Service connection failures - Verify SMARTMEMORY_API_KEY and SMARTMEMORY_API_URL
Performance issues - Adjust worker counts and batch sizes
Memory usage - Configure memory limits and garbage collection

Configuration Debugging

# Enable debug logging
import logging
logging.basicConfig(level=logging.DEBUG)

# Validate and inspect configuration
from smartmemory.configuration import MemoryConfig
cfg = MemoryConfig(config_path="config.json")
cfg.validate()
print(cfg.graph_db)