Comprehensive guide to all environment variables supported by Cipher for secure configuration and external service integration.

​
Configuration Priority

  1. Environment variables (.env file) - Highest priority
  2. Agent configuration (cipher.yml) - Medium priority
  3. System defaults - Lowest priority

​
API Configuration

VariablePurposeValues/DefaultNotes/Usage
OPENAI_API_KEYAPI key for OpenAI servicesRequiredUsed for LLM operations and always required for embedding functionality
ANTHROPIC_API_KEYAPI key for Anthropic Claude modelsOptionalRequired when provider: anthropic in cipher.yml
OPENROUTER_API_KEYAPI key for OpenRouterOptionalRequired when provider: openrouter in cipher.yml
OLLAMA_BASE_URLBase URL for local Ollama instanceDefault: http://localhost:11434/v1Required when provider: ollama in cipher.yml; no API key needed
OPENAI_BASE_URLCustom OpenAI API endpointDefault: https://api.openai.com/v1Override for custom deployments (Azure, proxies, etc.)

​
Application Settings

VariablePurposeValues/DefaultNotes/Usage
NODE_ENVNode.js environment modedevelopment, production, testDefault: development
CIPHER_LOG_LEVELControls logging verbosityerror, warn, info, debug, sillyDefault: info
REDACT_SECRETSRedact sensitive info in logstrue, falseDefault: true

​
Storage Configuration

VariablePurposeValues/DefaultNotes/Usage
STORAGE_CACHE_TYPEType of caching backendin-memory, redisDefault: in-memory
STORAGE_CACHE_HOSTRedis server hostnameDefault: localhostRequired when STORAGE_CACHE_TYPE=redis
STORAGE_CACHE_PORTRedis server portDefault: 6379Number
STORAGE_CACHE_PASSWORDRedis authentication passwordOptionalOnly if Redis requires auth
STORAGE_CACHE_DATABASERedis database numberDefault: 0Number (0-15 typically)
STORAGE_DATABASE_TYPEPersistent storage backendin-memory, sqliteDefault: in-memory
STORAGE_DATABASE_PATHDirectory path for SQLiteExample: ./dataWhere to store the database file
STORAGE_DATABASE_NAMESQLite database filenameDefault: cipher.dbDatabase file name within the path

​
Memory Search Configuration

VariablePurposeValues/DefaultNotes/Usage
SEARCH_MEMORY_TYPEWhich memory types to searchknowledge, reflection, both (Default: both)Controls which memory collections are queried

​
Vector Store Configuration

VariablePurposeValues/DefaultNotes/Usage
VECTOR_STORE_TYPEVector database backend typein-memory, qdrant, milvus (Default: in-memory)Storage for embeddings and similarity search
VECTOR_STORE_HOSTVector database hostnameExample: localhostRequired for Qdrant, Milvus
VECTOR_STORE_PORTVector database portExamples: 6333 (Qdrant), 19530 (Milvus)Number
VECTOR_STORE_URLComplete URL for vector databaseExample: http://localhost:6333Alternative to host/port
VECTOR_STORE_API_KEYAuth for cloud vector databasesOptionalQdrant Cloud, Zilliz Cloud (Milvus)
VECTOR_STORE_USERNAMEUsername for Milvus authOptionalZilliz Cloud and self-hosted Milvus
VECTOR_STORE_PASSWORDPassword for Milvus authOptionalPairs with username
VECTOR_STORE_COLLECTIONName of the knowledge collectionDefault: knowledge_memoryCollection name for storing knowledge embeddings
VECTOR_STORE_DIMENSIONVector embedding dimensionsDefault: 1536Must match embedding model output
VECTOR_STORE_DISTANCEDistance metric for similarityCosine, Euclidean, Dot, Manhattan (Default: Cosine)How vectors are compared for similarity
VECTOR_STORE_ON_DISKStore vectors on disk (Qdrant)true, false (Default: false)Performance vs storage trade-off
VECTOR_STORE_MAX_VECTORSMax vectors in memoryDefault: 10000Memory usage limit for in-memory storage

​
Reflection Memory Configuration

VariablePurposeValues/DefaultNotes/Usage
REFLECTION_VECTOR_STORE_COLLECTIONName of the reflection memory collectionDefault: reflection_memorySeparate collection for agent reflection/learning
DISABLE_REFLECTION_MEMORYDisable reflection memorytrue, false (Default: true)Performance optimization for simpler use cases

​
MCP Configuration

VariablePurposeValues/DefaultNotes/Usage
MCP_GLOBAL_TIMEOUTGlobal timeout for all MCP opsDefault: 30000 (ms)Max time to wait for MCP server responses

​
Knowledge Graph Configuration

VariablePurposeValues/DefaultNotes/Usage
KNOWLEDGE_GRAPH_ENABLEDEnable advanced KG featurestrue, false (Default: false)Enables Neo4j-based relationship modeling
KNOWLEDGE_GRAPH_TYPEKnowledge graph backend typeneo4j, in-memory (Default: in-memory)Choose between Neo4j and in-memory graph
KNOWLEDGE_GRAPH_HOSTNeo4j database hostnameDefault: localhost
KNOWLEDGE_GRAPH_PORTNeo4j bolt protocol portDefault: 7687Number
KNOWLEDGE_GRAPH_URIComplete Neo4j connection URIExample: bolt://localhost:7687Alternative to host/port
KNOWLEDGE_GRAPH_USERNAMENeo4j authentication usernameDefault: neo4j
KNOWLEDGE_GRAPH_PASSWORDNeo4j authentication passwordRequired for Neo4j connection
KNOWLEDGE_GRAPH_DATABASENeo4j database nameDefault: neo4jSupports multiple databases in Neo4j 4.0+

​
Embedding Configuration (Advanced)

VariablePurposeValues/DefaultNotes/Usage
EMBEDDING_MODELOverride default embedding modelDefault: text-embedding-3-smallControl which OpenAI embedding model to use
EMBEDDING_TIMEOUTTimeout for embedding requestsDefault: 30000 (ms)
EMBEDDING_MAX_RETRIESMax retry attempts for embeddingDefault: 3Number (0-10)

​
Required vs Optional Variables

​
Always Required

  • OPENAI_API_KEY - For embeddings, even with other LLM providers

​
Required for Specific Providers

  • ANTHROPIC_API_KEY - When using Anthropic
  • OPENROUTER_API_KEY - When using OpenRouter

​
Required for External Services

  • Redis: STORAGE_CACHE_HOST when STORAGE_CACHE_TYPE=redis
  • Qdrant: VECTOR_STORE_HOST or VECTOR_STORE_URL when VECTOR_STORE_TYPE=qdrant
  • Milvus: VECTOR_STORE_HOST or VECTOR_STORE_URL when VECTOR_STORE_TYPE=milvus
  • Neo4j: KNOWLEDGE_GRAPH_PASSWORD when KNOWLEDGE_GRAPH_ENABLED=true and KNOWLEDGE_GRAPH_TYPE=neo4j

​
Example .env File

# API Configuration (Required)
OPENAI_API_KEY=sk-proj-your-openai-key-here
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here
OPENROUTER_API_KEY=sk-or-your-openrouter-key-here

# Application Settings
NODE_ENV=production
CIPHER_LOG_LEVEL=info
REDACT_SECRETS=true

# Vector Store Configuration
VECTOR_STORE_TYPE=qdrant
VECTOR_STORE_HOST=localhost
VECTOR_STORE_PORT=6333
VECTOR_STORE_COLLECTION=knowledge_memory
VECTOR_STORE_DIMENSION=1536
VECTOR_STORE_DISTANCE=Cosine

# Knowledge Graph Configuration
KNOWLEDGE_GRAPH_ENABLED=true
KNOWLEDGE_GRAPH_TYPE=neo4j
KNOWLEDGE_GRAPH_HOST=localhost
KNOWLEDGE_GRAPH_PORT=7687
KNOWLEDGE_GRAPH_USERNAME=neo4j
KNOWLEDGE_GRAPH_PASSWORD=your-neo4j-password

# Storage Configuration
STORAGE_CACHE_TYPE=redis
STORAGE_CACHE_HOST=localhost
STORAGE_CACHE_PORT=6379
STORAGE_DATABASE_TYPE=sqlite
STORAGE_DATABASE_PATH=./data
STORAGE_DATABASE_NAME=cipher.db

# Memory Configuration
SEARCH_MEMORY_TYPE=both
DISABLE_REFLECTION_MEMORY=false
REFLECTION_VECTOR_STORE_COLLECTION=reflection_memory

# MCP Configuration
MCP_GLOBAL_TIMEOUT=30000

# Embedding Configuration (Advanced)
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_TIMEOUT=30000
EMBEDDING_MAX_RETRIES=3

​
Best Practices

​
Security

  • Never commit .env files to version control
  • Use different API keys for development and production
  • Enable REDACT_SECRETS=true in production
  • Rotate API keys regularly

​
Performance

  • Use external vector stores for production workloads
  • Configure appropriate timeouts for your network
  • Monitor memory usage with in-memory stores
  • Use Redis for better session persistence

​
Reliability

  • Set up proper monitoring for external services
  • Test configurations before deployment
  • Use environment-specific .env files
  • Validate all required variables are set before startup