Memory-powered AI agent framework with MCP integration

Cipher is an opensource memory layer specifically designed for coding agents. Compatible with Cursor, Windsurf, Claude Desktop, Claude Code, Gemini CLI, AWS's Kiro, VS Code, and Roo Code through MCP, and coding agents, such as Kimi K2. (see more on examples)

Built by Byterover team

Key Features:

• ⁠MCP integration with any IDE you want.
• ⁠Auto-generate AI coding memories that scale with your codebase.
• ⁠Switch seamlessly between IDEs without losing memory and context.
• ⁠Easily share coding memories across your dev team in real time.
• ⁠Dual Memory Layer that captures System 1 (Programming Concepts & Business Logic & Past Interaction) and System 2 (reasoning steps of the model when generating code).
• ⁠Install on your IDE with zero configuration needed.
• ⁠NEW: Workspace Memory - Team-aware memory system that automatically tracks project progress, team activities, and collaborative context. See WORKSPACE_MEMORY.md for details.

# Install globally npm install -g @byterover/cipher # Or install locally in your project npm install @byterover/cipher

# 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 -d # Test curl http://localhost:3000/health

pnpm i && pnpm run build && npm link

# Interactive mode cipher # One-shot command cipher "Add this to memory as common causes of 'CORS error' in local dev with Vite + Express." # API server mode cipher --mode api # MCP server mode cipher --mode mcp # Web UI mode cipher --mode ui

⚠️ Note: When running MCP mode in terminal/shell, export all environment variables as Cipher won't read from .env file.

💡 Tip: CLI mode automatically continues or creates the "default" session. Use /session new <session-name> to start a fresh session.

The Cipher Web UI provides an intuitive interface for interacting with memory-powered AI agents, featuring session management, tool integration, and real-time chat capabilities.

# LLM Configuration llm: provider: openai # openai, anthropic, openrouter, ollama, qwen model: gpt-4-turbo apiKey: $OPENAI_API_KEY # System Prompt systemPrompt: 'You are a helpful AI assistant with memory capabilities.' # MCP Servers (optional) mcpServers: filesystem: type: stdio command: npx args: ['-y', '@modelcontextprotocol/server-filesystem', '.']

Configure embeddings in memAgent/cipher.yml. If not specified, uses automatic fallback based on your LLM provider. Below is the table of fallback embedding models:

# OpenAI embedding: type: openai model: text-embedding-3-small apiKey: $OPENAI_API_KEY # Qwen (fixed dimensions - must specify) embedding: type: qwen model: text-embedding-v3 apiKey: $QWEN_API_KEY dimensions: 1024 # Required: 1024, 768, or 512 # AWS Bedrock (fixed dimensions - must specify) 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 # Voyage (fixed dimensions - must specify) embedding: type: voyage model: voyage-3-large apiKey: $VOYAGE_API_KEY dimensions: 1024 # Required: 1024, 256, 512, or 2048 # LM Studio (local, no API key required) embedding: type: lmstudio model: nomic-embed-text-v1.5 # or bge-large, bge-base, bge-small baseUrl: http://localhost:1234/v1 # Optional, defaults to this # dimensions: 768 # Optional, auto-detected based on model # Disable embeddings (chat-only mode) embedding: disabled: true

Note: Setting embedding: disabled: true disables all memory-related tools (cipher_memory_search, cipher_extract_and_operate_memory, etc.) and operates in chat-only mode.

If no embedding config is specified, automatically uses your LLM provider's embedding:

• 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)
• LM Studio LLM → LM Studio embedding (tries same model first, then dedicated embedding model, finally OpenAI)
• Ollama LLM → Ollama embedding (uses same local server)
• OpenAI/Gemini/Ollama → Same provider embedding

Note: For providers with fixed dimensions (Qwen, Voyage, AWS), you must specify dimensions: in the config to override the default value in .env.

Cipher supports three vector databases for storing embeddings. Configure in .env:

Qdrant (Qdrant Cloud)

# Remote (Qdrant Cloud) VECTOR_STORE_TYPE=qdrant VECTOR_STORE_URL=your-qdrant-endpoint VECTOR_STORE_API_KEY=your-qdrant-api-key # Local (Docker) VECTOR_STORE_TYPE=qdrant VECTOR_STORE_HOST=localhost VECTOR_STORE_PORT=6333 VECTOR_STORE_URL=http://localhost:6333

Milvus (Zilliz Cloud)

# Remote (Zilliz Cloud) VECTOR_STORE_TYPE=milvus VECTOR_STORE_URL=your-milvus-cluster-endpoint VECTOR_STORE_USERNAME=your-zilliz-username VECTOR_STORE_PASSWORD=your-zilliz-password # Local (Docker) VECTOR_STORE_TYPE=milvus VECTOR_STORE_HOST=localhost VECTOR_STORE_PORT=19530

# Collection configuration VECTOR_STORE_COLLECTION=knowledge_memory VECTOR_STORE_DIMENSION=1536 VECTOR_STORE_DISTANCE=Cosine # Reflection memory (optional) REFLECTION_VECTOR_STORE_COLLECTION=reflection_memory DISABLE_REFLECTION_MEMORY=true

Cipher supports multiple LLM providers:

llm: provider: openai model: gpt-4-turbo apiKey: $OPENAI_API_KEY

llm: provider: anthropic model: claude-3-5-sonnet-20241022 apiKey: $ANTHROPIC_API_KEY

llm: provider: openrouter model: openai/gpt-4-turbo # Any OpenRouter model apiKey: $OPENROUTER_API_KEY

llm: provider: ollama model: qwen2.5:32b # Recommended for best performance baseURL: $OLLAMA_BASE_URL

llm: provider: lmstudio model: hermes-2-pro-llama-3-8b # e.g. TheBloke/Mistral-7B-Instruct-v0.2-GGUF # No apiKey required # Optionally override the baseURL if not using the default # baseURL: http://localhost:1234/v1 # OPTIONAL: Configure specific embedding model # If not specified, Cipher will automatically try: # 1. Same model as LLM (if it supports embeddings) # 2. Default embedding model (nomic-embed-text-v1.5) # 3. OpenAI fallback (if OPENAI_API_KEY available) embedding: provider: lmstudio model: nomic-embed-text-v1.5 # Optional - smart fallback if not specified # baseURL: http://localhost:1234/v1

Note: LM Studio is fully OpenAI-compatible and now supports both LLM and embedding models! By default, Cipher will connect to LM Studio at http://localhost:1234/v1. No API key is required.

🆕 Embedding Support: LM Studio now supports embedding models like nomic-embed-text-v1.5, bge-large, bge-base, and other BERT-based models in GGUF format.

Smart Fallback Logic:

1. First try: Uses the same model loaded for LLM as the embedding model (many models support both)
2. Second try: Falls back to nomic-embed-text-v1.5 if the LLM model doesn't support embeddings
3. Final fallback: Uses OpenAI embeddings when available

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

llm: provider: aws model: meta.llama3-1-70b-instruct-v1:0 # Or another Bedrock-supported model maxIterations: 50 aws: region: $AWS_REGION accessKeyId: $AWS_ACCESS_KEY_ID secretAccessKey: $AWS_SECRET_ACCESS_KEY # sessionToken: $AWS_SESSION_TOKEN # (uncomment if needed)

Required environment variables:

• AWS_REGION
• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_SESSION_TOKEN (optional, for temporary credentials)

llm: provider: azure model: gpt-4o-mini # Or your Azure deployment/model name apiKey: $AZURE_OPENAI_API_KEY maxIterations: 50 azure: endpoint: $AZURE_OPENAI_ENDPOINT deploymentName: gpt-4o-mini # Optional, defaults to model name

Required environment variables:

• AZURE_OPENAI_API_KEY
• AZURE_OPENAI_ENDPOINT

# Basic usage cipher # Interactive CLI mode cipher "Your prompt here" # One-shot mode # Server modes cipher --mode api # REST API server cipher --mode mcp # MCP server (make sure all necessary environment variables are set in the shell environment) # Configuration cipher --agent /path/to/config.yml # Custom config cipher --strict # Strict MCP connections cipher --new-session [id] # Start with new session # CLI commands /session list # List sessions /session new [id] # Create session /session switch <id> # Switch session /config # Show config /stats # Show statistics /help # Show help

Cipher supports persistent chat history using PostgreSQL as the primary storage backend. This allows conversations to be restored across application restarts.

To use PostgreSQL for chat history persistence, set the following environment variables:

export CIPHER_PG_URL="postgresql://username:password@localhost:5432/cipher_db"

export STORAGE_DATABASE_HOST="localhost" export STORAGE_DATABASE_PORT="5432" export STORAGE_DATABASE_NAME="cipher_db" export STORAGE_DATABASE_USER="username" export STORAGE_DATABASE_PASSWORD="password" export STORAGE_DATABASE_SSL="false"

1. Create a PostgreSQL database:

CREATE DATABASE cipher_db;

2. The application will automatically create the necessary tables and indexes on first run.

If PostgreSQL is not available or fails to connect, Cipher will automatically fall back to:

1. SQLite (local file-based storage)
2. In-memory storage (no persistence)

Sessions are stored with the following key pattern:

• Session data: cipher:sessions:{sessionId}
• Message history: messages:{sessionId}

Cipher can run as an MCP (Model Context Protocol) server, allowing integration with MCP-compatible clients like Claude Desktop, Cursor, Windsurf, and other AI coding assistants.

To use Cipher as an MCP server in your MCP client configuration:

{ "mcpServers": { "cipher": { "type": "stdio", "command": "cipher", "args": ["--mode", "mcp"], "env": { "OPENAI_API_KEY": "your_openai_api_key", "ANTHROPIC_API_KEY": "your_anthropic_api_key"	}	}	} }

Add to your Claude Desktop MCP configuration file:

{ "mcpServers": { "cipher": { "type": "stdio", "command": "cipher", "args": ["--mode", "mcp"], "env": { "OPENAI_API_KEY": "sk-your-openai-key", "ANTHROPIC_API_KEY": "sk-ant-your-anthropic-key"	}	}	} }

Cipher now supports a new MCP Aggregator Mode that exposes all available tools (not just ask_cipher) to MCP clients, including all built-in tools for cipher, such as cipher_search_memory and MCP server tools specified in cipher.yml. This is controlled by the MCP_SERVER_MODE environment variable.

• default: Only the ask_cipher tool is available.
• aggregator: All tools (including those from connected MCP servers) are available, with conflict resolution and timeout options.

# Select MCP server mode: 'default' (only ask_cipher) or 'aggregator' (all tools) MCP_SERVER_MODE=aggregator # (Optional) Tool name conflict resolution: 'prefix' (default), 'first-wins', or 'error' AGGREGATOR_CONFLICT_RESOLUTION=prefix # (Optional) Tool execution timeout in milliseconds (default: 60000) AGGREGATOR_TIMEOUT=60000

{ "mcpServers": { "cipher-aggregator": { "type": "stdio", "command": "cipher", "args": ["--mode", "mcp"], "env": { "OPENAI_API_KEY": "sk-your-openai-key", "MCP_SERVER_MODE": "aggregator", "AGGREGATOR_CONFLICT_RESOLUTION": "prefix", "AGGREGATOR_TIMEOUT": "60000"	}	}	} }

• In aggregator mode, all tools are exposed. Tool name conflicts are resolved according to AGGREGATOR_CONFLICT_RESOLUTION.
• If you want only the ask_cipher tool, set MCP_SERVER_MODE=default or omit the variable.

Check out the MCP Aggregator Hub example that further demonstrates the usecase of this MCP server mode.

Cipher now supports SSE (Server-Sent Events) as a transport for MCP server mode, in addition to stdio and http.

To start Cipher in MCP mode with SSE transport:

cipher --mode mcp --mcp-transport-type sse --mcp-port 4000

• --mcp-transport-type sse enables SSE transport.
• --mcp-port 4000 sets the port (default: 3000).

{ "mcpServers": { "cipher-sse": { "type": "sse", "url": "http://localhost:4000/mcp", "env": { "OPENAI_API_KEY": "sk-your-openai-key"	}	}	} }

• Set "type": "sse" and provide the "url" to the running Cipher SSE server.

Watch our comprehensive tutorial on how to integrate Cipher with Claude Code through MCP for enhanced coding assistance with persistent memory:

Click the image above to watch the tutorial on YouTube.

This tutorial covers:

• Setting up Cipher as an MCP server
• Configuring Claude Code to use Cipher
• Demonstrating memory storage and retrieval
• Real-world coding scenarios with persistent context

For detailed configuration instructions, see the CLI Coding Agents guide.

For detailed documentation, visit:

• Quick Start Guide
• Configuration Guide
• Complete Documentation

We welcome contributions! Refer to our Contributing Guide for more details.

cipher is the opensource version of the agentic memory of byterover which is built and maintained by the byterover team.

• Join our Discord to share projects, ask questions, or just say hi!
• If you enjoy cipher, please give us a ⭐ on GitHub—it helps a lot!
• Follow @kevinnguyendn on X

Thanks to all these amazing people for contributing to cipher!

Contributors

Elastic License 2.0. See LICENSE for full terms.