GBrain Brain-Ops 技能深度解析：知识库 Ambient Context Layer 的读写循环与记忆协议实战

GBrain Brain-Ops 技能深度解析知识库 Ambient Context Layer 的读写循环与记忆协议实战【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain本指南以 gbrain 仓库中的brain-ops技能plugin/skills/brain-ops/SKILL.md为核心系统讲解 Agent 与知识库brain交互的全套纪律与操作协议从先查脑再查外部 API的 brain-first 查找链、READ→WRITE 回写循环、必选回链Iron Law到 v1 记忆动词协议remember/recall/entity/synthesize/forget 等七动词与跨源引用格式。读完本文你将掌握 gbrain 中 Agent 正确读写、引用、回链与增量维护知识库的完整实战方案以及这些规则在源码层MCP surface 过滤、auto-link 图边修复、sweep 维护的具体落地方式。技能定位Brain Operations 是什么brain-ops是 gbrain 插件技能体系中负责知识库运维的核心技能。从它的 frontmatter 可以完整还原其职责边界name: brain-ops version: 1.2.0 upstream: brain-opsfc834ee description: | Brain knowledge base operations. The core read/write cycle: brain-first lookup, read-enrich-write loop, source attribution, ambient enrichment, back-linking. Read this before any brain interaction. triggers: - any brain read/write/lookup/citation tools: - search - query - get_page - put_page - add_link - add_timeline_entry - get_backlinks - sync_brain mutating: true writes_pages: true writes_to: - people/ - companies/ - deals/ - concepts/ - meetings/关键信息触发条件极广任何一次 brain 的读取、写入、查找、引用都会触发本技能因此它是读我优先Read this before any brain interaction的前置技能写权限明确mutating: true、writes_pages: true允许写入people/、companies/、deals/、concepts/、meetings/五类页面目录与 skills/conventions/brain-first.md 中的实体页面目录约定一致工具面完整read 类search/query/get_page/get_backlinks、write 类put_page/add_link/add_timeline_entry与维护类sync_brain一应俱全。技能正文还立下了三条默认原则避免 Agent读了一个技能就擅自行动回复前先回忆相关上下文Recall relevant context before responding显式请求才保存且必须带出处provenance自动捕获默认关闭直到用户显式 opt-in仅阅读本技能不等于开启捕获、委派或付费增强chat-only 指令会在当轮抑制写入即使已开启 standing capture。核心契约brain-ops 保证什么技能头部定义了五个必须满足的硬性保证Contract这是 Agent 使用知识库的最低行为底线Brain-first 查找任何外部 API 调用之前必须先查 brain显式保存触发 READ→WRITE 循环显式保存请求与已 opt-in 的入站信号触发读写循环增强enrichment需要单独配置的授权每次出站响应都检查 brain回答前先看 brain 是否有相关上下文逐条出处标注每条写入的事实必须带内联[Source: ...]引用用户直接陈述是最高权威数据每次写入维护回链Iron Law。这些契约与 skills/conventions/brain-first.md5 步查找协议和 skills/conventions/quality.md引用与回链细则互相引用、共同构成完整的合规闭环。值得一提的细节是brain-ops自身之所以不需要声明brain_first: exempt正是因为技能体内已包含指向brain-first.md的规范 Convention 引用块合规检查gbrain doctor的skill_brain_first检查项会直接短路判 OK——同路径通过的还有signal-detector、idea-ingest、enrich等技能。Iron Law回链是强制的Every mention of a person or company with a brain page MUST create a back-link FROM that entitys page TO the page mentioning them. An unlinked mention is a broken brain.回链格式见 skills/conventions/quality.md- **YYYY-MM-DD** | Referenced in page title -- context权威顺序高→低用户直接陈述 编译后的真值compiled truth 时间线条目原始证据 外部来源。这条铁律与 Phase 2.5 的 auto-link 机制相互配合前者约束 Agent 手写回链后者在写入路径上自动抽取并修复图边。七大记忆动词MEMORY_VERBS v1 内存线协议从 gbrain ≥ 0.43 起MCP 上优先使用五个核心记忆动词完成读写循环另有context_pack与delta两个增强动词共七个全部冻结在protocol_version: 1完整规范见 docs/protocol/MEMORY_VERBS_v1.md动词方向说明remember(fact, provenance, ttl?)write保存单条持久事实provenance 必填自动去重duplicate与替代supersededrecall(query \| entity, budget_tokens)read按预算打包读回事实与页面摘要entity(name)read零 LLM 的实体卡片p99 100mssynthesize(question)read昂贵的跨页综合问答LLM 调用forget(id)write撤回活跃记忆历史、源材料与备份可保留context_pack(...)read会话边界用为一批常驻实体打包确定性上下文体delta(...)read心跳用自 T 以来发生了什么变化要点与实战细节何时用哪个当你已经拥有一条成形的 facts 时用remember而不是extract_factsput_page/add_link/add_timeline_entry仍是页面/图写入路径。若动词不在当前 surface 上回退到经典操作。remember 的关键参数provenance必填≤500 字符、原样存储为空返回provenance_required错误kind的枚举是冻结协议值——event | preference | commitment | belief | factidea不是其中之一visibility默认world所有连接该 brain 的 Agent 可读private仅本地 CLI 可读。entity 是 Phase 1 的第一选择一个已知的人/公司/项目 → 完整卡片描述、别名、开放线程、近期事件、图边、回链/事实计数零 LLM 调用、亚百毫秒近匹配返回 suggestions。解析优先级冻结alias 精确 slug 精确标题 slug 后缀。synthesize 是刻意定价的慢动词耗时数秒到数分钟、产生真实费用优先recall/entity做查找只在答案需要跨页综合证据时才用。无 LLM 配置时返回协议错误unavailable而绝不伪造答案综合失败且有检索结果时降级为extractive_fallback只引用已检索页面的抽取式摘要。forget 幂等按remember/recall.facts[].fact_id返回的不透明字符串 id 操作绝不接受页面 slug重复遗忘已过期的事实返回成功expired: false。从源码看--surface verbs只会精确暴露这七个动词广告列表与分发都是 fail-closed 过滤隐藏操作即使按名调用也返回unknown_tool——该 surface 集合定义在 src/mcp/surface.ts 中另有--surface starter约 27 个日常操作集STARTER_OPS与默认的--surface full单调性由测试钉死verbs ⊆ starter ⊆ full。Keyless Brains当抽取器缺席时当extract_facts返回skipped: extraction_unavailable无嵌入/抽取能力时Agent 自己就是抽取器从当轮对话中抽出事实逐条用remember写入并设置kind必须是上述五个冻结枚举值之一以及 envelope 的agent_action声明的可见性默认 private 需要显式钉住因为remember默认 world或者在实体页面上手写## Factsfence。若 envelope 是skipped: extraction_failed服务端抽取器报错同样邀请当轮手动remember回退——自动抽取仍对未来写入保持开启。Phase 1Brain-First 查找强制任何用外部 API 研究一个人、公司或主题之前必须按序执行gbrain entity namev0.43——一个已知的人/公司/项目 → 完整卡片这一步对已知实体替代了步骤 2–6近匹配返回建议gbrain search name——精确 token 查找已有页面廉价混合检索、无扩展gbrain query 自然语言问题——概念/全景类问题先走这里扩展可恢复同义表达search计数非零不是完整性的证明gbrain get slug——已知 slug 时读取完整页面检查回链谁引用了这个实体检查时间线该实体的近期事件。核心信念brain 几乎总是有东西。外部 API 用来补缺口而不是从零开始。⚠️语料统计警告反浅层 ls联邦来源常常同时存在多种目录约定——一层扁平历史目录 一层meetings/YYYY/MM/日期嵌套目录。非递归的ls dir/*.md只能看到其中一层会严重低估。真实案例对某来源meetings/的一次浅层ls数到 132 个文件就断言那是全部语料却漏掉了meetings/YYYY/MM/下嵌套的数千份转录稿。正确的统计姿势首选gbrain sources list显示每个来源的索引页面数gbrain query。gbrain 正确索引所有联邦来源信任索引而不是文件系统必须碰文件系统时find dir -name *.md | wc -l绝不使用ls *.md再用find dir -name *.md | sed -E s#(.*/)[^/]$#\1# | sort | uniq -c摸清目录布局记住问题几乎从不是gbrain 看不到来源而是浅层 FS glob 造成的错觉。相信低计数之前先用gbrain sources list验证。Phase 1.5分析型查询gbrain think当问题需要综合、时间锚定或分析性回答——不是找页面而是回答问题时使用gbrain think question——跨页面 takes 图的多跳综合时间性问题走轨迹分析其余走 LLM 综合并带引用与冲突/缺口分析的答案最适合acme-example 上次融资是什么时候、三月 ARR 是多少、Q1 以来有什么变化、alice-example 的联创是谁、在做什么、总结我们和 acme-example 的关系无时间线事实匹配时优雅回退到标准检索成本提醒每次提问都有 LLM 调用这是昂贵路径只是想要 slug 或快速上下文检查时用query。Phase 2授权捕获READ → WRITE对显式保存请求或处于用户 opt-in 捕获范围内且无 chat-only 限制的消息识别实体——提到的人、公司、交易加载 brain 页面——回复前先读既有页面获取上下文识别新信息——这条信号告诉了我们页面还不知道什么回写——用新信息 时间线条目 来源引用更新 brain 页面缺失则创建——如果值得记录带出处保存提供的信息增强enrichment只在单独授权时调用。用户直接陈述的标注格式[Source: User, YYYY-MM-DD]。没有捕获授权时只在当前对话内使用信息而不持久化显式记住不等于开启持续捕获。Phase 2.5结构化图更新auto-linkAuto-link 对账从页面中抽取实体引用并写入图links表附带推断的关系类型过期的链接文本中已不存在的引用会被移除。由谁执行取决于写入路径可信本地写入gbrain put、gbrain capture、gbrain call put_page内联执行 auto-link返回auto_links: { created, removed, errors }**MCP 调用方stdio 和 HTTP**返回auto_links: { skipped: remote, hint }与auto_timeline: { skipped: remote }正文 wikilinks 按文本保存。stdio 的gbrain serve会在维护 sweep 中异步对账图边启动时 10 分钟空闲 tickgbrain serve --http不自我 sweep——需要时用gbrain sweep --once通过 IPC 委托给活动的 serve或gbrain extract links --source db按需对账。需要立即生效的关系用add_link。不可信正文文本可能植入提升排名的边这正是内联路径仅限本地的原因——相关实现可参考 src/core/link-extraction.ts 与 src/commands/reconcile-links.ts推断的链接类型attended会议→人、works_at、invested_in、founded、advises、sourcefrontmatter、mentions默认关闭方式gbrain config set auto_link false默认开启带具体日期的时间线条目仍需显式gbrain timeline-add或通过gbrain extract timeline --source db批量。Phase 3每次出站响应READ → PULL → RESPOND回答任何关于人、公司、主题的问题之前查 brain——读取相关页面拉上下文——使用编译后的真值 近期时间线带上下文回答——brain 让每个回答更好。不要在有 brain 页面时凭通用知识回答。Phase 4可选增强Enrichment增强是额外的用户选择。被提及的实体、分享的链接、捕获 opt-in 本身都不授权外部研究、付费调用或委派。必须跟随明确的摄取/增强请求或用户存储的范围与支出策略。没有该授权时回忆既有上下文只保存用户授权保留的提供信息。委派仅在 harness 支持且已授权时使用后台 Agent报告观察到的结果不声称生成了例行程序。输出格式与跨源引用v0.18.0使用检索到的上下文作答并引用。只在回读确认后才确认授权写入若没有写入请求或 opt-in不要仅为生成一条记忆更新而持久化对话。当 brain 有多个来源wiki、gstack、yc-media 等时每条引用必须带来源 id[source-id:slug]例如You told me about the retry budget approach — see [wiki:topics/resilience] and [gstack:plans/retry-policy] for where this came from.规则键是sources.id不可变绝不是sources.name可变显示名单来源 brain 写[default:slug]或为向后兼容省略前缀search、query、get_page、list_pages返回的每个页面载荷都带source_id——引用时永远用它不要猜。规则一句话搜索结果source_id: gstackslug: plans/foo→ 引用写[gstack:plans/foo]。反模式清单Anti-Patterns未先查 brain 就回答关于人/公司的问题未查 brain 就使用外部 API写入事实不带内联[Source: ...]引用阻塞响应去做增强用低权威来源覆盖用户的直接陈述为非显著实体创建 brain 页面为同一实体创建重复页面——创建前永远先查gbrain entity name能抓到别名与近匹配再用名称变体跑query。工具总览与命令速查工具用途search廉价混合检索向量 关键词无扩展query混合检索 LLM 多查询扩展概念/全景问题get_page读取 brain 页面put_page创建/更新 brain 页面add_link实体间交叉引用add_timeline_entry记录事件get_backlinks检查谁引用了实体sync_brain将变更同步进索引写入后记得触发新页面才可搜索CLI 等价gbrain sync --no-pull整体而言brain-ops把读脑优先、写则带出处、写必回链、图边自动对账这套纪律固化成了 Agent 可执行的阶段化流程entity/search/query/get完成查找remember/put_page完成写入auto-link与sweep在源码层保证图的一致性相关实现散布于 src/core/ops/links.ts、src/core/sweep.ts、src/mcp/surface.ts。任何接入 gbrain 的 Agent 与子代理都应先读本技能与 skills/conventions/brain-first.md再开始任何与 brain 的交互。【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考