organizing-multi-brain-sources

能力目标

让 Agent 把知识按两条正交的轴组织：brain 轴用独立数据库把不同域（个人/团队）完全隔离，source 轴在同一 brain 内让同一个 slug 的不同来源内容共存；并能注册跨 brain 挂载、写 fan-out 脚本做跨 brain 联合检索。

前置

• brain 轴 = 数据库边界：每个 brain 是一个独立目录、目录内有自己的 .gbrain/brain.pglite，彼此不共享数据；类比不同数据库实例。切换靠 GBRAIN_HOME 环境变量。
• source 轴 = 同库内容仓：同一 brain 内用 source_id 区分来源，pages 表复合键是 (slug, source_id)，所以同 slug 在不同 source 各存一行、互不覆盖；类比同库不同 schema。切换靠 GBRAIN_SOURCE。
• gbrain 命令用 timeout 包裹（exit 124 正常）。

实操流程

1. 建两个独立 brain。gbrain init 不看当前工作目录、默认初始化到 ~/.gbrain/，必须用 GBRAIN_HOME 显式指定路径：

   PERSONAL="/path/to/personal-brain"; TEAM="/path/to/team-brain"
   mkdir -p "$PERSONAL" "$TEAM"
   GBRAIN_HOME="$PERSONAL" gbrain init --pglite
   GBRAIN_HOME="$TEAM"     gbrain init --pglite
   

2. 各写入若干 page（所有命令都要带 GBRAIN_HOME 前缀）：

   GBRAIN_HOME="$PERSONAL" gbrain put people/me <<'EOF'
   ---
   type: person
   ---
   # Me
   个人知识管理中心。
   EOF
   GBRAIN_HOME="$PERSONAL" gbrain list
   GBRAIN_HOME="$TEAM" gbrain put companies/our-company <<'EOF'
   ---
   type: company
   ---
   # Our Company
   团队内部情报页面。
   EOF
   

3. 注册跨 brain 挂载（gbrain mounts add 是隐藏命令、写全局 ~/.gbrain/mounts.json）：

   gbrain mounts add team --path "$TEAM" --engine pglite --db-path "$TEAM/.gbrain/brain.pglite"
   gbrain mounts list --json    # {"version":1,"mounts":[{"id":"team",...}]}
   

4. 跨 brain 检索——GBrain 不在 DB 层做跨 brain 联合查询（"Cross-brain federation is YOUR JOB, not the DB's"），自己写 fan-out 逐 brain 检索、合并结果：

   echo "=== personal ==="; GBRAIN_HOME="$PERSONAL" gbrain search 'agent' -n 3
   echo "=== team ===";     GBRAIN_HOME="$TEAM"     gbrain search 'company' -n 3
   # 生产可解析 gbrain mounts list --json 自动遍历所有 brain
   

5. 用 source 轴让同 slug 内容共存。注册 source，再用 GBRAIN_SOURCE 分源写入（gbrain import 没有 --source flag，逐页精确写入用 put + GBRAIN_SOURCE）：

   GBRAIN_HOME="$PERSONAL" gbrain sources add wiki   --path "$PERSONAL/wiki"
   GBRAIN_HOME="$PERSONAL" gbrain sources add gstack --path "$PERSONAL/gstack"
   GBRAIN_HOME="$PERSONAL" GBRAIN_SOURCE=wiki   gbrain put topics/ai < "$PERSONAL/wiki/topics/ai.md"
   GBRAIN_HOME="$PERSONAL" GBRAIN_SOURCE=gstack gbrain put topics/ai < "$PERSONAL/gstack/topics/ai.md"
   

校验回路

• brain 隔离：GBRAIN_HOME="$TEAM" gbrain get companies/our-company 命中；GBRAIN_HOME="$PERSONAL" gbrain get companies/our-company 返回 page_not_found——两库互不可见。
• fan-out：personal 与 team 各只返回自己库的匹配结果、互不串。
• source 共存：gbrain list --source wiki 与 gbrain list --source gstack 各列出自己的 topics/ai；GBRAIN_SOURCE=wiki gbrain get topics/ai 与 GBRAIN_SOURCE=gstack gbrain get topics/ai 内容不同、互不覆盖。
• gbrain sources list 显示各 source 的 page 计数（同 slug 在 default / wiki / gstack 各计一条）。

常见陷阱

• gbrain init --pglite 忽略 cwd：cd 到目标目录再 init 仍落到 ~/.gbrain/，因为 configDir() 默认 ~/.gbrain/、init 不读 cwd。所有命令必须加 GBRAIN_HOME=<dir> 前缀——这是设计选择、不是 bug。
• --brain <id> flag 与 GBRAIN_BRAIN_ID 环境变量当前不生效：源码里 6 层 brain 解析优先级已实现但 CLI dispatch 层尚未接入（connectEngine 未调 resolveBrainId）。--brain team 报 Unknown command: --brain、GBRAIN_BRAIN_ID=team 仍路由到默认 brain。当前统一用 GBRAIN_HOME 切换 brain。
• gbrain import 无 --source flag：import 是批量导入层、按设计不参与 source 路由。目录级分源同步用 gbrain sync --source <id>（要求目录是 git repo，否则报 Not a git repository）；否则逐页 GBRAIN_SOURCE=<id> gbrain put。
• 跨 brain 结果不可直接合并排序：不同 brain 的向量空间独立、相关度分数不跨 brain 可比。fan-out 合并时按 brain 优先级或业务规则处理，别假设分数可直接排序。