1. 从「搜到页面」到「写出答案」GBrain 要解决的真实问题你明天要和 Alice 开会打开某个知识工具输入「Alice 最近在做什么」它返回五个页面链接——你得自己点开、自己读、自己拼结论。工具找到了材料但活没干完。GBrain 想做的是直接输出一段带来源的答案Alice 在 Acme 做工程主管你们上次聊是 4 月 22 号她欠你一份安全审查你承诺了一个定价方案她还说要招 CISO。末尾还会补一句最近六周大脑里没有 Alice 和 Acme 的新记录她可能回过邮件或 Slack那些渠道大脑看不到。这就是 GBrain 作为 AI Agent 知识大脑的基本立场检索到页面不算完成任务阅读页面并写出答案才算。它不是一个笔记应用也不是搜索引擎套壳——在向量检索之外它把知识图谱、混合排序、内容合成与缺口分析焊在了一起。默认存储用 PGLite编译成 WASM 的 Postgres 17.5规模上来后切到 Postgres pgvector两套引擎在同一个 BrainEngine 接口下同步演进。这篇文章面向三类人正在给 Agent 搭长期记忆的工程师、想搞懂混合检索为什么比纯向量强的技术负责人、以及准备把个人知识库接进 Claude Code / Cline 这类工具的开发者。我会按存储层、组织模型、摄入管线、检索栈、合成层、信任边界、Agent 集成逐层拆每层都给可复制的目录结构、索引配置和验证命令最后用 TaoToken 统一 Key/API 通道跑通一次端到端知识问答。先说清楚一个前提GBrain 的知识以 Markdown 文件存在 git 仓库里数据库只是从 Markdown 同步进去的索引层。删除 git 里的文件等于 DB 里的软删除。这个设计决定了后面所有的取舍——你可以用任何编辑器浏览脑内容git 历史就是审计日志备份就是 git push。2. 存储层与组织模型PGLite 单连接锁与 Brain ⊥ Source 双轴路由2.1 两套引擎一份合约GBrain 的存储层由两个引擎实现支撑共享同一个 BrainEngine 接口。PGLite 引擎是默认项把 Postgres 编译成 WASM 嵌在 Bun 进程里跑gbrain init不加参数直接给你一个零配置本地脑不需要 Docker两秒钟可用50K 页以内性能稳定。但 PGLite 有个硬限制单连接。Postgres 在单连接模式下只有一个写入者所以src/core/pglite-lock.ts实现了一个基于文件系统 advisory lock 的互斥机制——mkdir 一个锁目录加心跳刷新配合 PID 活性检查和一个 600 秒的 steal grace。它不依赖 PID 文件PID 会被回收而是把 PID 检测和心跳刷新配对如果锁持有者的 PID 不存在了或者超过 grace 时间没刷新等待者才能 steal。Postgres 引擎通过 postgres.js 连接 Supabase 或自建 Postgres pgvector支持多连接池、事务模式 PgBouncer、连接恢复。1000 文件、多机器同步、团队共享走这条路。这里有个容易踩的坑JSONB 写入必须通过executeRaw或executeRawJsonb传原始对象不能用JSON.stringify转一道。因为 postgres.js 会对字符串做二次编码而 PGLite 不会触发这个 bug。只在 PGLite 上测试代码可能默默通过到 Postgres 上就炸。项目里有个scripts/check-jsonb-pattern.sh的 CI 守卫专门拦这个模式。2.2 Brain ⊥ Source 双轴GBrain 用两条互相垂直的轴切分知识空间。Brain脑是哪个数据库你的个人脑叫 host可以通过gbrain mounts add挂载其他脑。Source源是数据库里的哪个仓库一个脑可以放多个源——wiki、gstack、essays 等等。Slug 在 source 级别唯一topics/ai可以同时存在于sourcewiki和sourcegstack它们是不同的页面。两条轴都走同一个 6 层解析链命令行 flag → 环境变量 →.gbrain-mount/.gbrain-sourcedotfile → 路径最长前缀匹配 → 配置默认值 → 系统默认值。懂了一条轴的解析规则另一条完全一致。这个双轴设计解决了一个实际问题怎样让同一个 CLI 命令在~/brain/和~/team-brains/media-team/下自动路由到正确的数据库和源。答案就是 dotfile。你 cd 到团队脑的目录.gbrain-mount自动把脑切到 media-teamcd 到子目录.gbrain-source再精准到 research 源整个过程不需要 flag。一个可复制的目录结构长这样~/brain/ ├── .gbrain-mount # 内容: host ├── .gbrain-source # 内容: wiki ├── wiki/ │ ├── topics/ │ │ └── ai.md │ └── people/ │ └── alice.md ├── gstack/ │ ├── .gbrain-source # 内容: gstack │ └── plans/ │ └── q3-pricing.md └── .gbrain/ └── config.toml对应的config.toml关键片段[engine] type pglite path ~/.gbrain/host.db [search] mode balanced rerank true [sources] default wiki跨脑查询不走 SQL federation——Agent 自己看脑列表自己决定什么时候跨脑扇出自己合成结果。设计者的取舍很清楚SQL federation 在调试和访问控制上是噩梦让 Agent 来做路由决策更干净。3. 可复制配置MCP 搜索接口与 TaoToken 统一 Key 接入3.1 用 TaoToken 统一模型调用通道GBrain 的查询扩展、合成、重排序、缺口分析这些环节需要调 LLM。与其在多个供应商之间管理一堆 Key不如用 TaoToken 做统一通道——一个 Key 覆盖多家模型Base URL 固定切换模型只改 Model ID。先拿 Key打开 https://taotoken.net/api-keys 创建一个 API Key复制保存。然后在 GBrain 的配置里指定模型通道。GBrain 走 OpenAI 兼容协议所以配置项就是标准的 Base URL Key Model ID 三件套[llm] base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 model claude-sonnet-4-5如果你用 Claude Code 作为 Agent 前端接入方式是在项目根目录的.mcp.json里注册 GBrain 的 MCP 服务同时把模型通道指向 TaoToken{ mcpServers: { gbrain: { command: gbrain, args: [serve], env: { GBRAIN_LLM_BASE_URL: https://taotoken.net/api, GBRAIN_LLM_API_KEY: sk-你的TaoToken密钥, GBRAIN_LLM_MODEL: claude-sonnet-4-5 } } } }Cline 用户走 MCP 配置面板填的也是同样三件套Base URL 填https://taotoken.net/apiAPI Key 填 TaoToken 的 KeyModel ID 填你要用的模型。Codex 用户则在~/.codex/auth.json里配置{ openai: { base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥 } }三件套缺一不可。只填 Base URL 不填 Key 会 401只填 Key 不填 Model ID 会走默认模型导致行为不一致。我试过在 Cline 里漏填 Model ID结果重排序环节调了一个不存在的模型名报错信息是reading choices相关的解析失败——这个后面排障章节细说。3.2 MCP 搜索接口注册GBrain 通过 MCP 协议暴露 30 个工具支持 stdio 和 HTTP 两种传输。stdio 模式一行命令claude mcp add gbrain -- gbrain serve零服务器、零隧道、零 token。HTTP 模式支持 OAuth 2.1 bearer token 管理面板适用于远程部署。瘦客户端架构值得单拎出来gbrain init --mcp-only创建的安装没有任何本地脑内容只有一个指向远程gbrain serve --http的 OAuth 客户端。CLI 里的路由分支在connectEngine()之前先检测isThinClient(cfg)如果是瘦客户端就通过callRemoteTool走远程 MCP永远不打开空的本地 PGLite——这种情况在 v0.31.1 之前会静默返回「No results.」。3.3 索引配置检索栈的四层策略需要对应的索引。PGLite 和 Postgres 的索引配置略有差异PGLite 不支持CREATE INDEX CONCURRENTLY通过sqlFor.pglite分支处理。核心索引-- 向量索引 (HNSW) CREATE INDEX idx_pages_embedding ON pages USING hnsw (embedding vector_cosine_ops) WITH (m 16, ef_construction 64); -- 全文检索索引 CREATE INDEX idx_pages_fts ON pages USING gin (to_tsvector(english, content)); -- 图谱边索引 CREATE INDEX idx_links_source ON links (source_slug); CREATE INDEX idx_links_target ON links (target_slug);HNSW 的m16和ef_construction64是默认值50K 页以内够用。超过这个量级可以把ef_construction提到 128构建时间翻倍但召回率更稳。4. 验证请求跑通一次端到端知识问答4.1 初始化与摄入先建脑、写页面、同步gbrain init gbrain put_page --source wiki --slug people/alice --file ./alice.md gbrain sync --source wikiput_page写入时会触发自动链接系统用三个正则表达式从 Markdown 正文里提取实体引用——标准链接[name](path)、Obsidian wikilink[[path|name]]、以及类型化链接块引用。零 LLM token。提取出的边通过一次addLinksBatchSQL 写入使用jsonb_to_recordset做批量插入避免逐条 INSERT 的连接开销和参数上限问题。边类型推断attended、works_at、invested_in、founded、advises从上下文句子中提取同样不调用 LLM。一个 17K 页的脑全量图谱提取在几秒内完成。4.2 检索验证gbrain search Alice 最近在做什么 --mode balanced --limit 10balanced 模式默认开启重排序器ZeroEntropy zerank-2。一次 cross-encoder 重排能翻掉 60% 的 top-1 结果——意味着 hybrid RRF 图谱三层在局部最优但全局上看仍有很多排错的情况。zerank-2 读查询和候选文档的联合注意力把那些「语义相关但主题错误」的文档踢下去。延迟 150ms p50约 $0.025/M token对于下游还要跑 LLM 的 Agent loop 来说这部分延迟完全被后面的推理时间淹没。4.3 合成答案gbrain think Alice 最近在做什么gbrain think不是对检索结果做简单模板拼接。它在检索之后运行几件事证据标记evidence stamp给每个结果带上为什么被检索到的说明以及create_safety提示exists/probable/unknown轨迹分析trajectory在实体页面有结构化 metric claim 时拉出时序历史并自动标记回归缺口分析gap detection在答案末尾诚实地说脑里缺什么——哪个页面过期了、哪条断言没引用、哪两页互相矛盾。内容质量有一层 voice-gate。五个用户界面的输出都通过gateVoice()过滤器——用 Haiku 做裁判拒绝学术腔最多两次重生成兜底到手工模板。设计原则是GBrain 说话要像一个知道你的过去的聪明朋友不是一个临床评分系统。4.4 检索栈的叠加效应BrainBench 的评测数据值得单独看纯向量 RAG 的 P5 约 18%关了图谱的 hybrid向量关键词RRF也是约 18%但开启完整栈四层叠加后 P5 跳到 49.1%R5 达到 97.9%。31.4 个百分点的 P5 提升证明了向量相似不等于事实相关。在这四层之上还有两个附加信号。图信号在 post-fusion 阶段做三种微调邻接提升一个页面被 2 个其他 top-K 结果链接它对这个查询是本地枢纽、跨源提升被 2 个不同 source 的页面链接跨团队确认、会话降权同一会话产出 3 个结果时保留最高分、压低其余。三种信号都套了 floor-ratio gate弱页面不会因为「流行度」超过强页面。SQL 层还有一套基于 source 的排名权重精选内容originals/、concepts/权重高于批量内容chat/、daily/test/ 和 .raw/ 被硬排除。archive/ 不硬排除采用 0.5x 降权而非隐藏——历史内容有信号价值不能完全隐藏但也不该和当前内容同等对待。5. 本篇常见错排查401、local proxy failed 与 reading choices5.1 401 Unauthorized最常见的原因是 TaoToken Key 没填对或者 Base URL 和 Key 不匹配。检查三件套echo $GBRAIN_LLM_BASE_URL # 应为 https://taotoken.net/api echo $GBRAIN_LLM_API_KEY # 应为 sk- 开头 echo $GBRAIN_LLM_MODEL # 应为有效模型 ID如果 Key 是从别处复制的注意前后有没有空格。401 还有一种情况是 Key 被撤销或额度耗尽去 https://taotoken.net/console 看用量。5.2 local proxy failed这个报错通常出现在 MCP 客户端Cline、Claude Code连不上 GBrain 服务时。先确认gbrain serve进程在跑ps aux | grep gbrain gbrain serve --http --port 8787如果是 stdio 模式检查.mcp.json里的command路径是不是绝对路径。Cline 里如果 MCP 服务启动超时也会报类似的 proxy failed把超时时间从默认 30 秒调到 60 秒通常能解决。5.3 reading choices 解析失败这个报错来自 LLM 响应解析环节。原因通常是 Model ID 填错或者 Base URL 指向了一个不返回 OpenAI 兼容格式的端点。GBrain 的重排序和合成环节都期望标准的choices[0].message.content结构。检查curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的密钥 \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-5,messages:[{role:user,content:hi}]}如果这个 curl 返回正常说明通道没问题问题在 GBrain 配置。如果返回 404检查 Base URL 是不是漏了/v1——TaoToken 的 API 地址是https://taotoken.net/api具体路径以接入文档为准。5.4 OAuth 相关报错HTTP 模式下如果看到 OAuth 报错检查 scope 是否包含需要的权限read/write/admin。mcp_spend_log表做按日 UTC 对齐的付费 API 支出追踪checkBudget在调用前做预检。本地 CLI 用户跳过预算检查——没有 clientId 就走不掉计费路径。如果预算超了报错信息里会带budget exceeded。5.5 PGLite 锁冲突如果看到lock held by another process说明有另一个gbrain serve在跑。PGLite 单连接限制意味着大同步需要先停掉服务。检查锁目录ls -la ~/.gbrain/*.lock确认没有活跃进程后可以手动清理锁目录或者等 600 秒的 steal grace 自动释放。6. 把 GBrain 接进你的 Agent 工作流GBrain 的 Agent 集成层通过 MCP 协议暴露 30 个工具。OpenClaw 上下文引擎在 Agent 每轮对话的上下文组装阶段运行从当轮消息里提取实体候选纯规则零 LLM然后通过别名匹配或精确标题匹配把候选解析成脑内页面指针。这些指针附带source_id、匹配置信度、匹配 arm别名 0.9 / 标题 0.8 / slug 后缀 0.6注入到对话上下文。整个解析过程是确定性的、零 LLM 的保证 Agent 在每次对话开始时知道哪些脑内页面和当前话题相关。项目附带 43 个技能都是 Markdown 文件工具无关CLI 和插件上下文都能用。skills/RESOLVER.md做了两层分发主路由器列出功能领域每个领域声明自己负责的子技能。这个设计解决了大型 AGENTS.md 膨胀的问题——在一个真实 fork 上把 25KB 的路由文件压缩到 13KB48%而路由准确率在 Opus/Sonnet/Haiku 上反而提升了 13-17 个百分点。如果你要长期跑编码 Agent 或者多轮知识问答建议用 Coding Plan 把模型调用成本固定下来配合 TaoToken 的统一通道切换模型不用改代码。验证模型行为时可以直接在模型对话里对比不同 Model ID 的输出差异。接入文档里有完整的 MCP 配置示例和 OAuth 流程说明。最后给一个实用技巧GBrain 的gbrain eval export加gbrain eval replay能捕获真实查询并重放这个机制让检索变更可以被 A/B 测试而不是靠直觉判断。每次调整索引参数或重排序配置后跑一遍 replay看 P5 和 MRR 的变化比拍脑袋靠谱得多。
