https://github.com/campfirein/cipher
Byterover Cipher is an opensource memory layer specifically designed for coding agents. Compatible with Cursor, Codex, Claude Code, Windsurf, Cline, Claude Desktop, Gemini CLI, AWS's Kiro, VS Code, Roo Code, Trae, Amp Code and Warp through MCP. Built by https://byterover.dev/
https://github.com/campfirein/cipher
agent llm mcp memory vibe-coding
Last synced: 4 days ago
JSON representation
Byterover Cipher is an opensource memory layer specifically designed for coding agents. Compatible with Cursor, Codex, Claude Code, Windsurf, Cline, Claude Desktop, Gemini CLI, AWS's Kiro, VS Code, Roo Code, Trae, Amp Code and Warp through MCP. Built by https://byterover.dev/
- Host: GitHub
- URL: https://github.com/campfirein/cipher
- Owner: campfirein
- License: other
- Created: 2025-06-19T22:40:22.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-12-16T16:08:55.000Z (about 1 month ago)
- Last Synced: 2025-12-20T07:12:26.777Z (27 days ago)
- Topics: agent, llm, mcp, memory, vibe-coding
- Language: TypeScript
- Homepage: https://docs.byterover.dev/cipher/overview
- Size: 6.55 MB
- Stars: 3,350
- Watchers: 20
- Forks: 340
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-claude - cipher - 1.7k⭐ - Memory layer for coding agents (Claude Code Ecosystem / Memory & Context Management)
- awesome-claude-code - **cipher**
- awesome-ai-agents - campfirein/cipher - Cipher is an open-source memory layer designed for AI coding agents, enabling seamless memory and context management across multiple IDEs and AI assistants with MCP integration. (Agent Integration & Deployment Tools / MCP Server Framework)
README
# Byterover Cipher
Memory-powered AI agent framework with MCP integration
## Overview
Byterover Cipher is an opensource memory layer specifically designed for coding agents. Compatible with **Cursor, Codex, Claude Code, Windsurf, Cline, Claude Desktop, Gemini CLI, AWS's Kiro, VS Code, Roo Code, Trae, Amp Code and Warp** through MCP, and coding agents, such as **Kimi K2**. (see more on [examples](./examples))
Built by [Byterover team](https://byterover.dev/)
**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.
## Quick Start 🚀
### NPM Package (Recommended for Most Users)
```bash
# Install globally
npm install -g @byterover/cipher
# Or install locally in your project
npm install @byterover/cipher
```
### Docker
Show Docker Setup
```bash
# 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
```
> **💡 Note:** Docker builds automatically skip the UI build step to avoid ARM64 compatibility issues with lightningcss. The UI is not included in the Docker image by default.
>
> To include the UI in the Docker build, use: `docker build --build-arg BUILD_UI=true .`
### From Source
```bash
pnpm i && pnpm run build && npm link
```
### CLI Usage 💻
Show CLI commands
```bash
# 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 ` 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._
## Configuration
Cipher supports multiple configuration options for different deployment scenarios. The main configuration file is located at `memAgent/cipher.yml`.
### Basic Configuration ⚙️
Show YAML example
```yaml
# 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', '.']
```
📖 **See [Configuration Guide](./docs/configuration.md)** for complete details.
### Environment Variables 🔐
Create a `.env` file in your project root with these essential variables:
Show .env template
```bash
# ====================
# API Keys (At least one required)
# ====================
OPENAI_API_KEY=sk-your-openai-api-key
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key
GEMINI_API_KEY=your-gemini-api-key
QWEN_API_KEY=your-qwen-api-key
# ====================
# Vector Store (Optional - defaults to in-memory)
# ====================
VECTOR_STORE_TYPE=qdrant # qdrant, milvus, or in-memory
VECTOR_STORE_URL=https://your-cluster.qdrant.io
VECTOR_STORE_API_KEY=your-qdrant-api-key
# ====================
# Chat History (Optional - defaults to SQLite)
# ====================
CIPHER_PG_URL=postgresql://user:pass@localhost:5432/cipher_db
# ====================
# Workspace Memory (Optional)
# ====================
USE_WORKSPACE_MEMORY=true
WORKSPACE_VECTOR_STORE_COLLECTION=workspace_memory
# ====================
# AWS Bedrock (Optional)
# ====================
AWS_ACCESS_KEY_ID=your-aws-access-key
AWS_SECRET_ACCESS_KEY=your-aws-secret-key
AWS_DEFAULT_REGION=us-east-1
# ====================
# Advanced Options (Optional)
# ====================
# Logging and debugging
CIPHER_LOG_LEVEL=info # error, warn, info, debug, silly
REDACT_SECRETS=true
# Vector store configuration
VECTOR_STORE_DIMENSION=1536
VECTOR_STORE_DISTANCE=Cosine # Cosine, Euclidean, Dot, Manhattan
VECTOR_STORE_MAX_VECTORS=10000
# Memory search configuration
SEARCH_MEMORY_TYPE=knowledge # knowledge, reflection, both (default: knowledge)
DISABLE_REFLECTION_MEMORY=true # default: true
```
> **💡 Tip:** Copy `.env.example` to `.env` and fill in your values:
>
> ```bash
> cp .env.example .env
> ```
## MCP Server Usage
Cipher can run as an MCP (Model Context Protocol) server, allowing integration with MCP-compatible clients like Codex, Claude Desktop, Cursor, Windsurf, and other AI coding assistants.
### Installing via Smithery
To install cipher for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@campfirein/cipher):
```bash
npx -y @smithery/cli install @campfirein/cipher --client claude
```
### Quick Setup
To use Cipher as an MCP server in your MCP client configuration:
```json
{
"mcpServers": {
"cipher": {
"type": "stdio",
"command": "cipher",
"args": ["--mode", "mcp"],
"env": {
"MCP_SERVER_MODE": "aggregator",
"OPENAI_API_KEY": "your_openai_api_key",
"ANTHROPIC_API_KEY": "your_anthropic_api_key"
}
}
}
}
```
📖 **See [MCP Integration Guide](./docs/mcp-integration.md)** for complete MCP setup and advanced features.
👉 **Built‑in tools overview** — expand the dropdown below to scan everything at a glance. For full details, see [`docs/builtin-tools.md`](./docs/builtin-tools.md) 📘.
Built-in Tools (overview)
- Memory
- `cipher_extract_and_operate_memory`: Extracts knowledge and applies ADD/UPDATE/DELETE in one step
- `cipher_memory_search`: Semantic search over stored knowledge
- `cipher_store_reasoning_memory`: Store high-quality reasoning traces
- Reasoning (Reflection)
- `cipher_extract_reasoning_steps` (internal): Extract structured reasoning steps
- `cipher_evaluate_reasoning` (internal): Evaluate reasoning quality and suggest improvements
- `cipher_search_reasoning_patterns`: Search reflection memory for patterns
- Workspace Memory (team)
- `cipher_workspace_search`: Search team/project workspace memory
- `cipher_workspace_store`: Background capture of team/project signals
- Knowledge Graph
- `cipher_add_node`, `cipher_update_node`, `cipher_delete_node`, `cipher_add_edge`
- `cipher_search_graph`, `cipher_enhanced_search`, `cipher_get_neighbors`
- `cipher_extract_entities`, `cipher_query_graph`, `cipher_relationship_manager`
- System
- `cipher_bash`: Execute bash commands (one-off or persistent)
## Tutorial Video: Claude Code with Cipher MCP
Watch our comprehensive tutorial on how to integrate Cipher with Claude Code through MCP for enhanced coding assistance with persistent memory:
[](https://www.youtube.com/watch?v=AZh9Py6g07Y)
> **Click the image above to watch the tutorial on YouTube.**
For detailed configuration instructions, see the [CLI Coding Agents guide](./examples/02-cli-coding-agents/README.md).
## Documentation
### 📚 Complete Documentation
| Topic | Description |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| [Configuration](./docs/configuration.md) | Complete configuration guide including agent setup, embeddings, and vector stores |
| [LLM Providers](./docs/llm-providers.md) | Detailed setup for OpenAI, Anthropic, AWS, Azure, Qwen, Ollama, LM Studio |
| [Embedding Configuration](./docs/embedding-configuration.md) | Embedding providers, fallback logic, and troubleshooting |
| [Vector Stores](./docs/vector-stores.md) | Qdrant, Milvus, In-Memory vector database configurations |
| [Chat History](./docs/chat-history.md) | PostgreSQL, SQLite session storage and management |
| [CLI Reference](./docs/cli-reference.md) | Complete command-line interface documentation |
| [MCP Integration](./docs/mcp-integration.md) | Advanced MCP server setup, aggregator mode, and IDE integrations |
| [Workspace Memory](./docs/workspace-memory.md) | Team-aware memory system for collaborative development |
| [Examples](./docs/examples.md) | Real-world integration examples and use cases |
### 🚀 Next Steps
For detailed documentation, visit:
- [Quick Start Guide](https://docs.byterover.dev/cipher/quickstart)
- [Configuration Guide](https://docs.byterover.dev/cipher/configuration)
- [Complete Documentation](https://docs.byterover.dev/cipher/overview)
## Contributing
We welcome contributions! Refer to our [Contributing Guide](./CONTRIBUTING.md) for more details.
## Community & Support
**cipher** is the opensource version of the agentic memory of [byterover](https://byterover.dev/) which is built and maintained by the byterover team.
- Join our [Discord](https://discord.com/invite/UMRrpNjh5W) 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](https://x.com/kevinnguyendn) on X
## Contributors
Thanks to all these amazing people for contributing to cipher!
[](https://github.com/campfirein/cipher/graphs/contributors)
## MseeP.ai Security Assessment Badge
[](https://mseep.ai/app/campfirein-cipher)
## Star History
## License
Elastic License 2.0. See [LICENSE](LICENSE) for full terms.