Cipher

笔记 TypeScript

🚀 Cipher

Cipher是一个集成了MCP的记忆驱动型人工智能代理框架，专为编码代理设计，能有效提升编码效率和协作性。

🚀 快速开始

NPM 包（推荐大多数用户使用）

# 全局安装
npm install -g @byterover/cipher

# 或者在项目中本地安装
npm install @byterover/cipher

Docker

显示 Docker 设置

# 克隆并设置
git clone https://github.com/campfirein/cipher.git
cd cipher

# 配置环境
cp .env.example .env
# 使用你的 API 密钥编辑 .env

# 使用 Docker 启动
docker-compose up --build -d

# 测试
curl http://localhost:3000/health

⚠️ 重要提示

Docker 构建会自动跳过 UI 构建步骤，以避免与 lightningcss 出现 ARM64 兼容性问题。默认情况下，Docker 镜像中不包含 UI。

若要在 Docker 构建中包含 UI，请使用：docker build --build-arg BUILD_UI=true .

从源代码安装

pnpm i && pnpm run build && npm link

CLI 使用方法 💻

显示 CLI 命令

# 交互模式
cipher

# 一次性命令
cipher "Add this to memory as common causes of 'CORS error' in local dev with Vite + Express."

# API 服务器模式
cipher --mode api

# MCP 服务器模式
cipher --mode mcp

# Web UI 模式
cipher --mode ui

⚠️ 重要提示

在终端/ shell 中运行 MCP 模式时，请导出所有环境变量，因为 Cipher 不会从 .env 文件中读取。

💡 使用建议

CLI 模式会自动继续或创建 "default" 会话。使用 /session new 可启动新会话。

Cipher Web UI 为与记忆驱动型人工智能代理进行交互提供了直观的界面，具有会话管理、工具集成和实时聊天功能。

✨ 主要特性

🔌 通过 MCP 与任意你想要的 IDE 集成。
🧠 自动生成可随代码库扩展的人工智能编码记忆。
🔄 在不同 IDE 之间无缝切换，不会丢失记忆和上下文。
🤝 轻松在开发团队中实时共享编码记忆。
🧬 双记忆层，可捕获系统 1（编程概念、业务逻辑和过往交互）和系统 2（模型生成代码时的推理步骤）。
⚙️ 零配置即可安装到你的 IDE 中。

📦 安装指南

基本配置 ⚙️

显示 YAML 示例

# LLM 配置
llm:
provider: openai # openai, anthropic, openrouter, ollama, qwen
model: gpt-4-turbo
apiKey: $OPENAI_API_KEY

# 系统提示
systemPrompt: 'You are a helpful AI assistant with memory capabilities.'

# MCP 服务器（可选）
mcpServers:
filesystem:
type: stdio
command: npx
args: ['-y', '@modelcontextprotocol/server-filesystem', '.']

📖 详见配置指南 以获取完整详细信息。

环境变量 🔐

在项目根目录创建一个 .env 文件，并包含以下必要变量：

显示 .env 模板

# ====================
# API 密钥（至少需要一个）
# ====================
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_TYPE=qdrant  # qdrant, milvus, or in-memory
VECTOR_STORE_URL=https://your-cluster.qdrant.io
VECTOR_STORE_API_KEY=your-qdrant-api-key

# ====================
# 聊天历史记录（可选 - 默认使用 SQLite）
# ====================
CIPHER_PG_URL=postgresql://user:pass@localhost:5432/cipher_db

# ====================
# 工作区记忆（可选）
# ====================
USE_WORKSPACE_MEMORY=true
WORKSPACE_VECTOR_STORE_COLLECTION=workspace_memory

# ====================
# AWS Bedrock（可选）
# ====================
AWS_ACCESS_KEY_ID=your-aws-access-key
AWS_SECRET_ACCESS_KEY=your-aws-secret-key
AWS_DEFAULT_REGION=us-east-1

# ====================
# 高级选项（可选）
# ====================
# 日志记录和调试
CIPHER_LOG_LEVEL=info  # error, warn, info, debug, silly
REDACT_SECRETS=true

# 向量存储配置
VECTOR_STORE_DIMENSION=1536
VECTOR_STORE_DISTANCE=Cosine  # Cosine, Euclidean, Dot, Manhattan
VECTOR_STORE_MAX_VECTORS=10000

# 记忆搜索配置
SEARCH_MEMORY_TYPE=knowledge  # knowledge, reflection, both (default: knowledge)
DISABLE_REFLECTION_MEMORY=true  # default: true

💡 使用建议

复制 .env.example 到 .env 并填写你的值：
cp .env.example .env

📚 详细文档

📚 完整文档

主题	描述
配置	完整的配置指南，包括代理设置、嵌入和向量存储
大语言模型提供商	OpenAI、Anthropic、AWS、Azure、Qwen、Ollama、LM Studio 的详细设置
嵌入配置	嵌入提供商、回退逻辑和故障排除
向量存储	Qdrant、Milvus、内存向量数据库配置
聊天历史记录	PostgreSQL、SQLite 会话存储和管理
CLI 参考	完整的命令行界面文档
MCP 集成	高级 MCP 服务器设置、聚合器模式和 IDE 集成
工作区记忆	支持团队协作开发的记忆系统
示例	实际集成示例和用例

🚀 下一步

如需详细文档，请访问：

🔧 技术细节

MCP 服务器使用方法

Cipher 可以作为 MCP（模型上下文协议）服务器运行，允许与兼容 MCP 的客户端（如 Claude Desktop、Cursor、Windsurf 和其他人工智能编码助手）集成。

快速设置

要在 MCP 客户端配置中使用 Cipher 作为 MCP 服务器，请使用以下配置：

{
"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"
}
}
}
}

📖 详见 MCP 集成指南 以获取完整的 MCP 设置和高级功能。

👉 内置工具概述 — 展开下面的下拉菜单，快速浏览所有内容。完整详细信息请参阅 📘。

内置工具（概述）

记忆
- cipher_extract_and_operate_memory：一步提取知识并执行添加/更新/删除操作
- cipher_memory_search：对存储的知识进行语义搜索
- cipher_store_reasoning_memory：存储高质量的推理痕迹
推理（反思）
- cipher_extract_reasoning_steps（内部）：提取结构化的推理步骤
- cipher_evaluate_reasoning（内部）：评估推理质量并提出改进建议
- cipher_search_reasoning_patterns：在反思记忆中搜索模式
工作区记忆（团队）
- cipher_workspace_search：搜索团队/项目工作区记忆
- cipher_workspace_store：后台捕获团队/项目信号
知识图谱
- 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
系统
- cipher_bash：执行 bash 命令（一次性或持久化）

教程视频：Claude Code 与 Cipher MCP 集成

观看我们的综合教程，了解如何通过 MCP 将 Cipher 与 Claude Code 集成，以获得具有持久记忆的增强编码辅助功能：

点击上面的图片在 YouTube 上观看教程。

详细的配置说明请参阅 CLI 编码代理指南。

📄 许可证

采用 Elastic License 2.0 许可协议。完整条款请参阅 LICENSE。

贡献代码

我们欢迎贡献代码！更多详细信息请参阅我们的贡献指南。

社区与支持

cipher 是 byterover 代理记忆的开源版本，由 byterover 团队开发和维护。

加入我们的 Discord，分享项目、提问或只是打个招呼！
如果你喜欢 cipher，请在 GitHub 上给我们一个 ⭐，这对我们帮助很大！
在 X 上关注 @kevinnguyendn