为 Codex 接入 GBrain 记忆插件、远程 MCP 与 brain-first 协议实战指南【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrainGBrain 提供了一套为已有编码 Agent 增加显式记忆的完整方案——它保留你正在使用的 Codex 身份与配置不改动任何私有仓库通过 MCP 协议把带出处provenance、可修正correction、可跨 harness 访问的记忆层接到 Codex 上。本文基于 docs/mcp/CODEX.md 展开系统讲解两种接入路径原生 Codex 插件与免插件远程 MCP、gbrain connect一键接线、--source-guard源路由防护、表面surface机制、验证与排障方法并结合仓库源码说明其底层实现原理。读完本文你将能独立完成 Codex ↔ GBrain 的接线、验证与日常使用并理解为什么给编码 Agent 加记忆不等于换一个 Agent。本文是连接参考手册。如果你是第一次接触 GBrain推荐先通读端到端教程 给编码 Agent 添加记忆connect-coding-agent.md它同时覆盖本地从零开始与连接已有脑两条路径并解释了值得这么做的 brain-first 协议。如果你想要的是完整 Agent身份 记忆 日程 私有仓库作为持久载体而不是一次简单连接那是gbrain bootstrap的职责参见 bootstrap 指南。一、两条接入路径概览GBrain 为 Codex 提供两条互补的接入方式路径适用场景关键命令Codex 原生插件推荐在已有 Codex 环境中直接启用插件自带 MCP server 精选 brain-first 技能集安装即用codex plugin marketplace addcodex plugin add免插件远程 MCP记忆托管在其他机器hosted brain通过 HTTPS streamable-HTTP MCP 连接gbrain connect url --token ... --agent codex或手工codex mcp add两条路径都以记忆只读/写入为目标均不需要私有仓库也不创建新的个人 Agent 身份。若你的记忆已经托管在远端正确入口是 托管 harness 访问指南hosted-harness-access.md其中包含能跨新 shell 存活的私有交接private handoff与授权 profile 配置。二、路径一作为 Codex 插件安装推荐GBrain 以原生 Codex 插件形态发布——一个 MCP server 加一套精选的 brain-first 技能集只需要两条命令codex plugin marketplace add garrytan/gbraincodex-plugin # slim dist 发布分支 codex plugin add gbraingbrain2.1 ref 与 marketplace 的语义codex-plugin这个 ref 指向发布版插件产物dist 分支每次发版都会强制推进类似latest-stable。裸的garrytan/gbrain形式也能用但它会下载完整开发仓库并跟踪 master 最新提交——只建议在从源码安装时使用。刷新快照codex plugin marketplace upgrade。移除插件codex plugin remove gbraingbrain codex plugin marketplace remove gbrain2.2 人格变体Persona variants的现状gbrain-coding/gbrain-daily两个精选变体目前随 Claude Code marketplace 发布codex marketplace 有意保持单一完整插件直到 codex 对多条目 marketplace 的处理完成一轮观察验证dist 分支其实已经携带了变体树验证后只需两行 marketplace 编辑即可启用见仓库 TODOS.md 的后续事项。2.3 前置条件二进制与脑插件不能内置 gbrain 二进制需要先装一次并初始化一个脑bun install -g github:garrytan/gbrain#latest-stable # 注意npm 上名为 gbrain 的包与本项目无关切勿 npm install -g gbrain gbrain init # 默认零配置本地 PGLite 脑插件自带的setup技能会一步步引导这两步。边界行为很明确没有二进制插件的 MCP server 会在 stderr 直接退出并打印那条精确的安装命令没有脑server 退出并提示No brain configured. Run: gbrain init。当前仅支持 UnixmacOS/Linux。2.4 插件到底提供了什么插件的 MCP server 通过随包启动器.agents/gbrain-launcher运行gbrain serve --surface starter --source-guard启动器的二进制解析顺序为$GBRAIN_BIN→~/.bun/bin/gbrain→ PATH 上的gbrain。把受监管的安装位置排在 PATH 之前是为了防止 PATH 中更靠前的野生 gbrain遮蔽shadow正式安装。这里的两个参数含义分别是--surface starter暴露日常驱动表面——七个记忆动词recall/remember/entity/synthesize/forget/context_pack/delta 日常脑操作精选技能集通过gbrainCLI 驱动其余一切。--source-guard源路由防护详见下文 §5.2在存在多个来源且未绑定任何来源时对写与管理操作默认失败关闭。不改快照即可扩权在启动 Codex 的环境中设置GBRAIN_SURFACEfull新会话生效或走下面的 bootstrap lane。与 OpenClaw bundle 不同插件还顺带发布了宿主侧技能setup、migrate、smoke-test、gbrain-upgrade、schema 编写等——因为插件用户本身就是脑的宿主。2.5 插件 lane 下的路由规则插件 serve 是用户全局进程且以插件快照目录为工作目录因此按项目生效的.gbrain-source/.gbrain-mount点文件在这里不生效。取而代之的是用启动 Codex 的环境变量GBRAIN_SOURCEsource-id路由来源轴用GBRAIN_BRAIN_ID路由脑轴仅环境变量——脑轴没有 config 默认值。--source-guard的失败关闭语义当脑有多个来源可选且未绑定来源时写与管理操作会报出可操作的错误信息直到绑定来源为止用户全局的 stdio serve 从GBRAIN_SOURCE绑定来源而非 flag并且当该值指向一个缺失或已归档的来源时会在启动时直接退出唯一真实来源时无歧义、不受影响读操作始终放行。边界坑把.gbrain-source点文件放在$HOME会使其成为插件快照目录的祖先从而把插件 lane 的所有写入都绑定到它。来源钉source pin请放在项目目录不要放在$HOME。2.6 一个名字只能有一个 owner有三条 lane 都能提供名为gbrain的 MCP server本插件、手工codex mcp add下文 §3、以及gbrain bootstrap harness托管块。只保留其中一个gbrain bootstrap hooks在插件启用时会跳过自己的注册可用--mcp-even-if-plugin覆盖gbrain doctor会对真实的双重注册发出警告。要点插件被ENABLED是配置信号不是健康信号——如果它的 server 不工作要么修二进制要么移除插件。2.7 升级是两半codex plugin marketplace upgrade # 刷新插件快照技能 manifest # 以及二选一 gbrain-upgrade 技能 # 或 bun install -g github:garrytan/gbrain#latest-stable # 重新执行刷新启动器解析的二进制三、路径二免插件连接较新版本的 Codex CLIopenai/codex支持远程 streamable-HTTP MCP serverbearer token 从环境变量读取。在本文gbrain connect路径下token 保存在 shell 环境里而不是 Codex 的配置文件里。唯一的例外是gbrain bootstrap harness本地 Agent 框架盒子框架拉起的 codex 不会继承 shell profile所以该 lane 会把 token内联写入一个受管、权限 0600 的[mcp_servers.gbrain]配置块——这一行为在其同意块中明确声明可用gbrain bootstrap harness --remove移除。3.1 最快路径gbrain connect在任意安装了gbrain的地方执行先在脑宿主上铸造 tokengbrain auth create codex gbrain connect https://YOUR-DOMAIN.ngrok.app/mcp --token gbrain_xxx --agent codex这会打印一个可直接粘贴的配置块。或者直接接线并冒烟测试 tokengbrain connect https://YOUR-DOMAIN.ngrok.app/mcp --token gbrain_xxx --agent codex --install--install会替你执行codex mcp add然后真实调用一次脑让错误/过期 token 立即失败而不是等到 Agent 第一次请求时才静默报 401。因为 Codex 在运行时从环境变量读 token请把GBRAIN_REMOTE_TOKEN保留在 shell profile 的 export 中。从源码看src/commands/connect.tscodex lane 生成的命令形态是codex mcp add gbrain --url url --bearer-token-env-var GBRAIN_REMOTE_TOKEN其中GBRAIN_REMOTE_TOKEN是写死的环境变量名常量ENV_VAR与 opencode lane 的{env:GBRAIN_REMOTE_TOKEN}插值字面量共用同一出处保证打印内容与所有权指纹不会漂移。--install还会调用probeBrainIdentity对 MCP URL 发起一次真实的get_brain_identity探测默认超时DEFAULT_PROBE_TIMEOUT_MS成功才输出内置的LEARN_INSTRUCTION引导文本。另外注意--install在非交互 shell 下要求显式--yes避免在无确认的情况下注册携带凭据的 MCP server。3.2 手工配置export GBRAIN_REMOTE_TOKENgbrain_xxx codex mcp add gbrain --url https://YOUR-DOMAIN.ngrok.app/mcp \ --bearer-token-env-var GBRAIN_REMOTE_TOKENCodex 存的是环境变量的名字GBRAIN_REMOTE_TOKEN不是 token 本身它会在启动 MCP server 时读取该变量的值。把export行加进~/.zshrc/~/.bashrc保证每个会话都有这个变量。3.3 本地 stdio 方式如果脑和 Codex 在同一台机器上本地 stdio 同样可用codex mcp add gbrain -- gbrain serve --surface verbs--surface verbs暴露的正是七个记忆动词协议见 MEMORY_VERBS v1 协议去掉该 flag 则暴露完整操作目录。四、验证连接在 Codex 中直接让它使用脑Call get_brain_identity, then search my brain for [topic].get_brain_identity确认你连的是谁的脑list_skills展示它能做的所有事情。list_skills为空它由宿主的mcp.publish_skills门控——用gbrain config set mcp.publish_skills true开启。核心工具search、query、get_page、put_page、capture、think、find_experts不受影响、始终可用。写操作建议快速笔记优先capture自动 slug 去重需要完全控制写入时用put_page。为什么不同脑对默认值有差异参见 connect-coding-agent.md 的 A1 小节宿主机经 HTTP serve。LEARN_INSTRUCTIONsrc/commands/connect.ts 中定义还补充了第三步连接后调用list_brain_skillpack若脑携带 skillpack询问用户是否安装gbrain skillpack scaffold spec——这保证 Agent 不只在能连还在会用。五、移除与安全注意事项5.1 移除连接codex mcp remove gbrain5.2 安全要点Token 是长期、全权限的秘密。保持GBRAIN_REMOTE_TOKEN不进版本控制若宿主支持优先使用受限scopedtoken。--source-guard的启动期失败关闭。在 stdio laneassertStdioSourceBindablesrc/mcp/source-preflight.ts会检查一个格式合法但指向不存在或已归档来源的GBRAIN_SOURCE必须拒绝启动——否则每次读都会作用到一个零页面来源search/query 返回空数组每次写都会撞上facts_source_id_fkey外键而所有健康检查仍然绿灯。启动期大声失败而不是盲区静默。插件 lane 下的来源绑定走环境变量详见 §2.5.gbrain-source点文件只应放在项目目录。六、NotesPGLite 并发、环境变量与 Ambient Recall6.1 PGLite 脑是单进程的PGLite 是单写者的嵌入式 Postgres第一个运行中的gbrain serve插件的或某个 stdio 注册通过数据目录锁拥有脑的数据目录。第二个serve——比如同一台机器上第二个 harness 里又注册了一个 gbrain——或任何打开 DB 的 CLI 命令在该 serve 存活期间都会撞锁失败gbrain sync是唯一例外它委托给存活的 serve。多个进程需要同时访问时运行一个共享的gbrain serve --http让所有客户端都指向它即上面的远程路径或迁移到支持并发连接的 Postgres/Supabase 引擎。细节见 serve ↔ sync 并发模型serve-sync-concurrency.md。6.2 表面surface机制与 fail-closed 双层层叠--surface有三种取值单调包含由测试钉死verbs ⊆ starter ⊆ full表面暴露内容典型用途verbs恰好七个冻结记忆动词快速上手、协议一致性starter七个动词 日常脑操作切片 whoamicapturerequest_tools发现元操作 写入回执助手插件与 connect 的默认日常表面full默认全部操作保留既有高级工具从 src/mcp/surface.ts 的实现看STARTER_OPS是程序化组合的动词切片直接 spreadVERB_NAMES引擎升级为七个动词后自动跟随绝无手数日常切片来自BRAIN_TOOL_ALLOWLIST加上 agent lanesubmit_agent/get_agent_job/cancel_job、whoami、request_tools以及作为直接字面量加入的capture刻意不走 allowlist避免顺带给每个 minion 子代理授予新写工具。解析顺序为--surfaceflag 配置mcp_surfacefull可持久化gbrain config set mcp_surface verbs。fail-closed 是两层的ListTools只广告过滤后的集合dispatchToolCall收到同一个allowedOps集合——即使客户端猜到隐藏操作的名字直接调用也会返回unknown_tool。所以隐藏操作不可调用不是靠隐藏而是靠 dispatch 层的强制过滤。6.3 Ambient recallCodex 没有生命周期钩子走拉取路径Codex 不像某些 harness 那样提供生命周期钩子所以环境记忆ambient recall用拉取pull路径在专题线程开始、以及一次压缩compaction之后调用context_pack(entities, budget_tokens)预热常驻实体周期性唤醒时调用delta(session_id, budget_tokens)获取自上次唤醒以来的变化按 session 去重。两者都是zero-LLM、亚秒级、默认仅世界可见world-only位于--surface verbs之上。协议级细节如delta的 at-least-once keyset 游标(updated_at, slug)、context_pack的 8 实体上限与世界可见默认见 MEMORY_VERBS v1 协议放置时机的前沿讨论见 ambient recall 指南。七、进一步阅读与仓库线索端到端教程两条路径 brain-first 协议动机docs/tutorials/connect-coding-agent.md托管脑授权与私有交接docs/guides/hosted-harness-access.md完整 Agent身份 记忆 日程 私有仓库docs/guides/bootstrap.md七个记忆动词的冻结线协议与一致性认证gbrain protocol conformancedocs/protocol/MEMORY_VERBS_v1.md源码线索gbrain connect的实现与 codex 注册命令形态见 src/commands/connect.ts表面过滤与 fail-closed 分派见 src/mcp/surface.tsstdio 来源预检见 src/mcp/source-preflight.ts插件技能树与表面说明见 plugin/README.md。至此从两条命令装插件到一条gbrain connect --install完成接线与 token 冒烟测试再到理解 surface 单调性、--source-guard失败关闭与 PGLite 单写者边界你已经掌握了 GBrain ↔ Codex 连接的全部关键路径。【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考