cachly-dev

cachly——面向编码 Agent 的体验（MCP 服务）

一次解决问题。从此，你的 AI 就知道了。

每一次修复、每一个决策和每一次碰壁，都会成为 AI 在恰当时机运用的经验。你能更快地构建，而你的团队也能基于你的发现继续前进。

@cachly-dev/mcp-server 通过 MCP 将 cachly 连接到 Claude Code、Cursor、 GitHub Copilot、Windsurf、Cline、Continue.dev、Zed、Codex CLI 和 Gemini CLI。它提供 124 个 MCP 工具。默认情况下，编辑器会列出 27 个条目，其余工具可通过其中一个条目 cachly_tool 调用（详情见下文的 MCP 工具）。每次修复后，你的 AI 都会保存一条经验，并在同一问题再次出现时重新找到它。你的 Brain（存储经验的地方）位于欧盟服务器上。

无需账户即可开始

Claude Code

/plugin marketplace add cachly-dev/cachly-mcp
/plugin install cachly-brain@cachly

无需编写 JSON、设置路径或复制密钥。如果没有密钥，cachly 会在会话启动时于欧盟服务器上创建一个测试 Brain（由插件钩子创建；如果钩子未运行，则在首次调用工具时创建）。测试 Brain 可使用 Dev 层级 14 天。之后，它会使用同一密钥切换到免费层级。

运行 claude mcp list 检查状态。你应该会看到 plugin:cachly-brain:cachly … ✔ Connected。即使服务正在运行，claude plugin details 也会显示 MCP servers (0)，因为它不会统计这些服务。

该插件会添加三个 Claude Code 钩子：

开启一次自动更新：/plugin → Marketplaces → cachly → Enable auto-update。对于 Anthropic 自己以外的市场，Claude Code 默认会关闭自动更新。MCP 服务会在每次启动时自行更新，但钩子属于插件，只有插件更新时才会更新。如果有待安装的更新，会在会话首次触发 session_start 时用一行消息提示。

保留测试 Brain

npx @cachly-dev/mcp-server@latest claim

你只需在浏览器中登录一次。随后，测试 Brain 会连同其中的所有经验一起迁移到你的账户。所有测试密钥都会被撤销，你会获得一个新密钥，并存储在编辑器和钩子查找密钥的位置。Brain 会重启一次，大约需要 20 秒。如果你已经有一个免费 Brain，则适用免费层级只能拥有一个 Brain 的限制，迁移会被拒绝并显示提示消息。

Cursor、Windsurf、VS Code、Cline、Continue.dev、Zed

npx @cachly-dev/mcp-server@latest autopilot

autopilot 会查找你使用的编辑器，并为每个编辑器写入 MCP 配置。它会添加一个 git 钩子，从你的提交中学习，并用你的 git 历史填充 Brain。你只需在浏览器中登录一次（使用设备代码，无需密码或信用卡），Brain 从一开始就属于你自己的账户。之后请重启编辑器。

你也可以手动添加服务（参见手动设置）。如果没有密钥，首次调用工具时会创建与 Claude Code 中相同的测试 Brain。

已经在 Claude、Cursor 或 Copilot 中？ 将以下内容粘贴给你的 AI：

为此项目设置 cachly。运行：npx @cachly-dev/mcp-server@latest autopilot
按照浏览器中的步骤登录，然后重启编辑器。

VS Code 扩展

安装 cachly Brain。 它会在首次启动时创建你的 Brain，无需填写账户表单。

JetBrains 插件

从 JetBrains Marketplace 安装 Cachly Brain （IntelliJ IDEA、PyCharm、GoLand、WebStorm、Rider）。状态栏、Brain 健康状况和课程视图都位于 IDE 中。源代码位于 cachly-dev/cachly-intellij。JetBrains 插件指南 介绍了 Claude Code、Junie 和 JetBrains AI Assistant 如何通过 MCP 获取 Brain。

MCP Registry

该服务已列入官方 MCP Registry，名称为 io.github.cachly-dev/mcp-server。浏览 Registry 的客户端可以按名称找到它。该条目指向这个 npm 软件包。

指南

工作原理

1. 将修复、决策或走不通的方案记录为经验：主题、有效的方法、失败的尝试、严重程度、文件路径、命令和作者。
2. 会话开始时，你的 AI 会收到一份简报，其中包含上次会话、未解决的问题和近期经验。
3. 当你提出需求时，smart_recall 会查找相关经验。它会结合关键词搜索（BM25）、基于语义的搜索和因果图，支持 11 种语言。
4. 出现错误时，causal_trace 会从症状追溯到原因，再追溯到有效的修复方案。
5. 部署前，brain_predict 会列出以往事故中的故障模式。
6. Git hook 和 CI 模板 会从提交和由红转绿的运行中添加经验。
7. 经验会在团队中共享。每条经验都会注明学习者的姓名。

如想了解安装前你的 AI 能获取哪些信息，请在项目文件夹中运行 npx @cachly-dev/mcp-server@latest demo。它会读取你的 Git 历史记录， 并输出你的修复方案、模式和决策。任何信息都不会离开你的设备。

我们对你的承诺。 你可以随时离开并带走数据： npx @cachly-dev/mcp-server@latest export 会将每条经验写入 lessons.md（供阅读） 和 lessons.jsonl（供复用）。只有在你自行调用 index_project 时，才会存储代码摘录， 且仅存储在你自己的欧盟实例上。请在决定前阅读 哪些内容会离开你的设备。

MCP 工具（共 124 个，默认列出 27 个）

默认情况下，编辑器会看到 27 个条目：日常工具（共 26 个）和一个分发器 cachly_tool。这是有意为之。完整的 124 个工具在每个请求中会占用约 28,000 个 token。 列出的 27 个条目约占 8,000 个 token。其余所有工具（共 98 个）都通过 分发器运行：

cachly_tool(tool: "team_roster")                  run any of them by name
cachly_tool(tool: "team_roster", describe: true)  get its schema first

没有任何工具无法访问。服务会按名称分发，因此直接调用 team_roster 仍然有效。设置 CACHLY_ALLE_WERKZEUGE=1 可列出全部 124 个工具。设置 CACHLY_PROFILE=lean 可列出 8 个工具和 cachly_tool，或设置 CACHLY_PROFILE=recall 以列出 3 个只读工具。

会话与经验（最常用）

团队 Brain 与组织知识图谱

因果智能

示例：

causal_trace(problem="auth breaks after restart")

→ Root: k8s:namespace-terminating
→ Via:  keycloak:jwks-race
→ Fix:  PollUntilContextTimeout 3min

可分享的公开 Brain

知识共享库、基础设施与路线图

运行 health，查看编辑器中已接入的内容。完整目录根据 src/tools.ts 生成。

CLI 命令

npx @cachly-dev/mcp-server@latest autopilot # One command: signs in, configures every editor, fills the Brain from git

下面的每条命令都会以 npx @cachly-dev/mcp-server@latest <command> 运行。密钥和 Brain 实例来自环境变量，或来自 ~/.cachly/credentials.json（由 autopilot 写入的文件）。

bench 使用的方法见 BENCH.md。

提示：从每个已合并的 PR 中学习。 在 CI 中使用 cachly-brain-setup GitHub Action 运行 learn-git， 并设置 mode: learn。这样，每个已合并的 PR 都会教会你的 Brain 新知识。

CI 集成

每次 CI 运行都是一次经验。红→绿的转变代表经过验证的修复，绿→红的转变则代表已知原因。可直接粘贴使用的模板位于 src/ci-integration/：

• GitHub Actions： 使用 cachly-dev/cachly-action。 它需要密钥 CACHLY_API_KEY 和 CACHLY_BRAIN_INSTANCE_ID。
• GitLab CI： 使用 include: remote: 引入 GitLab 模板。 它会添加用于 learn、scan、confirm 和 hygiene 的隐藏作业； 可按需扩展。
• 其他平台： push-ci-outcome.mjs 是一个 无依赖的独立 Node.js 辅助程序。它始终以 0 退出，因此 CI 不会因为 Brain 推送而 失败。

已经积累了数月的 CI 历史记录？brain_from_ci 工具可以一次性导入过去的结果，就像 brain_from_git 导入提交一样。

常见问题

我的 AI 需要手动调用 session_start 吗？ 不需要。首次调用工具时会启动会话，编辑器关闭时会结束会话。

整个团队可以共享一个 Brain 吗？ 可以。使用 team_learn 和 team_recall，或运行 npx @cachly-dev/mcp-server@latest invite [email protected]。

我的代码会发送到 cachly 服务器吗？ 只有在你自行调用 index_project 时才会。它会在你自己的欧盟实例上，为每个已索引文件存储一段简短摘录（最多 summary_chars 个字符，默认为 1200 个字符）。 其他所有工具都会存储经验文本、提交消息、会话摘要和键值上下文，但不会存储源代码。数据存储在德国，嵌入向量在欧盟计算。 API 流量会经过美国公司 Cloudflare。 欧盟指南列出了所有数据流。

什么是 causal_trace？ 给定一个错误，它会遍历因果知识图谱，找出根本原因、中间原因以及奏效的修复方法，并提供日期和命令。

如果我在会话中途达到上下文窗口限制，该怎么办？ 调用 compact_recover。它会根据 Crystal、近期会话以及进行中工作的登记信息重建上下文。通常调用一次工具就足够了。

如何编写能让 Agent 再次找到的经验？ 先写最关键的事实。 经验指南通过示例说明了具体方法。

编辑器支持矩阵

npx @cachly-dev/mcp-server@latest autopilot 会检测并配置以下编辑器。 手动配置片段见手动设置。

各场景使用的登录方式：

手动设置

{
  "mcpServers": {
    "cachly": {
      "command": "npx",
      "args": ["-y", "@cachly-dev/mcp-server@latest"]
    }
  }
}

{
  "mcpServers": {
    "cachly": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cachly-dev/mcp-server@latest"]
    }
  }
}

{
  "context_servers": {
    "cachly": {
      "command": {
        "path": "npx",
        "args": ["-y", "@cachly-dev/mcp-server@latest"]
      }
    }
  }
}

嵌入会将文本转换为向量，以便按含义进行搜索。默认情况下，登录后，cachly 会立即在其位于欧盟的服务器上计算嵌入。只有在你自行指定第三方提供商时，文本才会发送给该提供商：

运行 npx @cachly-dev/mcp-server@latest health，查看当前使用的提供商。

连接到你自己的后端。 每个安装都可以连接到私有后端，而不是连接到 api.cachly.dev：

# One command: run the setup against your self-hosted backend
npx @cachly-dev/mcp-server@latest autopilot --api-url https://cachly.mycorp.internal

# Or without prompts
npx @cachly-dev/mcp-server@latest autosetup \
  --instance-id <uuid> --api-key <cky_live_...> \
  --api-url https://cachly.mycorp.internal

只有在 CACHLY_API_URL 与默认云端地址不同时，autosetup 才会将其写入编辑器配置。默认安装的配置保持简洁，自托管安装则会在每次启动编辑器时继续连接到你的后端。

定价

当前价格和限额请见 cachly.dev/pricing。

免费套餐无需信用卡。

环境变量

生态系统与文档

VS Code 扩展会在编辑器中显示同一个 Brain：

• cachly.dev：仪表板和注册
• 文档
• MCP 文档
• 发行说明
• GitHub Issues：错误和功能请求

一次解决，从此你的 AI 就会记住。

npx @cachly-dev/mcp-server@latest autopilot