Environment Variables Reference

Environment Variables Reference

Complete reference for all AutoMem environment variables.

Quick Start

# Copy example and customize
cp .env.example .env
nano .env

Required Variables

Core Services

Authentication

⚠️ Important: Admin Endpoints Require BOTH Tokens

Admin endpoints (like /enrichment/reprocess, /admin/reembed) require two-level authentication:

1. Authorization: Bearer <AUTOMEM_API_TOKEN> - For general API access
2. X-Admin-Token: <ADMIN_API_TOKEN> - For admin-level operations

Example:

curl -X POST \
  -H "Authorization: Bearer ${AUTOMEM_API_TOKEN}" \
  -H "X-Admin-Token: ${ADMIN_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["memory-id"]}' \
  https://automem.up.railway.app/enrichment/reprocess

Embedding Providers

AutoMem supports five embedding backends with automatic fallback.

Provider Options:

• auto (default): Try Voyage → OpenAI → Ollama (if configured) → FastEmbed local model → Placeholder
• voyage: Use Voyage API only (requires VOYAGE_API_KEY)
• openai: Use OpenAI API only (requires OPENAI_API_KEY)
• local: Use FastEmbed local model only (~210MB download on first use)
• ollama: Use Ollama only (requires OLLAMA_BASE_URL and a pulled model)
• placeholder: Use hash-based embeddings (no semantic search)

Local Model Details:

• Models: BAAI/bge-small-en-v1.5 (384d), BAAI/bge-base-en-v1.5 (768d), BAAI/bge-large-en-v1.5 (1024d)
• Size: 67MB / ~210MB / ~1.2GB (cached to `/.config/automem/models/`)
• No API key or internet required after first download
• Good semantic quality, faster than API calls
• Recommended: pin onnxruntime<1.20 with fastembed 0.4.x to avoid runtime issues
• Docker: persist model cache with a volume (see docker-compose.yml)
• Ensure VECTOR_SIZE equals the selected model's dimension (default 768)

Ollama Details:

• Requires a running Ollama server (default http://localhost:11434)
• Pull the embedding model before use: ollama pull nomic-embed-text
• Embedding dimensions vary by model; set VECTOR_SIZE to match the model output
• For auto mode, Ollama is only attempted if OLLAMA_BASE_URL or OLLAMA_MODEL is set

Voyage Details:

• Requires VOYAGE_API_KEY
• Optional model override via VOYAGE_MODEL (default voyage-4)
• Voyage 4 family supports output dimensions 256, 512, 1024, or 2048
• Set VECTOR_SIZE to one of the supported Voyage dimensions

OpenAI-Compatible Providers (OpenRouter, LiteLLM, Azure, vLLM, etc.):

The openai provider works with any service that exposes an OpenAI-compatible /v1/embeddings endpoint. Set OPENAI_BASE_URL to point at the provider and OPENAI_API_KEY to your provider's key:

EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-or-v1-your-openrouter-key
OPENAI_BASE_URL=https://openrouter.ai/api/v1
EMBEDDING_MODEL=openai/text-embedding-3-small   # model name varies by provider
VECTOR_SIZE=768                                  # must match the model's output dimension

Important notes for non-OpenAI providers:

• The dimensions parameter (which lets OpenAI truncate embeddings) is only sent to OpenAI's own API (api.openai.com). For all other base URLs it is omitted because most compatible providers don't support it.
• You must set VECTOR_SIZE to match the model's native output dimension since dimension truncation is unavailable.
• Model names may differ per provider (e.g. openai/text-embedding-3-small on OpenRouter vs text-embedding-3-small on OpenAI).

Additional Configuration:

Embedding Provider Tradeoffs

Dimension matching tip: If embeddings fail with a size mismatch, confirm your model's output length and set VECTOR_SIZE accordingly (or use VECTOR_SIZE_AUTODETECT=true if you accept adopting the existing collection size).

Hosting Considerations (Railway vs Self-Hosted)

• Railway / managed PaaS: Voyage and OpenAI are the simplest choices (no local model downloads). FastEmbed works but increases image size and cold-start time; use a persistent volume for AUTOMEM_MODELS_DIR if supported. Ollama typically requires a separate service (Railway does not ship Ollama by default), so you'll need to deploy Ollama elsewhere and set OLLAMA_BASE_URL to that service.
• Self-hosted Docker/VPS: FastEmbed and Ollama are straightforward and avoid API costs. Ollama benefits from GPU acceleration if available; otherwise expect higher latency on CPU. Ensure the Ollama base URL is reachable from the AutoMem container (OLLAMA_BASE_URL=http://ollama:11434 in docker-compose setups).
• Dimension consistency: Regardless of host, make sure VECTOR_SIZE matches the embedding model output. Changing models requires re-embedding existing memories.

Optional Variables

Qdrant (Vector Database)

👉 New to Qdrant? See the Qdrant Setup Guide for step-by-step instructions on creating a collection with the right settings.

Notes:

• Without Qdrant, AutoMem uses deterministic placeholder embeddings (for testing only).
• Existing deployments on 768d: set VECTOR_SIZE=768 (and EMBEDDING_MODEL=text-embedding-3-small) until you run the migration script.
• By default the service fails fast if the configured vector size does not match the Qdrant collection to prevent silent corruption.
• To opt into legacy auto-detection (use the existing collection dimension), set VECTOR_SIZE_AUTODETECT=true.

API Server

⚠️ Railway Deployment: PORT must be explicitly set to 8001 in Railway. Without it, Flask defaults to port 5000, causing service connection failures. This is required for Railway deployments, even though it has a default in local development.

Viewer Compatibility

Behavior:

• AutoMem no longer serves built viewer assets in-process.
• /viewer now redirects/bootstraps to GRAPH_VIEWER_URL and forwards server=<automem-origin>.
• URL hash tokens (for example #token=...) stay client-side and are preserved during redirect.

Scripts Only

Backward Compatibility: MCP_MEMORY_HTTP_ENDPOINT is deprecated but still supported (falls back to this if AUTOMEM_API_URL not set).

Health Monitor

Note: Auto-recovery is disabled by default. Use --auto-recover flag to enable (not recommended without testing).

Advanced Configuration

Consolidation Engine

Controls memory merging, pattern detection, and decay.

Model Configuration

Controls which OpenAI models are used for embeddings and classification.

Embedding Model Comparison:

To use small embeddings (saves ~$0.11/1M tokens):

EMBEDDING_MODEL=text-embedding-3-small
VECTOR_SIZE=768

Upgrade safety: Changing embedding dimensions requires a full re-embed. AutoMem refuses to start if VECTOR_SIZE does not match the existing Qdrant collection; set the value to your current dimension (usually 768) before migrating, then switch to 3072 after running scripts/reembed_embeddings.py. To override strict mode and adopt the existing collection dimension, set VECTOR_SIZE_AUTODETECT=true (use only if you understand the risk of dimension drift).

Classification Model Pricing (Dec 2025):

⚠️ Changing embedding models requires re-embedding all memories. See Re-embedding Guide below.

Enrichment Engine

Controls entity extraction and relationship linking.

Note: Enrichment requires spaCy: pip install spacy && python -m spacy download en_core_web_sm

JIT Enrichment: When enabled, memories that haven't been processed by the async worker yet receive lightweight inline enrichment (entity extraction + summary) during recall. This adds ~50ms per unenriched result but ensures entity tags and summaries are available immediately. The async worker still runs expensive operations (temporal links, patterns, semantic neighbors) later.

Search Weights

Controls how different factors are weighted in memory recall scoring.

These act as relative weights in the scoring formula. Keeping them roughly normalized (summing to ~1.0) is recommended for interpretability, but the service does not auto-normalize them.

SEARCH_WEIGHT_RELEVANCE (new): This weight incorporates relevance_score, a value maintained by the consolidation decay engine that reflects access patterns and age. It's synced to both FalkorDB and Qdrant payloads. Default is 0.0 (disabled) — set to e.g. 0.15 to boost frequently-accessed memories. Use the Recall Quality Lab to test different values before changing production.

Memory Content Limits

Controls auto-summarization and content size validation on store.

Sync Configuration

Background worker that checks FalkorDB ↔ Qdrant consistency.

Recall Settings

Railway Auto-Populated

Railway automatically injects these variables in production. Do not set manually.

Usage in AutoMem: app.py falls back to RAILWAY_PRIVATE_DOMAIN if FALKORDB_HOST not set.

Railway Networking Notes:

• Railway's internal networking uses IPv6. AutoMem binds to :: (IPv6 dual-stack) to accept connections from other services.
• RAILWAY_PRIVATE_DOMAIN resolves to IPv6 addresses (e.g., fd12:ca03:42be:0:1000:50:1079:5b6c).
• This is handled automatically - no configuration needed.

Testing Only

These variables are only used by test suites.

Recall Quality Lab

The scripts/lab/ directory provides a data-driven framework for testing and optimizing recall scoring. It uses IR metrics (Recall@K, MRR, NDCG) and statistical comparison to evaluate config changes.

Makefile targets:

Config files live in scripts/lab/configs/ as JSON. Each config maps env var names to values that override the server's search weights for that test run. See baseline.json for an example.

Variable Priority & Fallbacks

AutoMem loads environment variables from multiple sources with this priority:

1. Process environment (highest priority)
2. .env in project root
3. ~/.config/automem/.env (global config)
4. Defaults in code (lowest priority)

Example Fallback Chain

# FalkorDB host resolution
FALKORDB_HOST = (
    os.getenv("FALKORDB_HOST")                  # 1. Explicit setting
    or os.getenv("RAILWAY_PRIVATE_DOMAIN")      # 2. Railway internal domain
    or os.getenv("RAILWAY_PUBLIC_DOMAIN")       # 3. Railway public domain
    or "localhost"                              # 4. Default
)

Security Best Practices

✅ Do

• Use Railway's secret generation for tokens
• Rotate AUTOMEM_API_TOKEN and ADMIN_API_TOKEN regularly
• Keep .env out of version control (already in .gitignore)
• Use Railway's private domains for service-to-service communication
• Set FALKORDB_PASSWORD in production

❌ Don't

• Commit .env to Git
• Share API tokens in public channels
• Use weak passwords for FALKORDB_PASSWORD
• Expose FalkorDB publicly (use RAILWAY_PRIVATE_DOMAIN)
• Hardcode credentials in code

Troubleshooting

"FalkorDB connection failed"

Check:

1. FALKORDB_HOST is correct (Railway: use ${{FalkorDB.RAILWAY_PRIVATE_DOMAIN}})
2. FALKORDB_PORT matches service port
3. FALKORDB_PASSWORD matches FalkorDB's REDIS_PASSWORD
4. FalkorDB service is running and healthy

"Qdrant is not available"

Check:

1. QDRANT_URL is reachable
2. QDRANT_API_KEY is correct (if using Qdrant Cloud)
3. Collection exists: curl $QDRANT_URL/collections/memories

Note: AutoMem works without Qdrant (graph-only mode) but semantic search is disabled.

"401 Unauthorized"

Check:

1. AUTOMEM_API_TOKEN is set and matches request token
2. Token is passed correctly: Authorization: Bearer $TOKEN
3. For admin endpoints: X-Admin-Token header also required

Migration Guide

From Old Variable Names

Backward compatibility: Old names still work as fallbacks.

Re-embedding Memories

When changing EMBEDDING_MODEL or VECTOR_SIZE, you must re-embed all existing memories:

1. Backup First

python scripts/backup_automem.py

2. Set New Environment Variables

export EMBEDDING_MODEL=text-embedding-3-large  # or text-embedding-3-small
export VECTOR_SIZE=3072  # 3072 for large, 768 for small

3. Recreate Qdrant Collection

The collection must be recreated with the new dimension:

# Delete old collection
curl -X DELETE "$QDRANT_URL/collections/memories" \
  -H "api-key: $QDRANT_API_KEY"

# Create new collection with correct dimension
curl -X PUT "$QDRANT_URL/collections/memories" \
  -H "api-key: $QDRANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vectors": {"size": 3072, "distance": "Cosine"}}'  # Use 768 for small

4. Re-embed All Memories

python scripts/reembed_embeddings.py --batch-size 32

The script reads from FalkorDB (which retains all memory data) and re-creates the vector embeddings in Qdrant.

Cost estimate: ~$0.15 for 6000 memories with large embeddings, ~$0.02 with small.

See Also

• Railway Deployment Guide
• Deployment Checklist
• Installation Guide