Skip to main content
This quickstart guide will walk you through setting up Cipher, ByteRover’s memory-powered AI agent framework with MCP integration. Follow these steps to install Cipher, configure your agent, set up environment variables, and start using Cipher in both CLI and MCP modes.

​
Installation

Choose one of the following installation methods: 
# Install globally
npm install -g @byterover/cipher

# Or install locally in your project
npm install @byterover/cipher

​
From Source

# Clone the repository
git clone https://github.com/campfirein/cipher.git
cd cipher

# Install dependencies and build
pnpm i && pnpm run build && npm link

​
Docker (Alternative)

# Clone and setup
git clone https://github.com/campfirein/cipher.git
cd cipher

# Configure environment
cp .env.example .env
# Edit .env with your API keys

# Start with Docker
docker-compose up --build -d

# Test
curl http://localhost:3000/health

​
1. Configure cipher.yml

First, you’ll need to configure your agent settings in the memAgent/cipher.yml file. This file controls your LLM provider, MCP servers, and system prompts.

​
Basic Configuration

Create or modify memAgent/cipher.yml with your preferred settings: 
# MCP Servers (optional)
mcpServers: 
  filesystem:
    type: stdio
    command: npx
    args:
      - -y
      - '@modelcontextprotocol/server-filesystem'
      - .
# If you don't wanna add any mcp server, leave this like this:
# mcpServers: {}

# Choose ONLY ONE of the following LLM providers
llm:
  provider: openai
  model: gpt-4o-mini
  apiKey: $OPENAI_API_KEY
  maxIterations: 50

# System Prompt - User customizable
systemPrompt:
  enabled: true
  content: |
    You are an AI programming assistant focused on coding and reasoning tasks.

​
LLM Provider Options

llm:
  provider: openai
  model: gpt-4o-mini
  apiKey: $OPENAI_API_KEY
  maxIterations: 50

llm:
  provider: anthropic
  model: claude-3-5-haiku-20241022
  apiKey: $ANTHROPIC_API_KEY
  maxIterations: 50

llm:
  provider: gemini
  model: gemini-2.5-flash
  apiKey: $GEMINI_API_KEY
  maxIterations: 50

llm:
  provider: aws
  model: us.anthropic.claude-3-5-sonnet-20241022-v2:0
  maxIterations: 50
  aws:
    region: $AWS_REGION
    accessKeyId: $AWS_ACCESS_KEY_ID
    secretAccessKey: $AWS_SECRET_ACCESS_KEY
    sessionToken: $AWS_SESSION_TOKEN  # Optional

llm:
  provider: azure
  model: gpt-4o-mini
  apiKey: $AZURE_OPENAI_API_KEY
  maxIterations: 50
  azure:
    endpoint: $AZURE_OPENAI_ENDPOINT
    deploymentName: gpt-4o-mini  # Optional

llm:
  provider: qwen
  model: qwen2.5-72b-instruct
  apiKey: $QWEN_API_KEY
  maxIterations: 50
  qwenOptions:
    enableThinking: true  # Enable Qwen's thinking mode
    thinkingBudget: 1000  # Thinking budget for complex reasoning

llm:
  provider: lmstudio
  model: mistral-7b-instruct
  maxIterations: 50
  baseUrl: $LMSTUDIO_BASE_URL  # default: http://localhost:1234/v1

​
Embedding Configuration (Optional)

If not specified, Cipher uses automatic fallback based on your LLM provider: 
# OpenAI Embeddings
embedding:
  type: openai
  model: text-embedding-3-small
  apiKey: $OPENAI_API_KEY

# Voyage (recommended for Anthropic users)
embedding:
  type: voyage
  model: voyage-3-large
  apiKey: $VOYAGE_API_KEY
  dimensions: 1024

# Disable embeddings (chat-only mode)
embedding:
  disabled: true

​
2. Environment Variables

​
Required API Keys

Based on your providers, provide an appropriate API key: 
# OpenAI
OPENAI_API_KEY="sk-your-openai-key"

# Anthropic
ANTHROPIC_API_KEY="sk-ant-your-anthropic-key"

# Gemini (Google AI Studio)
GEMINI_API_KEY="your-gemini-key"

# Qwen (Alibaba Cloud)
QWEN_API_KEY="your-qwen-key"

# AWS Bedrock
AWS_REGION="us-east-1"
AWS_ACCESS_KEY_ID="your-access-key"
AWS_SECRET_ACCESS_KEY="your-secret-key"

# Azure OpenAI
AZURE_OPENAI_API_KEY="your-azure-key"
AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com"

# Voyage (for embeddings)
VOYAGE_API_KEY="your-voyage-key"

​
Vector Store Configuration

Choose between Qdrant, Milvus, ChromaDB, or In-Memory: 
# Basic setup (ephemeral)
docker run -d --name qdrant -p 6333:6333 qdrant/qdrant

# With persistent storage
docker run -d --name qdrant-storage -v $(pwd)/qdrant_storage:/qdrant/storage -p 6333:6333 qdrant/qdrant

VECTOR_STORE_TYPE=qdrant
VECTOR_STORE_HOST=localhost
VECTOR_STORE_PORT=6333
VECTOR_STORE_URL=http://localhost:6333

curl -sfL https://raw.githubusercontent.com/milvus-io/milvus/master/scripts/standalone_embed.sh -o standalone_embed.sh
bash standalone_embed.sh start

VECTOR_STORE_TYPE=milvus
VECTOR_STORE_HOST=localhost
VECTOR_STORE_PORT=19530

# Basic setup (ephemeral)
docker run -d --name chromadb -p 8000:8000 chromadb/chroma

# With persistent storage
docker run -d --name chromadb-storage -v $(pwd)/chroma-data:/data -p 8000:8000 chromadb/chroma

VECTOR_STORE_TYPE=chroma
VECTOR_STORE_HOST=localhost
VECTOR_STORE_PORT=8000
VECTOR_STORE_URL=http://localhost:8000

VECTOR_STORE_TYPE=in-memory
# No additional configuration needed

​
Memory Settings

💡 Heads up! All the config variables below come with sensible defaults. You only need to add them to your .env file if you want to override something—otherwise, you’re good to go! 
# Knowledge memory config
VECTOR_STORE_COLLECTION=knowledge_memory # (default: "knowledge_memory")
VECTOR_STORE_DIMENSION=1536
VECTOR_STORE_DISTANCE=Cosine
VECTOR_STORE_MAX_VECTORS=10000

# Reflection memory config
REFLECTION_VECTOR_STORE_COLLECTION=reflection_memory # (default: "reflection_memory")
DISABLE_REFLECTION_MEMORY=false # (default: true)

# Workspace memory config
USE_WORKSPACE_MEMORY=true 
WORKSPACE_VECTOR_STORE_COLLECTION=workspace_memory # (default: "workspace_memory")

​
3. Running CLI Mode and Basic Slash Commands

# Install globally
npm install -g @byterover/cipher

# Interactive mode
cipher

# One-shot command
cipher "Add this to memory as common causes of 'CORS error' in local dev with Vite + Express."

# Session management
/session list                       # List all sessions
/session new [id]                   # Create new session
/session switch <id>                # Switch to session

# Configuration and stats
/config                            # Show current config
/stats                             # Show memory statistics
/help                              # Show help
Note: When you start Cipher in CLI mode, the active session is always set to default unless you create or switch to another session.

​
4. Running MCP Mode

Cipher can run as an MCP server for integration with Claude Desktop, Cursor, Windsurf, and other MCP-compatible clients. Aggregator mode to expose all tools (including MCP server tools from cipher.yml): 
{
  "mcpServers": {
    "cipher": {
      "type": "stdio",
      "command": "cipher",
      "args": ["--mode", "mcp"],
      "env": {
        "YOUR_API_KEY": "your-api-key",
        "MCP_SERVER_MODE": "aggregator",
        "VECTOR_STORE_TYPE": "your-vector-type",
        "VECTOR_STORE_URL": "your-vector-store-endpoint"
      }
    }
  }
}

​
Alternative Transports

You can also run Cipher MCP server using HTTP-based transports. 
# Start SSE transport (HTTP server)
cipher --mode mcp --mcp-transport-type sse --mcp-port 4000

{
  "mcpServers": {
    "cipher-sse": {
      "type": "sse",
      "url": "http://localhost:4000/sse",
      "env": {
        "MCP_SERVER_MODE": "aggregator"
      }
    }
  }
}

# Optional: enable DNS rebinding protection
cipher --mode mcp --mcp-transport-type sse --mcp-dns-rebinding-protection

# Start Streamable-HTTP transport (HTTP server)
cipher --mode mcp --mcp-transport-type streamable-http --mcp-port 5000

{
  "mcpServers": {
    "cipher-sse": {
      "type": "sse",
      "url": "http://localhost:5000/http",
      "env": {
        "MCP_SERVER_MODE": "aggregator"
      }
    }
  }
}

​
5. Wrap‑Up 🎉

StepStatus
1. Installation✅
2. cipher.yml configuration✅
3. Environment variables and vector store setup✅
4. MCP mode setup✅
All set! Your Cipher agent is ready with persistent memory in CLI and MCP modes.
⌘I