Configuration

SmartMemory provides extensive configuration options to customize behavior for your specific use case. This guide covers all available configuration options and best practices.

Configuration File Structure

SmartMemory uses JSON configuration files with environment variable expansion support:

{
  "graph_db": {
    "backend_class": "FalkorDBBackend",
    "host": "localhost",
    "port": 6379,
    "graph_name": "smartmemory"
  },
  "vector": {
    "backend": "falkordb",
    "host": "localhost",
    "port": 9010,
    "dimension": 768,
    "metric": "cosine"
  },
  "llm": {
    "provider": "openai",
    "model": "gpt-4",
    "api_key": "${OPENAI_API_KEY}"
  },
  "extractor": {
    "spacy_model": "en_core_web_sm"
  },
  "background": {
    "enabled": true,
    "max_workers": 3,
    "queue_size": 1000
  },
  "similarity": {
    "semantic_weight": 0.4,
    "content_weight": 0.3,
    "temporal_weight": 0.2,
    "metadata_weight": 0.1
  },
  "evolution": {
    "enabled": true,
    "algorithms": [
      "maximal_connectivity",
      "rapid_enrichment",
      "strategic_pruning"
    ]
  }
}

Graph Backend Configuration

FalkorDB Backend (Recommended)

{
  "graph_db": {
    "backend_class": "FalkorDBBackend",
    "host": "localhost",
    "port": 6379,
    "graph_name": "smartmemory",
    "password": "${REDIS_PASSWORD}",
    "ssl": false,
    "ssl_cert_reqs": "none"
  }
}

SQLite Backend (Lite Mode)

For zero-infrastructure local use, SmartMemory ships a SQLite graph backend (SmartMemory Lite). It requires no Docker — point backend_class at SQLiteBackend and supply a file path:

{
  "graph_db": {
    "backend_class": "SQLiteBackend",
    "db_path": "./data/memory.db"
  }
}

Vector Store Configuration

SmartMemory defaults to FalkorDB for vector storage and search.

FalkorDB (Default)

{
  "vector": {
    "default": "falkordb",
    "type": "falkordb",
    "dimension": 1536,
    "metric": "cosine",
    "hnsw_m": 16,
    "hnsw_ef_construction": 200,
    "hnsw_ef_runtime": 64
  }
}

Backend writes embeddings as native vectors and creates a Vector Index automatically. Minimal Cypher (for reference):

// Schema
CREATE VECTOR INDEX FOR (n:Vec_default) ON (n.embedding)
OPTIONS {dimension:768, similarityFunction:'cosine', M:16, efConstruction:200, efRuntime:64};

// Insert
CREATE (:Vec_default {id:'a', embedding: vecf32([1.0, 0.0])});

// Search top-8
CALL db.idx.vector.queryNodes('Vec_default','embedding', 8, vecf32([0.9, 0.1]))
YIELD node, score
RETURN node.id, score
ORDER BY score DESC;

Knobs: vector.dimension, vector.metric ('cosine'|'euclidean'), vector.hnsw_m, vector.hnsw_ef_construction, vector.hnsw_ef_runtime.

falkordb is the default and only required vector backend — embeddings live natively inside FalkorDB, so there is no separate vector service to run. An optional usearch backend is also registered for embedded, file-backed use cases:

{
  "vector": {
    "backend": "usearch",
    "dimension": 768,
    "metric": "cosine"
  }
}

These are the only two registered vector backends.

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

Evolution Algorithms

The keys in the example above (maximal_connectivity, rapid_enrichment, strategic_pruning, plus hierarchical_organization) select the experimental agent-optimized suite — 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/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"
  }
}

Environment-Specific Configurations

Development Configuration

{
  "environment": "development",
  "debug": true,
  "log_level": "DEBUG",
  "graph_db": {
    "backend_class": "FalkorDBBackend",
    "host": "localhost",
    "port": 6379
  },
  "background": {
    "enabled": false
  },
  "evolution": {
    "enabled": false
  }
}

Production Configuration

{
  "environment": "production",
  "debug": false,
  "log_level": "INFO",
  "graph_db": {
    "backend_class": "FalkorDBBackend",
    "host": "${REDIS_HOST}",
    "port": 6379,
    "password": "${REDIS_PASSWORD}",
    "ssl": true
  },
  "background": {
    "enabled": true,
    "max_workers": 8
  },
  "performance": {
    "enable_caching": true,
    "connection_pool_size": 20
  }
}

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 (at least one required)
export OPENAI_API_KEY="your-openai-api-key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"

# Database credentials (production deployments)
export REDIS_PASSWORD="your-redis-password"

`SMARTMEMORY_*` — Server-side Configuration

All SMARTMEMORY_* variables are read by smartmemory-core and the API service. They override values in the JSON config file at runtime.

Variable	Purpose	Default / Example
`SMARTMEMORY_CONFIG`	Path to the JSON configuration file.	`/etc/smartmemory/config.json`
`SMARTMEMORY_CONFIG_DIR`	Directory containing per-environment configs (`dev.json`, `prod.json`).	`~/.smartmemory/config`
`SMARTMEMORY_ENV`	Environment selector — controls which config is loaded and which defaults apply.	`development` \| `production`
`SMARTMEMORY_VERSION`	Override the reported version string (mostly for tests/CI).	from `VERSION` file
`SMARTMEMORY_LLM_MODEL`	Default LLM model identifier (overrides `llm.model` in config).	`gpt-4o`, `claude-sonnet-4-6`
`SMARTMEMORY_LLM_TIMEOUT_SECS`	Hard timeout per LLM call.	`30`
`SMARTMEMORY_EMBEDDING_PROVIDER`	Embedding backend — `openai`, `local`, `mock`.	`openai`
`SMARTMEMORY_EMBEDDING_LOCAL_MODEL`	When using local embeddings, the sentence-transformers model id.	`all-MiniLM-L6-v2`
`SMARTMEMORY_PROMPTS`	Path to a custom prompts directory; falls back to bundled prompts when unset.	`/etc/smartmemory/prompts`
`SMARTMEMORY_OBSERVABILITY`	Enable structured tracing emitters.	`true` \| `false`
`SMARTMEMORY_PROGRESS_MAXLEN`	Per-workspace progress-stream cap (Redis Streams `MAXLEN ~`).	`10000`
`SMARTMEMORY_COMPACTION_ENABLED`	Globally toggle the pipeline `CompactionStage` that strips extraction intermediates.	`false`
`SMARTMEMORY_GROUNDING_OFFLINE`	Skip Wikipedia grounding (useful in air-gapped envs and tests).	`false`
`SMARTMEMORY_STALE_DEMOTION`	Score multiplier (float) applied to stale items during search ranking — lower values demote them harder.	`0.5`
`SMARTMEMORY_CACHE_DISABLED`	Disable in-process config cache; every `get_config()` reloads from disk.	`false`

`SMARTMEMORY_*` — Client-side (SDK + Maya)

Used by smart-memory-client (Python) and any external service connecting to a SmartMemory deployment.

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
`SMARTMEMORY_SERVER_HOST`	Host of the SmartMemory server (used to compose the connection URL when no full URL is set).	`localhost`

`VITE_*` — Frontend Integration

Build-time variables consumed by the React frontends (smart-memory-web, smart-memory-studio, smart-memory-admin, smart-memory-insights). All VITE_* values are baked into the static bundle at build time, so rotation requires a redeploy.

Variable	Purpose	Example
`VITE_API_URL`	Base URL of the SmartMemory API used by the frontend.	`https://api.smartmemory.ai`
`VITE_API_TARGET`	Alternative API target — used by per-app routing in dev.	`http://localhost:9001`
`VITE_AUTH_API_URL`	Base URL for auth (Clerk) API calls; can differ from `VITE_API_URL` when auth is split out.	`https://auth.smartmemory.ai`
`VITE_AUTH_ADMIN_FALLBACK_URL`	Fallback URL for the admin-auth flow when primary auth is unreachable.	`https://admin.smartmemory.ai/auth`
`VITE_CLERK_PUBLISHABLE_KEY`	Clerk publishable key (frontend-safe).	`pk_live_...`
`VITE_DEV_BYPASS_AUTH`	In dev only, skip Clerk and inject a fake user. Never set in production builds.	`true`
`VITE_MEMORY_TARGET`	App routing — which SmartMemory instance to talk to (single-tenant vs shared).	`prod` \| `staging`
`VITE_WEB_APP_URL`	Public origin of the `smart-memory-web` UI.	`https://app.smartmemory.ai`
`VITE_STUDIO_BASE_URL`	Public origin of `smart-memory-studio`.	`https://studio.smartmemory.ai`
`VITE_STUDIO_API_URL`	API target for Studio (may differ from `VITE_API_URL`).	`https://api.smartmemory.ai`
`VITE_INSIGHTS_BASE_URL`	Public origin of `smart-memory-insights`.	`https://insights.smartmemory.ai`
`VITE_WS_URL` / `VITE_WS_TARGET`	WebSocket endpoint for live progress streams.	`wss://api.smartmemory.ai/ws`
`VITE_PIPELINE_STREAM_PROVIDER`	Which transport to use for pipeline progress events (Redis SSE vs WS shim).	`sse`
`VITE_PUBLIC_POSTHOG_KEY`	PostHog project key for product analytics.	`phc_...`
`VITE_PUBLIC_POSTHOG_HOST`	PostHog ingest host.	`https://app.posthog.com`
`VITE_GA_MEASUREMENT_ID`	Google Analytics 4 measurement ID.	`G-XXXXXXX`
`VITE_ERROR_TRACKING_ENDPOINT`	Optional Sentry/Raygun-compatible error sink.	`https://errors.smartmemory.ai/api`
`VITE_SHOW_ALL_LAUNCHERS`	Show every app-launcher tile, even gated ones (internal builds).	`false`

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
Separate configurations for different environments (dev, staging, prod)
Enable background processing in production for better performance
Configure appropriate worker counts based on your hardware
Use persistent storage for graph and vector databases in production
Enable caching for frequently accessed data
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
Backend connection failures - Verify database services are running
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)

Configuration

On this page