GBrain Agent 安装与运行协议全解：为现有 AI Agent 装配 Keyless 持久记忆大脑

GBrain Agent 安装与运行协议全解：为现有 AI Agent 装配 Keyless 持久记忆大脑

【免费下载链接】gbrainGarry's Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain

本篇技术指南以开源仓库 GBrain 根目录的 AGENTS.md 为核心协议骨架，系统讲解 AI Agent（Claude 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 接缝）。
• 其他所有 Agent（Codex、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 agent's 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/gbrain

npm 陷阱：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: 0（Bun 偶尔会在全局安装时阻止顶层 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 步：初始化 brain

gbrain init

gbrain 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 归纳）：

模式	tokenBudget	LLM 扩展	searchLimit 默认	适用场景
conservative	4000（tight 4K）	关	10	Haiku 子代理、成本敏感、高容量循环
balanced	12000（12K）	关	25	Sonnet 级甜点
tokenmax（推荐默认，保持 v0.31.x 检索形态）	无预算	开	50	Opus / frontier 模型

若用户选择非默认模式，执行：

gbrain config set search.mode <mode>

若选tokenmax且想保留字面意义上的 v0.31.x 默认（limit=20 而非 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 用一段话定义了记忆操作协议，拆解为四条：

1. 先回忆再回答：回答任何问题前，先检索相关已保存上下文（recall）。
2. 显式请求才保存：用户明确要求记住的内容才保存，并携带来源（provenance）；对存储记录的纠正需与存储内容核对后再确认。
3. 自动捕获需 opt-in：自动采集默认关闭，开启是用户的显式选择。
4. 忘记≠物理删除：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 按以下顺序建立知识：

1. ./AGENTS.md（本文档）——安装 + 操作协议；
2. CLAUDE.md——方向 + 分发器：架构、跨切面不变量、参考地图、内联发布规则，并按需路由到docs/architecture/KEY_FILES.md（改文件前先读该文件条目）、docs/TESTING.md（测试分层 + 隔离 lint + E2E 生命周期）、docs/architecture/thin-client.md（远程 MCP 接缝）；
3. docs/architecture/brains-and-sources.md——双轴心智模型：brain = 哪个数据库，source = 库内哪个仓库；每条查询都沿两个轴路由；写任何触及 brain ops 的代码前必读；
4. skills/conventions/brain-routing.md——面向 Agent 的决策表：何时切 brain、何时切 source、跨 brain 联邦如何工作（仅潜空间，由 Agent 决策）；
5. skills/RESOLVER.md——技能分发器，任何任务前必读。

双轴模型：一图掌握

brains-and-sources.md 用"brain 是数据库、source 是库内命名内容仓库"一句话概括：

• Brain（DB 轴）：一个 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_id，slug 按 source 唯一而非全局——同一 brain 中topics/ai可以同时存在于source=wiki和source=gstack且是两个不同页面。路由：--source <id>、GBRAIN_SOURCE、.gbrain-sourcedotfile，或按注册的local_path匹配。

经验法则：数据所有者变了，就是 brain 边界；所有者不变但主题/仓库变了，就是 source 边界。选错轴会导致查询静默错路由——这正是该文档存在的意义。

信任边界：remote=false 与 remote=true 的 fail-closed 设计

AGENTS.md 把信任边界列为critical一节，这是 Agent 开发者必须理解的安全模型：

• 可信的本地 CLI 调用方：OperationContext.remote = false，由 src/cli.ts 设置（src/mcp/server.ts中gbrain call <op>路径的注释明确标注sets remote=false in src/cli.ts）；
• 不可信的 Agent 面对调用方：remote = true，由 src/mcp/server.ts 设置——该文件第 256 行注释写得很清楚："MCP stdio callers are remote/untrusted; dispatch defaults remote=true"，第 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.md：MCP 部署。

导入聊天历史

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_MODE=1，然后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_enabled=false退出）。非度量事件行（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-ops；"what do we know about" / "tell me about" →query；"capture this" / "save this thought" →capture；"fact check" →fact-check；"that's 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 感知子集。要求本机有 Docker（Docker Desktop / OrbStack / Colima）与gitleaks（brew 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_BASE=https://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 的安装面、运行面与安全模型。

【免费下载链接】gbrainGarry's Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain