Environment variables

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

API Configuration

Variable	Purpose	Values/Default	Notes/Usage
OPENAI_API_KEY	API key for OpenAI services	Required	Used for LLM operations and always required for embedding functionality
ANTHROPIC_API_KEY	API key for Anthropic Claude models	Optional	Required when provider: anthropic in cipher.yml
OPENROUTER_API_KEY	API key for OpenRouter	Optional	Required when provider: openrouter in cipher.yml
OLLAMA_BASE_URL	Base URL for local Ollama instance	Default: http://localhost:11434/v1	Required when provider: ollama in cipher.yml; no API key needed
OPENAI_BASE_URL	Custom OpenAI API endpoint	Default: https://api.openai.com/v1	Override for custom deployments (Azure, proxies, etc.)
AWS_ACCESS_KEY_ID	AWS access key for Bedrock	Optional	Required when provider: aws-bedrock in cipher.yml
AWS_SECRET_ACCESS_KEY	AWS secret key for Bedrock	Optional	Required when provider: aws-bedrock in cipher.yml
AWS_REGION	AWS region for Bedrock	Default: us-east-1	Required when provider: aws-bedrock in cipher.yml
AZURE_OPENAI_API_KEY	API key for Azure OpenAI Service	Optional	Required when provider: azure-openai in cipher.yml
AZURE_OPENAI_ENDPOINT	Azure OpenAI endpoint URL	Optional	Required when provider: azure-openai in cipher.yml
AZURE_OPENAI_API_VERSION	Azure OpenAI API version	Default: 2024-02-15-preview	Required when provider: azure-openai in cipher.yml
GEMINI_API_KEY	API key for Google AI Studio (Gemini)	Optional	Required when provider: gemini in cipher.yml
GOOGLE_API_KEY	API key for Google AI Studio (Gemini)	Optional	Required when provider: gemini in cipher.yml
GOOGLE_GEMINI_BASE_URL	Custom Gemini API endpoint	Default: https://generativelanguage.googleapis.com	Override for custom Gemini deployments
QWEN_API_KEY	API key for Alibaba Cloud (Qwen)	Optional	Required when provider: qwen in cipher.yml
VOYAGE_API_KEY	API key for Voyage AI	Optional	Required when using Voyage embeddings
AWS_DEFAULT_REGION	AWS default region	Default: us-east-1	Alternative to AWS_REGION for Bedrock
ALIBABA_API_KEY	API key for Alibaba Cloud (Qwen)	Optional	Required when provider: qwen in cipher.yml
ALIBABA_BASE_URL	Custom Alibaba Cloud API endpoint	Default: https://dashscope.aliyuncs.com	Override for custom Qwen deployments

Application Settings

Variable	Purpose	Values/Default	Notes/Usage
NODE_ENV	Node.js environment mode	development, production, test	Default: development
CIPHER_LOG_LEVEL	Controls logging verbosity	error, warn, info, debug, silly	Default: info
REDACT_SECRETS	Redact sensitive info in logs	true, false	Default: true

Storage Configuration

Variable	Purpose	Values/Default	Notes/Usage
STORAGE_CACHE_TYPE	Type of caching backend	in-memory, redis	Default: in-memory
STORAGE_CACHE_HOST	Redis server hostname	Default: localhost	Required when STORAGE_CACHE_TYPE=redis
STORAGE_CACHE_PORT	Redis server port	Default: 6379	Number
STORAGE_CACHE_PASSWORD	Redis authentication password	Optional	Only if Redis requires auth
STORAGE_CACHE_DATABASE	Redis database number	Default: 0	Number (0-15 typically)
STORAGE_DATABASE_TYPE	Persistent storage backend	in-memory, sqlite	Default: in-memory
STORAGE_DATABASE_PATH	Directory path for SQLite	Example: ./data	Where to store the database file
STORAGE_DATABASE_NAME	SQLite database filename	Default: cipher.db	Database file name within the path

Multi-Backend Storage Configuration

Variable	Purpose	Values/Default	Notes/Usage
CIPHER_MULTI_BACKEND	Enable multi-backend storage	1, 0 (Default: 0)	Enables PostgreSQL + SQLite fallback system
CIPHER_PG_URL	PostgreSQL connection string	Required when enabled	Full PostgreSQL connection URL
CIPHER_WAL_FLUSH_INTERVAL	WAL flush interval (ms)	Default: 5000	How often WAL syncs to backup storage
MULTI_BACKEND_ENABLED	Enable multi-backend storage	true, false (Default: false)	Enables PostgreSQL + SQLite fallback system
MULTI_BACKEND_PRIMARY_TYPE	Primary database type	postgresql, sqlite (Default: postgresql)	Primary storage backend
MULTI_BACKEND_FALLBACK_TYPE	Fallback database type	sqlite, postgresql (Default: sqlite)	Backup storage when primary fails
POSTGRES_HOST	PostgreSQL server hostname	Default: localhost	Required when using PostgreSQL
POSTGRES_PORT	PostgreSQL server port	Default: 5432	Number
POSTGRES_DATABASE	PostgreSQL database name	Default: cipher	Database name for chat history
POSTGRES_USERNAME	PostgreSQL authentication user	Default: postgres	Database user
POSTGRES_PASSWORD	PostgreSQL authentication pass	Required	Database password
POSTGRES_SSL	Enable SSL for PostgreSQL	true, false (Default: false)	Secure connection to PostgreSQL
MULTI_BACKEND_SYNC_INTERVAL	Cache sync interval (ms)	Default: 5000	How often cache syncs to fallback
MULTI_BACKEND_MAX_RETRIES	Max retry attempts for writes	Default: 3	Number of retries for failed operations
MULTI_BACKEND_RETRY_DELAY	Delay between retries (ms)	Default: 1000	Time to wait between retry attempts

Memory Search Configuration

Variable	Purpose	Values/Default	Notes/Usage
SEARCH_MEMORY_TYPE	Which memory types to search	knowledge, reflection, both (Default: both)	Controls which memory collections are queried

Vector Store Configuration

Variable	Purpose	Values/Default	Notes/Usage
VECTOR_STORE_TYPE	Vector database backend type	in-memory, qdrant, milvus (Default: in-memory)	Storage for embeddings and similarity search
VECTOR_STORE_HOST	Vector database hostname	Example: localhost	Required for Qdrant, Milvus
VECTOR_STORE_PORT	Vector database port	Examples: 6333 (Qdrant), 19530 (Milvus)	Number
VECTOR_STORE_URL	Complete URL for vector database	Example: http://localhost:6333	Alternative to host/port
VECTOR_STORE_API_KEY	Auth for cloud vector databases	Optional	Qdrant Cloud, Zilliz Cloud (Milvus)
VECTOR_STORE_USERNAME	Username for Milvus auth	Optional	Zilliz Cloud and self-hosted Milvus
VECTOR_STORE_PASSWORD	Password for Milvus auth	Optional	Pairs with username
VECTOR_STORE_COLLECTION	Name of the knowledge collection	Default: knowledge_memory	Collection name for storing knowledge embeddings
VECTOR_STORE_DIMENSION	Vector embedding dimensions	Default: 1536	Must match embedding model output
VECTOR_STORE_DISTANCE	Distance metric for similarity	Cosine, Euclidean, Dot, Manhattan (Default: Cosine)	How vectors are compared for similarity
VECTOR_STORE_ON_DISK	Store vectors on disk (Qdrant)	true, false (Default: false)	Performance vs storage trade-off
VECTOR_STORE_MAX_VECTORS	Max vectors in memory	Default: 10000	Memory usage limit for in-memory storage

Reflection Memory Configuration

Variable	Purpose	Values/Default	Notes/Usage
REFLECTION_VECTOR_STORE_COLLECTION	Name of the reflection memory collection	Default: reflection_memory	Separate collection for agent reflection/learning
DISABLE_REFLECTION_MEMORY	Disable reflection memory	true, false (Default: true)	Performance optimization for simpler use cases

MCP Configuration

Variable	Purpose	Values/Default	Notes/Usage
MCP_GLOBAL_TIMEOUT	Global timeout for all MCP ops	Default: 30000 (ms)	Max time to wait for MCP server responses

Event Management Configuration

Variable	Purpose	Values/Default	Notes/Usage
EVENT_FILTERING_ENABLED	Enable or disable event filtering	true, false (Default: false)	Controls whether events are filtered during processing
EVENT_FILTERED_TYPES	Event types to filter out	Comma-separated list	Example: tool:executionStarted,tool:executionCompleted,llm:thinking
EVENT_PERSISTENCE_ENABLED	Enable or disable event persistence	true, false (Default: true)	Controls whether events are saved to storage
EVENT_PERSISTENCE_PATH	Path to store event log files	Default: ./data/events	Directory where event logs are stored

Knowledge Graph Configuration

Variable	Purpose	Values/Default	Notes/Usage
KNOWLEDGE_GRAPH_ENABLED	Enable advanced KG features	true, false (Default: false)	Enables Neo4j-based relationship modeling
KNOWLEDGE_GRAPH_TYPE	Knowledge graph backend type	neo4j, in-memory (Default: in-memory)	Choose between Neo4j and in-memory graph
KNOWLEDGE_GRAPH_HOST	Neo4j database hostname	Default: localhost
KNOWLEDGE_GRAPH_PORT	Neo4j bolt protocol port	Default: 7687	Number
KNOWLEDGE_GRAPH_URI	Complete Neo4j connection URI	Example: bolt://localhost:7687	Alternative to host/port
KNOWLEDGE_GRAPH_USERNAME	Neo4j authentication username	Default: neo4j
KNOWLEDGE_GRAPH_PASSWORD	Neo4j authentication password	Required for Neo4j connection
KNOWLEDGE_GRAPH_DATABASE	Neo4j database name	Default: neo4j	Supports multiple databases in Neo4j 4.0+

Embedding Configuration (Advanced)

Variable	Purpose	Values/Default	Notes/Usage
EMBEDDING_MODEL	Override default embedding model	Default: text-embedding-3-small	Control which OpenAI embedding model to use
EMBEDDING_TIMEOUT	Timeout for embedding requests	Default: 30000 (ms)
EMBEDDING_MAX_RETRIES	Max retry attempts for embedding	Default: 3	Number (0-10)
EMBEDDING_PROVIDER	Default embedding provider	openai, gemini, ollama, voyage, qwen, aws-bedrock	Primary embedding service to use
EMBEDDING_FALLBACK_PROVIDER	Fallback embedding provider	openai, gemini, ollama, voyage, qwen, aws-bedrock	Backup provider if primary fails
EMBEDDING_HEALTH_CHECK_INTERVAL	Health check frequency (ms)	Default: 30000	How often to check provider health
EMBEDDING_CIRCUIT_BREAKER_THRESHOLD	Error threshold for circuit breaker	Default: 5	Consecutive errors before circuit breaker trips
EMBEDDING_CIRCUIT_BREAKER_TIMEOUT	Circuit breaker timeout (ms)	Default: 60000	Time to wait before retrying failed provider

Embedding Provider-Specific Configuration

OpenAI Embedding

Variable	Purpose	Values/Default	Notes/Usage
OPENAI_EMBEDDING_MODEL	OpenAI embedding model	text-embedding-3-small, text-embedding-3-large, text-embedding-ada-002	Model for OpenAI embeddings
OPENAI_EMBEDDING_DIMENSION	Vector dimension for OpenAI	Default: 1536	Must match model output dimension

Gemini Embedding

Variable	Purpose	Values/Default	Notes/Usage
GOOGLE_EMBEDDING_MODEL	Gemini embedding model	text-embedding-004, gemini-embedding-001	Model for Gemini embeddings
GOOGLE_EMBEDDING_DIMENSION	Vector dimension for Gemini	Default: 768	Must match model output dimension

Ollama Embedding

Variable	Purpose	Values/Default	Notes/Usage
OLLAMA_EMBEDDING_MODEL	Ollama embedding model	nomic-embed-text, all-minilm	Model for Ollama embeddings
OLLAMA_EMBEDDING_DIMENSION	Vector dimension for Ollama	Default: 384	Must match model output dimension

Voyage Embedding

Variable	Purpose	Values/Default	Notes/Usage
VOYAGE_API_KEY	Voyage AI API key	Required	Required when using Voyage embeddings
VOYAGE_EMBEDDING_MODEL	Voyage embedding model	voyage-large-2, voyage-code-2	Model for Voyage embeddings
VOYAGE_EMBEDDING_DIMENSION	Vector dimension for Voyage	Default: 1024	Must match model output dimension

Qwen Embedding

Variable	Purpose	Values/Default	Notes/Usage
ALIBABA_EMBEDDING_MODEL	Qwen embedding model	text-embedding-v1, text-embedding-v2	Model for Qwen embeddings
ALIBABA_EMBEDDING_DIMENSION	Vector dimension for Qwen	Default: 1536	Must match model output dimension

AWS Bedrock Embedding

Variable	Purpose	Values/Default	Notes/Usage
AWS_EMBEDDING_MODEL	AWS Bedrock embedding model	amazon.titan-embed-text-v1:0	Model for AWS Bedrock embeddings
AWS_EMBEDDING_DIMENSION	Vector dimension for AWS Bedrock	Default: 1536	Must match model output dimension

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
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION (or AWS_DEFAULT_REGION) - When using AWS Bedrock
AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT - When using Azure OpenAI Service
GEMINI_API_KEY or GOOGLE_API_KEY - When using Google AI Studio (Gemini)
QWEN_API_KEY or ALIBABA_API_KEY - When using Alibaba Cloud (Qwen)
VOYAGE_API_KEY - When using Voyage AI embeddings

Required for External Services

Redis: STORAGE_CACHE_HOST when STORAGE_CACHE_TYPE=redis
PostgreSQL: POSTGRES_PASSWORD when MULTI_BACKEND_ENABLED=true and MULTI_BACKEND_PRIMARY_TYPE=postgresql
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
QWEN_API_KEY=your-qwen-api-key-here
GEMINI_API_KEY=your-gemini-api-key-here
VOYAGE_API_KEY=your-voyage-api-key-here

# AWS Bedrock Configuration (Optional)
AWS_ACCESS_KEY_ID=your-aws-access-key
AWS_SECRET_ACCESS_KEY=your-aws-secret-key
AWS_REGION=us-east-1

# Azure OpenAI Configuration (Optional)
AZURE_OPENAI_API_KEY=your-azure-openai-key
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_API_VERSION=2024-02-15-preview

# Google AI Studio Configuration (Optional)
GOOGLE_API_KEY=your-google-api-key
GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com

# Alibaba Cloud Configuration (Optional)
ALIBABA_API_KEY=your-alibaba-api-key
ALIBABA_BASE_URL=https://dashscope.aliyuncs.com

# 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

# Multi-Backend Storage Configuration
CIPHER_MULTI_BACKEND=1
CIPHER_PG_URL=postgres://cipheruser:cipherpass@localhost:5432/cipherdb
CIPHER_WAL_FLUSH_INTERVAL=5000
MULTI_BACKEND_ENABLED=true
MULTI_BACKEND_PRIMARY_TYPE=postgresql
MULTI_BACKEND_FALLBACK_TYPE=sqlite
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DATABASE=cipher
POSTGRES_USERNAME=postgres
POSTGRES_PASSWORD=your-postgres-password
POSTGRES_SSL=false
MULTI_BACKEND_SYNC_INTERVAL=5000
MULTI_BACKEND_MAX_RETRIES=3
MULTI_BACKEND_RETRY_DELAY=1000

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

# MCP Configuration
MCP_GLOBAL_TIMEOUT=30000

# Event Management Configuration
EVENT_FILTERING_ENABLED=false
EVENT_FILTERED_TYPES=tool:executionStarted,tool:executionCompleted,llm:thinking
EVENT_PERSISTENCE_ENABLED=true
EVENT_PERSISTENCE_PATH=./data/events

# Embedding Configuration (Advanced)
EMBEDDING_PROVIDER=openai
EMBEDDING_FALLBACK_PROVIDER=gemini
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_TIMEOUT=30000
EMBEDDING_MAX_RETRIES=3
EMBEDDING_HEALTH_CHECK_INTERVAL=30000
EMBEDDING_CIRCUIT_BREAKER_THRESHOLD=5
EMBEDDING_CIRCUIT_BREAKER_TIMEOUT=60000

# OpenAI Embedding Configuration
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
OPENAI_EMBEDDING_DIMENSION=1536

# Gemini Embedding Configuration
GOOGLE_EMBEDDING_MODEL=text-embedding-004
GOOGLE_EMBEDDING_DIMENSION=768

# Ollama Embedding Configuration
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
OLLAMA_EMBEDDING_DIMENSION=384

# Voyage Embedding Configuration
VOYAGE_API_KEY=your-voyage-api-key
VOYAGE_EMBEDDING_MODEL=voyage-large-2
VOYAGE_EMBEDDING_DIMENSION=1024

# Qwen Embedding Configuration
ALIBABA_EMBEDDING_MODEL=text-embedding-v1
ALIBABA_EMBEDDING_DIMENSION=1536

# AWS Bedrock Embedding Configuration
AWS_EMBEDDING_MODEL=amazon.titan-embed-text-v1:0
AWS_EMBEDDING_DIMENSION=1536

Getting Started

Configuration

Memory System

MCP Integration

Session Management

Environment variables

API Configuration

Application Settings

Storage Configuration

Multi-Backend Storage Configuration

Memory Search Configuration

Vector Store Configuration

Reflection Memory Configuration

MCP Configuration

Event Management Configuration

Knowledge Graph Configuration

Embedding Configuration (Advanced)

Embedding Provider-Specific Configuration

OpenAI Embedding

Gemini Embedding

Ollama Embedding

Voyage Embedding

Qwen Embedding

AWS Bedrock Embedding

Required vs Optional Variables

Always Required

Required for Specific Providers

Required for External Services

Example .env File

Getting Started

Configuration

Memory System

MCP Integration

Session Management

​API Configuration

​Application Settings

​Storage Configuration

​Multi-Backend Storage Configuration

​Memory Search Configuration

​Vector Store Configuration

​Reflection Memory Configuration

​MCP Configuration

​Event Management Configuration

​Knowledge Graph Configuration

​Embedding Configuration (Advanced)

​Embedding Provider-Specific Configuration

​OpenAI Embedding

​Gemini Embedding

​Ollama Embedding

​Voyage Embedding

​Qwen Embedding

​AWS Bedrock Embedding

​Required vs Optional Variables

​Always Required

​Required for Specific Providers

​Required for External Services

​Example .env File

API Configuration

Application Settings

Storage Configuration

Multi-Backend Storage Configuration

Memory Search Configuration

Vector Store Configuration

Reflection Memory Configuration

MCP Configuration

Event Management Configuration

Knowledge Graph Configuration

Embedding Configuration (Advanced)

Embedding Provider-Specific Configuration

OpenAI Embedding

Gemini Embedding

Ollama Embedding

Voyage Embedding

Qwen Embedding

AWS Bedrock Embedding

Required vs Optional Variables

Always Required

Required for Specific Providers

Required for External Services

Example .env File