GBrain Agent 安装与运行协议全解为现有 AI Agent 装配 Keyless 持久记忆大脑【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain本篇技术指南以开源仓库 GBrain 根目录的 AGENTS.md 为核心协议骨架系统讲解 AI AgentClaude Code、Codex、Cursor、OpenClaw、Hermes、Aider、Continue 等如何为宿主 Agent 安装并运行 GBrain 记忆大脑包括 5 分钟零配置安装流程、必须停下向用户确认的搜索模式成本决策、五份文档的阅读顺序、remote 信任边界、以及从调试排障到发货前检查的常见任务速查。读完本文你将掌握一套可直接执行的「给现有 Agent 添加记忆」的完整操作协议并能看懂其背后的 CLI/MCP 双入口实现机制。AGENTS.md 是什么非 Claude Code 系 Agent 的安装与操作总入口GBrain 仓库用两份顶层文档服务两类 Agent 读者Claude Code会自动读取CLAUDE.md入口文件它承载的是总是加载的方向 分发器——架构总览、跨切面不变量、参考地图与内联发布规则按需再加载docs/architecture/KEY_FILES.md逐文件索引、docs/TESTING.md测试分层与 docs/architecture/thin-client.md远程 MCP 接缝。其他所有 AgentCodex、Cursor、OpenClaw、Aider、Continue或通过 URL 拉取文档的 LLM一律从AGENTS.md开始它是安装 操作协议的总入口本文即围绕它展开。默认协议给现有 Agent 添加记忆而非替换身份AGENTS.md 开篇就给出三条分叉路径Agent 必须先判断自己属于哪种场景场景走哪条路默认给现有 Agent 添加记忆保持其身份与无关指令不变无 key 起步自动捕获与付费增强均为 opt-in不需要启动访谈bootstrap interview也不需要私有仓库在Grok Bot 或 Muse内部遵循 docs/guides/grok-bot.md 或 docs/guides/muse.md使用隔离的 docs/guides/in-agent-setup.md 入口每次调用都用绝对记录的启动器launcher来源source只组织本地记忆不会隔离共享文件或凭据的 Agent没有原生 harness 证据不得把生成的技能标记为已激活已有托管 brain遵循 docs/guides/hosted-harness-access.md在宿主上配置把私有交接handoff装进目标 harness 内仅有 URL 或普通 OAuth token不构成管理权限用户明确要求创建新的个人 Agent遵循 BOOTSTRAP_FOR_AGENTS.md 完成引导再回到 AGENTS.md 执行运行协议这条默认路径设计是 GBrain 的关键产品决策记忆是附加在既有 Agent 身上的能力不改变身份、不索要密钥、不做访谈。这与skills/RESOLVER.md中的 Memory defaults 一节完全一致——Preserve the existing agents identity and instructions. Ordinary setup adds keyless memory; personal-agent bootstrap requires an explicit request。五分钟安装三步走并在第二步强制停下询问AGENTS.md 给出的安装流程极短但其中埋着一个不可跳过的确认点。第 1 步通过 Bun 安装规范路径curl -fsSL https://bun.sh/install | bash export PATH$HOME/.bun/bin:$PATH bun install -g github:garrytan/gbrainnpm 陷阱GBrain 不通过 npm registry 分发npm 上名为gbrain的包是无关项目。绝不能执行npm install -g gbrain或bun add -g gbrain注意缺失的github:前缀正是陷阱。唯一受支持的来源是github:garrytan/gbrain可固定为github:garrytan/gbrain#latest-stable或 git clone。若已误装无关 npm 包先npm uninstall -g gbrain/bun remove -g gbrain卸载gbrain doctor也能检测到这种误装。故障恢复如果bun install -g中途中止或gbrain doctor报告schema_version: 0Bun 偶尔会在全局安装时阻止顶层 postinstall 钩子导致 schema 迁移没有自动执行CLI 会打印指向 issue #218 的恢复提示。执行gbrain apply-migrations --yes恢复仍不行则回退到确定性安装git clone https://github.com/garrytan/gbrain.git ~/gbrain cd ~/gbrain bun install bun link第 2 步初始化 braingbrain initgbrain init默认使用PGLite通过 WASM 内嵌的 Postgres零配置、无需服务器。当用户有 1000 文件或多机同步需求时init 会建议改用 Postgres pgvector如 Supabase 托管。初始化后立刻运行gbrain doctor --json验证所有检查通过。第 3 步STOP必须把搜索模式成本矩阵转达给用户这是 AGENTS.md 中语气最重的一步gbrain init会自动应用一个默认搜索模式tokenmax除非子代理是 Haiku 级或未配置任何可做扩展的 API key并打印一张9 格成本矩阵模式 × 下游模型前面带有[AGENT]标记。Agent必须把矩阵转达给操作者并确认选择后才能继续——因为矩阵角落之间的成本差是25 倍静默接受默认值是错误默认值。同一横幅也会在既有用户执行gbrain post-upgrade时触发搜索模式自 v0.32.3 引入。矩阵原文同时存在于 CLAUDE.md「Search Mode」、src/commands/init-mode-picker.ts与INSTALL_FOR_AGENTS.mdStep 3.5 三处属同步维护的 verbatim 文本Per-query cost 10K queries/mo (typical single-user volume): Haiku 4.5 Sonnet 4.6 Opus 4.7 ($1/M) ($3/M) ($5/M) conservative $40/mo $120/mo $200/mo balanced $100/mo $300/mo $500/mo tokenmax $200/mo $600/mo $1,000/mo (scales linearly: ×10 for 100K/mo, ÷10 for 1K. 25x corner-to-corner spread. Natural diagonal pairings — cheap/cheap → frontier/frontier — span ~4x.)三种模式的语义由 CLAUDE.md 的模式表与 INSTALL_FOR_AGENTS.md Step 3.5 归纳模式tokenBudgetLLM 扩展searchLimit 默认适用场景conservative4000tight 4K关10Haiku 子代理、成本敏感、高容量循环balanced1200012K关25Sonnet 级甜点tokenmax推荐默认保持 v0.31.x 检索形态无预算开50Opus / frontier 模型若用户选择非默认模式执行gbrain config set search.mode mode若选tokenmax且想保留字面意义上的 v0.31.x 默认limit20 而非 50追加gbrain config set search.searchLimit 20最后用gbrain search modes验证选择。之所以必须停下确认是因为成本同时取决于模式与下游模型两个变量Agent 静默跑tokenmax会对没有预期的用户产生意外开销。完整流程的深度版本以上只是两步半摘要AGENTS.md 明确要求 Agent 通读INSTALL_FOR_AGENTS.md获取完整流程包括 API key 配置Voyage 为默认 embedding reranker 栈voyage:voyage-4 1024d voyage:rerank-2.5一个 key 覆盖两者OpenAI 为主流替代无 embedding provider 时关键词检索仍可用、init --prefer-postgres的五级阶梯选引擎env URL → Supabase 发现 → 本地 Postgres → docker 容器pgvector/pgvector:pg16→ PGLite 兜底、导入索引gbrain import/gbrain embed --stale/gbrain query、知识图谱回填gbrain extract links --source db、技能装载gbrain skillpack scaffold --all、可选身份定制soul-audit 技能生成 SOUL.md / USER.md / ACCESS_POLICY.md / HEARTBEAT.md、定时任务与验证。记忆运行协议Agent 操作记忆的四个铁律AGENTS.md 用一段话定义了记忆操作协议拆解为四条先回忆再回答回答任何问题前先检索相关已保存上下文recall。显式请求才保存用户明确要求记住的内容才保存并携带来源provenance对存储记录的纠正需与存储内容核对后再确认。自动捕获需 opt-in自动采集默认关闭开启是用户的显式选择。忘记≠物理删除forget从活跃记忆中移除事实但历史、源材料和私有备份可能仍在永不承诺物理擦除。验证变更要用真实的 GBrain 调用并区分本地测试与harness 中的新会话测试。这套协议的底层实现与记忆动词一一对应CLAUDE.md 指出src/core/operations.ts定义了 100 共享操作其中包含七个冻结的MEMORY_VERBS——recall/remember/entity/synthesize/forget/context_pack/delta全部盖protocol_version: 1章可单独通过gbrain serve --surface verbs对外服务。五份文档的阅读顺序分层加载的心智模型AGENTS.md 规定 Agent 按以下顺序建立知识./AGENTS.md本文档——安装 操作协议CLAUDE.md——方向 分发器架构、跨切面不变量、参考地图、内联发布规则并按需路由到docs/architecture/KEY_FILES.md改文件前先读该文件条目、docs/TESTING.md测试分层 隔离 lint E2E 生命周期、docs/architecture/thin-client.md远程 MCP 接缝docs/architecture/brains-and-sources.md——双轴心智模型brain 哪个数据库source 库内哪个仓库每条查询都沿两个轴路由写任何触及 brain ops 的代码前必读skills/conventions/brain-routing.md——面向 Agent 的决策表何时切 brain、何时切 source、跨 brain 联邦如何工作仅潜空间由 Agent 决策skills/RESOLVER.md——技能分发器任何任务前必读。双轴模型一图掌握brains-and-sources.md 用brain 是数据库、source 是库内命名内容仓库一句话概括BrainDB 轴一个 brain 就是一个数据库PGLite 文件、自托管 Postgres 或 Supabase拥有独立的pages/chunks/embeddings表、OAuth 面与生命周期/备份/访问控制。枚举方式host默认 brain配置于~/.gbrain/config.json与mounts经gbrain mounts add id注册的额外 brain。路由--brain id、GBRAIN_BRAIN_ID、.gbrain-mountdotfile兜底host。Source仓库轴brain 内命名的内容仓库每条pages记录都带source_idslug 按 source 唯一而非全局——同一 brain 中topics/ai可以同时存在于sourcewiki和sourcegstack且是两个不同页面。路由--source id、GBRAIN_SOURCE、.gbrain-sourcedotfile或按注册的local_path匹配。经验法则数据所有者变了就是 brain 边界所有者不变但主题/仓库变了就是 source 边界。选错轴会导致查询静默错路由——这正是该文档存在的意义。信任边界remotefalse 与 remotetrue 的 fail-closed 设计AGENTS.md 把信任边界列为critical一节这是 Agent 开发者必须理解的安全模型可信的本地 CLI 调用方OperationContext.remote false由 src/cli.ts 设置src/mcp/server.ts中gbrain call op路径的注释明确标注sets remotefalse in src/cli.ts不可信的 Agent 面对调用方remote true由 src/mcp/server.ts 设置——该文件第 256 行注释写得很清楚MCP stdio callers are remote/untrusted; dispatch defaults remotetrue第 291 行正是remote: true的赋值点。安全敏感操作如file_upload在remote true时收紧文件系统围栏未设置时默认走严格行为。正在编写或评审操作operation的开发者应查阅src/core/operations.ts的契约。CLAUDE.md 进一步把这条固化为跨切面不变量Trust is fail-closed——OperationContext.remote在类型上是必填的任何不严格等于false的值都按 remote/untrusted 处理不允许默认成 falsy。与信任边界并列的还有来源隔离所有读侧操作经sourceScopeOpts(ctx)路由优先级为联邦数组 标量 sourceId 无禁止手搓来源过滤以防跨源泄漏等不变量。常见任务速查从配置到排障AGENTS.md 用一整节给出 Agent 日常高频任务的命令级速查以下完整继承并补充说明配置docs/ENGINES.md引擎配置docs/guides/live-sync.md实时同步docs/mcp/DEPLOY.mdMCP 部署。导入聊天历史gbrain transcripts ingest导入下载的 ChatGPT / Claude 导出或 agent 会话日志gbrain connectors连接账户并按 opt-in 计划增量、实时同步新会话cookie/OAuth 凭据留在本机权限 0600。完整指南docs/guides/chat-connectors.md。调试与数据库不可达排障docs/GBRAIN_VERIFY.md、docs/guides/minions-fix.md、gbrain doctor --fix数据库不可达或任何输出中出现GBRAIN_DB_ACCESS reason标记先gbrain engine status --probe哪个引擎、URL 从哪来、可达性分类再gbrain db-repair诊断、gbrain db-repair --yes应用安全修复。三个命令都是engine-free——数据库宕机时依然可用。完整循环见 docs/ENGINES.md 的「Engine detection and access repair」。迁移 / 升级gbrain upgrade二进制自更新 schema 迁移 post-upgrade 提示docs/UPGRADING_DOWNSTREAM_AGENTS.md、skills/migrations/目录gbrain apply-migrations --yes仅手动应用 schema。评估检索变更捕获默认关闭。要对真实捕获查询做基准测试设GBRAIN_CONTRIBUTOR_MODE1然后gbrain eval export --since 7d base.ndjson与gbrain eval replay --against base.ndjson。公共基准LongMemEval、ground-truth 评分gbrain eval longmemeval dataset.jsonl在每个问题上跑隔离的内存 PGLite——绝不会打开你的~/.gbrain。完整指南docs/eval-bench.md。驱动 brain 达到目标健康分单命令循环gbrain doctor --remediation-plan --json # 预览将被修复的内容 gbrain doctor --remediate --yes --target-score 90 --max-usd 5 # 按依赖顺序执行计划每步之间重查分数超过成本上限即拒绝陈旧抽取使用 source-scoped 数据库页面含 DB-only 页面不需要先同步仓库。空 brain无实体页面或未配置 embedding key 时会命中max_reachable_score上限并列出缺失项后退出。注意synthesize / patterns / consolidate 三个 phase handler 是PROTECTED——只有可信本地调用方能提交MCP 不能。参考 docs/architecture/topologies.md。跟踪创始人 / 公司的时间轨迹当实体在## Factsfence 中有带类型的度量声明metric: mrr、value: 50000、unit: USD、period: monthly列时gbrain eval trajectory entity-slug # 时序历史 回归自动标记 gbrain founder scorecard entity-slug # 四信号 JSON 汇总MCP 操作find_trajectory暴露同样数据只读作用域、对 remote 调用方做可见性过滤。gbrain think在 temporal / knowledge_update 意图下自动使用该底层默认开think.trajectory_enabledfalse退出。非度量事件行meeting、job_change、location_change经facts.event_type走同一管道向find_trajectory传kind: event或all查询。回答「谁在等我」连接用户 Google 账户一次gbrain google setup两次用户交互[SHOW USER]块必须逐字转达然后gbrain waiting --json返回按序排列的等待者 承诺 证据引用 Gmail 深链。用gbrain loops done|drop|mute管理循环。数据过期时它会拒绝执行并点名要先运行的同步命令。指南docs/guides/google-connect.md配置 每个错误及修复、docs/guides/open-loops.md检测原理harness 协议在 skills/google-loops/SKILL.md。其他一切llms.txt 是完整文档地图llms-full.txt 是同一地图但内联了核心文档适合单次抓取灌入。技能分发RESOLVER.md 与 50 技能AGENTS.md 的阅读顺序中skills/RESOLVER.md 排在第五位且任何任务前必读。它本质是技能分发器每个技能的 frontmattertriggers:数组是权威路由信号harness 对入站消息做子串匹配RESOLVER.md 是同一路由的人类可读映射。两者冲突时frontmatter 胜出。高频触发示例任何 brain 读/写/查找/引用 →brain-opswhat do we know about / tell me about →querycapture this / save this thought →capturefact check →fact-checkthats wrong / I never said that →correction-pipeline。完整技能清单在 skills/manifest.json。发货前检查ci:local 与 /ship对 Contributor 而言AGENTS.md 规定的最省事路径是bun run ci:local——在 Docker 内跑完整 CI 门禁gitleaks、guards typecheck然后 4 分片并行单元 针对四个 pgvector 容器和事务模式 PgBouncer 的 E2E单元阶段保持DATABASE_URL不设并自动清理。快速迭代用bun run ci:local:diff跑 diff 感知子集。要求本机有 DockerDocker Desktop / OrbStack / Colima与gitleaksbrew install gitleaks。手动路径bun test加 CLAUDE.md 描述的 E2E 生命周期拉起测试 Postgres 容器 →bun run test:e2e→ 拆除。发货必须走/ship技能而非手工。完整发布 贡献流程CHANGELOG 语气、版本位置同步、PR 约定、社区 PR 波在 docs/RELEASING.md发货前必读。隐私、分叉与社区规矩隐私绝不把真人、真公司、真基金的名字提交进公开产物。GBrain 页面会引用真实联系人公开文档必须用通用占位符alice-example、acme-example、fund-a。此规则源自 CLAUDE.md 的 Privacy rule。分叉如果你是 fork发布前必须用自己的 URL 基座重新生成文档地图LLMS_REPO_BASEhttps://raw.githubusercontent.com/your-org/your-fork/main bun run build:llms这一步确保llms.txt与llms-full.txt指向你自己的仓库而非上游。小结AGENTS.md 的设计哲学可以概括为一句话GBrain 是装进任何 Agent 里的记忆层而不是一个要替换掉 Agent 身份的新人格。它通过默认给现有 Agent 加 keyless 记忆、需要时再升级的分叉路径、强制人工确认的搜索模式成本决策、fail-closed 的 remote 信任边界以及一份精确到命令的阅读顺序与任务速查表把安装、运行、维护一个持久记忆大脑这件复杂工程压缩成 Agent 可一步步照做的操作协议。理解这份协议就等于同时理解了 GBrain 的安装面、运行面与安全模型。【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
