gBrain 系统搭建与使用指南

2026-05-22 约 1209 字预计阅读 3 分钟

gBrain 是一个基于 SQLite + 向量嵌入的个人知识脑系统，自动汇聚多个 AI agent 的对话记录，让你随时搜索历史对话。

一、系统架构

日常对话 (零改动)
├── Hermes  → ~/.hermes/sessions/
├── Codex   → ~/.codex/sessions/
├── Claude Code → ~/.claude/projects/ (如安装)
└── Copilot → (需手动导出)
        │
        │ launchd 每周自动触发
        ▼

hermes-gbrain-bridge (导出器)
  发现各 agent 会话 → 过滤噪声 → 统一 Markdown
        │
        ▼

gBrain (知识脑)
  ~/.hermes/gbrain/brain.db
  ├── FTS5 全文索引
  └── Ollama 向量嵌入 (qwen3-embedding:4b)
        │
  ┌─────┼─────┐
  ▼     ▼     ▼
全文搜索 语义搜索 知识列表

二、安装位置

组件	路径
gBrain 核心	`~/.hermes/gbrain/`
hermes-gbrain-bridge	`~/.hermes/hermes-gbrain-bridge/`
自动化脚本	`~/.hermes/scripts/gbrain_update.py`
数据库	`~/.hermes/gbrain/brain.db`
运行日志	`~/.hermes/logs/gbrain.log` / `gbrain.error.log`
launchd plist	`~/Library/LaunchAgents/ai.hermes.gbrain.plist`

三、核心依赖

依赖	版本	用途
bun	1.3.11	gBrain 运行时
Ollama	0.20.7	本地向量嵌入
qwen3-embedding	4.7GB, 4096 维	嵌入模型（中英双语）

四、gBrain CLI 命令

基本命令

命令	说明
`gbrain init`	初始化 brain.db（仅首次）
`gbrain stats`	查看知识库统计
`gbrain list`	列出所有页面
`gbrain list --type concept`	按类型筛选

写入

命令	说明
`gbrain put <slug> < file.md`	创建/更新页面（自动向量化）
`gbrain ingest file.md [file2.md ...]`	导入 Markdown 文件（按 ## 分块）
`gbrain import ./dir/`	批量导入目录下所有 Markdown

检索

命令	说明
`gbrain get <slug>`	按 slug 获取页面
`gbrain search "关键词"`	全文搜索 (FTS5)
`gbrain query "问题"`	语义搜索（向量相似度）
`gbrain tags <slug>`	查看页面标签
`gbrain backlinks <slug>`	查看哪些页面链接到此页面

向量化

命令	说明
`gbrain embed <slug>`	为单个页面生成嵌入
`gbrain embed --all`	为所有页面生成嵌入

数据库

命令	说明
`gbrain stats`	页面数、链接数、标签数、嵌入数、DB 大小

五、自动化配置

launchd 任务

Label: ai.hermes.gbrain
执行时间: 每周日凌晨 3:00
导入范围: 最近 7 天的会话
管理命令:

        
# 查看状态
launchctl list | grep gbrain

# 卸载
launchctl unload ~/Library/LaunchAgents/ai.hermes.gbrain.plist

# 重新加载
launchctl load ~/Library/LaunchAgents/ai.hermes.gbrain.plist

# 手动触发一次
launchctl start ai.hermes.gbrain

自动化脚本

~/.hermes/scripts/gbrain_update.py

执行流程：

用 bridge 导出最近 N 天的各 agent 会话
导入到 gBrain
生成向量嵌入
输出统计信息

环境变量

脚本支持以下环境变量（写在 plist 中，也可手动设置）：

变量	默认值	说明
`GBRAIN_DB`	`~/.hermes/gbrain/brain.db`	数据库路径
`GBRAIN_DAYS`	`7`	导入最近 N 天的会话
`GBRAIN_SOURCES`	`all`	导入哪些 agent（all/hermes/codex/claude-code/openclaw）

六、数据库结构

gBrain 使用 SQLite，包含以下表：

表名	说明
`pages`	核心内容：slug、type、title、内容、时间线
`page_fts`	FTS5 全文索引虚拟表
`page_embeddings`	向量嵌入（Float32 BLOB, 4096 维）
`links`	页面间的交叉引用
`tags`	页面标签
`config`	脑配置（嵌入模型、维度、分块策略）

七、gBrain 设计理念

gBrain 基于 Garry Tan 的 “compiled truth + timeline” 架构：

Above the line (compiled truth): 编译过的真相，永远是最新的，有新信息就重写
Below the line (timeline): 只追加的证据库，永不重写，保留原始对话

核心原则：Skills are the brain. CLI is just the hands. 智能体现在 Markdown skill 文件中，CLI 只是搬运数据。

八、Slug 命名规范

页面通过 slug 标识，格式为 category/subcategory/name：

hermes/hermes/sessions/20260414_100149_99b821a1  ← Hermes 会话
codex/codex/019cd858-5f35-77f0-be76-352036fce857  ← Codex 会话
hermes/hermes/memory/user                          ← 用户记忆
hermes/hermes/memory/long-term                     ← 长期记忆

自定义页面可以任意命名：

user/me              ← 个人信息
user/projects        ← 项目列表
user/preferences     ← 偏好设置
feedback/lessons     ← 经验教训
reference/tools      ← 工具参考

九、实用查询示例

        
# 搜索包含 "PostgreSQL" 的会话
gbrain search "PostgreSQL"

# 语义查询
gbrain query "上次讨论数据库架构时说了什么"
gbrain query "Tailscale 怎么配置子网路由"

# 列出所有条目
gbrain list

# 查看特定会话内容
gbrain get hermes/hermes/sessions/20260414_100149_99b821a1

# 手动触发更新
python3 ~/.hermes/scripts/gbrain_update.py

十、故障排查

常见问题

        
# 1. 检查 Ollama 是否运行
ollama list
pgrep -f ollama

# 2. 检查 gBrain 状态
export GBRAIN_DB

目录