Environment Variables

This page is a quick-reference table of all AutoMem environment variables, grouped by category. For full documentation of each variable including validation rules, behavior details, and configuration examples, see Configuration Reference.

---

Configuration Loading

Variables are loaded from multiple sources in priority order:

1. Process environment — export VAR=value or variables injected by the platform (Railway, Docker)
2. Project .env — File in repository root
3. User config — ~/.config/automem/.env (personal overrides, never committed)

Variables set earlier in this list take precedence over later sources.

Tip

Use ~/.config/automem/.env for personal API keys and secrets that should never be committed. Use project .env for shared development defaults like FALKORDB_HOST=localhost.

---

Server Variables

Core Database

Variable	Required	Default	Description
FALKORDB_HOST	No	localhost	FalkorDB graph database hostname
FALKORDB_PORT	No	6379	FalkorDB port
FALKORDB_PASSWORD	No	unset	FalkorDB/Redis password (set in production)
FALKORDB_GRAPH	No	memories	Graph name for Cypher queries
GRAPH_NAME	—	memories	Python-internal alias for FALKORDB_GRAPH; set FALKORDB_GRAPH, not this name
PORT	No	8001	Flask API server port

Tip

AutoMem defaults PORT to 8001 when it is unset — it does not fall back to Flask’s usual 5000. Set PORT explicitly only when you need a different port, or when your platform expects to inject one (Railway sets it for you).

Vector Search (Qdrant)

AutoMem operates in graph-only mode if these variables are not set. Qdrant enables semantic vector search but is optional.

Variable	Required	Default	Description
QDRANT_URL	No	unset	Qdrant API endpoint (HTTP or HTTPS)
QDRANT_HOST	No	unset	Qdrant hostname (alternative to QDRANT_URL)
QDRANT_PORT	No	6333	Qdrant port (used with QDRANT_HOST)
QDRANT_API_KEY	No	unset	Qdrant authentication key (required for Qdrant Cloud)
QDRANT_COLLECTION	No	memories	Collection name for memory vectors
COLLECTION_NAME	—	memories	Python-internal alias for QDRANT_COLLECTION; set QDRANT_COLLECTION, not this name
VECTOR_SIZE	No	1024	Embedding dimension — must match collection (768/1024/2048/3072)
QDRANT_VECTOR_SIZE	No	1024	Alternative name for VECTOR_SIZE (checked as fallback when VECTOR_SIZE is unset)

Authentication

Variable	Required	Default	Description
AUTOMEM_API_TOKEN	Yes	unset	Token for all standard API operations
ADMIN_API_TOKEN	Yes	unset	Token for admin endpoints (/admin/*, /enrichment/reprocess)

See Authentication for token generation and usage details.

Embeddings

Variable	Required	Default	Description
EMBEDDING_PROVIDER	No	auto	Provider selection: auto / voyage / openai / local / ollama / placeholder
EMBEDDING_MODEL	No	text-embedding-3-small	OpenAI model name
OPENAI_API_KEY	No	unset	OpenAI (or compatible provider) API key
OPENAI_BASE_URL	No	unset	Custom base URL for OpenAI-compatible APIs (OpenRouter, LiteLLM, vLLM)
VOYAGE_API_KEY	No	unset	Voyage AI API key
VOYAGE_MODEL	No	voyage-4	Voyage AI embedding model (also: voyage-4-large, voyage-4-lite)
OLLAMA_BASE_URL	No	http://localhost:11434	Ollama server endpoint
OLLAMA_MODEL	No	nomic-embed-text	Ollama embedding model
OLLAMA_TIMEOUT	No	30	Ollama request timeout in seconds
OLLAMA_MAX_RETRIES	No	2	Retry attempts on Ollama connection failure
EMBEDDING_BATCH_SIZE	No	20	Items per batch API call (reduces costs 40–50%)
EMBEDDING_BATCH_TIMEOUT_SECONDS	No	2.0	Max wait before flushing a partial batch
AUTOMEM_MODELS_DIR	No	~/.config/automem/models/	Local FastEmbed model cache directory

Enrichment Pipeline

Background enrichment runs after each memory is stored — it generates similarity links, entity tags, and summaries.

Variable	Required	Default	Description
ENRICHMENT_MAX_ATTEMPTS	No	3	Retry limit before marking a job failed
ENRICHMENT_SIMILARITY_LIMIT	No	5	Number of semantic neighbors to link
ENRICHMENT_SIMILARITY_THRESHOLD	No	0.8	Min cosine similarity for SIMILAR_TO edge
ENRICHMENT_IDLE_SLEEP_SECONDS	No	2	Worker sleep duration when queue is empty
ENRICHMENT_FAILURE_BACKOFF_SECONDS	No	5	Delay between retry attempts
ENRICHMENT_ENABLE_SUMMARIES	No	true	Auto-generate memory summaries
ENRICHMENT_SPACY_MODEL	No	en_core_web_sm	spaCy model for NER (if installed)
JIT_ENRICHMENT_ENABLED	No	true	Run lightweight entity/summary extraction inline during recall, for results that the background worker has not enriched yet (just-in-time)

Consolidation Engine

Background maintenance cycles that decay, cluster, and optionally forget low-value memories.

Variable	Required	Default	Description
CONSOLIDATION_TICK_SECONDS	No	60	Scheduler check interval
CONSOLIDATION_DECAY_INTERVAL_SECONDS	No	86400	Decay cycle frequency (1 day)
CONSOLIDATION_DECAY_IMPORTANCE_THRESHOLD	No	0.3	Min importance to process in decay
CONSOLIDATION_CREATIVE_INTERVAL_SECONDS	No	604800	Creative association cycle frequency (1 week)
CONSOLIDATION_CLUSTER_INTERVAL_SECONDS	No	2592000	Cluster pattern cycle frequency (1 month)
CONSOLIDATION_FORGET_INTERVAL_SECONDS	No	0	Forget cycle frequency (disabled by default)
CONSOLIDATION_ARCHIVE_THRESHOLD	No	0.0	Relevance threshold for archiving (0.0 = disabled)
CONSOLIDATION_DELETE_THRESHOLD	No	0.0	Relevance threshold for deletion (0.0 = disabled)
CONSOLIDATION_GRACE_PERIOD_DAYS	No	90	Min age in days before a memory can be forgotten
CONSOLIDATION_IMPORTANCE_PROTECTION_THRESHOLD	No	0.7	Memories above this importance are never forgotten
CONSOLIDATION_PROTECTED_TYPES	No	Decision,Insight	Comma-separated types to never forget
CONSOLIDATION_BASE_DECAY_RATE	No	0.01	Base rate applied per decay cycle
CONSOLIDATION_IMPORTANCE_FLOOR_FACTOR	No	0.3	Minimum importance fraction after decay
CONSOLIDATION_HISTORY_LIMIT	No	20	Max consolidation run records retained in the graph
CONSOLIDATION_CONTROL_NODE_ID	No	global	ID of the consolidation control node in the graph
CONSOLIDATION_CLUSTER_SIMILARITY_THRESHOLD	No	0.75	Min cosine similarity for cluster membership (0–1)
CONSOLIDATION_MIN_CLUSTER_SIZE	No	3	Min memories required to form a cluster
IDENTITY_SYNTHESIS_ENABLED	No	false	Enable experimental scheduled entity identity synthesis
CONSOLIDATION_IDENTITY_INTERVAL_SECONDS	No	0 (604800 when enabled)	Identity synthesis cycle frequency; 0 disables the cycle
IDENTITY_SYNTHESIS_MODEL	No	CLASSIFICATION_MODEL	Model used for entity identity synthesis

Search and Recall

Variable	Required	Default	Description
SEARCH_WEIGHT_VECTOR	No	0.35	Vector similarity weight
SEARCH_WEIGHT_KEYWORD	No	0.35	Keyword/TF-IDF matching weight
SEARCH_WEIGHT_METADATA	No	0.35	Structured metadata field match weight
SEARCH_WEIGHT_TAG	No	0.20	Tag overlap weight
SEARCH_WEIGHT_IMPORTANCE	No	0.10	User-assigned importance weight
SEARCH_WEIGHT_RECENCY	No	0.10	Freshness boost weight
SEARCH_WEIGHT_CONFIDENCE	No	0.05	Memory confidence weight
SEARCH_WEIGHT_EXACT	No	0.20	Content token overlap weight
SEARCH_WEIGHT_RELATION	No	0.25	Graph relation proximity boost
SEARCH_WEIGHT_RELEVANCE	No	0.0	Weight on the consolidation-decay relevance_score (access patterns + age). Experimental; 0.0 makes it a no-op
RECALL_RELATION_LIMIT	No	5	Max related memories per result
RECALL_EXPANSION_LIMIT	No	25	Max memories added via expand_relations=true
RECALL_MIN_SCORE	No	0.0	Minimum score threshold for returned results
RECALL_ADAPTIVE_FLOOR	No	true	Dynamically adjust score floor based on result set
RECALL_VECTOR_OVERFETCH	No	4	Vector candidate pool multiplier before hybrid re-rank (1 = legacy 1× fetch)
RECALL_VECTOR_FETCH_CAP	No	200	Hard cap on over-fetched vector candidates (separate from RECALL_MAX_LIMIT)
RECALL_EXCLUDED_TYPES	No	MetaPattern	Comma-separated memory types excluded from /recall and vector sync counts
RECALL_MAX_LIMIT	No	100	Hard cap on the number of results /recall can return
SEARCH_RECENCY_WINDOW_DAYS	No	180	Recency decay window in days (shapes SEARCH_WEIGHT_RECENCY, not a weight)
SEARCH_RECENCY_CURVE	No	linear	Recency decay curve: linear (reaches 0 at the window) or exp (window acts as half-life); invalid falls back to linear
SEARCH_WEIGHT_TEMPORAL	No	0.1	Relative-recency re-rank bonus; only applied when the recency_bias re-rank runs. Inert by default
RECALL_METADATA_SEARCH_ENABLED	No	true	Enable bounded metadata sidecar recall candidates (on by default; no request parameter)
RECALL_RECENCY_BIAS	No	off	Default relative-recency re-rank mode: off, on, or auto (temporal-intent queries only). Per-request override via the recency_bias query param
RECALL_RELEVANCE_GATE	No	0.0	Within-pool relevance gate; ramps down query-independent score components for low-evidence results. 0.0 = disabled
SEARCH_TAG_SCORE_TOKEN_CAP	No	0	Caps the tag-score normalization denominator; 0 = legacy behavior (raising it is opt-in — it regressed Recall@5 in testing)

For guidance on when to tune these ranking knobs, see the Recall Tuning guide.

Sync Worker

Variable	Required	Default	Description
SYNC_CHECK_INTERVAL_SECONDS	No	3600	Frequency of drift checks between FalkorDB and Qdrant (1 hour)
SYNC_AUTO_REPAIR	No	true	Automatically queue missing embeddings when drift detected

Memory Types and Classification

Variable	Required	Default	Description
CLASSIFICATION_MODEL	No	gpt-4o-mini	OpenAI model used for content classification fallback
MEMORY_CONTENT_SOFT_LIMIT	No	500	Character threshold above which a warning is issued and auto-summarize may trigger
MEMORY_CONTENT_HARD_LIMIT	No	2000	Character limit above which the request is rejected immediately
MEMORY_AUTO_SUMMARIZE	No	true	Automatically summarize content exceeding the soft limit
MEMORY_SUMMARY_TARGET_LENGTH	No	300	Target character length for auto-generated summaries

API Server

The service has no logging or Flask-mode environment variables. Logging is configured once at startup at INFO level and there is no LOG_LEVEL override; FLASK_ENV and FLASK_DEBUG are not read anywhere, so setting them has no effect (debug mode and hot reload are not available). To change the log level today you have to edit the configure_logging() call in app.py.

AUTOMEM_LOG_LEVEL in the MCP client table below is unrelated — it controls the mcp-automem client, not the Python service.

---

MCP Client Variables

These variables configure the mcp-automem client package, not the server.

Variable	Required	Default	Description
AUTOMEM_API_URL	Yes	http://127.0.0.1:8001	HTTP URL of the AutoMem server (canonical name)
AUTOMEM_ENDPOINT	No	unset	Deprecated alias for AUTOMEM_API_URL; still accepted but logs a warning
AUTOMEM_API_KEY	No	unset	API key for authenticated instances (preferred name)
AUTOMEM_API_TOKEN	No	unset	Alternative name for the API key
AUTOMEM_LOG_LEVEL	No	unset	Set to debug for verbose MCP client logging
AUTOMEM_RECALL_TOKEN_BUDGET	No	18000	Global estimated token budget for MCP recall_memory responses (applies to all formats, including json; memory_id fetches are never truncated)
AUTOMEM_PROCESS_TAG	No	unset	Process title tag for safe process management
MCP_PROCESS_TAG	No	unset	Alternative process tag variable

The client checks endpoint variables in this priority order: AUTOMEM_API_URL → AUTOMEM_ENDPOINT (deprecated). The client checks API key variables in this priority order: AUTOMEM_API_KEY → AUTOMEM_API_TOKEN.

---

Testing Variables

Used only for the AutoMem test suite — do not set in production.

Variable	Required	Default	Description
AUTOMEM_RUN_INTEGRATION_TESTS	No	0	Enable integration test suite
AUTOMEM_START_DOCKER	No	0	Auto-start Docker Compose before tests
AUTOMEM_STOP_DOCKER	No	0	Auto-stop Docker after tests
AUTOMEM_TEST_BASE_URL	No	http://localhost:8001	Test target URL
AUTOMEM_ALLOW_LIVE	No	0	Allow tests against non-localhost URLs
AUTOMEM_TEST_API_TOKEN	No	unset	API token for integration tests
AUTOMEM_TEST_ADMIN_TOKEN	No	unset	Admin token for integration tests

---

Example Configurations

Minimal local (graph-only, no vector search)

AUTOMEM_API_TOKEN=your-token-here
ADMIN_API_TOKEN=your-admin-token-here
FALKORDB_HOST=localhost
FALKORDB_PORT=6379
PORT=8001

Local with OpenAI embeddings and Qdrant

AUTOMEM_API_TOKEN=your-token-here
ADMIN_API_TOKEN=your-admin-token-here
FALKORDB_HOST=localhost
PORT=8001
OPENAI_API_KEY=sk-...
QDRANT_URL=http://localhost:6333
VECTOR_SIZE=1024

Local with Ollama (fully offline)

AUTOMEM_API_TOKEN=your-token-here
ADMIN_API_TOKEN=your-admin-token-here
FALKORDB_HOST=localhost
PORT=8001
EMBEDDING_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=nomic-embed-text
QDRANT_URL=http://localhost:6333
VECTOR_SIZE=768

Railway production

PORT=8001
FALKORDB_HOST=falkordb.railway.internal
FALKORDB_PORT=6379
FALKORDB_PASSWORD=<generated>
AUTOMEM_API_TOKEN=<generated>
ADMIN_API_TOKEN=<generated>
OPENAI_API_KEY=sk-...
QDRANT_URL=https://your-cluster.cloud.qdrant.io
QDRANT_API_KEY=your-qdrant-key
VECTOR_SIZE=1024

MCP client (in platform config file)

{
  "env": {
    "AUTOMEM_API_URL": "https://your-service.railway.app",
    "AUTOMEM_API_KEY": "your-api-token"
  }
}

---

Security Checklist

• Never commit .env files — add to .gitignore
• Use strong tokens — minimum 32 bytes: openssl rand -hex 32
• Use separate tokens for AUTOMEM_API_TOKEN and ADMIN_API_TOKEN
• Set FALKORDB_PASSWORD in all production environments
• Use HTTPS for all external service endpoints (Qdrant Cloud, OpenAI, Voyage)
• Use Railway private networking — never expose FalkorDB publicly
• Avoid query parameter auth (?api_key=) in production — tokens appear in server logs