构建编译型知识图谱:为AI智能体打造持久化记忆中枢
1. 项目概述:为AI智能体构建一个持久化、结构化的个人知识大脑
如果你和我一样,每天在各种即时通讯工具(Telegram、Slack、WhatsApp、iMessage)和AI助手之间切换,最头疼的问题可能就是“记忆断层”。上个月和某位投资人聊过的关键细节,上周研究过的一个技术概念,昨天在某个频道里讨论的潜在合作方——这些信息散落在不同的对话、笔记和文档里,当你在新的对话中需要调用它们时,往往只能靠模糊的印象,或者得花大量时间翻找。这正是我深度使用OpenClaw这类多通道AI代理平台时遇到的核心痛点:每个对话都是孤岛,智能体缺乏一个跨会话、跨通道的持久化记忆中枢。
市面上的知识管理工具,无论是Obsidian、Notion这类笔记应用,还是基于向量数据库的RAG(检索增强生成)流水线,都未能完美解决这个问题。笔记应用依赖手动整理,维护成本高;而传统的RAG更像一个“文档垃圾场”,你把一堆文件扔进去,它返回一些相关片段,但缺乏对实体(人、公司、交易、概念)的持续追踪和结构化理解。我需要的是一个能像大脑一样工作的系统:它能记住关于一个实体的“当前共识”(即最新、最准确的理解),同时保留所有历史证据和演变过程,并且能让AI智能体像调用API一样自然地查询和更新它。
这就是gbrain-openclaw项目的由来。它不是一个通用的笔记工具,而是一个专为“实体关系网络”设计的编译型知识图谱。其核心思想源于Garry Tan提出的 GBrain规范 ,即“编译事实+时间线”架构。我(Phillip Wu)基于此规范,专门为OpenClaw生态实现了它。整个系统被浓缩成一个单一的SQLite数据库文件(brain.db),集成了全文搜索、向量嵌入和结构化查询,并通过MCP(模型上下文协议)服务器的方式,无缝接入OpenClaw,成为其所有AI智能体共享的“外接大脑”。
简单来说,gbrain-openclaw是为需要长期追踪人、事、物及其关系的知识工作者打造的。无论是风险投资人管理投资组合和创始人网络,还是销售负责人梳理客户历史和关键决策人,抑或是研究者跟踪论文脉络和实验进展,只要你的知识是围绕一个个“实体”积累并产生复利效应的,这个工具就能让你和你的AI助手真正做到“过目不忘”,在任意对话中随时调取精准、结构化、带上下文的记忆。
2. 核心架构解析:编译事实与时间线的双轨制设计
gbrain-openclaw的威力,根植于其独特的数据模型。它彻底摒弃了传统的、线性的笔记或文档存储方式,采用了“编译事实+时间线”的双轨制架构。理解这个架构,是理解其所有功能设计的关键。
2.1 什么是“编译事实”?
你可以把“编译事实”想象成维基百科上关于一个主题的当前版本页面。它代表了关于某个实体(例如一个人、一家公司)此时此刻最准确、最完整的共识性描述。这个描述不是一成不变的,而是会随着新信息的到来被不断地、主动地“重写”或“重新编译”。
举个例子,你有一个关于“Jane Doe”的页面。最初,你可能只知道她是“Acme Corp的创始人”。几周后,你通过一次会议了解到她曾是“Google的工程师”,并且公司刚完成了“A轮融资”。这时,你不会仅仅在页面末尾追加一条笔记,而是会重写整个“编译事实”部分,将其更新为:“Jane Doe,前Google工程师,Acme Corp(一家专注于AI基础设施的初创公司)的创始人兼CEO,于2025年11月完成1200万美元的A轮融资,由a16z领投。”
注意:这里的“重写”是系统设计上的逻辑概念,并非指手动编辑。在实际使用中,通常由
gbrain-ingest技能包驱动的AI智能体,在分析新信息(如会议记录、新闻)后,自动合并新旧信息,生成新的“编译事实”版本。旧版本会作为历史证据保存在“时间线”中。
这种设计的核心优势在于检索效率和信息时效性。当AI智能体被问到“告诉我关于Jane Doe的一切”时,它可以直接读取“编译事实”这个字段,立刻获得一份精炼、最新、无需二次整理的摘要,而不是去解析一堆杂乱无章、可能包含过时信息的历史笔记。
2.2 什么是“时间线”?
与可被重写的“编译事实”相对,“时间线”是一个只追加、永不修改的审计日志。它按时间顺序记录所有与实体相关的事件、观察结果和原始信息片段。
继续上面的例子,关于Jane Doe的时间线可能包含以下条目:
2025-10-15 | news:TechCrunch报道Acme Corp获得种子轮融资。2025-11-15 | meeting:与Jane进行初次会议,讨论产品路线图。2026-01-20 | email:Jane发送邮件更新了产品发布计划。2026-04-01 | news:公司宣布完成A轮融资。
时间线的价值在于提供了信息的溯源和上下文。它回答了“我们是怎么知道这件事的?”以及“这件事是在什么背景下发生的?”。当你需要回顾与某人的交往历程,或者验证某个信息的来源时,时间线是无价的。它确保了知识的透明度和可信度。
2.3 双轨制如何协同工作?
在gbrain-openclaw中,每个“页面”都严格遵循这个模型。一个页面的Markdown源文件结构如下:
--- title: Jane Doe type: person tags: [founder, yc-alum, ai-infrastructure] --- # Jane Doe > CEO of Acme Corp. Former Google engineer. Building next-gen AI infrastructure tools. YC W22 alum. ## Current Status Leading Acme Corp post a $12M Series A led by a16z. Focused on scaling engineering team and launching v2.0 of their core platform in Q3 2026. ## Open Threads - [ ] Follow up on Series B investor interest mentioned on 2026-04-01. - [ ] Schedule a catch-up call in Q2 to discuss partnership potential. --- ## Timeline - **2026-04-01** | meeting — Demo day follow-up. Very impressed with product maturity. Hinted at potential Series B interest from Sequoia. - **2025-11-15** | news — Announced $12M Series A led by a16z. Participating investors include XYZ Ventures. - **2025-10-15** | meeting — Initial intro call. Discussed pain points in current ML ops stack. Strong technical depth. - **2025-09-01** | news — TechCrunch covered Acme's $2M seed round.注意那个三个连字符(---)构成的分隔线。在数据库中,这条线之上的所有内容(包括Frontmatter和正文)被存储为compiled_truth字段,之下的所有内容被存储为timeline字段。两者在SQLite中是独立的列,这意味着你可以:
- 高效查询最新状态:直接SELECT
compiled_truthWHERE slug = ‘people/jane-doe’。 - 按时间追溯历史:SELECT * FROM
timeline_entriesWHERE page_slug = ‘people/jane-doe’ ORDER BY date DESC。 - 进行复杂的联合查询:例如,“找出所有在2025年Q4有过会议记录,且当前状态中包含‘scaling’关键词的人”。
这种将“当前最佳理解”与“原始证据链”分离并关联的设计,是gbrain-openclaw区别于其他所有笔记或知识库工具的根本所在。它模拟了人类大脑处理信息的理想方式:一个不断更新的“工作记忆”(编译事实)和一个忠实记录的“情景记忆”(时间线)。
3. 技术栈选型与实现:追求极简与零依赖
在实现这样一个系统时,技术选型至关重要。gbrain-openclaw的哲学是“一个文件,零运维”,旨在成为个人工作流中一个安静、可靠、高性能的基础设施。以下是每个技术决策背后的考量:
3.1 运行时:为什么选择Bun?
- 原生性能与一体化:Bun不仅仅是一个JavaScript运行时,它内置了打包器、测试运行器和Node.js兼容的API。最重要的是,它提供了原生的SQLite驱动(
bun:sqlite)。这意味着我们不需要安装任何像better-sqlite3这样的原生模块(N-API),避免了跨平台编译和版本兼容的噩梦。bun build --compile更能将整个应用(包括SQLite逻辑)编译成单个独立的二进制文件,分发和部署极其简单。 - 开发体验:Bun的启动速度极快,内置的TypeScript支持意味着无需额外的
ts-node或编译步骤,直接bun run src/cli.ts即可,极大提升了开发迭代效率。
3.2 数据库:SQLite的王者归来
选择SQLite作为唯一的数据存储,是这个项目最核心也最大胆的决定。
- 单文件,零配置:
brain.db就是一个文件。备份?复制这个文件。迁移?移动这个文件。同步?用任何云盘同步这个文件。其简洁性无与伦比。 - 内嵌的全文搜索(FTS5):SQLite内置的FTS5扩展提供了生产级全文检索能力,支持词干提取(Porter Stemmer)、unicode分词等。我们不需要启动一个Elasticsearch或MeiliSearch服务,所有搜索都在进程内完成,延迟极低。
- 足够的性能:对于个人甚至小团队规模的知识库(数万至数十万个页面/条目),SQLite的性能完全绰绰有余。它的读写效率在单用户场景下甚至优于许多客户端-服务器数据库。
- 可靠性:SQLite经过最严格的测试,其ACID事务保证和数据一致性是业界标杆。你的知识库数据安全有坚实的保障。
3.3 向量搜索:纯JavaScript实现
为了实现语义搜索(“找到与‘机器学习框架’概念相似的页面”),我们需要向量嵌入和相似度计算。常见的方案是接入Pinecone、Weaviate或pgvector。
- 我们的方案:为了坚守“零外部依赖”的原则,
gbrain-openclaw实现了纯JavaScript的向量存储和计算。页面文本通过OpenAI的text-embedding-3-small等模型转换为浮点数向量(Float32),然后以BLOB格式直接存入SQLite。 - 搜索过程:当执行语义查询时,系统计算查询向量与数据库中所有向量之间的余弦相似度。虽然对于海量数据(>10万条)全表扫描可能成为瓶颈,但对于个人知识库的规模,在内存中进行的这些计算仍然是瞬间完成的。这种设计用微小的性能代价,换来了部署的极致简单。
3.4 交互协议:MCP(模型上下文协议)
这是gbrain-openclaw能无缝融入OpenClaw生态的关键。MCP是一种标准协议,允许AI助手(客户端)通过标准输入/输出(stdio)与工具(服务器)通信。
- 标准化集成:通过实现一个MCP服务器,
gbrain将所有功能(搜索、获取、更新、查询)暴露为一组标准的工具(Tools)。OpenClaw中的任何AI智能体,无需特殊配置,就能发现并调用这些工具。 - 与工具解耦:AI智能体不需要知道
gbrain内部是SQLite还是别的什么,它只需要按照MCP协议发送JSON-RPC请求。这为未来替换底层实现或扩展功能提供了清晰的接口。
这个技术栈的选择,体现了一种“功能强大但接口极简”的工程美学。最终交付物就是一个可以通过cp命令拷贝的二进制文件和一个SQLite数据库文件,没有任何需要管理的服务进程,真正做到了开箱即用。
4. 安装、配置与OpenClaw深度集成实操
理论说得再多,不如动手搭起来。下面我将带你完成从零开始,将gbrain-openclaw安装并深度集成到OpenClaw环境中的全过程,并分享一些关键的配置心得。
4.1 环境准备与编译安装
首先,确保你的系统满足前置条件:
- 安装Bun:如果你的系统还没有Bun,访问 bun.sh 按照指引安装。建议使用Bun 1.0或更高版本以获得最佳稳定性和性能。
- 安装OpenClaw:这是一个前提,因为
gbrain是作为其扩展存在的。请根据OpenClaw的官方文档完成安装和基础配置。
接下来,获取并编译gbrain:
# 1. 克隆仓库 git clone https://github.com/imphillip/gbrain-openclaw cd gbrain-openclaw # 2. 安装依赖(Bun会读取package.json并快速安装) bun install # 3. 编译为独立二进制文件 # 使用 `--compile` 参数,Bun会将你的TypeScript代码、依赖以及Bun运行时本身打包成一个可执行文件。 bun build --compile --outfile bin/gbrain src/cli.ts # 4. 将二进制文件放到系统PATH包含的目录,方便全局调用 sudo cp bin/gbrain /usr/local/bin/gbrain # 5. 初始化你的知识大脑 # 这会在默认位置(~/.openclaw/brain.db)创建SQLite数据库文件,并初始化所有数据表。 gbrain init实操心得:
bun build --compile生成的二进制文件体积相对较大(因为包含了Bun运行时),但换来的是无与伦比的便捷性。你可以把这个gbrain文件扔到任何同类系统上直接运行,完全不需要关心目标机器有没有安装Node.js或Bun。
4.2 配置向量搜索(可选但推荐)
纯关键词搜索(FTS5)已经很强大了,但语义搜索能帮你发现那些关键词不匹配但含义相关的内容。要启用它,你需要一个嵌入模型API。项目默认配置为OpenAI,这也是最稳定易用的选择。
# 将你的OpenAI API Key设置为环境变量 # 你可以把它加到你的shell配置文件(如 ~/.zshrc 或 ~/.bashrc)中以便永久生效 export OPENAI_API_KEY="sk-your-actual-api-key-here" # 验证Key是否生效且项目能访问到 gbrain embed --test如果未来你想使用其他嵌入模型(如Cohere、Jina等),需要修改源码中src/embedding.ts相关的代码和配置。社区也有使用本地模型(如all-MiniLM-L6-v2)的讨论,但这会引入新的依赖和复杂度,背离了项目的“零运维”初衷,需谨慎评估。
4.3 与OpenClaw的核心集成:MCP服务器
这是让AI智能体“拥有”记忆的关键一步。你需要编辑OpenClaw的配置文件。
- 找到配置文件:通常位于
~/.openclaw/openclaw.json。如果不存在,你可能需要先运行一次OpenClaw来生成它。 - 添加gbrain MCP服务器配置:在配置文件的
mcp.servers部分添加如下条目:
{ "mcp": { "servers": { // ... 其他已有的MCP服务器配置 ... "gbrain": { "command": "gbrain", // 这里假设gbrain已在PATH中。也可用绝对路径,如 "/usr/local/bin/gbrain" "args": ["serve"] // 启动MCP服务器模式 } } } }这个配置告诉OpenClaw:“当你启动时,同时运行gbrain serve这个命令,并将其标准输入/输出作为一个MCP服务器连接起来。”
- 重启OpenClaw:修改配置后,需要重启OpenClaw客户端以使新的MCP服务器生效。
完成这一步后,你的OpenClaw AI助手(无论是在哪个聊天通道)就自动获得了访问gbrain所有工具的权限。你可以在对话中直接使用这些能力。
4.4 安装技能包:赋予AI自动化能力
MCP服务器提供了基础的“读写查”API,而技能包(Skill Pack)则是预先编写好的、更复杂的AI工作流。它们利用这些API,帮你完成多步骤的智能任务。
# 1. 创建OpenClaw技能目录(如果不存在) mkdir -p ~/.openclaw/workspace/skills # 2. 复制项目自带的技能包 cp -r gbrain-openclaw/skills/* ~/.openclaw/workspace/skills/现在,你的OpenClaw技能库中就拥有了以下五个强大的自动化技能:
| 技能 | 功能描述 | 典型使用场景 |
|---|---|---|
gbrain-ingest | 信息摄取引擎。分析会议记录、文章、对话文本,自动提取其中提到的实体(人、公司、概念),创建或更新对应的页面,并建立页面间的关联链接。 | 将一次长达一小时的会议录音转文字后,直接交给这个技能处理。它会自动总结出讨论了哪些公司、哪些人,更新他们的“编译事实”,并把会议要点作为时间线条目添加进去。 |
gbrain-query | 智能问答。结合全文搜索和向量语义搜索,理解你的自然语言问题,从大脑中找出最相关的信息,并组织成连贯的回答。 | 在聊天中问:“我认识哪些在AI安全领域创业的YC校友?” 技能会综合搜索type:person、tag:yc-alum、tag:ai-safety等,并理解“AI安全”的语义。 |
gbrain-maintain | 知识库巡检员。定期检查大脑中的数据健康度,例如发现互相矛盾的陈述、标记长时间未更新的陈旧信息、找出没有入链的孤立页面、检测失效的链接等。 | 每周运行一次,生成一份“大脑健康报告”,提示你“关于Acme Corp的融资额,在A页面说是$10M,在B页面说是$12M,请核实”。 |
gbrain-enrich | 信息增强器。调用外部API(如设想中的Crustdata获取公司信息、Happenstance获取活动信息、Exa进行网络搜索),为已有的页面补充更丰富的背景资料。 | 对“people/jane-doe”页面运行此技能,它可能会去抓取她的最新领英简介、公司新闻,并更新到页面中。 |
gbrain-briefing | 每日简报生成器。扫描时间线和新近更新的页面,为你生成一份定制化的每日简报,例如:过去24小时涉及的关键交易、需要跟进的开环线程、近期需要联系的重要人物等。 | 每天早上启动OpenClaw时自动触发,给你一个快速的上下文更新,让你迅速进入工作状态。 |
4.5 高级集成:会话自动摄取钩子
这是我最喜欢的功能之一,它实现了“对话即记录”的无感体验。配置后,每当你在OpenClaw中开始一个新会话(/new)或重置当前会话(/reset)时,系统会自动将刚刚结束的整个对话历史送入gbrain-ingest技能进行处理。
# 1. 复制会话钩子脚本 cp -r gbrain-openclaw/hooks/gbrain-ingest-session ~/.openclaw/workspace/skills/ # 2. 编辑OpenClaw配置文件,添加钩子配置在~/.openclaw/openclaw.json的hooks部分添加(如果hooks或internal不存在,则需要创建对应的结构):
{ "hooks": { "internal": { "handlers": [ { "event": "command:new", // 当用户输入 /new 命令时触发 "module": "~/.openclaw/workspace/skills/gbrain-ingest-session/hook.js", "export": "default" }, { "event": "command:reset", // 当用户输入 /reset 命令时触发 "module": "~/.openclaw/workspace/skills/gbrain-ingest-session/hook.js", "export": "default" } ] } } }注意事项:自动摄取非常方便,但也可能产生“噪音”。一些随意的、无关紧要的聊天也可能被记录。建议在初期谨慎使用,或者仅在某些特定的、工作相关的频道中启用此钩子。你也可以修改钩子脚本,添加一些过滤逻辑,比如只处理超过一定字数的对话,或只处理包含特定关键词(如“会议总结”、“行动计划”)的对话。
完成以上所有步骤后,你的gbrain-openclaw系统就已经全功能就绪,深度融入了你的OpenClaw工作流。接下来,我们就可以看看如何在日常中真正用它来思考和记忆了。
5. 日常使用模式:CLI、MCP与自然语言交互
gbrain-openclaw提供了多层交互界面,从底层的命令行到与AI的自然对话,你可以根据场景选择最合适的方式。
5.1 命令行界面:精准控制与批量操作
CLI是你管理知识大脑的“手术刀”,适合执行明确、批量的任务。
# 核心操作:增删改查 # 1. 创建或更新一个页面:使用管道符将Markdown内容传递给 `gbrain put` echo '--- title: Acme Corp type: company tags: [ai-infrastructure, series-a] --- # Acme Corp > Next-generation AI infrastructure startup. ## State Recently closed a $12M Series A. Scaling engineering team. ' | gbrain put companies/acme-corp # 2. 读取页面内容 gbrain get companies/acme-corp # 3. 关键词全文搜索(利用FTS5) gbrain search "Series A scaling engineering" # 这会返回所有包含这些词汇的页面,并按相关性排序。 # 4. 语义搜索(需要配置OPENAI_API_KEY) gbrain query "startups working on AI infrastructure like TensorFlow" # 即使页面中没有出现“TensorFlow”,只要其向量表示语义相近,也能被找到。 # 高级查询与管理 # 5. 列出特定类型的页面 gbrain list --type person --limit 10 --sort updated gbrain list --tag investor --tag venture-capital # 6. 查看知识库统计 gbrain stats # 输出示例:Pages: 142, Timeline entries: 587, Tags: 23, Total size: 4.2MB # 7. 手动添加时间线条目(不通过AI) gbrain timeline-add people/jane-doe \ --date 2026-04-10 \ --summary "Had a quick call to discuss partnership integration timeline." \ --source call \ --metadata '{"channel": "Slack DM"}' # 数据导入导出 # 8. 导出整个大脑为Markdown文件(便于备份或迁移) gbrain export --dir ./my-brain-backup-2026-04-10/ # 9. 从Markdown目录导入(例如从Obsidian迁移) gbrain import ./path/to/your/obsidian/vault/ # 维护任务 # 10. 为所有页面生成或更新向量嵌入 gbrain embed --all # 或只为自上次更新后修改过的页面生成 gbrain embed --stale5.2 通过MCP工具与AI智能体交互
这是最强大的使用方式。一旦MCP服务器配置成功,你可以在与OpenClaw的任何对话中,直接要求AI使用你的大脑。
基本查询:
- 你:“关于Acme Corp,我的大脑里记得什么?”
- AI:(调用
brain_get工具)然后呈现companies/acme-corp页面的编译事实和时间线摘要。
复杂检索:
- 你:“找出我大脑里所有和‘开源大模型’相关,并且类型是‘公司’的条目。”
- AI:(可能组合调用
brain_search、brain_list和brain_query)然后列出符合条件的公司,并附上简要说明。
主动记忆:
- 你:“把下面这段会议记录摄取到我的大脑里。” [粘贴记录]
- AI:(调用
brain_put或触发gbrain-ingest技能)分析记录,更新或创建相关实体页面,并反馈处理结果,如:“已更新‘people/jane-doe’和‘companies/acme-corp’页面,并添加了3条时间线记录。”
智能分析:
- 你:“给我一份关于当前所有进行中交易(open threads)的简报。”
- AI:(调用
gbrain-briefing技能)扫描所有标记为deal类型或包含[ ]开放线程的页面,生成一份汇总报告。
5.3 使用技能包进行自动化处理
除了在对话中触发,你也可以直接运行技能包来处理特定文件或数据。
# 假设你有一个刚整理好的会议记录 meeting-2026-04-10.md # 你可以让 ingest 技能直接处理它 openclaw run gbrain-ingest --input ./meeting-2026-04-10.md # 或者,你想每周一次检查大脑的健康状况 openclaw run gbrain-maintain # 运行后,它会输出一个报告,指出潜在的数据不一致、陈旧页面等问题。实操心得:建立你的页面命名规范(Slug Convention)项目的灵活性也带来了选择的负担。尽早建立一套自己的页面命名规范(Slug Convention)至关重要。我个人的习惯是:
people/firstname-lastname: 用于个人,如people/sam-altman。companies/company-name: 用于公司,使用常见的英文名或拼音,如companies/openai。deals/company-name-round: 用于具体的融资或交易,如deals/acme-series-a。concepts/kebab-case-concept: 用于抽象概念或技术,如concepts/retrieval-augmented-generation。projects/project-name: 用于内部或外部项目。tags的使用:在Frontmatter中用tags数组进行多维度分类,如[vc, seed-stage, ai, healthcare]。这比创建复杂的文件夹层级更灵活,便于通过brain_list进行筛选。
6. 维护、备份与故障排查指南
任何系统都需要维护,gbrain-openclaw虽然设计简洁,但也有一些最佳实践和常见问题需要注意。
6.1 常规维护操作
- 定期生成嵌入向量:如果你频繁使用语义搜索,需要确保新添加或修改的页面被向量化。可以设置一个简单的cron任务:
# 例如,每天凌晨2点更新向量 0 2 * * * cd /path/to/your/brain && OPENAI_API_KEY=your_key gbrain embed --stale - 运行维护技能:每周或每两周运行一次
gbrain-maintain,检查数据一致性。手动处理它报告的矛盾或陈旧信息,保持大脑的“清洁度”。 - 审查自动摄取结果:如果开启了会话自动摄取钩子,定期浏览一下新添加的时间线条目,确保AI的总结是准确的,必要时进行手动修正。
6.2 数据备份策略
你的全部知识都存储在~/.openclaw/brain.db这个单一文件中。备份极其简单,但也至关重要。
- 本地备份:最简单的就是用
cp命令定期复制到其他硬盘或目录。cp ~/.openclaw/brain.db ~/Documents/backups/brain-$(date +%Y%m%d).db - 云同步:你可以使用Dropbox、iCloud Drive、Google Drive等工具同步
~/.openclaw/目录。但需要注意:SQLite是文件型数据库,如果同时在两台设备上打开并写入,可能导致数据库损坏。最佳实践是:- 确保OpenClaw和
gbrain serve只在其中一台设备上运行。 - 使用云盘的“按需同步”功能,不要让数据库文件始终在所有设备上保持在线。
- 或者,使用像
rsync这样的工具进行手动单向同步。
- 确保OpenClaw和
6.3 常见问题与排查
MCP服务器连接失败
- 症状:OpenClaw启动时报错,或AI助手无法调用brain相关工具。
- 排查:
- 检查
openclaw.json配置中command的路径是否正确。尝试使用绝对路径/usr/local/bin/gbrain。 - 在终端直接运行
gbrain serve,看是否能正常启动,有无报错。 - 检查OpenClaw日志,通常会有更详细的MCP握手错误信息。
- 检查
语义搜索(
gbrain query)不返回结果或报错- 症状:CLI执行
gbrain query无结果,或提示嵌入错误。 - 排查:
- 确认
OPENAI_API_KEY环境变量已设置且有效。echo $OPENAI_API_KEY。 - 确认已为页面生成嵌入向量。运行
gbrain stats,查看embedded_pages计数是否大于0。如果为0,运行gbrain embed --all。 - 检查网络连接,确保能访问OpenAI API。
- 确认
- 症状:CLI执行
数据库文件损坏(罕见但严重)
- 症状:任何
gbrain命令都报SQLite错误,如“database disk image is malformed”。 - 恢复:
- 立即停止写入:不要再运行任何
gbrain或OpenClaw命令。 - 从备份恢复:用你最新的备份文件替换损坏的
brain.db。 - 尝试修复:如果没有备份,可以尝试SQLite的修复命令(有风险,先备份损坏的文件):
这可能会恢复部分数据。sqlite3 corrupted.db ".recover" | sqlite3 new.db
- 立即停止写入:不要再运行任何
- 症状:任何
性能变慢
- 症状:搜索或列表操作响应变慢。
- 优化:
- 确保数据库文件所在的磁盘有足够空间。
- 对于非常大的库(>10万页面),纯JS向量计算可能成为瓶颈。可以考虑定期归档非常陈旧的页面(导出为Markdown后从数据库中删除)。
- 运行
gbrain stats查看数据库大小和索引情况。SQLite通常会自动管理索引,但如果你自定义了复杂查询,可能需要手动创建索引。
技能包执行失败
- 症状:在OpenClaw中调用
gbrain-ingest等技能无响应或报错。 - 排查:
- 确认技能包文件已正确复制到
~/.openclaw/workspace/skills/目录下。 - 检查技能包内部的JavaScript代码是否有语法错误(虽然项目自带的一般是好的)。
- 查看OpenClaw的运行日志,通常能输出技能执行时的详细错误堆栈。
- 确认技能包文件已正确复制到
- 症状:在OpenClaw中调用
这个系统最吸引我的地方,就在于它将一个复杂的概念——个人知识图谱——简化到了一个几乎无感的基础设施层面。它不像一个需要你每天打开、精心维护的“应用”,而更像一个默默工作的“副驾驶”。你只管在OpenClaw里像平常一样聊天、工作,它则在后台自动帮你整理、记忆、建立连接。当你需要时,一句自然的提问就能唤回所有相关的、结构化的上下文。这种“记忆外挂”的感觉,在经过几周的深度使用后,已经变得不可或缺。它真正开始改变我与信息交互的方式,从被动的记录和检索,转向主动的编译和连接。
