实践

给 OpenClaw 装上长期记忆：让 AI Agent 不再每次重新认识你

记录我如何把 GBrain 接入 OpenClaw：从安装、PostgreSQL、独立 Brain Repo，到 MCP、Context Engine、Signal Detector 和最终验收。

作者：黄撑更新于 2026-07-10

很多人在使用 AI 助手时都会遇到同一个问题：

昨天已经告诉它的事情，今天为什么又忘了？

原因很简单：大部分 AI 对话主要依赖当前聊天窗口里的上下文。对一次性任务来说够用，但当任务变成长期项目，例如维护博客、开发 Agent、管理自动化流程时，就会越来越难受。

你会不断重复：

这个项目是做什么的；
为什么之前没有选某个方案；
我的长期偏好是什么；
上次已经踩过哪些坑。

所以我最近把 GBrain 接进了自己的 OpenClaw。

我的目标不是再给 Agent 多装一个搜索工具，而是让它真的形成两条闭环：

自动想起来：每次对话开始时，系统主动召回相关长期知识。
自动记下来：新消息进入后，后台判断是否值得长期保存，并写回 GBrain。

BEFORE / AFTER区别不在“多一个工具”，而在记忆能不能形成闭环

普通 AI每次重新认识你

当前聊天结束后，项目背景、历史决策和长期偏好很容易散掉。

重复解释上下文断裂经验难积累

+GBrain

OpenClaw + GBrain逐渐了解你的长期助手

重要项目、历史决定和可复用经验会被保存，并在需要时重新召回。

自动召回自动沉淀长期积累

OpenClaw 和 GBrain 分别负责什么？

不要把 GBrain 理解成另一个聊天机器人。

它更像是 Agent 的长期知识库和记忆层。

你提出一个目标

↓

OpenClaw理解问题 · 推理 · 调用工具 · 执行任务

短期状态Memory Core当前会话、最近状态、轻量偏好

长期记忆GBrain项目、人物、公司、决策、经验和方法论

主动操作MCP搜索、读取、写入和查询长期知识

简单理解：

部分	负责什么
OpenClaw	AI 助手的运行中心，负责推理、调用工具和执行任务
Memory Core	OpenClaw 自己的短期状态和轻量记忆
GBrain	保存长期项目、历史决策和可复用经验
GBrain MCP	让 Agent 主动搜索、读取和写入 GBrain

为什么只装 MCP 还不够？

刚开始接入时，我也认为：

安装 GBrain MCP，让 Agent 能调用工具，不就完成了吗？

实际不是。

MCP 只解决了：

Agent 可以主动查询和写入记忆。

真正的长期记忆还要补两块。

自动想起来：Context Engine

当我说到某个项目时，系统应该主动找到相关历史信息，而不是等 Agent 先猜“要不要搜索 GBrain”。

这部分由 Context Engine 负责。

自动记下来：Signal Detector

聊天里也不是所有内容都值得保存。

例如：

今天帮我把这个标题改一下

通常没必要长期保存。

但：

以后博客文章默认公开，除非我明确要求草稿

这种长期规则就值得记录。

这部分由 Signal Detector 判断。

我最终跑通的完整架构

我没有删除 OpenClaw 原来的 memory-core，而是让短期记忆和长期记忆分工。

LONG-TERM MEMORY SYSTEM同一条用户消息，同时进入“自动想起”和“自动记住”两条链路

用户消息

RECALL · 自动想起

01Context Engine接管每轮上下文组装

→

02Retrieval Reflex识别相关实体和长期知识

→

03注入 OpenClaw让主 Agent 带着历史继续思考

CAPTURE · 自动记住

01message_received每条新消息到达

→

02Signal Detector后台判断是否值得长期保存

→

03写入 GBrain统一保存到 brain source

短期层Memory Core

长期数据层GBrain + PostgreSQL 17

这张图就是整篇文章最核心的东西。

真正成为“长期大脑”后：

旧知识能自动回来；
新知识能自动沉淀；
主 Agent 的回复不会被后台记忆任务卡住；
多会话同时运行也不会抢同一份本地数据库锁。

先说安装：我是怎么装 GBrain 的

GBrain 官方现在更推荐让 Agent 自己读取安装说明并执行，而不是人工一条条抄命令。

官方入口是：

GBrain GitHub 仓库

把下面这句话直接交给可以访问网络和终端的 Agent：

Retrieve and follow the instructions at:
https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md

如果只想先装 CLI，官方也提供了手动方式：

bun install -g github:garrytan/gbrain
gbrain doctor

我当前本机实际使用的是：

GBrain 0.42.57.0
OpenClaw 2026.7.1-beta.2

我的最终配置顺序

这不是我最开始走的路径，而是把踩过的坑排除后，留下来的顺序。

最终配置路径

Step 1 安装 GBrain，并先确认 CLI 正常

先运行 gbrain doctor，确保不是在后面排查 OpenClaw 时才发现 GBrain 本身就没有装好。

Step 2 把存储层换成 PostgreSQL 17

多 Agent、多会话场景不再使用 PGLite，避免多个 gbrain serve 抢同一个文件锁。

Step 3 建立独立 Brain Repo

使用 ~/brain 保存长期知识，并注册成名为 brain 的 GBrain source。

Step 4 接入 Retrieval Reflex 和 MCP

让 Agent 能查询、读写长期知识，并明确所有写入都落到 brain source。

Step 5 把 Context Engine 切到 GBrain

让 GBrain 真正进入每轮上下文组装，而不是只作为一个可选工具存在。

Step 6 补上 Signal Detector 事件触发

在 message_received 后台运行官方 Signal Detector，让值得保存的消息自动落库。

Step 7 按行为做最终验收

不仅看插件 loaded，还要真实验证自动召回、自动写入和多会话并发。

1. 存储层：直接使用 PostgreSQL 17

我最初使用的是 PGLite。

单独运行 GBrain 时没问题，但接入 OpenClaw 后，问题马上出现了。

OpenClaw 的 MCP runtime 会按 session 启动独立进程。多个会话同时加载 GBrain MCP 时，就可能出现多个 gbrain serve 去争同一份 PGLite 数据库文件。

结果就是：

第一个 gbrain serve -> 正常持有数据库锁
第二个 gbrain serve -> 等待锁
第三个 gbrain serve -> 继续等待

最终表现：MCP 启动卡住约 30 秒

所以我最后改成了本地 PostgreSQL 17 + pgvector。

brew install postgresql@17 pgvector
brew services start postgresql@17

createdb gbrain
psql gbrain -c 'CREATE EXTENSION IF NOT EXISTS vector;'

然后让 GBrain 直接使用 PostgreSQL：

gbrain init \
  --url "postgresql://<user>@127.0.0.1:5432/gbrain" \
  --no-embedding

我当前先没有配置 Embedding，所以使用 --no-embedding。

这不会影响：

关键词搜索；
实体召回；
MCP 查询；
Signal Detector 自动写入。

只是暂时没有完整的向量语义检索。

2. 建立独立的 Brain Repo

我没有把长期知识直接塞进 OpenClaw workspace，而是单独建立：

~/brain

这个目录本身是一个 Git 仓库，负责保存长期知识源。

mkdir -p ~/brain
cd ~/brain
git init

gbrain sources add brain --path ~/brain
gbrain sync --source brain --no-pull --no-embed

最终目录职责是：

~/.openclaw/workspace  -> Agent 工作区、规则、Skill
~/brain                -> 长期知识源
PostgreSQL              -> GBrain 检索与运行数据

我最终只保留一个明确的长期 source：

brain

这一步看起来简单，但后面非常重要，因为 MCP 写入也必须明确落到这个 source。

3. 接入 Retrieval Reflex 和 MCP

接下来是三块能力：

GBrain 官方 Skillpack：告诉 Agent 各类 GBrain 能力怎么使用；
Retrieval Reflex：提到相关实体时，主动召回长期知识；
MCP：提供搜索、查询、读取和写入工具。

Retrieval Reflex 安装到 OpenClaw workspace：

gbrain integrations install retrieval-reflex \
  --target ~/.openclaw/workspace

MCP 的关键不是只有 cwd，而是要明确指定 source：

openclaw mcp add gbrain \
  --command "$(command -v gbrain)" \
  --arg serve \
  --cwd ~/brain \
  --env GBRAIN_SOURCE=brain

我当前实际配置的核心结构是：

{
  "command": "/Users/<user>/.bun/bin/gbrain",
  "args": ["serve"],
  "cwd": "/Users/<user>/brain",
  "env": {
    "GBRAIN_SOURCE": "brain"
  }
}

这里把个人用户名做了脱敏，真正重要的是：

GBRAIN_SOURCE=brain

最后验证：

openclaw mcp doctor

我当前真实结果是：

gbrain: ok

4. 让 GBrain 真正成为 Context Engine

只安装 MCP 还不够。

如果 OpenClaw 仍然是：

contextEngine = legacy

那么 GBrain 只是一个“可以被调用的工具”，并没有进入每轮上下文组装过程。

我当前真正使用的 slot 是：

{
  "plugins": {
    "slots": {
      "memory": "memory-core",
      "contextEngine": "gbrain-context"
    }
  }
}

这代表：

短期记忆    -> memory-core
上下文组装  -> gbrain-context

这里有一个很容易踩的坑：

插件 ID：gbrain-context-engine
Context Engine ID：gbrain-context

slot 必须填 Context Engine ID，不是插件 ID。

我的本地桥接插件位于：

~/.openclaw/extensions/gbrain-context-engine

它的职责很克制：

加载 GBrain 官方 Context Engine；
适配当前版本 OpenClaw 与 GBrain 的 prompt / messages 参数差异；
在 message_received 上启动官方 Signal Detector。

核心不是重写 GBrain，而是把两个宿主接口接起来。

5. 让 Signal Detector 真正自动运行

这一块是我误判最久的地方。

GBrain 的 signal-detector/SKILL.md 里虽然写了触发描述，但 OpenClaw 不会因为 Skill 文件里有 triggers: 就自动执行它。

所以只在 AGENTS.md 里写：

每条消息都启动 Signal Detector

也不够稳定。

这只是 Prompt 约束，不是系统事件。

我最后使用 OpenClaw 原生的 message_received hook，在每条入站消息到来后启动隐藏子 Agent，让它执行官方 Signal Detector Skill。

核心逻辑可以压缩成：

api.on('message_received', (event, ctx) => {
  void runSignalDetector(event.content ?? '', ctx)
    .catch((error) => api.logger.error(String(error)));
});

这里最重要的是 void。

Signal Detector 在后台继续运行，不等待它完成，主 Agent 可以正常回复。

我实际验收时：

主消息 ACK：约 3 秒
Signal Detector 后台完成：约 6.5 秒

并且最终写入：

source_id = brain

这才算“自动记忆”闭环真正成立。

实际使用时会是什么感觉？

场景一：维护博客

以前：

每次开始写文章：
重新告诉 AI 博客定位、目录结构、视觉要求……

现在，长期记忆可以保存：

- 博客定位
- 写作偏好
- 文章默认发布规则
- 过去做过的视觉改造
- 已经确定过的项目决策

最明显的变化不是 AI 突然变聪明，而是不用不断重复背景。

场景二：长期开发项目

大型项目最怕的不是代码，而是历史决策丢失。

例如：

为什么不用方案 A？
之前遇到什么问题？
这个设计是怎么决定的？

长期记忆真正有价值的地方，就是把这些以后还会再次用到的上下文留下来。

经常遇到的坑

很多现象看起来都像“GBrain 没生效”，但根因完全不同。

坑 1：装了 MCP，就以为 GBrain 已经是大脑

现象： Agent 能看到大量 gbrain__* 工具，也能主动搜索，但新对话不会自动想起历史知识。

真正原因： MCP 只提供工具调用，没有进入 OpenClaw 的 Context Engine。

修复： 把 plugins.slots.contextEngine 切到 gbrain-context，再做不调用工具的自动召回测试。

坑 2：把插件 ID 当成 Context Engine ID

错误配置：

contextEngine = gbrain-context-engine

正确配置：

contextEngine = gbrain-context

插件叫什么，和它注册了哪个 Context Engine，是两层不同的 ID。

坑 3：Context Engine 已加载，但还是不自动召回

现象： 插件状态正常、没有降级，但新会话里依然没有 GBrain 上下文。

真正原因： 在我当前版本组合里，OpenClaw 把当前用户输入放在 prompt，而 GBrain Context Engine 实际从 messages 读取当前用户消息。

修复： 在插件边界把当前 prompt 临时补成一条 user message，调用官方 Context Engine 后再恢复原 messages。

坑 4：PGLite 在 OpenClaw 多会话下抢锁

现象： 每开一个新会话，GBrain MCP 可能卡约 30 秒，日志出现：

Timed out waiting for PGLite lock

真正原因： OpenClaw 的 MCP runtime 按 session 隔离，每个会话可能启动新的 gbrain serve。

修复： 改用 PostgreSQL 17 + pgvector。

坑 5：Signal Detector Skill 存在，但从来不自动写入

现象： Skill 已经存在，手动让 Agent 记忆也会回复“已记录”，但数据库里没有新页面。

真正原因： Skill 的触发描述不是 OpenClaw 的原生事件机制。

修复： 使用宿主侧 message_received hook，真实启动隐藏子 Agent。

坑 6：明明写入成功，为什么 `brain` 里搜不到

真正原因： gbrain serve 不会因为 cwd=~/brain 就自动把所有 MCP 写入路由到 brain。没有明确 source 时，会回退到 default。

修复： MCP 服务必须带：

GBRAIN_SOURCE=brain

真实验收时还要查：

source_id = brain

不要只相信模型说“已经写入”。

我现在故意没有开启的东西

当前 GBrain 已经可以正常体验，但我没有把所有功能一次开满。

ZeroEntropy Embedding

暂时不启用。

当前状态：

embedding_disabled = true

关键词、实体召回和 MCP 查询仍然可以使用。先体验基础召回，再决定是否需要完整语义检索。

Autopilot

暂时不恢复。

我当前本机真实状态是：

Autopilot: not running

原因也很简单：先看 GBrain 到底记了什么、召回准不准，再增加后台维护循环。

我的最终验收标准

配置完成后，我不会只看“进程启动了没有”，而是按链路逐层验收。

基础健康检查：

openclaw health
openclaw mcp doctor
gbrain status

我当前本机实际状态：

GBrain 0.42.57.0
brain source: pages=1
Embedding: 0%
Autopilot: not running
MCP: gbrain ok

但真正重要的是行为。

ACCEPTANCE CHECK只有两条闭环都经过真实测试，才算完成

01自动召回

新会话不主动调用 GBrain 工具，提到已知实体时仍能看到历史知识。

02主回复不被阻塞

发送长期观点后，主 Agent 先正常回复，不等待后台记忆完成。

03自动写入

几秒后 Signal Detector 显示 captured，数据库出现新页面。

04写入正确 source

真实检查 source_id = brain，而不是只相信模型回复。

05多会话稳定

多个会话同时运行时，不再出现 PGLite 锁等待和 30 秒超时。

✓闭环成立

自动想起 + 自动记住，GBrain 才真正成为 OpenClaw 的长期大脑。

这套配置目前仍然保留一个原则：先让最小闭环稳定，再增加复杂能力。

Embedding、reranker、Autopilot 都可以后面再补，但“自动想起”和“自动记住”必须先真的跑通。