gbrain 环境记忆回写（Ambient Memory Writeback）完全指南：让 Agent 在对话中自主保存事实的写入侧协议

gbrain 环境记忆回写Ambient Memory Writeback完全指南让 Agent 在对话中自主保存事实的写入侧协议【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain环境记忆回写Ambient memory writeback是 gbrain 记忆系统的写入侧能力当大脑的运营者operator显式选择开启后Agent 会在日常对话中——无需用户额外下令——通过既有的MEMORY_VERBS协议面remember与extract_facts两个记忆动词把用户直接陈述的重要事实保存进大脑。它与 环境记忆召回Ambient Recall读取侧会话边界处上下文无问自达互为读写两面但不引入任何新协议动词。读完本文你将掌握该功能的三种运行模式、个人/团队大脑的受众判定与同意机制、三个激活表面MCP 指令、托管 harness 指令块、Claude Code Stop-hook 兜底通道的底层实现、瞬态事实的读取时过期语义以及完整的启用、验证与关闭操作流程。功能默认关闭任何情况下都不会自我启用。一句话启用方式对 Agent 说Turn on ambient memory writeback for my brain或remember things I tell you without being askedAgent 会执行以下两条命令完成开启gbrain config set memory.auto_writeback salient gbrain bootstrap harness --yes第一条命令写入回写模式配置第二条把写回契约安装到各 harness 的用户级指令文件中。谁会被询问以及谁永远不会被询问gbrain 严格区分个人大脑personal与公司/团队大脑shared/company并且只在个人大脑上主动提议开启环境写回——因为在共享大脑上捕获成员对 Agent 说的话是整个团队共有的隐私决策绝不能成为默认行为。核心规则如下声明优先Declaration winsbrain.audience取值为personal|shared是声明轴。你可以自己设置可以让company-brainify在 Phase-5 交接时盖上shared戳也可以在 bootstrap 面试中回答。任何声明都优先于启发式判断。启发式非常保守在没有声明的情况下只有最近 30 天内活跃过≥3 个不同的非自动化 MCP 客户端才被判定为共享证据。注意这里的粒度是表面广度而非人数——Claude Code Codex 一个手机客户端可能仍是同一个人。gbrain doctor的memory_writeback检查会显示解析出的受众及其理由如误判用gbrain config set brain.audience personal|shared一行修正。询问只发生一次在个人大脑上gbrain init和升级后横幅会通过[AGENT]转达一次性的披露与询问以配置键memory.auto_writeback_notice_shown作为哨兵标记用户拒绝即为永久拒绝。之后gbrain advisor只会保留一个安静的提醒——纯信息性永远不可--apply同意consent绝不能被自动化。其余场景一律静默shared/unknown 大脑、挂载的团队大脑、thin client、远程 MCP 调用者以及任何分类器失败的情况。在共享分类的大脑上显式开启仍然有效运营者主权但会打印一条警示成员的言语会被持久化进一个其他授权 Agent 可读取的存储。从源码看受众判定逻辑位于 src/core/facts/writeback-audience.ts它先读 DB 平面上的brain.audience声明文件镜像仅在宿主大脑场景下兜底挂载/选中的团队大脑绝不继承宿主声明无声明时才调用readClientOpUsage统计 30 天内的非自动化客户端阈值常量SHARED_CLIENT_THRESHOLD 3。失败方向是静默关闭配置读取失败返回unknown询问面保持静默启发式读取失败但 DB 可达则返回personal缺少多客户端基础设施本身即是个人大脑的特征。该模块注释明确声明本模块永不启用任何东西——分类只服务于 ask-vs-silence 决策。三种模式Modesmemory.auto_writeback配置键控制 Agent 被指示保存什么memory.auto_writebackAgent 被指示保存的内容off默认什么都不保存——无指令段、无兜底通道、无写入。salient推荐仅保存持久、值得注意的主张偏好、更正、决策、承诺、关系、项目状态变化。兜底通道保留中等以上显著度的事实。all保存用户每条直接的事实性陈述——仍排除操作性闲聊、助手生成内容、机密/凭证、以及引用的第三方材料。精确度依赖抽取器extractor的语义跳过规则两道过滤器中的第二道预期会出现更多低价值事实和更高的抽取开销。配置解析集中在 src/core/facts/writeback-config.ts其中WRITEBACK_MODES [off, salient, all]冻结枚举。值得注意的健壮性细节normalizeMode对未知字符串失败关闭为off并标记mode_valid: falsegbrain doctor会显式提示memory.auto_writeback值 is unrecognized (expected off|salient|all)。双平面配置与平面漂移Plane Drift两个平面同时携带该设置DB 平面权威gbrain config set memory.auto_writeback …会把配置双写进 DB 的config表。服务端在任何抽取之前都会重新检查 DB 平面见writeback_offsidecar所以陈旧的配置无法违背运营者意图进行抽取。文件平面镜像~/.gbrain/config.json中的memory槽位供无引擎的读取方使用——Stop-hook 子进程它绝不能打开引擎因为 PGLite 是单写者和 bootstrap-harness 渲染器。镜像永远不会自行启用任何东西文件镜像按机器全局生效而 DB 行按大脑隔离因此引擎支持的解析只认 DB——一个挂载或选中、其运营者从未开启的大脑无法继承另一大脑的设置。当两个平面不一致时一次失败的双写、一次重建的 DB、或在共享 Postgres 大脑的另外一台机器上执行config set即为平面漂移plane drift抽取门会保持已入账banked的回合而不做终结性跳过不会销毁任何数据gbrain doctor会警告并给出单行重新同步命令gbrain config set memory.auto_writeback mode而config set过程中 DB 写入失败本身会以非零码退出并说明运行时值未改变。选择挂载大脑--brain、GBRAIN_BRAIN_ID、.gbrain-mount只会写入挂载大脑的 DB 行——机器本地镜像只约束宿主的 Stop hook因此启用团队挂载永远不会把宿主自己的对话纳入写入。错误的 hook 入账无害——由目标 serve 自身的 DB 门决定。源码中的具体实现见 src/commands/config.tsMEMORY_DUAL_PLANE_LEAVES [auto_writeback, auto_writeback_transient_ttl]定义了双写叶子集合两个通道使用同一份叶子列表防止新键只被一个通道双写、另一个通道单删写入顺序为先文件后 DB——DB 失败时两平面短暂分歧且会明确告知由 doctor 呈现平面漂移。此外resolveWritebackConfigsrc/core/facts/writeback-config.ts维护了最后已知良好last-known-good包按引擎实例缓存的 mode ttl visibility 原子元组默认消费方指令通道在总读取失败时返回缓存的 LKG 包避免瞬态 DB 抖动中途静默丢掉环境契约而{ gate: true }的抽取门serve 收割 sweep绝不提供 LKG 启用包——运营者关闭操作必须在 DB 抖动期间也生效读取失败无条件为offread_error门调用方跳过且不加终结性 sidecar入账工作会在配置恢复一致后重试。三个激活表面Activation Surfaces1. MCPinstructions所有传输层启用后initialize 握手会在基础操作契约之后追加一段约 15 行的环境写回契约每次remember调用一条主张、主体是人物/公司/项目时携带entity、简洁的来源信息harness 会话 id 日期、持久事实不带ttl、瞬态事实带配置的 TTL、跳过列表、以及可见性规则。stdio启动时解析切换需重启——与mcp.strict_params同一姿态。HTTP 传输按请求解析无需重启配置抖动时由 LKG 包兜底。指令段仅在调用方确实能调用remember时才渲染——无写作用域的 OAuth token、围栏fence拒绝该动词的 slug 绑定客户端、以及裁剪后丢弃该动词的表面都只获得基础指令绝不指示分发会拒绝的调用extract_facts仅在传输层实际工具集可调用时才被命名。共享的指令构建器位于 src/core/facts/writeback-instructions.ts其中包含 11 条契约要点记忆候选定义、remember单主张调用与kind/entity约定、多事实回合的extract_facts或逐条remember策略、来源信息要求、持久事实省略ttl、瞬态事实携带ttl、跳过清单、禁止把自身推断当作用户事实、可见性规则、作用域约束、静默写入无例行已保存回执。2. 托管 harness 指令块Managed harness instruction blocksgbrain bootstrap harness --yes把同一份契约同一构建器各表面结构上不可能漂移安装为受管块位于用户级CLAUDE.mdClaude Code和$CODEX_HOME/AGENTS.mdCodex的!-- gbrain:ambient-writeback:begin/end --哨兵标记之间幂等重跑关断收敛写回关闭时重跑会移除该块--remove直接剥离。Codex 注意事项当$CODEX_HOME/AGENTS.override.md存在时Codex 会完全忽略AGENTS.md——此时 bootstrap 会大声失败该目标且 doctor 会警告而不是把死集成报为健康。块头部标注 serve 端点更改 mode/TTL/visibility 配置后需先重跑gbrain config set memory.auto_writeback mode再bootstrap harnessconfig set 会刷新无引擎姿态戳doctor 的漂移警告指向同一组合。块只在同一次运行的 MCP 注册确认之后才安装最终冒烟测试失败会剥离该次运行安装的块——没有块能活过回滚的注册。注册者模式--url指向非回环 serve从不安装指令块本地设置只代表本地大脑远端大脑的契约由其自身的 MCP 指令在它的运营者启用时承载。块拼接的底层实现在 src/core/bootstrap/instructions-block.tsscanMarkers是唯一的标记扫描拼接、移除、状态探测、doctor 漂移比对共用同一扫描避免不同表面手写扫描对损坏文件的分类不一致无标记则 EOF 追加新块恰好一对有序标记则替换内部其余任何情况重复、孤儿、乱序直接抛错——这些是必须人工处理的手工编辑。块体内部与标记等价的文本行会被前置空格中和防止正文摘录在下次拼接时自锁。3. Claude Code Stop-hook 兜底通道Backstop每轮助手回合结束后hook 将用户消息通过一个确定性、零 LLM的过滤器最短长度CJK 感知、确认/问候词表、斜杠命令、纯提问回合、引用/工具输出、超过 8KB 的批量粘贴随后进行秘密扫描并以内容寻址的.wb-语料文件入账同一回合 同名 免费去重即使无 key 大脑也成立再请求 serve异步抽取。hook 永不阻塞自身 2 秒截止期处于 Stop 的 10 秒上限内所有路径退出码为 0并为每种结果输出带类型的 heartbeat 原因。serve 不在文件等待维护扫描sweep。该通道引擎统一IPC 监听器以大脑的连接 URL 为 socket 键因此只要该大脑有gbrain serve在运行Postgres 大脑就按同样方式收割serve 之间的 heartbeat 为no_serve——入账文件无论如何都是持久工件。各 harness 的现实诚实的局限Harness实时契约兜底通道Claude CodeMCP 指令 受管用户级 CLAUDE.md 块Stop-hook 通道上文CodexMCP 指令 受管$CODEX_HOME/AGENTS.md块不存在逐回合 hook仅 SessionEnd3 秒硬杀。既有的 SessionEnd 捕获 → 语料 → 维护扫描抽取通道作为延迟兜底——整会话级、下一次扫描的延迟、受facts.extraction_enabled支配先于此功能存在。opencode / OpenClaw / 其他连接时提供 MCP 指令无接线——已立项跟进。工作区 bootstrap 的同回合写回契约gbrain bootstrap contract、AGENTS.md与上述两个表面是同一姿态的三种渲染MCP 段与 harness 块共享同一构建器工作区契约则是 bootstrap.md 中记录的始终开启约定。编辑其中任一表面时须保持它们彼此一致。TTL瞬态事实在读取时过期Agent 在瞬态事实当前健康状况、位置、出行、心情、近期日程上传递ttl: 3d可配置memory.auto_writeback_transient_ttl仅限时长简写最大365d持久事实不带 TTL。过期是精确时间且读取侧的活跃读取recall、实体卡片、热记忆注入、去重候选都会排除valid_until已过的事实——无需清理器不产生任何变更。行仍留在数据库中作为历史--asof与超旧视图仍可见过期后重新陈述的事实会以新行插入。兜底抽取的事实目前不带 TTL抽取器尚未对瞬时性分类——已立项跟进因此仅被兜底捕获的瞬态事实在遗忘前一直持久。关于过期行lapsed rows的说明valid_until是时间有效性且活跃读取遵循它因此已经携带过期行的大脑在迁移后的第一次读取时就会看到它们离开活跃集facts-health 计数相应变化。不删除、不修改任何数据doctor 的validity_lapsed_facts计数衡量这一变化。TTL 语法解析位于纯函数叶子模块 src/core/facts/ttl-parse.ts不依赖 AI gateway 的依赖链供无引擎 hook 子进程使用支持30d/12h/45m/90s简写及拼写全称30 days、12 hours、绝对 ISO 8601 日期/时间ISO-8601 DURATION 语法P30D是文档化的陷阱会被带类型地拒绝iso_duration错误码。瞬态 TTL 配置的边界谓词isValidTransientTtl要求正时长简写且不超过一年常量TRANSIENT_TTL_MAX_MS 365 天配置设置的拒绝路径与解析器的降级路径共用同一谓词逐字节一致。隐私与可见性永不保存的内容问候语、确认语、无事实的提问、助手自身的推断/诊断/推测、工具输出、引用的第三方材料、粘贴/导入的文本除非用户明确要求、原始转录——以及所有模式下的机密/凭证入账回合在触及磁盘前先做秘密扫描扫描器不可用 失败关闭跳过。world不是互联网事实可见性world意为本大脑上获授权的 Agent 可读——这是让 remember→recall 跨会话往返成立的默认值。当facts.default_visibility未设置时指令模板会指示 Agent 写world只有显式私密的大脑才获得 private 姿态并附带其权衡说明private 事实仅本地 CLI 可读因此远程 Agent 日后无法召回它们。显式的 private 设置绝不会被放宽——模板不会、兜底通道也不会后者解析facts.default_visibility的方式与extract_facts一贯的方式完全一致。兜底事实携带source: hook:writeback与会话的GBRAIN_SOURCE两条抽取路径都带提示期 IPC 请求直接携带入账文件名嵌入之.src-sourceId段因此即使 Stop 时 serve 不在扫描回退也会把回合归入同一来源——绝不会归入扫描自身的来源。跨多大脑的会话仍归因于配置中的那个大脑与既有捕获通道相同的局限。源码中的可见性语义有一个值得注意的未设置陷阱F5src/core/facts/writeback-config.ts 读取的是原始facts.default_visibility值而非resolveDefaultVisibility()——因为后者的失败关闭会把未设置解析为private这对读取正确、对写入指导却是错的默认安装下让模板指示 Agent 默认写 private会让环境事实对保存它们的远程 Agent 不可见远程召回仅限 world。因此未设置 →worldremember动词文档化的默认值往返成立仅显式非world值 →private姿态并呈现召回权衡。成本姿态指令路径零额外成本对话中的模型内联完成显著性过滤。兜底通道每入账回合一次抽取调用上限为每会话 30 次提示收割溢出降级到扫描的批处理——失去新鲜度但语料保留窗口内不丢任何内容未摄取且早于语料 GC 的 30 天保留期的文件会被删除因此无 key 大脑——或其 serve 与 sweep 一个月都没到访的大脑——最终会脱落未入账回合serve 重启会重置计数器。无 key 大脑完全跳过抽取带类型的keyless跳过仍可接受 Agent 撰写的remember写入注意无 key 去重是降级的degraded_dedup——近似重复措辞可能插入。全局抽取开关参见 spend-controls.md。诊断gbrain doctor→memory_writeback执行gbrain doctor后查看memory_writeback检查实现于 src/commands/doctor/checks/memory-writeback.ts它会报告解析出的模式mode_valid、TTLttl_valid、两种可见性姿态指令模板 vs 兜底通道大脑受众及理由audienceaudience_reasons直接来自 writeback-audience.ts 的启发式证据文本已安装的 harness 块收据 vs 活跃哨兵探测、override 文件检测、配置漂移警告——标记为 FAILED 的收据目标例如冒烟回滚剥离本身失败在bootstrap harness重跑或--remove收敛之前保持常驻警告有效性过期事实计数validity_lapsed_factsSQL 统计facts表中valid_until now() AND expired_at IS NULL的行数。写回关闭时该检查仍会探测遗留的指令块并警告——在bootstrap harness重跑收敛之前关闭开关是不完整的遗留块会继续指示每个新会话用remember保存——一个不受门控的写操作。它还报告 7 天计数器MCP 上的remember结果所有调用方——线路上无法区分环境保存与显式保存标签如实标注与 serve 侧收割回执中的持久化兜底结果。计数器是本地、追加式、容忍丢失的可观测性——永非真相来源。测试 test/ambient-writeback-wiring-pins.test.ts 验证了dispatchToolCall对remember的调用会在 usage sidecar 上盖上remember_statusinserted/duplicate/superseded/failed 四臂且 doctor 检查聚合它们并带诚实标签ambient and explicit saves are indistinguishable on the wire。启用 / 验证 / 禁用gbrain config set memory.auto_writeback salient gbrain config set memory.auto_writeback_transient_ttl 3d # 可选默认值 gbrain bootstrap harness --harness codex --yes grep -n gbrain:ambient-writeback ${CODEX_HOME:-$HOME/.codex}/AGENTS.md gbrain doctor | grep -A6 memory_writeback # 在 NEW 的 agent 会话中说I prefer dark mode in every editor. 然后 gbrain recall --grep dark mode gbrain sweep --once # 立即驱动 sweep 兜底抽取 # 关闭开关随时用另一次 bootstrap 运行收敛 harness 块 gbrain config set memory.auto_writeback off gbrain bootstrap harness --yes各步骤要点config set memory.auto_writeback salient双写 DB 平面权威与~/.gbrain/config.json镜像同时刷新文件镜像中的可见性姿态戳供无引擎渲染器读取。推荐先于任何 bootstrap 运行执行。config set memory.auto_writeback_transient_ttl 3d可选。仅接受正时长简写如3d/12h/45m上限 365 天无效值会降级回默认3d并由 doctor 标记ttl_valid: false。bootstrap harness --yes把写回契约安装为哨兵标记包裹的受管块。--harness codex指定目标幂等关闭时重跑会收敛移除。安装前提是同一次运行的 MCP 注册已确认失败冒烟测试会剥离已装块。grep验证块落盘确认gbrain:ambient-writeback标记存在于目标指令文件。doctor | grep memory_writeback核对解析模式、TTL 合法性、可见性姿态、受众与理由、块收据/探测/漂移三态、7 天计数器。对话验证在新会话中直接陈述事实I prefer dark mode in every editor.随后gbrain recall --grep dark mode验证 remember→recall 往返gbrain sweep --once立即驱动兜底通道的延迟抽取无需等待维护扫描。关闭先config set memory.auto_writeback off再bootstrap harness --yes收敛移除已安装的指令块否则遗留块仍会指示新会话保存——关闭不完整。--remove可单独剥离块。环境记忆回写是 gbrain 记忆闭环中无问自存的关键一环它与 环境记忆召回 一起让大脑在会话之间自然积累用户直接表达的事实而全程尊重大脑受众、隐私边界、成本上限与运营者同意——默认关闭、声明优先、失败关闭正是其设计的三条底线。【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考