🧠 gbrain：AI 智能知识库 — 架构·部署·维护

1. 智能知识库的概念

gbrain 的核心理念：脑 ≠ memory，两者分工明确：

脑-Agent 循环（Brain-Agent Loop）

智能知识库的体现

• 主动感知 — AI agent 在对话中检测到人名/公司名/项目名，自动调用 gbrain MCP 工具（search/get_page/query）查询，无需用户手动操作
• 语义理解 — 支持关键词搜索（最快）和语义搜索（需 embedding），理解查询意图而非简单匹配
• 知识图谱 — 通过 wikilink 和时间线提取，构建实体之间的关联网络
• 持续学习 — 新信息通过 gbrain put 即时写入，每日 1AM cron 自动同步 Trilium 笔记嵌入，知识保鲜
• 评分机制 — gbrain doctor 输出综合健康评分（Brain Score），量化知识库完备度
• 不阻塞对话 — gbrain 不是中间件，不自动注入 system prompt。AI 按需调用 MCP 工具查询，轻量无侵入

2. Hermes ↔ gbrain 架构关系

两者是 Agent + Knowledge Base 的分工协作关系，通过 MCP Server 原生集成：

集成模型

• MCP Server 集成 — gbrain 通过 gbrain serve 作为 Hermes 的 MCP 子进程运行，search/get_page/query 等工具注册到 Hermes 的工具列表中，AI 可直接调用
• AI 主动触发 — 对话中检测到人名/公司/项目等实体，AI 直接调用 gbrain MCP 工具查询，无需走 CLI 命令
• 无中间件 — gbrain 不拦截对话流量，不自动注入 system prompt。AI 在对话中主动检测实体后调用 MCP 工具查询
• 知识保鲜 — 新信息通过 gbrain put 即时写入。每日 1AM cron master 自动同步 Trilium 笔记并运行 gbrain dream 维护

分离优势

• 框架无关 — gbrain 作为独立知识库，可从任意框架调用（Hermes / Claude Code / Cursor / LangChain），MCP 协议标准
• 数据独立 — PGLite 数据库可 gbrain export 导出，不绑定 Hermes
• 性能独立 — 知识检索不影响对话响应速度（按需调用而非流式过滤）

3. 部署

部署形态

安装与初始化

# 前提：Bun 运行时（aarch64）
curl -fsSL https://github.com/oven-sh/bun/releases/latest/download/bun-linux-aarch64.zip -o /tmp/bun.zip
python3 -c "import zipfile; z=zipfile.ZipFile('/tmp/bun.zip'); z.extractall('/tmp/bun-extracted')"
chmod +x /tmp/bun-extracted/bun-linux-aarch64/bun
cp /tmp/bun-extracted/bun-linux-aarch64/bun /opt/data/home/.bun/bun/bun

# 初始化数据库（会清空数据，备份后再操作）
cd /opt/data/home/gbrain && /opt/data/home/.bun/bun/bun run src/cli.ts init

# 验证安装
gbrain doctor
gbrain stats

数据库状态

• 规模：~1240 pages / ~3500 chunks / 100% embedded ✅
• Embedding 维度：1024（V100 Qwen3-Embedding-0.6B）
• Slug 规范：people/、companies/、projects/、concepts/、meetings/
• 数据源：Trilium 共享笔记（每日 1AM 自动同步）+ 手动 gbrain put 写入

数据来源与同步

gbrain 的数据来源分两条路径：

同步管道脚本：/opt/data/scripts/cron-tasks/trilium-sync.py（6 并发，300s 超时）

4. 配置

主配置文件 — ~/.gbrain/config.json

{
  "engine": "pglite",
  "database_path": "/opt/data/home/.gbrain/brain.pglite"
}

Hermes MCP 配置（config.yaml）

⚠️ 注意：gbrain MCP 子进程在 Docker 容器内有 HOME 不一致问题（passwd 记录为 /opt/data，但 $HOME 实际指向 /opt/data/home）。
配置时必须做到：① 使用绝对路径 ② 不要用 2>&1 ③ 显式设置 HOME。否则 MCP 连接会因 JSON-RPC 解析失败而断开。

mcp_servers:
  gbrain:
    command: /opt/data/home/.bun/bin/bun
    args:
    - run
    - /opt/data/home/gbrain/src/cli.ts
    - serve
    env:
      HOME: /opt/data/home
      V100_API_KEY: ${V100_API_KEY}
      GBRAIN_EMBEDDING_MODEL: v100:embed
      GBRAIN_EMBEDDING_DIMENSIONS: '1024'

配置说明（踩坑记录）：

• 绝对路径 command — 不用 bash -c 包装，直接用 bun 绝对路径，避免 shell 注入问题和路径查找失败
• 绝对路径 args — src/cli.ts 用绝对路径，不依赖 cwd
• 不要用 2>&1 — gbrain 启动时 console.warn/console.error 输出到 stderr，如果重定向到 stdout 会污染 JSON-RPC 协议流，导致 MCP 客户端解析失败
• 显式设置 HOME — 因为 Docker passwd home=/opt/data 但实际 $HOME=/opt/data/home，gbrain 的 os.homedir() 依赖 HOME 环境变量才能找到 ~/.gbrain/config.json
• env 中 V100_API_KEY 等 — 用于 gbrain 内部 embedding 调用 V100 推理服务

关键配置项

5. 应用场景

6. 维护

Cron 维护任务（hermes-cron-master）

所有维护任务由 hermes-cron-master 统一调度，每日 凌晨 1AM 按顺序执行 4 个任务：

触发关系：

session-transcripts → trilium-sync → gbrain (dream) → sitemap
(会话→transcript)    (笔记→gbrain)   (提取+嵌入+链接)   (更新sitemap.xml)

脚本路径：/opt/data/scripts/hermes-cron-master.sh，任务脚本在 /opt/data/scripts/cron-tasks/。

维护命令速查

# ── 健康检查 ──
gbrain doctor              # 综合健康评分 + 各项检查
gbrain stats               # 数据库统计概览

# ── 知识写入 ──
gbrain put <slug>          # 创建/更新脑页（stdin 传入内容）
gbrain put <slug> < file.md

# ── 搜索 ──
gbrain search "关键词"     # 关键词搜索（最快，无需 embedding）
gbrain query "自然语言问题" # 语义搜索（需 embedding）
gbrain get <slug>          # 已知 slug 直接取

# ── Embedding 管理 ──
gbrain embed --stale       # 只处理缺失嵌入的 chunks（增量）
gbrain embed <slug>        # 单页嵌入测试

# ── 知识图谱 ──
gbrain extract links       # 提取 wikilinks
gbrain extract timeline    # 提取时间线条目
gbrain extract all         # 一次完成所有提取

# ── 全量维护 ──
gbrain dream               # 一键维护循环（cron 友好）

# ── 数据导出 ──
gbrain export --dir ./out/ # 导出为 markdown 文件
gbrain list -n 1000        # 列出所有脑页

健康评分解读

常见维护任务

• 补全 Embedding：gbrain embed --stale — 增量处理缺失的 chunks，零成本收益最大
• 修复 Schema：gbrain apply-migrations --yes — 升级数据库 schema
• 健康巡检：gbrain doctor — 观察 brain_score 趋势，低于 50 查明原因
• 释放锁：报 Another sync is in progress (lock gbrain-sync held) → 运行 gbrain doctor 释放
• 即时同步 Trilium：/opt/data/scripts/cron-tasks/trilium-sync.py — 编辑 Trilium 后立即同步到 gbrain

📅 最后更新: 2026-05-21 · gbrain v0.30.2 · PGLite · ~1240 pages · 💡 MCP 集成: search/get_page/query 对话中自动可用