一文读懂 Cipher：让 AI 记住你每一次编码的“记忆层”框架

“

“如果 Cursor、Windsurf、Claude Code 这些 AI 编码助手能记住我之前的上下文，是否就不用反复解释需求？”
—— 几乎所有用过 AI 写代码的人都这么想。Cipher 把这件事做成了开源方案。

”

1. Cipher 是什么？

Cipher 是一个专为编码场景设计的记忆层，通过 MCP（Model Context Protocol）把记忆能力插进你正在用的任何 IDE 或命令行工具。
一句话：它让 AI 记住你写过的代码、踩过的坑、聊过的需求，换工具也不丢上下文。

它能解决哪些实际问题？

场景	没有 Cipher	有了 Cipher
从 Cursor 换到 VS Code	重新解释项目结构	自动加载历史记忆
多人协作	同事不知道你昨晚改了什么	实时共享同一份记忆库
回归 bug	忘记当时为什么这么写	检索当时的思路、报错、修复步骤
切换模型	新模型不了解业务	记忆跟着你走，模型即插即用

2. 核心概念：双记忆层

Cipher 把记忆拆成两层，对应丹尼尔·卡尼曼提出的“系统 1 / 系统 2”：

系统 1 记忆
- 编程概念（如“React hooks 规则”）
- 业务逻辑（如“订单状态机”）
- 历史交互（如“上次把 vite.config.ts 的 CORS 设置改成 origin: true 才解决本地调试”）
系统 2 记忆
- AI 当时怎样一步步推理出那段代码
- 方便以后复现、审查、改进

3. 五分钟上手

3.1 NPM 一条命令装完

# 全局安装，随时可用
npm install -g @byterover/cipher

# 或者放进项目里
npm install @byterover/cipher

3.2 零配置启动

# 1. 交互模式，边聊边记
cipher

# 2. 一句话记录
cipher "把 Vite + Express 本地开发常见的 CORS 报错原因记下来"

# 3. 启动 API 服务，供其他工具调用
cipher --mode api

第一次运行会自动在当前目录生成 .env 模板，把要用的 API key 填进去即可。

4. 安装方式总览

方式	适用场景	一句话指令
NPM	90% 用户	`npm i -g @byterover/cipher`
Docker	需要隔离环境	`docker-compose up -d`
源码	想二次开发	`pnpm i && pnpm build && npm link`

Docker 步骤：

git clone https://github.com/campfirein/cipher.git
cd cipher
cp .env.example .env
# 编辑 .env 填 API key
docker-compose up -d
curl http://localhost:3000/health   # 返回 ok 即成功

5. 配置：从环境变量到 YAML

5.1 最少只需两行

OPENAI_API_KEY=sk-xxx
# 或 ANTHROPIC_API_KEY、GEMINI_API_KEY 任意一个即可

5.2 高阶玩法：cipher.yml

放在 memAgent/cipher.yml，可同时指定 LLM、嵌入模型、MCP 服务器。

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

# 想让 Claude Desktop 也能访问本地文件
mcpServers:
  filesystem:
    type: stdio
    command: npx
    args: ['-y', '@modelcontextprotocol/server-filesystem', '.']

6. 嵌入模型怎么选？

Cipher 默认用 OpenAI 的 text-embedding-3-small，但也支持免费或本地方案。

方案	费用	配置示例
OpenAI	按 token 计费	`embedding: {type: openai, model: text-embedding-3-small, apiKey: $OPENAI_API_KEY}`
Gemini	免费额度	`embedding: {type: gemini, model: gemini-embedding-001, apiKey: $GEMINI_API_KEY}`
Ollama	本地 0 成本	`embedding: {type: ollama, model: nomic-embed-text, baseUrl: $OLLAMA_BASE_URL}`
关闭嵌入	最轻量	`embedding: {disabled: true}`

本地 Ollama 三步：

# macOS
brew install ollama
ollama serve               # 启动服务
ollama pull nomic-embed-text

7. LLM 支持矩阵

提供商	模型示例	备注
OpenAI	gpt-4-turbo	最常用
Anthropic	claude-3-5-sonnet-20241022	长上下文
OpenRouter	任意 200+ 模型	统一入口
Ollama	qwen2.5:32b	完全本地
阿里云 Qwen	qwen2.5-72b-instruct	支持思考模式
AWS Bedrock	meta.llama3-1-70b-instruct-v1:0	需 AWS 凭证
Azure OpenAI	gpt-4o-mini	企业合规

YAML 片段：

# 本地 Ollama
llm:
  provider: ollama
  model: qwen2.5:32b
  baseURL: http://localhost:11434/v1

# 阿里云 Qwen 思考模式
llm:
  provider: qwen
  model: qwen2.5-72b-instruct
  qwenOptions:
    enableThinking: true
    thinkingBudget: 1000

8. 命令行完全指南

模式	作用	示例
交互	像聊天一样	`cipher`
一次性	记录一句话	`cipher "记录订单接口幂等实现"`
API 服务	给前端/脚本调用	`cipher --mode api`
MCP 服务	供 Claude Desktop 等使用	`cipher --mode mcp`

常用子命令：

/session list          # 查看记忆会话
/session new fix-bug   # 新建会话
/session switch legacy # 切换会话
/config                # 打印当前配置
/stats                 # 查看用量统计
/help                  # 帮助

9. MCP：把 Cipher 插进任何 IDE

9.1 Claude Desktop 示例

在 Claude Desktop 的配置文件里加一段：

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

重启 Claude Desktop，侧边栏多了一个 ask_cipher 工具，随时检索历史记忆。

9.2 MCP Aggregator 模式（高级）

如果想一次性暴露所有 MCP 工具（包括 Cipher 自带的搜索、其他服务器工具），把环境变量 MCP_SERVER_MODE=aggregator。

"env": {
  "MCP_SERVER_MODE": "aggregator",
  "AGGREGATOR_CONFLICT_RESOLUTION": "prefix"
}

这样 Cursor、Windsurf 也能同时用到 Cipher 记忆 + 其他 MCP 工具，冲突时自动加前缀。

10. SSE 传输：浏览器也能连

除了 stdio、http，Cipher 还支持 SSE（Server-Sent Events）。

启动：

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

浏览器/前端直接连 http://localhost:4000/mcp，实时推送记忆更新。

11. FAQ：你可能想问的 15 个问题

Q1 没 GPU 能跑吗？
能。除 Ollama 外，所有推理都在云端，本地只做轻量转发。

Q2 公司内网隔离怎么办？
用 Ollama + 本地嵌入模型即可 100% 离线。

Q3 记忆存哪里？
默认本地文件，也支持 Neo4j 图数据库；团队场景可指向共享库。

Q4 会不会泄露代码？
所有请求走你自己的 API key，Cipher 不做任何上传。

Q5 支持中文注释吗？
支持，嵌入模型对中文同样有效。

Q6 如何删除敏感记忆？

/session switch <id>
/config 查看路径后手动删文件即可

Q7 多项目如何隔离？
每个项目建一个会话，目录下自动放各自的 cipher.yml。

Q8 能跟 GitHub Copilot 一起用吗？
Copilot 不开放 MCP，但可以把 Cipher 当 API 调用，写脚本补全提示。

Q9 记忆有大小限制吗？
OpenAI 嵌入维度 1536，存 100 万条大约 600 MB，磁盘够就行。

Q10 如何备份？
把会话目录打包即可，内含 JSON + 向量索引。

Q11 和 LangChain Memory 有啥区别？
LangChain 侧重链式调用，Cipher 专注“IDE 级”上下文 + 即插即用 MCP。

Q12 Windows 能用吗？
能，NPM、Docker、源码三种方式都跨平台。

Q13 有 Web UI 吗？
目前 CLI + API，社区有人用 Next.js 套了简易 UI，官方后续会出。

Q14 怎么统计费用？
/stats 会列出 token 用量，对应各自云厂商账单。

Q15 能否只读不写？
启动时加 --read-only 即可，适合 CI 场景只查询。

12. 真实案例：三步把记忆接进 Claude Code

装好 Cipher
```
npm i -g @byterover/cipher
```

在 Claude Code 根目录放 .env

OPENAI_API_KEY=sk-xxx
ANTHROPIC_API_KEY=sk-ant-xxx

运行
```
cipher --mode mcp
```
打开 Claude Code，输入
```
@cipher 上次我怎么解决 Vite CORS 的？
```
立刻返回当时的对话记录 + 代码 patch。

13. 下一步

官方文档（含示例）：https://docs.byterover.dev/cipher/overview
加入 Discord 社群：https://discord.com/invite/UMRrpNjh5W
给仓库点星，第一时间收到更新：https://github.com/campfirein/cipher

“

Cipher 不是又一个“万能 AI 框架”，它只是做了一件小事：让 AI 记住你写代码时的每一次思考。
如果你厌倦了反复解释需求，不妨给它五分钟，它会回报你整个项目的长期记忆。

”

Cipher框架：让AI代码助手永久记住你的编程记忆（开源方案）