Cipher’s embedding subsystem provides high-performance, multi-provider, fault-tolerant text embeddings for coding agents. Supports OpenAI, Gemini, Ollama, Voyage, Qwen, AWS Bedrock with extensible, production-ready architecture.

Key Features

  • Unified API: Consistent interface across all providers
  • Multi-Provider: OpenAI, Gemini, Ollama, Qwen, AWS Bedrock support
  • Batch Processing: Single texts and large batches
  • Resilience: Error handling, retry logic, health monitoring, circuit breaker
  • Type Safety: Strong TypeScript types and runtime validation
  • Centralized Management: Provider lifecycle, health checks, statistics

Architecture

Cipher’s embedding system is modular and extensible:
  • Embedder: Each provider implements the Embedder interface for a consistent API.
  • EmbeddingManager: Orchestrates multiple embedders, provides health checks, fallback, and stats.
  • Config: Supports environment variables, YAML, or direct code configuration.

Configuration

Configuration Examples

Configure embeddings in your memAgent/cipher.yml file:
# OpenAI
embedding:
  type: openai
  model: text-embedding-3-small
  apiKey: $OPENAI_API_KEY
  dimensions: 1536             # Optional: custom dimensions
  timeout: 30000               # Optional: request timeout (ms)
  maxRetries: 3                # Optional: max retry attempts

# Gemini
embedding:
  type: gemini
  model: gemini-embedding-001
  apiKey: $GEMINI_API_KEY

# Ollama
embedding:
  type: ollama
  model: mxbai-embed-large
  baseUrl: $OLLAMA_BASE_URL

# Voyage (fixed dimensions)
embedding:
  type: voyage
  model: voyage-3-large
  apiKey: $VOYAGE_API_KEY
  dimensions: 1024             # Required: 1024, 256, 512, or 2048

# AWS Bedrock (fixed dimensions)
embedding:
  type: aws-bedrock
  model: amazon.titan-embed-text-v2:0
  region: $AWS_REGION
  accessKeyId: $AWS_ACCESS_KEY_ID
  secretAccessKey: $AWS_SECRET_ACCESS_KEY
  dimensions: 1024             # Required: 1024, 512, or 256

# Azure OpenAI
embedding:
  type: openai
  model: text-embedding-3-small
  apiKey: $AZURE_OPENAI_API_KEY
  baseUrl: $AZURE_OPENAI_ENDPOINT

# Qwen (fixed dimensions)
embedding:
  type: qwen
  model: text-embedding-v3
  apiKey: $QWEN_API_KEY
  dimensions: 1024             # Required: 1024, 768, or 512

Environment Variables

Cipher auto-detects provider configuration from environment variables. Example for OpenAI:
OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
Other providers (Gemini, Qwen, AWS, etc.) use similar variables. See src/core/brain/embedding/config.ts for details.

Disabled Embedding

To disable embeddings entirely and operate in chat-only mode:
embedding:
  disabled: true
When disabled, all memory-related tools (cipher_memory_search, cipher_extract_and_operate_memory, etc.) are unavailable.

Automatic Fallback Mechanism

If no embedding config is specified, Cipher automatically uses your LLM provider’s embedding based on the table below:
ProviderConfigFallback ModelFixed Dimensions
OpenAItype: openaitext-embedding-3-smallNo
Geminitype: geminigemini-embedding-001No
Qwentype: qwentext-embedding-v3Yes (1024, 768, 512)
Voyagetype: voyagevoyage-3-largeYes (1024, 256, 512, 2048)
AWS Bedrocktype: aws-bedrockamazon.titan-embed-text-v2:0Yes (1024, 512, 256)
Azure OpenAItype: openaitext-embedding-3-smallNo
Ollamatype: ollamanomic-embed-textNo
Automatic LLM-based Selection:
  • Anthropic LLM → Voyage embedding (needs VOYAGE_API_KEY)
  • AWS LLM → AWS Bedrock embedding (uses same credentials)
  • Azure LLM → Azure OpenAI embedding (uses same endpoint)
  • Qwen LLM → Qwen embedding (uses same API key)
  • OpenAI/Gemini/Ollama → Same provider embedding
Note: For providers with fixed dimensions (Qwen, Voyage, AWS), you must specify dimensions: in the config to override defaults.
Cipher’s embedding system makes it easy to use the best embedding models for your workflow—locally or in the cloud—while ensuring reliability, extensibility, and production-grade resilience.