人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载导读本文是 gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目中面向 Agent 与开发者的路由约定指南核心回答一个问题每一次读写操作应该落在哪个 brain数据库、哪个 source库内仓库上读完本文你将掌握--brain/--source/ 环境变量 / dotfile 四类路由信号的优先级、v0.41.13 起 7 层 Source 解析链的每一层行为与触发条件、跨 brain 的隐空间联邦查询模式以及跨 brain 写入时必须遵守的确认规则——并能在源码层面理解这些行为背后的实现。一、核心心智模型两条正交的轴gbrain 将知识组织拆成两个完全独立的维度任何混淆都会导致查询静默错路由silently misroute。原文档给出的一行总结是最简洁的表述Brain数据库轴决定操作的是哪个数据库。信号来源为--brain、GBRAIN_BRAIN_ID环境变量、.gbrain-mountdotfile。Source仓库轴决定操作的是数据库内的哪个内容仓库。信号来源为--source、GBRAIN_SOURCE环境变量、.gbrain-sourcedotfile。两条轴相互正交每次操作都必须各自选一个值任何组合host的任意 source、任意 mount 的任意 source都是合法目标。完整的拓扑心智模型单人多源、个人团队 brain、多团队 CEO 级形态维护在 docs/architecture/brains-and-sources.md原文档建议至少通读一遍后再处理实际路由问题。从源码看两条轴甚至实现了同构的解析模式。brain 轴由 src/core/brain-resolver.ts 的resolveBrainId()负责source 轴由 src/core/source-resolver.ts 的resolveSourceId()负责两者都遵循显式 flag 环境变量 dotfile 向上查找 注册路径最长前缀匹配 默认值 兜底的分层结构。如原文档所述两个解析器的 dotfile 读取都使用lstatSync而非statSyncisTrustedDotfile校验拒绝符号链接、他人所有、全局可写的 dotfile防止多用户主机上在共享父目录植入伪造路由文件source 轴对应 issue #418brain 轴为同款修复的镜像实现。一个快速判断规则来自 docs/architecture/brains-and-sources.md数据所有者变了 → 是 brain 边界所有者不变但主题/仓库变了 → 是 source 边界。例如把会议纪要写入团队 brain 是跨 brain 操作把个人笔记从wiki源挪到essays源只是跨 source 操作。二、默认行为ALWAYS信任解析器不要自作主张原文档对 Agent 的默认行为给出三条硬性要求先看 mounts如果还没看过用户的挂载列表先运行gbrain mounts list了解环境里有哪些 brain。信任解析器如果用户位于~/team-brains/media/目录下该目录的.gbrain-mount已经把 brain 钉死为media-team不要静默覆盖这个路由。显式传递解析结果每次调用工具时即使结果与默认一致也要显式传入解析出的 brain id让路由在日志里可见。裸命令gbrain query X会路由到默认 brain 的默认 source——在 90% 的情况下这就是正确答案。原文档强调没有充分理由就不要跨越这条边界。这一点与 plugin-variants/gbrain-daily/skills/conventions/brain-first.md 的查找链约定一脉相承默认先读 brain先查询、后询问只有解析器确实无法给出答案时才考虑跨 brain 或求助外部 API。三、何时切换 Brain原文档给出了明确的该切与不该切清单。应当切换 brain--brain id用户的问题明确关于其所属团队的特定内容如团队 X 决定了什么团队 X 的项目 Y 进度如何。关键在搜索之前就切换而不是在 host 搜索失败后再切换。用户要求摄入属于特定团队的数据团队会议的会议纪要、团队流水线的信件。数据所有者决定 brain。用户显式点名了团队/brain如查一下 media-team brain 里的……。不应切换 brain用户问的是一个可能来自任何地方的通用问题先在 host 开始如果 host 没有再按需跨查。你不确定该去哪留在 host把找到的内容呈现给用户让用户指出具体 brain。四、Source 解析链7 层优先级v0.41.13这是原文档信息密度最高的部分也是路由错误的头号来源。gbrain通过 src/core/source-resolver.ts 的resolveSourceId()解析当前生效的 source共 7 层优先级从高到低#层级信号来源1flag显式--source idCLI 参数gbrain extract/gbrain import上是--source-id id2envGBRAIN_SOURCE环境变量3dotfile当前工作目录或任意祖先目录中的.gbrain-source文件4local_pathlocal_path包含当前工作目录的已注册 source最长前缀优先5brain_defaultBrain 级sources.default配置项显式用户意图5.5sole_non_default第 1–5 层全部落空且恰好一个已注册 source 拥有local_path、不是default、且default源没有任何活动页面时自动路由到该 source6seed_default字面值default迁移 v16 之后必然存在4.1 各层实现细节源码级第 1 层flag显式参数最高优先。值得注意的一个特殊哨兵值--source __all__ALL_SOURCES会原样透传issue #1712它不是一个 source id因此跳过正则校验与assertSourceExists由sourceScopeOpts赋予跨越所有 source的语义。非法值不符合[a-z0-9-]{1,32}会直接抛出SourceTargetError——这是必须响亮拒绝的层级。第 2 层envGBRAIN_SOURCE环境变量同样支持__all__透传issue #2140。与第 1 层一样值非法时抛错而非静默回退。一个额外的守护记录在 docs/architecture/brains-and-sources.mdharness 启动的gbrain serveMCP stdio 通道会在启动时把格式良好的GBRAIN_SOURCE与sources表比对若指向非活动已归档源则直接退出并给出错误值与修复建议而不是提供一个零页面的作用域让所有健康检查保持绿色。CLI 环境变量层同样通过assertSourceExists位于 src/core/source-resolver.ts失败。第 3 层dotfilereadDotfileWalk()从当前目录逐级向上最多查找 50 层读取.gbrain-source的第一行内容。这是宽容回退层dotfile 内容非法旧式下划线 id、手写带空白等时静默落到下一层而不是抛错——因为 dotfile 是运维手编的宽容行为保留了解析器的既有语义codex P1-F 规范。信任校验symlink/他人所有/全局可写拒绝同样生效。第 4 层local_path查询sources表中local_path IS NOT NULL的所有行用最长前缀匹配决定谁包含当前工作目录如~/gstack与更深的~/gstack/plans同时注册时后者胜出。实现上两侧都做 realpath而非裸 resolve防止符号链接的 CWD 伪造前缀匹配且通过Promise.all并行解析所有路径的 realpath代价只由最慢的那个源决定而非所有源之和#4091-class 修复。#3880 还加入了活跃源优先于已归档源的分层归档更深的注册不得遮蔽活跃的父源若 CWD 只落在归档树内assertSourceExists仍会抛出。第 5 层brain_default读取sources.default配置通过gbrain sources default id设置。这也是宽容层配置值非法时静默落到下一层。源码注释明确这一层代表用户明确表达过意图因此优先级高于自动路由第 5.5 层。第 5.5 层sole_non_defaultv0.41.13 新增这是原文档重点强调的层级为单 source brain 设计——典型用户就是一个 Obsidian vault、一个笔记文件夹、一个项目。修复前从/tmp运行gbrain sync且 brain 只注册了studiovault时会静默路由到default随后每一次编辑都在createVersion处失败因为该 slug 在default里不存在。新层级自动路由到唯一且明显的答案。其实现pickSoleNonDefaultSource()src/core/source-resolver.ts的触发条件非常保守全部满足才会激活恰好一个非default源拥有local_path该源未被归档default源不持有任何活动页面空性守护 #3070非空的default会抑制该翻转——如果default已被实际使用自动路由会把每次裸put/capture/sync劫持到唯一的旁路源因此回退到seed_default同时向 stderr 输出一行说明双方身份的提示。触发时会打印一次性 stderr 提示每条 CLI 调用一次可通过GBRAIN_NO_SOLE_NON_DEFAULT_NUDGE1同时抑制路由提示与空性守护提示CI/脚本管道场景。多源 brain注册了 2 非默认源依然落到seed_default必须显式--source。位置放在brain_default之后是刻意设计显式设置过sources.default的用户意图优先于自动路由。已归档源不参与计数。第 6 层seed_default字面值default。迁移 v16 后必然存在是安全的终止层。4.2 层级的验证工具v0.37.7.0gbrain sources current [--json]回显解析出的 source以及获胜的层级对应resolveSourceWithTier()与SOURCE_TIER_NAMES见 src/core/source-resolver.ts。执行任何破坏性操作前先运行它确认即将写入的目标。gbrain sources current --source X展示显式 flag本会解析出什么同时校验 X 存在于 sources 表。4.3 遵循该解析链的 CLI 命令gbrain sync、gbrain import、gbrain search、gbrain extract此处是--source-id id因为--source是 fs|db 数据源轴、gbrain graph-query--source限定遍历范围--include-foreign扩大到所有 source。4.4 信任边界v0.34.1.0解析器仅作用于 CLI 层。Operations.ts中的 handler 不读取.gbrain-source或GBRAIN_SOURCE。MCP/远程调用方走的是ctx.auth.sourceId/ctx.auth.allowedSources——远程调用者无法继承服务进程的 CLI source 上下文。这一点配合 docs/architecture/brains-and-sources.md 中远程调用者隔离一节的 fail-closed 清单source 隔离、facts 可见性、takes 持有者、写侧 slug 围栏构成完整的安全边界。另外src/core/source-resolver.ts 定义了插件通道专用的WRITE_SAFE_SOURCE_TIERS与sourceGuardBlocksWrite()gbrain serve --source-guard插件管理的 MCP 服务器以插件快照目录为 cwddotfile与local_path两个环境解析层会失真因此写入/管理操作只允许在绑定刻意或明确时执行flag / env / dotfile / brain_default / sole_non_default 放行local_path在插件 serve 下被判定为 cwd 推导意图而拦截seed_default仅在default是唯一源时放行。五、何时切换 Source应当切换 source--source id用户正在某个具体仓库中工作.gbrain-sourcedotfile 通常已自动处理——不要与它对抗。用户的问题限定在某个仓库范围内如我的 gstack 笔记里关于重试策略写了什么。你要写入的页面逻辑上属于某个仓库。数据来源决定 source。不应切换 source用户意图跨越多个仓库为跨源搜索保留federatedtrue的源默认开启的联邦读会把缓存类查询带回每个仓库的结果。隔离会丢失跨仓库匹配。一个值得补充的细节来自 src/core/source-resolver.ts 的localFederatedSourceIds()#2561/#2928未限定范围的本地 CLI 调用其联邦读作用域是[已解析源, ...其他 federatedtrue 的源]但显式层flag/env/dotfile和显式隔离源config.federated false如gbrain sources unfederate不参与扩张——用户点名了源就是限定场景而--no-federated只治理读混合、不改变写路由。六、跨 Brain 查询隐空间联邦Latent-Space Federation原文档明确v0.19 不做确定性跨 brain 联邦。没有 SQL fan-out没有统一排序——联邦是 Agent 的职责不是数据库的职责。当用户的问题可能横跨多个 brain 时遵循固定模式用显而易见的查询先查 host用gbrain mounts list检查相关 brain id若你认为另一个 brain 有答案显式对那个 brain 重查--brain id综合多个结果并以brain:source:slug形式引用让用户可溯源。绝不静默混合 brain——每个发现都必须能溯源到它所在的 brain。这与 docs/architecture/brains-and-sources.md 中对 CEO 级多团队用户的描述一致跨 brain 查询不是确定性的。Agent 看到 brain 列表并按需重查。这正是特性——它让调试保持理智、让访问控制保持干净。七、跨 Brain 写入比读取更严格写入比读取严格得多跨 brain 写入前必须先询问用户。原文档给出的归属判断关于团队工作的事实→ 团队的 brain而不是 host用户确认的、只有他们知道的关于某个人的事实→ host/个人 brain而不是团队 brain从公开数据发现的补全信息→ 通常放 host除非用户另有说明。如果你即将执行put_page --brain team-brain除非用户明确说过把这存到团队-X否则先与用户确认。写入的默认 brain 是用户的个人 brain。从源码层面看写入侧还有额外的默认写保护当一次未限定范围的写解析到了seed_default层而 brain 的实际内容非默认源占据了大多数页面时CLI 会通过formatDefaultWriteRefusal()src/core/source-resolver.ts拒绝该写入跨源重复 slug 的根因保护并给出三条出路--source id路由到真实源、--source default故意写入default、或GBRAIN_ALLOW_DEFAULT_WRITE1用于脚本管道。MCP stdio 等无法拒绝的通道则降级为formatDefaultWriteWarning()的单行警告。八、带 Brain 上下文的引用格式标准引用格式保持不变[Source: ...]但当页面来自挂载的 brain 时追加 brain 前缀以便人工溯源单 brain 查询[Source: Meeting, 2026-04-10]不变跨 brain 综合[Source: media-team:meetings/2026-04-10]或[Source: policy-team:research/retry-budgets]。这延续了 v0.18.0 的 source 感知引用[source-id:slug]在相关场景下扩展出 brain 前缀。详细引用格式规范见 plugin-variants/gbrain-daily/skills/conventions/quality.md。九、决策表可直接套用原文档给出的速查决策表是 Agent 处理路由问题时最实用的参考场景BrainSource用户 cd 进团队 brain 的 checkout 后问一个通用问题dotfile 解析出的团队 braindotfile 解析出的 source用户问团队 X 决定了什么显式team-x解析器默认用户问我们所有团队在做什么跨 mounts 扇出Agent 驱动解析器默认用户说把这个加进我的 gstack 笔记hostgstack用户说保存这份团队 X 的会议纪要team-x有歧义则确认团队的 meetings source用户说给我写一篇随笔host个人essays无法归类留在 host询问用户解析器默认十、反模式Anti-patterns原文档明确禁止的四类行为本质都是路由不可见 / 归属错误 / 溯源断裂静默跳 brain 去找答案而用户显然指的是 host——这是审计痕迹上的漏洞。把显然团队所有的数据写进 host团队的方案出现在你的个人 brain 里是糟糕的意外。单次查询做跨 brain 联邦却不带指明来源 brain 的引用——用户无法把答案追回源头。无视.gbrain-mount/.gbrain-sourcedotfile——它们是承重墙般的上下文用户搭好它们是有原因的。十一、延伸阅读docs/architecture/brains-and-sources.md —— 完整心智模型含单人多源、个人团队 brain、CEO 级多团队三种拓扑图以及用一页记住解析优先级的对照表plugin-variants/gbrain-daily/skills/conventions/brain-first.md —— 先读 brain 再提问的查找约定plugin-variants/gbrain-daily/skills/conventions/quality.md —— 引用格式规范本文在跨 brain 场景下的扩展src/core/source-resolver.ts —— 7 层 source 解析链的全部实现包括resolveSourceWithTier()、空性守护、默认写保护与 source-guard 写策略src/core/brain-resolver.ts —— brain 轴 6 层解析实现与.gbrain-mountdotfile 信任校验src/commands/sources.ts ——gbrain sources系列命令current、list、add、default等的入口。赞分享人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载相关推荐gbrain Brain/Source 双轴路由完全指南数据库与仓库的解析链、切换时机与跨脑联邦gbrain Brain/Source 双轴路由完全指南数据库与仓库的解析链、切换时机与跨脑联邦 本指南面向所有通过 CLI 或 MCP 工具读写 gbrai人工智能RAGAgent 记忆MCP 服务知识管理gbrain Brain-First 查找约定Agent 在查询外部 API 之前必须优先检索知识图谱的完整实践指南gbrain Brain First 查找约定Agent 在查询外部 API 之前必须优先检索知识图谱的完整实践指南 Convention: 在进行任何实体/人工智能RAGAgent 记忆MCP 服务知识管理Restyle Your Carbon Trigger Browser Extension碳足迹浏览器扩展的 CSS 视觉重构实战指南Restyle Your Carbon Trigger Browser Extension碳足迹浏览器扩展的 CSS 视觉重构实战指南 导读 本指南基于 We人工智能RAGAgent 记忆MCP 服务知识管理上一篇开源项目 torrent-stream 常见问题解决方案下一篇Lobe Icons CDN使用指南无需安装一键引入AI品牌图标库创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
