持久记忆客户端 BrethofAI/brethof-brain-client

brethof-brain 客户端

brethof-brain 的轻量客户端 —— 为你的 AI 智能体提供持久记忆。它让智能体跨会话拥有可搜索的持久记忆：记住过去的决策、对话和项目上下文，你不必每次都重新解释一遍。

完整支持：Claude Code、Codex、Qwen Code、OpenClaw、Hermes Agent、DeepSeek Harness (dsh)、Cline、OpenCode（1.x 和 2.0）、Kilo Code、GitHub Copilot CLI、Pi、CodeBuddy Code、Devin CLI、Kiro CLI、Gemini CLI、Google Antigravity CLI、Amp、Qoder CLI、goose 和 MiniMax Code —— 下表标明哪些在 Windows 上也验证过 —— 「支持」指完整的环境回路（会话简报、每次提示词召回、自动归档），由我们的测试装置针对真实平台验证。任何兼容 MCP 的客户端还可以按需使用记忆工具 —— 那只是工具箱，不是环境回路。每个受支持的平台都会在全新虚拟机上针对其最新版本重新验证，结果由服务端判定 —— 版本升级导致集成失效，由我们发现，而不是你。

工作原理

客户端刻意做得极小。所有实际工作 —— 存储、嵌入、检索增强召回 —— 都在 brethof-brain 服务上完成。客户端只做两件事：

1. 通过 HTTPS 把智能体的钩子事件转发给服务，再把服务返回的记忆粘贴回来；
2. 接好 MCP 端点，让记忆工具可按需使用 —— 搜索（search_brain、search_history、get_record），以及四个写入入口：save_project / save_general（把一条事实写入项目历史；由服务的策展器决定它是否成为记录 —— 记录不能手工写入）、save_note（你这次会话的交接）、save_playbook（一套流程）、save_rule（一条长期约定），外加 add_project，附一行用途说明。

它没有第三方依赖 —— 纯 Python 标准库，所以只要 Python 3.9+ 能跑，它就能跑。

支持的智能体

| 智能体 | 适配器 | 你能得到什么 |
| Claude Code | 内置 | 完整：注入会话记忆、每次提示词环境召回、每轮对话归档、记忆工具 |
| Claude Cowork | Claude Code 插件 | 仅记忆工具 —— 搜索、读取、写入记忆；Cowork 不运行插件钩子，所以没有自动简报或召回，Cowork 对话也不会归档。不在完整支持列表中 |
| DeepSeek Harness (dsh) | adapters/dsh/ | 完整：基于 dsh 类型化扩展点的原生 cordis 插件 —— 注入、环境召回、归档（npm：brethof-brain-dsh） |
| Qwen Code | adapters/qwen-code/ | 完整：钩子（注入 + 召回 + 归档）+ MCP 工具 |
| Codex（OpenAI） | adapters/codex/ | 完整支持：钩子（注入 + 召回）+ 通过 notify 归档 + MCP 工具。有一处需要手动操作：codex 要求你先信任新钩子一次 —— 运行 /hooks，信任 brethof-brain 的条目 |
| OpenClaw（gateway） | adapters/openclaw-gateway/ | 完整支持：原生插件 —— 注入、环境召回、归档（npm：brethof-brain-openclaw） |
| Hermes Agent（Nous Research） | adapters/hermes/ | 完整支持：一个 Hermes MemoryProvider —— 系统提示词里带简报，每轮做环境召回，每轮都归档；记忆工具走 Hermes 原生 MCP 客户端（hermes plugins install BrethofAI/brethof-brain-client/adapters/hermes）。已在 Linux 上验证，也在 Windows 上通过 Hermes 原生安装器验证 |
| Cline | adapters/cline/ | 完整支持：beforeModel 请求叠加（简报 + 环境召回）+ afterRun 归档（npm：brethof-brain-cline） |
| OpenCode | adapters/opencode/ | 完整支持：一个原生插件 —— 持久化简报 + 召回片段，session.idle 归档（npm：brethof-brain-opencode） |
| Kilo Code | adapters/opencode/ | 完整支持：同一个插件文件，放进 ~/.config/kilo/plugin/ —— 覆盖 Kilo 的命令行、VS Code 和 JetBrains |
| GitHub Copilot CLI | adapters/copilot/ | 完整支持：用户钩子（注入 + 召回 + 归档）。已在 Linux 和 Windows 上验证，包括用你自己的模型离线运行 |
| Pi | adapters/pi/（npm：brethof-brain-pi） | 完整支持：一个扩展 —— 系统提示词里带简报，每次提示词前召回，每次运行都归档。已在 Linux 和 Windows 上验证 |
| CodeBuddy Code（腾讯） | adapters/codebuddy/ | 完整支持：钩子（注入 + 召回 + 归档）。已在 Linux 和 Windows 上验证 |
| Devin CLI（Cognition） | adapters/devin/ | 完整支持：钩子（注入 + 召回），每轮由钩子归档。已在 Linux 和 Windows 上验证 |
| Kiro CLI（AWS） | adapters/kiro/ | 完整支持：一个带钩子的 brethof-brain 智能体，设为你的默认。已在 Linux 和 Windows 上验证（Windows 上需要 Microsoft 的 Visual C++ 运行时） |
| Gemini CLI（Google） | Gemini CLI 扩展（adapters/gemini-cli/） | 完整支持：钩子（注入 + 召回 + 归档）。已在 Linux 和 Windows 上验证 |
| Antigravity CLI（Google，agy） | adapters/antigravity/ | 完整支持：每次模型调用都带简报和召回，每轮都归档。已在 Linux 和 Windows 上验证 |
| Amp | adapters/amp/ | 完整支持：一个插件文件 —— 线程的第一条提示词带简报，每次提示词都召回，每轮都归档。已在 Linux 上验证 |
| Qoder CLI（阿里巴巴） | adapters/qoder/ | 完整支持：钩子（注入 + 召回），每轮由钩子归档。已在 Linux 和 Windows 上验证 |
| goose | adapters/goose/ | 完整支持：插件钩子把记忆写入 goose 每轮都会读取的文件；每轮对话都会归档。已在 Linux 和 Windows 上验证通过（Windows 上需要 Visual C++ 运行时和 Git Bash） |
| MiniMax Code | adapters/minimax/ | 完整支持：本地插件（注入 + 召回 + 归档）。已在 Linux 上验证通过 |
| OpenClaw（库） | adapters/openclaw/ | MemorySession 封装，适用于自身没有钩子系统的智能体 |

每个适配器都有自己的 README，里面写了安装步骤。上表的链接指向这些 README。能力描述措辞精确：只说明测试环境在真实平台上验证过的内容，不多说一句。

Claude Code（推荐）

插件自带这个客户端，接好钩子和记忆工具，并加上 /recall /curate /onboard 命令——不需要 pip install，只要 PATH 里有 Python 3.9+。

/plugin marketplace add BrethofAI/brethof-brain-client
/plugin install brethof-brain@brethof

然后把它连到你的记忆：运行插件的 connect.py（你的智能体可以帮你运行）——你自己屏幕上会弹出一个窗口，让你输入 API key；如果用的是托管记忆，还要输入它的口令。你的智能体看不到这些内容。钩子和记忆工具会在下次会话启动时加载。

有一个手动步骤，建议做： Claude Code 有自己的文件记忆，除非另有指示，否则「记住这个」会被写进那里。插件不会改动你的 Claude Code 文件，所以请你自己（或让你的智能体）把 plugin/README.md 里的记忆块加到 ~/.claude/CLAUDE.md。用 pip 安装的话，brethof-brain install-hooks 会替你写好这个块。

命令带命名空间：/brethof-brain:recall、/brethof-brain:curate、/brethof-brain:onboard。/curate 结束一个会话：把找到的内容归档，并留下交接说明。记忆本身的整理、合并和修复是服务端的工作——你不需要每周运行什么。

OpenClaw

原生网关插件：每轮把会话记忆和环境召回追加到系统上下文，每个结束的轮次都会归档。一次安装，一次配置开启（hooks.allowConversationAccess——OpenClaw 对非内置插件的对话内容做了限制）。

openclaw plugins install --force --accept-capabilities brethof-brain-openclaw

（OpenClaw 2026.8.2+ 会在安装时要求你接受插件声明的 allowConversationAccess 能力——归档需要读取对话，这就是产品本身——还要加 --force，因为包不在 ClawHub 审核范围内：审核的人就是你。）

见 adapters/openclaw-gateway/README.md。

Hermes Agent

brethof-brain 是 Hermes 的记忆服务商——Hermes 为记忆选择的就是这一类插件。Hermes 能跑的地方它都能跑：Linux、macOS，以及 Windows 上 Hermes 的两条路径（原生 PowerShell 安装器，或 WSL2）。两个先执行命令，再填你的密钥：

hermes plugins install BrethofAI/brethof-brain-client/adapters/hermes --no-enable
hermes config set memory.provider brethof-brain

~/.hermes/.env
BRETHOF_BRAIN_API_KEY=bmv2_...
BRETHOF_BRAIN_PROJECT=my-agent

重启 Hermes；hermes memory status 会显示 brethof-brain 已启用。想按需使用记忆工具，就把 Brain 的 MCP 服务器加到 ~/.hermes/config.yaml 的 mcp_servers 里。详见 adapters/hermes/README.md。

Qwen Code

Qwen Code 自带 Claude 风格的钩子，所以能完整对接整套约定——一个安装脚本就能配好钩子、MCP 和 ~/.qwen/QWEN.md。详见 adapters/qwen-code/README.md。

Codex

python3 adapters/codex/setup.py 会注册 MCP 服务器（bearer token 走环境变量，绝不写进文件），在 Codex 的 notify 通道上装好回合归档器，并预先配好 hooks.json，这样 Codex 在无头模式下触发钩子的那一刻，上下文注入就能生效。详见 adapters/codex/README.md。

Cline

这是挂在 Cline 的 beforeModel / afterRun 扩展点上的只读叠加层——会话简报和环境召回会随每次请求送入，不碰你已存的对话，每次跑完的回合都会归档。安装：cline plugin install npm:brethof-brain-cline（只写名字的话会去 Cline 官方注册表里找，而不是 npm）。详见 adapters/cline/README.md。

OpenCode 与 Kilo Code

一个原生插件同时覆盖两者：会话简报和每次提示词前的召回会作为持久化的合成消息片段追加进去，session.idle 负责归档回合。把插件文件放进 ~/.config/opencode/plugins/（OpenCode）或 ~/.config/kilo/plugin/（Kilo——命令行、VS Code 和 JetBrains 都一样）：从本仓库取 adapters/opencode/lib/index.js，或者从 npm 取——npm pack brethof-brain-opencode，然后拿 package/lib/index.js。详见 adapters/opencode/README.md。

Gemini CLI

按 Gemini CLI 扩展来安装——整套流程都走扩展自带的钩子（会话开始时出简报，每次提示词前召回，每个回合都归档）：

gemini extensions install https://github.com/BrethofAI/brethof-brain-client

然后跑一次 brethof-brain connect（见配置）。老办法 python3 adapters/gemini-cli/setup.py（钩子写进 ~/.gemini/settings.json）依然可用。

GitHub Copilot CLI

Copilot CLI 直接安装 Claude Code 插件：

copilot plugin install BrethofAI/brethof-brain-client:plugin

然后跑一次插件的 connect.py。已在 Linux 上这样验证过（2026-10-04）；Windows 上用 python3 adapters/copilot/setup.py，这个脚本两个平台都验证过，还能配你自己的模型离线运行。

Pi

pi install npm:brethof-brain-pi

一个扩展：简报进系统提示词，每次提示词前召回，每次运行都归档。详见 adapters/pi/README.md。

CodeBuddy Code

python3 adapters/codebuddy/setup.py

钩子写在 ~/.codebuddy/settings.json 里（Linux、macOS，以及装了 Git Bash 的 Windows）。CodeBuddy 也能用它自己的插件命令安装 Claude Code 插件，但这条路还没验证过（2026-10-04 的 4 次台架运行里有 3 次漏掉了逐提示词召回）——请用安装脚本。

其他编辑器和 MCP 客户端

任何兼容 MCP 的客户端都能按需调用记忆工具（搜索、保存、规则、项目），只需一段配置块——那是一个工具箱，不是上面说的常驻记忆回路。各编辑器的完整配置块和鉴权说明见：adapters/editors/README.md。

DeepSeek Harness（dsh）

一个原生 cordis 插件，挂在 dsh 自己的类型化扩展点上——会话注入、逐提示词常驻召回、逐轮归档，全部失败开放。用 dsh plugin --profile <name> add brethof-brain-dsh 安装（也可以从本仓库的检出目录安装），并记住一条 dsh 专属规则：API key 要放进 ~/.brethof-brain/config.json，因为 dsh 会按设计从钩子环境里抹掉 _API_KEY。完整说明见：adapters/dsh/README.md。

OpenClaw（库封装）

给完全没有钩子系统的智能体用：一个 MemorySession 封装——在你的模型循环外面套上 start() / build_context() / record()。见 adapters/openclaw/README.md。

什么会离开你的机器（请读这段）

客户端之所以源码可见，正是为了让你能自己核实——去读 brethof_brain_client/，只有几百行。

- 会话开始时和每条提示词，它会把你的项目名和（常驻召回时）当前提示词文本发给服务，再把返回的记忆注入进来。
- 每轮助手回复（Stop 钩子）时，它读取智能体转录文件的新增*行并发去归档为你的记忆——其中包括你的消息、助手的回复、它的思考块，以及单行工具调用标记（[tool_use: Bash]）。工具输出在客户端就被丢弃：助手读到的文件内容、它运行的命令输出，永远不会离开你的机器。本地偏移文件（~/.brethof-brain/state/）保证每一行只发一次。
- 每个请求都用你的 API key 鉴权，并且只发往你的端点——你自己的记忆容器。端点在哪儿取决于你在账户面板里选的形态：
- 本地（默认端点 http://127.0.0.1:8610）：记忆容器跑在你自己的机器上；对话归档在那里，我们从不存储。
- 托管：你的容器跑在我们的云上，地址是 https://memory.brethof.cloud/t/<your-tenant>，用只有你持有的口令加密——在配置里加上 unlock_passphrase，客户端会在会话开始时解锁，并在你离开时让它自行锁定（lock_after_minutes，5–60）。
除此之外不收集任何内容。客户端从不发送文件、环境变量，也不发送上文所述对话文本之外的任何东西。钩子连不上服务时会静默失败——你的会话永远不会被阻塞。静默有两个例外，都属于持续存在的状况，继续沉默会丢失历史：API key 被拒会在下次会话开始时显示一行提示；TLS 信任失败会向 stderr 打印一行（在全新的 Windows 机器上会出现，这类机器延迟加载根证书——在浏览器里打开一次端点，就能永久解决）。

获取你的记忆（两种形态）

你的记忆存放在容器里。容器运行在哪里，是你在账户面板里做的一次性选择：

在你自己的机器上（本地）。 面板会签发你的 hub key（只显示一次）——它写进容器的配置，你的记忆靠它连到思考服务。容器由你自己运行（安装指南：brethof.ai/guides），在安装过程中签发你的 memory key，就完成了——客户端的默认端点（http://127.0.0.1:8610）已经指向它。你的对话从不离开你的硬件；只有正在整理的内容会经过 hub。

在我们的云上（托管）。 面板会创建你的容器，用只有你持有的口令加密，并只显示一次你的端点（https://memory.brethof.cloud/t/<tenant>）和 memory key。把这三项都写进配置——endpoint、api_key、unlock_passphrase——客户端会在会话开始时解锁你的记忆；静默 lock_after_minutes（5–60）分钟后自动锁定。

作为库 / 命令行安装（备选方式）

用于非插件场景（写脚本、其他智能体），直接从仓库安装： bash
pip install git+https://github.com/BrethofAI/brethof-brain-client.git

or pin a release (tags follow the package version):

pip install git+https://github.com/BrethofAI/brethof-brain-client.git@v1.2.22

（没有 PyPI 包——客户端从源码安装，所以你拿到的正是这里能读到的代码。）

然后把它连到你的记忆——一条命令，你的智能体可以替你运行： bash brethof-brain connect

你屏幕上会打开一个窗口，要求输入 API key（托管记忆还要输入口令）；它会用你的记忆校验这些信息，并保存到 ~/.brethof-brain/config.json（只有你能读）。你的智能体永远看不到它们。本机上的记忆会被自动找到，其安装程序已经把 key 存在那里——无需输入。没有屏幕（SSH）？它改为在终端里询问。托管记忆也可以用 brethof-brain login 让这台机器登录（你在 brethof.ai/account/device 确认一个验证码）。

你的口令无法找回。 一旦忘记，你的托管记忆就再也打不开了——无论你还是我们。

旧方式仍然可用： bash brethof-brain setup --api-key bmv2_xxxxxxxx brethof-brain install-hooks # 在 Claude Code 中自动加载并归档记忆 brethof-brain mcp-command # 打印要运行的 claude mcp add … 命令行

重启 Claude Code（或打开新会话），记忆就生效了。用下面的命令检查一切是否正常： bash brethof-brain doctor brethof-brain status

配置

配置的解析顺序是：先读环境变量，再读 ~/.brethof-brain/config.json，最后用默认值。用命令行安装时，密钥就存在配置文件里——setup 在 Linux/macOS 上创建该文件时只允许所有者读取（0600）；在 Windows 上由你的用户配置档 ACL 保护。用插件安装时，密钥由 Claude Code 保管，不需要配置文件。
json
{
"endpoint": "http://127.0.0.1:8610",
"api_key": "bmv2_…", "unlock_passphrase": "only for the hosted shape — unlocks your memory", "lock_after_minutes": 15, "default_project": "global",
"projects": [
{ "path": "/home/me/work/acme", "key": "acme" },
{ "path": "/home/me/work/blog", "key": "blog" }
]
}

- 项目用来划分记忆。客户端按工作目录选项目：$BRETHOF_BRAIN_PROJECT 优先，否则取匹配最长的 path 前缀，再否则用 default_project。项目键须匹配 [a-z][a-z0-9_]{0,15}。
- 环境变量覆盖：BRETHOF_BRAIN_ENDPOINT、BRETHOF_BRAIN_API_KEY、BRETHOF_BRAIN_PROJECT（本次会话的项目）、BRETHOF_BRAIN_DEFAULT_PROJECT（兜底默认值）、BRETHOF_BRAIN_HOME（把 ~/.brethof-brain 挪到别处）。
- 企业代理开箱即用：客户端遵循标准的 HTTPS_PROXY / HTTP_PROXY 环境变量。

命令

| 命令 | 作用 |
| brethof-brain setup | 保存凭据，验证连通性 |
| brethof-brain install-hooks | 把钩子写入 ~/.claude/settings.json（幂等，写入前先备份） |
| brethof-brain uninstall-hooks | 移除这些钩子 |
| brethof-brain mcp-command | 打印记忆工具所需的 claude mcp add 命令行 |
| brethof-brain status | 显示你的套餐与用量 |
| brethof-brain doctor | 诊断配置、连通性与钩子接线 |

卸载 bash brethof-brain uninstall-hooks claude mcp remove brethof-brain
pip uninstall brethof-brain-client

许可证

源码可见，遵循 brethof-brain Client License（见 LICENSE）——可自由阅读、审计，并配合 brethof-brain 服务使用；不得再分发，也不得用来构建竞品服务。与 Anthropic 无关联；「Claude」和「Claude Code」是 Anthropic 的商标。