Skip to main content

​
Environment Variables

CEMS server is configured via environment variables. These are typically set in a .env file or passed directly to Docker Compose.

​
Required Variables

​
OPENROUTER_API_KEY

​
OPENROUTER_API_KEY
string
required
OpenRouter API key for LLM and embedding operations.Get your key at: openrouter.ai/keysUsed for:
  • Embeddings (openai/text-embedding-3-small)
  • LLM operations (query synthesis, HyDE, maintenance)
  • All AI functionality
OPENROUTER_API_KEY=sk-or-v1-...

​
CEMS_ADMIN_KEY

​
CEMS_ADMIN_KEY
string
required
Admin API key for user and team management.Generate with:
openssl rand -hex 32
Used for:
  • Creating users (POST /admin/users)
  • Resetting API keys (POST /admin/users/{id}/reset-key)
  • Managing teams (POST /admin/teams)
  • All /admin/* endpoints
CEMS_ADMIN_KEY=a1b2c3d4e5f6...
Keep this secret! Anyone with the admin key can create/delete users and access all data.

​
Database Configuration

​
CEMS_DATABASE_URL

​
CEMS_DATABASE_URL
string
default:"auto-configured in docker-compose"
PostgreSQL connection URL.Format:
postgresql://username:password@host:port/database
Docker Compose default:
CEMS_DATABASE_URL=postgresql://cems:${POSTGRES_PASSWORD}@postgres:5432/cems
In Docker Compose, this is automatically set to use the postgres service.

​
POSTGRES_PASSWORD

​
POSTGRES_PASSWORD
string
default:"cems_secure_password"
PostgreSQL database password.Change this in production!
POSTGRES_PASSWORD=your_secure_password_here

​
Server Configuration

​
CEMS_MODE

​
CEMS_MODE
string
default:"server"
Operating mode for CEMS.Options:
  • server - Multi-user server mode (Docker deployment)
  • client - Client mode (connects to remote server)
Docker Compose sets:
CEMS_MODE=server

​
CEMS_SERVER_HOST

​
CEMS_SERVER_HOST
string
default:"0.0.0.0"
Host to bind the server to.
  • 0.0.0.0 - Listen on all interfaces (Docker default)
  • 127.0.0.1 - Localhost only
CEMS_SERVER_HOST=0.0.0.0

​
CEMS_SERVER_PORT

​
CEMS_SERVER_PORT
number
default:"8765"
Port for the REST API server.
CEMS_SERVER_PORT=8765

​
Embedding Configuration

​
CEMS_EMBEDDING_BACKEND

​
CEMS_EMBEDDING_BACKEND
string
default:"openrouter"
Embedding provider backend.Options:
  • openrouter - OpenRouter API (1536-dim, default)
  • llamacpp_server - Local llama.cpp server (768-dim)
Recommended: Use openrouter for best performance.
CEMS_EMBEDDING_BACKEND=openrouter

​
CEMS_EMBEDDING_DIMENSION

​
CEMS_EMBEDDING_DIMENSION
number
default:"1536"
Embedding vector dimension.Must match your backend:
  • 1536 - OpenRouter (openai/text-embedding-3-small)
  • 768 - llama.cpp (embeddinggemma-300M-Q8_0.gguf)
CEMS_EMBEDDING_DIMENSION=1536
Changing this after deployment requires rebuilding all embeddings.

​
CEMS_EMBEDDING_MODEL

​
CEMS_EMBEDDING_MODEL
string
default:"openai/text-embedding-3-small"
Embedding model (OpenRouter format: provider/model).Default:
CEMS_EMBEDDING_MODEL=openai/text-embedding-3-small
Other options:
  • openai/text-embedding-3-large (3072-dim, higher quality)
  • text-embedding-3-small (if using OpenAI directly)

​
LLM Configuration

​
CEMS_LLM_MODEL

​
CEMS_LLM_MODEL
string
default:"openai/gpt-4o-mini"
LLM model for maintenance operations and query synthesis.Default:
CEMS_LLM_MODEL=openai/gpt-4o-mini
Other options:
  • openai/gpt-4o (higher quality, slower)
  • anthropic/claude-3.5-sonnet (Anthropic via OpenRouter)
  • x-ai/grok-4.1-fast (fast alternative)

​
Retrieval Configuration

​
CEMS_RERANKER_BACKEND

​
CEMS_RERANKER_BACKEND
string
default:"disabled"
Reranker backend for search result refinement.Options:
  • disabled - No reranking (default, best performance)
  • llm - OpenRouter LLM reranker
  • llamacpp_server - Local llama.cpp reranker
Rerankers significantly hurt performance in testing:
  • LLM reranker: 88% → 81% (-7%)
  • llamacpp_server: 86% → 28% (-58%)
Recommendation: Keep disabled.
CEMS_RERANKER_BACKEND=disabled

​
Advanced Settings

These settings have sensible defaults and typically don’t need to be changed.

​
Debug Mode

​
CEMS_DEBUG_MODE
boolean
default:"true"
Enable debug mode (exceptions bubble up instead of silent fallbacks).
CEMS_DEBUG_MODE=true  # Development
CEMS_DEBUG_MODE=false # Production

​
Retrieval Settings

​
CEMS_RELEVANCE_THRESHOLD
number
default:"0.4"
Minimum similarity score to include in results.
CEMS_RELEVANCE_THRESHOLD=0.4
​
CEMS_DEFAULT_MAX_TOKENS
number
default:"4000"
Default token budget for retrieval results.
CEMS_DEFAULT_MAX_TOKENS=4000
​
CEMS_MAX_CANDIDATES_PER_QUERY
number
default:"150"
Max candidates per vector search query.
CEMS_MAX_CANDIDATES_PER_QUERY=150

​
Scheduler Settings

​
CEMS_ENABLE_SCHEDULER
boolean
default:"true"
Enable background maintenance jobs.
CEMS_ENABLE_SCHEDULER=true
​
CEMS_NIGHTLY_HOUR
number
default:"3"
Hour for nightly consolidation (0-23, UTC).
CEMS_NIGHTLY_HOUR=3
​
CEMS_WEEKLY_DAY
string
default:"sun"
Day for weekly summarization.
CEMS_WEEKLY_DAY=sun

​
Decay Settings

​
CEMS_STALE_DAYS
number
default:"90"
Days before memory is considered stale.
CEMS_STALE_DAYS=90
​
CEMS_ARCHIVE_DAYS
number
default:"180"
Days before memory is archived.
CEMS_ARCHIVE_DAYS=180
​
CEMS_DUPLICATE_SIMILARITY_THRESHOLD
number
default:"0.92"
Cosine similarity threshold for duplicate detection.
CEMS_DUPLICATE_SIMILARITY_THRESHOLD=0.92

​
Example .env File

Here’s a complete example for production: 
# Required
OPENROUTER_API_KEY=sk-or-v1-...
CEMS_ADMIN_KEY=a1b2c3d4e5f6...

# Database
POSTGRES_PASSWORD=your_secure_password_here

# Server
CEMS_MODE=server
CEMS_SERVER_HOST=0.0.0.0
CEMS_SERVER_PORT=8765

# Embeddings (defaults are fine)
CEMS_EMBEDDING_BACKEND=openrouter
CEMS_EMBEDDING_DIMENSION=1536
CEMS_EMBEDDING_MODEL=openai/text-embedding-3-small

# LLM
CEMS_LLM_MODEL=openai/gpt-4o-mini

# Retrieval
CEMS_RERANKER_BACKEND=disabled

# Optional: Adjust for your timezone
CEMS_NIGHTLY_HOUR=3  # 3 AM UTC

​
Verifying Configuration

Use the admin debug endpoint to verify your configuration: 
source .env
curl -H "Authorization: Bearer $CEMS_ADMIN_KEY" \
  http://localhost:8765/admin/debug
Response: 
{
  "config": {
    "OPENROUTER_API_KEY": "set",
    "CEMS_EMBEDDING_MODEL": "openai/text-embedding-3-small (default)",
    "CEMS_LLM_MODEL": "openai/gpt-4o-mini (default)",
    "VECTOR_STORE": "pgvector (unified PostgreSQL)"
  }
}

​
Testing LLM Connectivity

Test your OpenRouter API key: 
source .env
curl -H "Authorization: Bearer $CEMS_ADMIN_KEY" \
  http://localhost:8765/admin/debug/llm
This tests both LLM and embedding endpoints.

​
Next Steps

User Management

Create users and distribute API keys

Build docs developers (and LLMs) love

Get started for freeTalk to us