recovering-brain-database

能力目标

让 Agent 在 PGLite brain 数据库损坏（WASM 初始化失败）或某页面处于软删除态时，把 brain 恢复到可用状态——利用「DB 只是 markdown 的物化视图」这一事实，几条命令从原始 markdown 回放重建，或用内部 RPC 把软删除页面拉回可见。

前置

• brain 的原始 markdown 源目录还在（这是恢复的前提；DB 全损也能重建，只要 markdown 在）。
• PGLite 是浏览器内 WASM 的单 writer 数据库，不暴露 CLI 级 VACUUM / REINDEX；一旦被强制 kill 未正常 close()、或备份时机捕获到软删除态 tuple，只能靠重建或 restore_page、不能修底层 MVCC 一致性。
• gbrain 命令用 timeout -k 5 30 gbrain ... 包裹（exit 124 正常）。

实操流程

场景 A — 整库损坏（所有命令报 PGLite failed to initialize its WASM runtime. Original error: Aborted()）：

1. 若有残留 serve 进程占着写锁，先杀掉、清 postmaster.pid：

   pkill -f "gbrain serve" 2>/dev/null
   rm -f ~/.gbrain/brain.pglite/postmaster.pid 2>/dev/null
   

2. 备份损坏目录（不直接删、留回滚），重新 init——必须带正确的 embedding model 与维度，否则默认走 OpenAI 1536 维、与 DashScope 1024 维不匹配：

   mv ~/.gbrain ~/.gbrain.broken-backup-$(date +%Y%m%d-%H%M%S)
   export DASHSCOPE_API_KEY="<你的 key>"
   timeout -k 5 120 gbrain init --pglite \
     --embedding-model dashscope:text-embedding-v3 --embedding-dimensions 1024
   

3. 从 markdown 源重新 import + 建向量：

   BRAIN_DIR="/path/to/your-brain-markdown"
   timeout -k 5 120 gbrain import "$BRAIN_DIR/" --no-embed > /tmp/reimport.txt 2>&1
   timeout -k 5 120 gbrain embed --stale > /tmp/reembed.txt 2>&1
   timeout -k 5 30 gbrain stats
   

场景 B — 单页软删除（某页 deleted_at 非空，gbrain put 该页报 attempted to delete invisible tuple）：

1. 用内部 RPC restore_page 把该页从软删除态拉回可见（绕过 put 路径上的 invisible tuple 校验）：

   gbrain call restore_page --json '{"slug": "people/alice-chen"}'
   timeout -k 5 60 gbrain list > /tmp/list.txt 2>&1; cat /tmp/list.txt
   

   gbrain call 是 RPC 风格内部接口、参数走 JSON。restore_page 只置空 deleted_at、恢复行可见性，不修底层 MVCC——后续对该页 embed 可能仍触发 invisible tuple，此时该页内容仍能靠 BM25 字面命中 + graph_augment 邻居召回、不阻塞主检索路径。

校验回路

• 场景 A：gbrain stats 正常返回，Pages 数 = markdown 源的 page 数，Embedded 接近 Pages；随便一条 gbrain search 有命中。
• 场景 B：gbrain list 里该 slug 重新出现；gbrain get <slug> 能取到完整页面。
• 这条恢复本身印证「markdown 是真相源、git 是审计轨迹、DB 是物化视图」——即使 PGLite 数据目录全损，只要原始 markdown 还在，几条 import + embed 就能完整回放。

常见陷阱

• 重 init 忘带 --embedding-dimensions 1024：DB schema 会锁死成默认 1536 维，后续 embed 报 expected 1536 dimensions, not 1024；只能再 rm -rf ~/.gbrain/brain.pglite 带正确 flag 重来。
• 对软删除页面直接 gbrain put 想覆盖：会撞 invisible tuple 错误。要走 gbrain call restore_page，不是 put。
• PGLite 不适合多 writer：适合个人 brain（GB 级、单进程）。生产多 writer 协作场景应换 PostgreSQL 后端（把 brain DB 放独立 Postgres 实例），绕开 WASM 单 writer 的工程局限。
• 强制 kill 是损坏根源：timeout 强制结束 gbrain 时 PGLite 未正常 close，数据目录进 crash recovery。日常按 exit 124 正常处理即可、但连续异常 kill 后若命令开始报 WASM Aborted，就走场景 A 重建。