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

用一套完整的系统图和操作控制台，讲清 GBrain 如何接入 OpenClaw、形成自动召回与自动写入闭环，以及日常查询、同步、维护和排查方法。

很多人在长期使用 AI 助手后，都会遇到同一个问题：

昨天已经告诉它的事情，今天为什么又要重新解释？

一次性聊天只需要当前上下文；但维护博客、开发 Agent、管理自动化流程时，项目背景、历史决策、长期偏好和踩坑经验都需要持续保留。

所以我把 GBrain 接进了自己的 OpenClaw。目标不是多装一个搜索工具，而是让 Agent 形成两条真正可运行的闭环：

• 自动想起来：每次对话开始时，主动召回相关长期知识。
• 自动记下来：新消息进入后，判断哪些内容值得长期保存，并写回知识库。

先看整体：它不是一个插件，而是一套双闭环系统

GBrain 不是另一个聊天机器人，也不是 OpenClaw 的替代品。

OpenClaw 负责理解目标、推理、调用工具和执行任务；GBrain 负责保存长期项目、历史决定、人物关系和可复用经验。两者之间还需要 Context Engine、Retrieval Reflex、MCP 和 Signal Detector 把读写链路连接起来。

为什么只安装 MCP 还不够？

我最开始也以为，安装 GBrain MCP，让 Agent 能搜索和写入知识，就已经完成接入。

实际只完成了最下面一层：Agent 可以主动使用工具。如果每次都要靠模型临时判断“现在是不是应该搜索 GBrain”，记忆仍然不稳定。

我最终采用的安装与接入路径

下面不是我第一次安装时的顺序，而是排除无效尝试后留下的稳定路径。每一步都带一个验证点，上一层没有通过，不进入下一层排查。

第一步：安装 GBrain，先确认 CLI 正常

GBrain 官方更推荐让 Agent 读取安装说明并执行。可以把下面这段直接交给能够访问网络和终端的 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 装起来；这里重点记录它怎样进入现有 OpenClaw，并形成自动召回、自动写入和多会话稳定运行。

第二步：多会话场景直接使用 PostgreSQL 17

我最初使用 PGLite。单独运行 GBrain 没问题，但 OpenClaw 的 MCP runtime 会按 session 启动独立进程，多个 gbrain serve 可能同时争用一份数据库文件。

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

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

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

我当前没有配置 Embedding，所以使用 --no-embedding。这不会影响关键词搜索、实体召回、MCP 查询和 Signal Detector 写入，只是暂时没有完整的向量语义检索。

我实际安装时还遇到一次版本兼容：当时 Homebrew 的 pgvector 扩展没有落到 PostgreSQL 16 的扩展目录，换成 PostgreSQL 17 后恢复正常。最终只保留一个数据库版本，避免两套服务同时占端口。

第三步：建立独立的 Brain Repo

长期知识没有直接塞进 OpenClaw workspace，而是单独保存在：

~/brain

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

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

我最终只保留一个明确的长期 source：brain。后面的 MCP 写入也必须明确落到这个 source。

第四步：接入 Retrieval Reflex 和 MCP

Retrieval Reflex 负责识别相关实体，MCP 负责让 Agent 主动搜索和写入。

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

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

MCP 配置中最容易被忽略的不是 cwd，而是：

GBRAIN_SOURCE=brain

cwd=~/brain 不会自动保证所有写入都路由到 brain。没有明确 source 时，写入可能回退到 default。

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

最后运行：

openclaw mcp doctor

我当时的真实结果是 gbrain: ok。

第五步：让 GBrain 真正成为 Context Engine

如果 OpenClaw 仍然使用 contextEngine = legacy，GBrain 只是一个可选工具，没有进入每轮上下文组装。

我最终使用的 slot 是：

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

我的本地桥接插件位于 ~/.openclaw/extensions/gbrain-context-engine，只负责三件事：

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

这不是所有版本都要长期保留的代码。升级 OpenClaw 或 GBrain 后，应先检查上游是否已经原生解决，能删除桥接层就删除。

第六步：让 Signal Detector 通过系统事件自动运行

signal-detector/SKILL.md 里的 triggers: 只是 Skill 描述，不是 OpenClaw 的原生事件机制。在 AGENTS.md 中写“每条消息都启动 Signal Detector”也只是 Prompt 约束，不够稳定。

我最终使用宿主侧 message_received hook，在每条入站消息后启动隐藏子 Agent：

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

这里最重要的是 void：后台记忆任务继续运行，主 Agent 不等待它完成。

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

日常怎么用：从状态、检索、写入到同步维护

接入完成后，最常见的问题不再是“怎么安装”，而是：

现在应该先敲哪条命令，才能判断知识库、检索和 OpenClaw 接入到底哪一层有问题？

下面把原命令手册合并成一套日常控制台。原则只有一个：先证明 GBrain 自己正常，再向上检查 OpenClaw。

gbrain --version
gbrain status
gbrain stats
gbrain health

gbrain list --limit 10 --sort updated_desc
gbrain list --type concept --limit 20
gbrain list --tag openclaw --limit 20

gbrain search "OpenClaw" --source brain --limit 10
gbrain search "品牌雷达" --limit 5

gbrain query "OpenClaw 和 GBrain 分别负责什么？" --limit 5
gbrain query "最近有哪些 OpenClaw 配置变化？" --since 7d --recency strong --limit 10

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

gbrain capture --file ./notes/openclaw-memory.md --slug operational/openclaw-memory --type note

gbrain tag concepts/brand-radar openclaw

gbrain link projects/openclaw-memory concepts/gbrain --link-type uses --context "OpenClaw 使用 GBrain 作为长期知识层"

gbrain timeline-add projects/openclaw-memory 2026-07-25 "完成 GBrain 与 OpenClaw 接入验证"

gbrain history concepts/brand-radar
gbrain revert concepts/brand-radar <version_id>
gbrain delete concepts/brand-radar
gbrain get concepts/brand-radar --include-deleted

gbrain doctor --fast
gbrain doctor
gbrain advisor
gbrain orphans --count
gbrain lint ~/brain
gbrain check-backlinks check ~/brain

gbrain export --dir ./gbrain-export
gbrain check-update --json
gbrain upgrade
gbrain dream --dry-run
gbrain dream

出了问题，不要把所有故障都叫做“没生效”

很多现象看起来都像 GBrain 没有工作，但可能分别发生在 source、同步、检索、MCP、Context Engine 或 Signal Detector。正确排查方式不是反复重启，而是逐层拿证据。

真正使用起来，会发生什么变化？

长期记忆最明显的价值，不是让模型突然变聪明，而是减少背景重复，让历史决定继续参与今天的判断。

我现在故意没有开启的功能

当前系统已经可以正常体验，但我没有一次把所有功能开满。先稳定最小闭环，再决定是否增加更复杂的后台能力。

最终验收：不要只看插件是否 loaded

配置完成后，我不会只看进程是否启动，而是按两条闭环做真实验收。

基础健康检查可以先运行：

openclaw health
openclaw mcp doctor
gbrain status

我当时的本机状态是：

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

但这些只说明服务状态，真正重要的是行为。

这套方案最终保留的原则很简单：先让最小闭环稳定，再增加复杂能力。