{"id":30099452,"url":"https://github.com/campfirein/cipher","last_synced_at":"2026-01-12T01:58:05.527Z","repository":{"id":304774132,"uuid":"1005233473","full_name":"campfirein/cipher","owner":"campfirein","description":"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/","archived":false,"fork":false,"pushed_at":"2025-12-16T16:08:55.000Z","size":6866,"stargazers_count":3350,"open_issues_count":13,"forks_count":340,"subscribers_count":20,"default_branch":"main","last_synced_at":"2025-12-20T07:12:26.777Z","etag":null,"topics":["agent","llm","mcp","memory","vibe-coding"],"latest_commit_sha":null,"homepage":"https://docs.byterover.dev/cipher/overview","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/campfirein.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-19T22:40:22.000Z","updated_at":"2025-12-19T10:16:36.000Z","dependencies_parsed_at":"2025-07-15T10:08:23.656Z","dependency_job_id":"f7e64cac-736f-4c2a-aaaa-209b3645326c","html_url":"https://github.com/campfirein/cipher","commit_stats":null,"previous_names":["campfirein/cipher"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/campfirein/cipher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/campfirein%2Fcipher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/campfirein%2Fcipher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/campfirein%2Fcipher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/campfirein%2Fcipher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/campfirein","download_url":"https://codeload.github.com/campfirein/cipher/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/campfirein%2Fcipher/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28331434,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T00:36:25.062Z","status":"ssl_error","status_checked_at":"2026-01-12T00:36:15.229Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","llm","mcp","memory","vibe-coding"],"created_at":"2025-08-09T14:03:10.870Z","updated_at":"2026-01-12T01:58:05.516Z","avatar_url":"https://github.com/campfirein.png","language":"TypeScript","readme":"# Byterover Cipher\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"./assets/cipher-logo.png\" alt=\"Cipher Agent Logo\" width=\"400\" /\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cem\u003eMemory-powered AI agent framework with MCP integration\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-Elastic%202.0-blue.svg\" alt=\"License\" /\u003e\u003c/a\u003e\n\u003cimg src=\"https://img.shields.io/badge/Status-Beta-orange.svg\" alt=\"Beta\" /\u003e\n\u003ca href=\"https://docs.byterover.dev/cipher/overview\"\u003e\u003cimg src=\"https://img.shields.io/badge/Docs-Documentation-green.svg\" alt=\"Documentation\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://discord.com/invite/UMRrpNjh5W\"\u003e\u003cimg src=\"https://img.shields.io/badge/Discord-Join%20Community-7289da\" alt=\"Discord\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://www.producthunt.com/products/byterover?embed=true\u0026utm_source=badge-top-post-badge\u0026utm_medium=badge\u0026utm_source=badge-cipher\u0026#0045;by\u0026#0045;byterover\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://api.producthunt.com/widgets/embed-image/v1/top-post-badge.svg?post_id=1000588\u0026theme=light\u0026period=daily\u0026t=1754744170741\" alt=\"Cipher\u0026#0032;by\u0026#0032;Byterover - Open\u0026#0045;source\u0026#0044;\u0026#0032;shared\u0026#0032;memory\u0026#0032;for\u0026#0032;coding\u0026#0032;agents | Product Hunt\" style=\"width: 250px; height: 54px;\" width=\"250\" height=\"54\" /\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n## Overview\n\nByterover 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))\n\nBuilt by [Byterover team](https://byterover.dev/)\n\n**Key Features:**\n\n- 🔌 MCP integration with any IDE you want.\n- 🧠 Auto-generate AI coding memories that scale with your codebase.\n- 🔄 Switch seamlessly between IDEs without losing memory and context.\n- 🤝 Easily share coding memories across your dev team in real time.\n- 🧬 Dual Memory Layer that captures System 1 (Programming Concepts \u0026 Business Logic \u0026 Past Interaction) and System 2 (reasoning steps of the model when generating code).\n- ⚙️ Install on your IDE with zero configuration needed.\n\n## Quick Start 🚀\n\n### NPM Package (Recommended for Most Users)\n\n```bash\n# Install globally\nnpm install -g @byterover/cipher\n\n# Or install locally in your project\nnpm install @byterover/cipher\n```\n\n### Docker\n\n\u003cdetails\u003e\n\u003csummary\u003eShow Docker Setup\u003c/summary\u003e\n\n```bash\n# Clone and setup\ngit clone https://github.com/campfirein/cipher.git\ncd cipher\n\n# Configure environment\ncp .env.example .env\n# Edit .env with your API keys\n\n# Start with Docker\ndocker-compose up --build -d\n\n# Test\ncurl http://localhost:3000/health\n```\n\n\u003e **💡 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.\n\u003e\n\u003e To include the UI in the Docker build, use: `docker build --build-arg BUILD_UI=true .`\n\n\u003c/details\u003e\n\n### From Source\n\n```bash\npnpm i \u0026\u0026 pnpm run build \u0026\u0026 npm link\n```\n\n### CLI Usage 💻\n\n\u003cdetails\u003e\n\u003csummary\u003eShow CLI commands\u003c/summary\u003e\n\n```bash\n# Interactive mode\ncipher\n\n# One-shot command\ncipher \"Add this to memory as common causes of 'CORS error' in local dev with Vite + Express.\"\n\n# API server mode\ncipher --mode api\n\n# MCP server mode\ncipher --mode mcp\n\n# Web UI mode\ncipher --mode ui\n```\n\n\u003e **⚠️ Note:** When running MCP mode in terminal/shell, export all environment variables as Cipher won't read from `.env` file.\n\u003e\n\u003e **💡 Tip:** CLI mode automatically continues or creates the \"default\" session. Use `/session new \u003csession-name\u003e` to start a fresh session.\n\n\u003c/details\u003e\n\n![Cipher Web UI](./assets/cipher_webUI.png)\n\n_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._\n\n## Configuration\n\nCipher supports multiple configuration options for different deployment scenarios. The main configuration file is located at `memAgent/cipher.yml`.\n\n### Basic Configuration ⚙️\n\n\u003cdetails\u003e\n\u003csummary\u003eShow YAML example\u003c/summary\u003e\n\n```yaml\n# LLM Configuration\nllm:\n  provider: openai # openai, anthropic, openrouter, ollama, qwen\n  model: gpt-4-turbo\n  apiKey: $OPENAI_API_KEY\n\n# System Prompt\nsystemPrompt: 'You are a helpful AI assistant with memory capabilities.'\n\n# MCP Servers (optional)\nmcpServers:\n  filesystem:\n    type: stdio\n    command: npx\n    args: ['-y', '@modelcontextprotocol/server-filesystem', '.']\n```\n\n\u003c/details\u003e\n\n📖 **See [Configuration Guide](./docs/configuration.md)** for complete details.\n\n### Environment Variables 🔐\n\nCreate a `.env` file in your project root with these essential variables:\n\n\u003cdetails\u003e\n\u003csummary\u003eShow .env template\u003c/summary\u003e\n\n```bash\n# ====================\n# API Keys (At least one required)\n# ====================\nOPENAI_API_KEY=sk-your-openai-api-key\nANTHROPIC_API_KEY=sk-ant-your-anthropic-key\nGEMINI_API_KEY=your-gemini-api-key\nQWEN_API_KEY=your-qwen-api-key\n\n# ====================\n# Vector Store (Optional - defaults to in-memory)\n# ====================\nVECTOR_STORE_TYPE=qdrant  # qdrant, milvus, or in-memory\nVECTOR_STORE_URL=https://your-cluster.qdrant.io\nVECTOR_STORE_API_KEY=your-qdrant-api-key\n\n# ====================\n# Chat History (Optional - defaults to SQLite)\n# ====================\nCIPHER_PG_URL=postgresql://user:pass@localhost:5432/cipher_db\n\n# ====================\n# Workspace Memory (Optional)\n# ====================\nUSE_WORKSPACE_MEMORY=true\nWORKSPACE_VECTOR_STORE_COLLECTION=workspace_memory\n\n# ====================\n# AWS Bedrock (Optional)\n# ====================\nAWS_ACCESS_KEY_ID=your-aws-access-key\nAWS_SECRET_ACCESS_KEY=your-aws-secret-key\nAWS_DEFAULT_REGION=us-east-1\n\n# ====================\n# Advanced Options (Optional)\n# ====================\n# Logging and debugging\nCIPHER_LOG_LEVEL=info  # error, warn, info, debug, silly\nREDACT_SECRETS=true\n\n# Vector store configuration\nVECTOR_STORE_DIMENSION=1536\nVECTOR_STORE_DISTANCE=Cosine  # Cosine, Euclidean, Dot, Manhattan\nVECTOR_STORE_MAX_VECTORS=10000\n\n# Memory search configuration\nSEARCH_MEMORY_TYPE=knowledge  # knowledge, reflection, both (default: knowledge)\nDISABLE_REFLECTION_MEMORY=true  # default: true\n```\n\n\u003e **💡 Tip:** Copy `.env.example` to `.env` and fill in your values:\n\u003e\n\u003e ```bash\n\u003e cp .env.example .env\n\u003e ```\n\n\u003c/details\u003e\n\n## MCP Server Usage\n\nCipher 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.\n\n### Installing via Smithery\n\nTo install cipher for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@campfirein/cipher):\n\n```bash\nnpx -y @smithery/cli install @campfirein/cipher --client claude\n```\n\n### Quick Setup\n\nTo use Cipher as an MCP server in your MCP client configuration:\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"cipher\": {\n\t\t\t\"type\": \"stdio\",\n\t\t\t\"command\": \"cipher\",\n\t\t\t\"args\": [\"--mode\", \"mcp\"],\n\t\t\t\"env\": {\n\t\t\t\t\"MCP_SERVER_MODE\": \"aggregator\",\n\t\t\t\t\"OPENAI_API_KEY\": \"your_openai_api_key\",\n\t\t\t\t\"ANTHROPIC_API_KEY\": \"your_anthropic_api_key\"\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n📖 **See [MCP Integration Guide](./docs/mcp-integration.md)** for complete MCP setup and advanced features.\n\n👉 **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) 📘.\n\n\u003cdetails\u003e\n\u003csummary\u003eBuilt-in Tools (overview)\u003c/summary\u003e\n\n- Memory\n  - `cipher_extract_and_operate_memory`: Extracts knowledge and applies ADD/UPDATE/DELETE in one step\n  - `cipher_memory_search`: Semantic search over stored knowledge\n  - `cipher_store_reasoning_memory`: Store high-quality reasoning traces\n- Reasoning (Reflection)\n  - `cipher_extract_reasoning_steps` (internal): Extract structured reasoning steps\n  - `cipher_evaluate_reasoning` (internal): Evaluate reasoning quality and suggest improvements\n  - `cipher_search_reasoning_patterns`: Search reflection memory for patterns\n- Workspace Memory (team)\n  - `cipher_workspace_search`: Search team/project workspace memory\n  - `cipher_workspace_store`: Background capture of team/project signals\n- Knowledge Graph\n  - `cipher_add_node`, `cipher_update_node`, `cipher_delete_node`, `cipher_add_edge`\n  - `cipher_search_graph`, `cipher_enhanced_search`, `cipher_get_neighbors`\n  - `cipher_extract_entities`, `cipher_query_graph`, `cipher_relationship_manager`\n- System\n  - `cipher_bash`: Execute bash commands (one-off or persistent)\n\n\u003c/details\u003e\n\n## Tutorial Video: Claude Code with Cipher MCP\n\nWatch our comprehensive tutorial on how to integrate Cipher with Claude Code through MCP for enhanced coding assistance with persistent memory:\n\n[![Cipher + Claude Code Tutorial](https://img.youtube.com/vi/AZh9Py6g07Y/maxresdefault.jpg)](https://www.youtube.com/watch?v=AZh9Py6g07Y)\n\n\u003e **Click the image above to watch the tutorial on YouTube.**\n\nFor detailed configuration instructions, see the [CLI Coding Agents guide](./examples/02-cli-coding-agents/README.md).\n\n## Documentation\n\n### 📚 Complete Documentation\n\n| Topic                                                        | Description                                                                       |\n| ------------------------------------------------------------ | --------------------------------------------------------------------------------- |\n| [Configuration](./docs/configuration.md)                     | Complete configuration guide including agent setup, embeddings, and vector stores |\n| [LLM Providers](./docs/llm-providers.md)                     | Detailed setup for OpenAI, Anthropic, AWS, Azure, Qwen, Ollama, LM Studio         |\n| [Embedding Configuration](./docs/embedding-configuration.md) | Embedding providers, fallback logic, and troubleshooting                          |\n| [Vector Stores](./docs/vector-stores.md)                     | Qdrant, Milvus, In-Memory vector database configurations                          |\n| [Chat History](./docs/chat-history.md)                       | PostgreSQL, SQLite session storage and management                                 |\n| [CLI Reference](./docs/cli-reference.md)                     | Complete command-line interface documentation                                     |\n| [MCP Integration](./docs/mcp-integration.md)                 | Advanced MCP server setup, aggregator mode, and IDE integrations                  |\n| [Workspace Memory](./docs/workspace-memory.md)               | Team-aware memory system for collaborative development                            |\n| [Examples](./docs/examples.md)                               | Real-world integration examples and use cases                                     |\n\n### 🚀 Next Steps\n\nFor detailed documentation, visit:\n\n- [Quick Start Guide](https://docs.byterover.dev/cipher/quickstart)\n- [Configuration Guide](https://docs.byterover.dev/cipher/configuration)\n- [Complete Documentation](https://docs.byterover.dev/cipher/overview)\n\n## Contributing\n\nWe welcome contributions! Refer to our [Contributing Guide](./CONTRIBUTING.md) for more details.\n\n## Community \u0026 Support\n\n**cipher** is the opensource version of the agentic memory of [byterover](https://byterover.dev/) which is built and maintained by the byterover team.\n\n- Join our [Discord](https://discord.com/invite/UMRrpNjh5W) to share projects, ask questions, or just say hi!\n- If you enjoy cipher, please give us a ⭐ on GitHub—it helps a lot!\n- Follow [@kevinnguyendn](https://x.com/kevinnguyendn) on X\n\n## Contributors\n\nThanks to all these amazing people for contributing to cipher!\n\n[![Contributors](https://contrib.rocks/image?repo=campfirein/cipher\u0026max=40\u0026columns=10)](https://github.com/campfirein/cipher/graphs/contributors)\n\n## MseeP.ai Security Assessment Badge\n\n[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/campfirein-cipher-badge.png)](https://mseep.ai/app/campfirein-cipher)\n\n## Star History\n\n\u003ca href=\"https://star-history.com/#campfirein/cipher\u0026Date\"\u003e\n  \u003cimg width=\"500\" alt=\"Star History Chart\" src=\"https://api.star-history.com/svg?repos=campfirein/cipher\u0026type=Date\u0026v=2\"\u003e\n\u003c/a\u003e\n\n## License\n\nElastic License 2.0. See [LICENSE](LICENSE) for full terms.\n","funding_links":[],"categories":["Claude Code Ecosystem","📚 Projects (1974 total)","HarmonyOS","Tools \u0026 Utilities","TypeScript","Agent Integration \u0026 Deployment Tools","Skills \u0026 Plugins","MCP \u0026 Model Context Protocol","\u003ca name=\"TypeScript\"\u003e\u003c/a\u003eTypeScript"],"sub_categories":["Memory \u0026 Context Management","MCP Servers","Windows Manager","MCP Server Framework","Agent Memory \u0026 Context"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcampfirein%2Fcipher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcampfirein%2Fcipher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcampfirein%2Fcipher/lists"}