> ## Documentation Index > Fetch the complete documentation index at: https://docs.byterover.dev/llms.txt > Use this file to discover all available pages before exploring further. # Quickstart > Get started with Cipher in under 5 minutes 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: ### NPM Package (Recommended) ```bash theme={null} # Install globally npm install -g @byterover/cipher # Or install locally in your project npm install @byterover/cipher ``` ### From Source ```bash theme={null} # 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) ```bash theme={null} # 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: ```yaml theme={null} # 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 ```yaml theme={null} llm: provider: openai model: gpt-4o-mini apiKey: $OPENAI_API_KEY maxIterations: 50 ``` ```yaml theme={null} llm: provider: anthropic model: claude-3-5-haiku-20241022 apiKey: $ANTHROPIC_API_KEY maxIterations: 50 ``` ```yaml theme={null} llm: provider: gemini model: gemini-2.5-flash apiKey: $GEMINI_API_KEY maxIterations: 50 ``` ```yaml theme={null} 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 ``` ```yaml theme={null} llm: provider: azure model: gpt-4o-mini apiKey: $AZURE_OPENAI_API_KEY maxIterations: 50 azure: endpoint: $AZURE_OPENAI_ENDPOINT deploymentName: gpt-4o-mini # Optional ``` ```yaml theme={null} 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 ``` ```yaml theme={null} 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: ```yaml theme={null} # 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: ```bash theme={null} # 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: 🐳 Qdrant Local (Docker) ```bash theme={null} # 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 ``` .env for Local ```bash theme={null} VECTOR_STORE_TYPE=qdrant VECTOR_STORE_HOST=localhost VECTOR_STORE_PORT=6333 VECTOR_STORE_URL=http://localhost:6333 ``` 🐳 Milvus Local (Script) ```bash theme={null} curl -sfL https://raw.githubusercontent.com/milvus-io/milvus/master/scripts/standalone_embed.sh -o standalone_embed.sh bash standalone_embed.sh start ``` .env for Local ```bash theme={null} VECTOR_STORE_TYPE=milvus VECTOR_STORE_HOST=localhost VECTOR_STORE_PORT=19530 ``` 🐳 ChromaDB Local (Docker) ```bash theme={null} # 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 ``` .env for Local ```bash theme={null} VECTOR_STORE_TYPE=chroma VECTOR_STORE_HOST=localhost VECTOR_STORE_PORT=8000 VECTOR_STORE_URL=http://localhost:8000 ``` ```bash theme={null} 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!** ```bash theme={null} # 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 ```bash theme={null} # 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." ``` ```bash theme={null} # Session management /session list # List all sessions /session new [id] # Create new session /session switch # 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 (Recommended) Aggregator mode to expose all tools (including MCP server tools from `cipher.yml`): ```json theme={null} { "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. ```bash theme={null} # Start SSE transport (HTTP server) cipher --mode mcp --mcp-transport-type sse --mcp-port 4000 ``` ```json theme={null} { "mcpServers": { "cipher-sse": { "type": "sse", "url": "http://localhost:4000/sse", "env": { "MCP_SERVER_MODE": "aggregator" } } } } ``` ```bash theme={null} # Optional: enable DNS rebinding protection cipher --mode mcp --mcp-transport-type sse --mcp-dns-rebinding-protection ``` ```bash theme={null} # Start Streamable-HTTP transport (HTTP server) cipher --mode mcp --mcp-transport-type streamable-http --mcp-port 5000 ``` ```json theme={null} { "mcpServers": { "cipher-sse": { "type": "sse", "url": "http://localhost:5000/http", "env": { "MCP_SERVER_MODE": "aggregator" } } } } ``` *** ## 5. Wrap‑Up 🎉 | Step | Status | | :-------------------------------------------------- | -----: | | **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.